001/*
002 * file ControllableFolder.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 * 
007 * (c) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
008 * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
009 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
010 */
011package javax.wvcm;
012
013import javax.wvcm.PropertyNameList.PropertyName;
014import javax.wvcm.WvcmException.ReasonCode;
015
016/**
017 * A proxy for a controllable folder resource.
018 * 
019 * A controllable folder resource is a folder that can be placed under control.
020 * When a controllable folder is placed under version control, a version of that folder
021 * only captures the named mappings to version controlled members of that folder.
022 * In order to version control the entire configuration rooted at a folder,
023 * the folder must be placed under "baseline control".
024 * 
025 * @since 1.0
026 */
027public interface ControllableFolder extends ControllableResource, Folder {
028
029    /**
030     * Put this ControllableFolder under baseline control.
031     * If no ControllableFolder exists at this location, create one under baseline control.
032     * <p>
033     * A configuration resource is associated with
034     * this ControllableFolder, which allows versions of the configuration rooted at
035     * this ControllableFolder to be created by checking out and checking in the 
036     * configuration resource. </p>
037     * <p>
038     * A version of a configuration is called a "baseline". </p>
039     * <p>
040     * Postconditions:
041     * <li>(create-configuration): A new configuration is created,
042     *  whose {@link Configuration#ROOT_FOLDER} property identifies this ControllableFolder.
043     *  The {@link ControllableResource#WORKSPACE} property of the new configuration is the same as 
044     *  the {@link ControllableResource#WORKSPACE} property of the controllable folder identified by
045     *  this ControllableFolder.
046     * <li>(reference-configuration): The {@link ControllableResource#CONFIGURATION} property of the folder
047     *  and all its members identifies the new configuration. The {@link #ROOT_FOLDER_OF}
048     *  property of the folder identifies the new configuration.
049     * <li>(create-new-baseline): The request MUST have created a new baseline history
050     *  at a server-defined location, and MUST have created a new baseline in that baseline history.
051     *  The {@link Baseline#VERSION_LIST} of the new baseline MUST identify a
052     *  list of the {@link #CHECKED_IN} versions of each version-controlled member
053     *  of the request folder.
054     *  The {@link ControllableResource#CHECKED_IN} property of the new configuration MUST identify the new baseline.
055     *  The {@link ControllableResource#VERSION_HISTORY} property of the new configuration MUST identify the new
056     *  baseline history.
057     *  
058     * @param feedback Specifies optional feedback to the caller.
059     * @return A new proxy for this resource, whose properties are specified by feedback.
060     * @throws WvcmException ReasonCode:
061     * <li>{@link ReasonCode#CONTROLLED_CONFIGURATION_ALREADY_EXISTS}
062     *  If there already
063     *  is a Configuration that identifies this ControllableFolder
064     *  in its {@link Configuration#ROOT_FOLDER} property, the request MUST fail.
065     * <li>{@link ReasonCode#NO_CHECKED_OUT_BASELINE_CONTROLLED_FOLDER_MEMBERS}:
066     *  All version-controlled members of this folder MUST be checked-in.
067     * <li>{@link ReasonCode#FORBIDDEN}:
068     *  The folder must be baseline controllable.
069     */
070    public ControllableFolder doBaselineControl(Feedback feedback) throws WvcmException;
071
072    /**
073     * Create a baseline-controlled controllable folder at this location, and 
074     * initialize it with the contents of the specified baseline.
075     * If the specified baseline must be restored at a specific location,
076     * the new baseline-controlled folder is created at that specific location
077     * instead of this ControllableFolder.
078     * The request will fail if a resource already exists at that location.
079     * 
080     * <p>
081     * 
082     * Postconditions:
083     * <li>(create-configuration): A new baseline-controlled folder is created,
084     *  and a new configuration is created whose {@link Configuration#ROOT_FOLDER} property
085     *  identifies the new folder.
086     * <li>(reference-configuration): The {@link ControllableResource#CONFIGURATION} property of the folder
087     *  and all its members identifies the new configuration. The {@link #ROOT_FOLDER_OF}
088     *  property of the folder identifies the new configuration.
089     * <li>(select-existing-baseline): The {@link ControllableResource#CHECKED_IN} property of the new configuration
090     *  MUST have been set to identify the specified baseline.
091     *  A version-controlled member of the folder will be created for each version in the baseline,
092     *  where the version-controlled member will have the content of that version,
093     *  and will have the same name relative to the folder as the corresponding
094     *  version-controlled resource had when the baseline was created.
095     *  Any nested folders that are needed to provide the appropriate name
096     *  for a version-controlled member will be created.
097     *  
098     * @param baseline the baseline used to initialize the folder.
099     * @param feedback Specifies optional feedback to the caller.
100     * @return A proxy for this new resource, whose properties are specified by feedback.
101     * @throws WvcmException ReasonCode:
102     * <li>{@link ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION}:
103     *  The location for the new baseline-controlled folder MUST be a valid location for a baseline-controlled folder.
104     * <li>{@link ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION}:
105     *  The location for the new baseline-controlled folder MUST NOT identify an existing resource.
106     * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
107     *  The baseline argument MUST identify a baseline.
108     * <li>{@link ReasonCode#CANNOT_HAVE_MULTIPLE_BASELINE_CONTROLLED_FOLDERS}:
109     *  There MUST NOT be another folder
110     *  in the workspace of this ControllableFolder whose configuration property
111     *  identifies a configuration for the baseline history of that baseline. 
112     */
113    public ControllableFolder doCreateBaselineControlledFolder(Baseline baseline, Feedback feedback) throws WvcmException;
114
115    /**
116     * True if the folder can be put under baseline control with the
117     * {@link #doBaselineControl} or
118     * {@link #doCreateBaselineControlledFolder} methods, otherwise false.
119     */
120    public static final PropertyName<Boolean> IS_BASELINE_CONTROLLABLE =
121        new PropertyName<Boolean>("is-baseline-controllable"); //$NON-NLS-1$
122
123    /**
124     * Get the {@link #IS_BASELINE_CONTROLLABLE} property.
125     * 
126     * @return the {@link #IS_BASELINE_CONTROLLABLE} property.
127     * @throws WvcmException if this ControllableFolder was not created with
128     * {@link #IS_BASELINE_CONTROLLABLE} as a wanted property.
129     */
130    public boolean getIsBaselineControllable() throws WvcmException;
131
132    /**
133     * The configuration for which this is the root folder.
134     * The {@link #ROOT_FOLDER_OF} property is the computed inverse of the
135     * {@link Configuration#ROOT_FOLDER} property.
136     * @see #getRootFolderOf
137     */
138    public static final PropertyName<Configuration> ROOT_FOLDER_OF =
139        new PropertyName<Configuration>("root-folder-of"); //$NON-NLS-1$
140
141    /**
142     * Get the {@link #ROOT_FOLDER_OF} property.
143     * 
144     * @return the {@link #ROOT_FOLDER_OF} property.
145     * @throws WvcmException if this ControllableFolder was not created with
146     * {@link #ROOT_FOLDER_OF} as a wanted property.
147     */
148    public Configuration getRootFolderOf() throws WvcmException;
149
150    /**
151     * True if the folder has been baseline controlled. False if the folder
152     * has not been baseline controlled or is a child of a folder that has
153     * been baseline controlled.
154     * @see #getIsBaselineControlled
155     */
156    public static final PropertyName<Boolean> IS_BASELINE_CONTROLLED =
157        new PropertyName<Boolean>("is-baseline-controlled"); //$NON-NLS-1$
158
159    /**
160     * Get the {@link #IS_BASELINE_CONTROLLED} property.
161     * 
162     * @return the {@link #IS_BASELINE_CONTROLLED} property.
163     * @throws WvcmException if this ControllableFolder was not created with
164     * {@link #IS_BASELINE_CONTROLLED} as a wanted property.
165     */
166    public boolean getIsBaselineControlled() throws WvcmException;
167
168}