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 }