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
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.Feedback;
019import javax.wvcm.Folder;
020import javax.wvcm.ResourceList;
021import javax.wvcm.WvcmException;
022import 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 */
048public 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}