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 }