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     */
011    package javax.wvcm;
012    
013    import javax.wvcm.PropertyNameList.PropertyName;
014    import 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     */
027    public 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    }