001 /*
002 * file CqAttachmentFolder.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqAttachmentFolder
008 *
009 * © Copyright IBM Corporation 2004, 2008. All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights: Use, duplication or
011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
012 */
013
014 package com.ibm.rational.wvcm.stp.cq;
015
016 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018 import javax.wvcm.Feedback;
019 import javax.wvcm.Folder;
020 import javax.wvcm.ResourceList;
021 import javax.wvcm.WvcmException;
022 import javax.wvcm.PropertyNameList.PropertyName;
023
024 /**
025 * A folder that contains the attachments associated with an attachment field of
026 * a record and, hence, the value of such a record field. Attachments are added
027 * to a record by creating an attachment resource in an CqAttachmentFolder. They
028 * are removed by deleting the attachment resources from their respective
029 * attachment folders.
030 *
031 * <p>
032 * Attachment folders can neither be created nor deleted independent of the
033 * record with which they are associated. They are the one and only value of
034 * their attachment field for the lifetime of that field. Only their contents
035 * may be altered. And their content is altered by executing
036 * {@link CqAttachment#doCreateAttachment(String, Feedback, java.util.List)
037 * doCreateAttachment} and
038 * {@link CqAttachment#doUnbindAll(Feedback) doUnbindAll} operations on the
039 * attachment resources that are contained by the attachment folder.
040 * <p>
041 * The user-friendly specification for the location of an attachment folder has the form
042 * <pre>
043 * <b>cq.record:</b><i><record-type></i>/<i><record-id></i>/<i><field-name></i>@<i><db-set></i>/<i><user-db></i>
044 * </pre>
045 * where the /<i><field-name></i> segment identifies a field of type
046 * {@link CqFieldValue.ValueType#ATTACHMENT_LIST}
047 */
048 public interface CqAttachmentFolder extends CqUserDbMember, Folder {
049 /**
050 * The members of this folder. The attachments that are associated with
051 * this folder's parent record field. A more-strongly-typed version of the
052 * the {@link Folder#CHILD_LIST} property.
053 */
054 PropertyName<ResourceList<CqAttachment>> ATTACHMENT_LIST =
055 new PropertyName<ResourceList<CqAttachment>>(PROPERTY_NAMESPACE, "attachment-list");
056
057 /**
058 * Returns the value of the {@link #ATTACHMENT_LIST ATTACHMENT_LIST}
059 * property as defined by this proxy.
060 *
061 * @return A List of CqAttachment proxies for the attachments in this
062 * attachment folder.
063 *
064 * @throws WvcmException if this proxy does not define a value for the
065 * {@link #ATTACHMENT_LIST ATTACHMENT_LIST} property.
066 */
067 ResourceList<CqAttachment> getAttachmentList() throws WvcmException;
068
069 /** The record field that contains this attachment folder as its value. */
070 PropertyName<CqFieldValue<CqAttachmentFolder>> FIELD =
071 new PropertyName<CqFieldValue<CqAttachmentFolder>>(PROPERTY_NAMESPACE, "field");
072
073 /**
074 * Returns the value of the {@link #FIELD FIELD} property as defined by this
075 * proxy.
076 *
077 * @return A CqFieldValue structure for the field that references this
078 * folder. Will never be <b>null</b>.
079 *
080 * @throws WvcmException if this proxy does not define a value for the
081 * {@link #FIELD FIELD} property.
082 */
083 CqFieldValue<?> getField() throws WvcmException;
084
085 /** The parent record of this folder. */
086 PropertyName<CqRecord> RECORD =
087 new PropertyName<CqRecord>(PROPERTY_NAMESPACE, "record");
088
089 /**
090 * Returns the value of the {@link #RECORD RECORD} property as
091 * defined by this proxy.
092 *
093 * @return A Record proxy for the record with which this folder is associated.
094 *
095 * @throws WvcmException if this Property instance does not define a value
096 * for the {@link #RECORD RECORD} metadata
097 * component.
098 */
099 CqRecord getRecord()
100 throws WvcmException;
101
102 /**
103 * A CqRecordType proxy for the record-type resource that defines the parent
104 * record of this attachment folder.
105 */
106 PropertyName<CqRecordType> RECORD_TYPE =
107 new PropertyName<CqRecordType>(PROPERTY_NAMESPACE, "record-type");
108
109 /**
110 * A CqRecordType proxy for the record-type resource that defines what kind of
111 * record this is.
112 *
113 * @return The proxy for the record-type of this record is returned.
114 *
115 * @throws WvcmException if this proxy does not define a value for the
116 * {@link #RECORD_TYPE RECORD_TYPE} property.
117 */
118 CqRecordType getRecordType() throws WvcmException;
119 }