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     * (C) 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>&lt;record-type&gt;</i>/<i>&lt;record-id&gt;</i>/<i>&lt;field-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
044     * </pre>
045     * where the /<i>&lt;field-name&gt;</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    }