001/* 002 * file Version.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 java.util.List; 014 015import javax.wvcm.PropertyNameList.PropertyName; 016import javax.wvcm.WvcmException.ReasonCode; 017 018/** 019 * A proxy for a version resource. 020 * 021 * A version resource contains an immutable copy of the properties of a 022 * version-controlled resource. A version resource also contains mutable 023 * properties with metadata about that version. 024 * 025 * @since 1.0 026 */ 027public interface Version extends Resource { 028 029 /** 030 * Get the workspace provider of this resource. 031 * 032 * @return the {@link WorkspaceProvider} for this Resource. 033 */ 034 public WorkspaceProvider workspaceProvider(); 035 036 /** 037 * The {@link Activity} object that identify the 038 * activity to which this version contributes. 039 * A provider may refuse to allow the activity of a version to be modified. 040 * This version must be on the same line of descent 041 * as all other versions with this activity from the same version history. 042 * If the {@link Activity#ACTIVITY_CHECKOUT_LIST} of the activity identifies a 043 * controllable resource that is reserved and checks out a version 044 * in the version history of this version, 045 * then the checked-out version must be a successor of all other 046 * versions with this activity from the same version history. 047 * @see #setActivity 048 * @see #getActivity 049 */ 050 public static final PropertyName<Activity> ACTIVITY = 051 new PropertyName<Activity>("activity"); //$NON-NLS-1$ 052 053 /** 054 * Get the {@link #ACTIVITY} property. 055 * 056 * @return the {@link #ACTIVITY} property. 057 * @throws WvcmException if this property was not set and 058 * this Version was not created with 059 * {@link #ACTIVITY} as a wanted property. 060 * @see #setActivity 061 */ 062 public Activity getActivity() throws WvcmException; 063 064 /** 065 * Set the {@link #ACTIVITY} property. 066 * 067 * @param activity an {@link Activity} object that specifies 068 * the new {@link #ACTIVITY} property for this Version. 069 * @see #getActivity 070 */ 071 public void setActivity(Activity activity); 072 073 /** 074 * Valid values for the {@link #CHECKIN_FORK} and {@link #CHECKOUT_FORK} properties. 075 */ 076 public enum Fork { 077 078 /** 079 * Forking is allowed without special options. 080 */ 081 OK("ok"), //$NON-NLS-1$ 082 083 /** 084 * Forking is allowed only if specifically requested. 085 */ 086 DISCOURAGED("discouraged"), //$NON-NLS-1$ 087 088 /** 089 * Forking is not allowed. 090 */ 091 FORBIDDEN("forbidden"); //$NON-NLS-1$ 092 093 private final String _forkType; 094 095 private Fork(String forkType) { 096 _forkType = forkType; 097 } 098 099 /** 100 * Returns a string representation of this Fork suitable for diagnostics. 101 */ 102 @Override 103 public String toString() { return _forkType; } 104 } 105 106 /** 107 * An enumeration that determines whether this Version can be given 108 * more than one successor. 109 * If {@link #CHECKIN_FORK} is {@link Fork#DISCOURAGED}, a doCheckin request 110 * MUST fail unless forkOk is specified in the doCheckin request. 111 * If the {@link #CHECKIN_FORK} of a version is {@link Fork#FORBIDDEN}, 112 * a doCheckin request MUST fail if it would result in that version 113 * appearing in the {@link #PREDECESSOR_LIST} of more than one version. 114 * A server MAY reject attempts to modify the {@link #CHECKIN_FORK} of a version. 115 * @see #setCheckinFork 116 * @see #getCheckinFork 117 */ 118 public static final PropertyName<Fork> CHECKIN_FORK = 119 new PropertyName<Fork>("checkin-fork"); //$NON-NLS-1$ 120 121 /** 122 * Get the {@link #CHECKIN_FORK} property. 123 * 124 * @return the {@link #CHECKIN_FORK} property. 125 * @throws WvcmException if this property was not set and 126 * this Version was not created with 127 * {@link #CHECKIN_FORK} as a wanted property. 128 * @see #setCheckinFork 129 */ 130 public Fork getCheckinFork() throws WvcmException; 131 132 /** 133 * Set the {@link #CHECKIN_FORK} property. 134 * 135 * @param val the new {@link #CHECKIN_FORK} value for this Version. 136 * @see #getCheckinFork 137 */ 138 public void setCheckinFork(Fork val); 139 140 /** 141 * An enumeration that determines whether a version-controlled resource 142 * selecting this Version can be checked out when it already has 143 * a successor version. 144 * If {@link #CHECKOUT_FORK} is {@link Fork#DISCOURAGED}, a doCheckout request MUST fail 145 * unless forkOk is specified in the doCheckout request. 146 * If the {@link #CHECKOUT_FORK} of a version is {@link Fork#FORBIDDEN}, 147 * a doCheckout request will fail if it would result in that version 148 * appearing in the {@link #PREDECESSOR_LIST} or {@link ControllableResource#CHECKED_OUT} property 149 * of more than one version or checked-out resource. 150 * A server MAY reject attempts to modify the {@link #CHECKOUT_FORK} of a version. 151 * @see #setCheckoutFork 152 * @see #getCheckoutFork 153 */ 154 public static final PropertyName<Fork> CHECKOUT_FORK = 155 new PropertyName<Fork>("checkout-fork"); //$NON-NLS-1$ 156 157 /** 158 * Get the {@link #CHECKOUT_FORK} property. 159 * 160 * @return the {@link #CHECKOUT_FORK} property. 161 * @throws WvcmException if this property was not set and 162 * this Version was not created with 163 * {@link #CHECKOUT_FORK} as a wanted property. 164 * @see #setCheckoutFork 165 */ 166 public Fork getCheckoutFork() throws WvcmException; 167 168 /** 169 * Set the {@link #CHECKOUT_FORK} property. 170 * 171 * @param val the new {@link #CHECKOUT_FORK} value for this Version. 172 * @see #getCheckoutFork 173 */ 174 public void setCheckoutFork(Fork val); 175 176 /** 177 * A list of all controllable resources that are checked out from this version. 178 * This is the computed inverse of the {@link ControllableResource#CHECKED_OUT} property. 179 * @see #getCheckoutList 180 */ 181 public static final PropertyName<ResourceList<ControllableResource>> CHECKOUT_LIST = 182 new PropertyName<ResourceList<ControllableResource>>("checkout-list"); //$NON-NLS-1$ 183 184 /** 185 * Get the {@link #CHECKOUT_LIST} property. 186 * 187 * @return the {@link #CHECKOUT_LIST} property. 188 * @throws WvcmException if this Version was not created with 189 * {@link #CHECKOUT_LIST} as a wanted property. 190 */ 191 public ResourceList<ControllableResource> getCheckoutList() 192 throws WvcmException; 193 194 /** 195 * A list of strings that identify the labels 196 * that currently select this Version. 197 * @see #getLabelNameList 198 */ 199 public static final PropertyName<List<String>> LABEL_NAME_LIST = 200 new PropertyName<List<String>>("label-name-list"); //$NON-NLS-1$ 201 202 /** 203 * Get the {@link #LABEL_NAME_LIST} property. 204 * @return the {@link #LABEL_NAME_LIST} property. 205 * @throws WvcmException if this Version was not created with 206 * {@link #LABEL_NAME_LIST} as a wanted property. 207 */ 208 public List<String> getLabelNameList() throws WvcmException; 209 210 /** 211 * A list of all versions that are direct predecessors of this version. 212 * @see #getPredecessorList 213 */ 214 public static final PropertyName<ResourceList<Version>> PREDECESSOR_LIST = 215 new PropertyName<ResourceList<Version>>("predecessor-list"); //$NON-NLS-1$ 216 217 /** 218 * Get the {@link #PREDECESSOR_LIST} property. 219 * @return the {@link #PREDECESSOR_LIST} property. 220 * @throws WvcmException if this Version was not created with 221 * {@link #PREDECESSOR_LIST} as a wanted property. 222 */ 223 public ResourceList<Version> getPredecessorList() throws WvcmException; 224 225 /** 226 * A list of all versions that are direct successors of this version. 227 * The {@link #SUCCESSOR_LIST} property is the computed inverse of the 228 * {@link #PREDECESSOR_LIST} property. 229 * @see #getSuccessorList 230 */ 231 public static final PropertyName<ResourceList<Version>> SUCCESSOR_LIST = 232 new PropertyName<ResourceList<Version>>("successor-list"); //$NON-NLS-1$ 233 234 /** 235 * Get the {@link #SUCCESSOR_LIST} property. 236 * 237 * @return the {@link #SUCCESSOR_LIST} property. 238 * @throws WvcmException if this Version was not created with 239 * {@link #SUCCESSOR_LIST} as a wanted property. 240 */ 241 public ResourceList<Version> getSuccessorList() throws WvcmException; 242 243 /** 244 * The version history that contains this version. 245 * @see #getVersionHistory 246 */ 247 public static final PropertyName<VersionHistory> VERSION_HISTORY = 248 new PropertyName<VersionHistory>("version-history"); //$NON-NLS-1$ 249 250 /** 251 * Get the {@link #VERSION_HISTORY} property. 252 * 253 * @return the {@link #VERSION_HISTORY} property. 254 * @throws WvcmException if this Version was not created with 255 * {@link #VERSION_HISTORY} as a wanted property. 256 */ 257 public VersionHistory getVersionHistory() throws WvcmException; 258 259 /** 260 * A server-defined string that is different for each version 261 * in the version history of this version. 262 * This string is intended for display to a user, 263 * unlike the location of a version, which is normally only used by a client 264 * and not displayed to a user. 265 * @see #getVersionName 266 */ 267 public static final PropertyName<String> VERSION_NAME = 268 new PropertyName<String>("version-name"); //$NON-NLS-1$ 269 270 /** 271 * Get the {@link #VERSION_NAME} property. 272 * 273 * @return the {@link #VERSION_NAME} property. 274 * @throws WvcmException if this Version was not created with 275 * {@link #VERSION_NAME} as a wanted property. 276 */ 277 public String getVersionName() throws WvcmException; 278 279 /** 280 * Add the specified label to this version. 281 * 282 * @param label the label to be added to this version 283 * @param feedback Specifies optional feedback to the caller. 284 * @return A new proxy for this resource, whose properties are specified by feedback. 285 * @throws WvcmException 286 * <li>{@link ReasonCode#ADD_MUST_BE_NEW_LABEL}: 287 * The label MUST NOT already identify a version in the version history of this version. 288 */ 289 public Version doAddLabel(String label, Feedback feedback) throws WvcmException; 290 291 /** 292 * Remove the specified label from this version. 293 * 294 * @param label the label to be removed from this version. 295 * @param feedback Specifies optional feedback to the caller. 296 * @return A new proxy for this resource, whose properties are specified by feedback. 297 * @throws WvcmException ReasonCode: 298 * <li>{@link ReasonCode#CANNOT_REMOVE_LABEL_DOES_NOT_EXIST}: 299 * The label must be on this version. 300 */ 301 public Version doRemoveLabel(String label, Feedback feedback) throws WvcmException; 302 303 /** 304 * Set the specified label on this version. 305 * 306 * @param label The label to be set on this version 307 * @param feedback Specifies optional feedback to the caller. 308 * @return A new proxy for this resource, whose properties are specified by feedback. 309 * @throws WvcmException if label cannot be set 310 */ 311 public Version doSetLabel(String label, Feedback feedback) throws WvcmException; 312 313 /** 314 * A list of all workspaces that have a controllable resource that contains 315 * this version in its {@link ControllableResource#CHECKED_IN} or 316 * {@link ControllableResource#CHECKED_OUT} property. 317 * Because there can be many workspaces that contain a given version, 318 * this property is most commonly used in a {@link Resource#doFind} request. 319 * @see #getInWorkspaceList 320 */ 321 public static final PropertyName<ResourceList<Workspace>> IN_WORKSPACE_LIST = 322 new PropertyName<ResourceList<Workspace>>("in-workspace-list"); //$NON-NLS-1$ 323 324 /** 325 * Get the {@link #IN_WORKSPACE_LIST} property. 326 * 327 * @return the {@link #IN_WORKSPACE_LIST} property. 328 * @throws WvcmException if this Version was not created with 329 * {@link #IN_WORKSPACE_LIST} as a wanted property. 330 */ 331 public ResourceList<Workspace> getInWorkspaceList() 332 throws WvcmException; 333 334 /** 335 * A list of all baselines that contain this version in their {@link Baseline#VERSION_LIST} 336 * property. 337 * This is the computed inverse of the {@link Baseline#VERSION_LIST} property. 338 * Because there can be many baselines that contain a given version, 339 * this property is most commonly used in a {@link Resource#doFind} request. 340 * @see #getInBaselineList 341 */ 342 public static final PropertyName<ResourceList<Baseline>> IN_BASELINE_LIST = 343 new PropertyName<ResourceList<Baseline>>("in-baseline-list"); //$NON-NLS-1$ 344 345 /** 346 * Get the {@link #IN_BASELINE_LIST} property. 347 * 348 * @return the {@link #IN_BASELINE_LIST} property. 349 * @throws WvcmException if this Version was not created with 350 * {@link #IN_BASELINE_LIST} as a wanted property. 351 */ 352 public ResourceList<Baseline> getInBaselineList() 353 throws WvcmException; 354 355}