001 /*
002 * file CcVersion.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cc.CcVersion
008 *
009 * (C) Copyright IBM Corporation 2004, 2009. All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights: Use, duplication or
011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
012 */
013
014 package com.ibm.rational.wvcm.stp.cc;
015
016 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018 import javax.wvcm.Feedback;
019 import javax.wvcm.ResourceList;
020 import javax.wvcm.Version;
021 import javax.wvcm.WvcmException;
022 import javax.wvcm.PropertyNameList.PropertyName;
023
024 import com.ibm.rational.wvcm.stpex.StpExBase;
025
026 /**
027 * <p>
028 * A proxy for a version of a ClearCase element.
029 * </p>
030 * <p>
031 * Each time a new revision of a version-controlled file or
032 * directory is checked in, a new <i>version</i> of that element is created.
033 * Versions are created, in sequence, on the branch of an element selected
034 * by the view's config spec.
035 * </p>
036 * <p>
037 * For more information about version, see the ClearCase "Guide to Developing Software"
038 * manual.
039 * </p>
040 * @see com.ibm.rational.wvcm.stp.cc.CcBranch
041 * @see com.ibm.rational.wvcm.stp.cc.CcElement
042 * @see com.ibm.rational.wvcm.stp.cc.CcConfigSpec
043 * @see com.ibm.rational.wvcm.stp.cc.CcBranchType
044 */
045 public interface CcVersion
046 extends Version, CcVobResource
047 {
048 /**
049 * This version's branch.
050 * @see javax.wvcm.Version#VERSION_BRANCH
051 */
052 PropertyName<CcBranch> BRANCH =
053 new PropertyName<CcBranch>(PROPERTY_NAMESPACE, "version-branch");
054
055 /**
056 * Get the value of this version's {@link #BRANCH} property.
057 *
058 * @return a proxy for this version's branch
059 * @throws WvcmException if property was not requested
060 */
061 public CcBranch getBranch() throws WvcmException;
062
063 /**
064 * This version's element.
065 * @see javax.wvcm.Version#VERSION_HISTORY
066 */
067 PropertyName<CcElement> ELEMENT =
068 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
069
070 /**
071 * Get the value of this version's {@link #ELEMENT} property.
072 *
073 * @return a proxy for this version's element
074 * @throws WvcmException if property was not requested
075 */
076 public CcElement getElement() throws WvcmException;
077
078 /**
079 * <p>
080 * The view-relative path for this version, possibly including
081 * the version extension.
082 * </p>
083 * <p>
084 * NOTE: This property is only available if it is retrieved
085 * using a method with a view context, such as
086 * Resource.doReadProperties(CcView, PropertyRequest).
087 * ClearCase needs a view context to resolve version paths.
088 * </p>
089 */
090 PropertyName<String> VIEW_RELATIVE_PATH =
091 new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
092
093 /**
094 * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
095 *
096 * @return view-relative path
097 * @throws WvcmException
098 * if property was not requested, or if the view context
099 * was not provided
100 */
101 public String getViewRelativePath() throws WvcmException;
102
103 /**
104 * <p>
105 * The immediate predecessor of this version on this version's branch,
106 * or if this is the first version on the branch, the version from
107 * which the branch emanates. Will be <code>null</code> if this version
108 * is the <code>/main/0</code> version of its element.
109 * </p>
110 */
111 PropertyName<CcVersion> PREDECESSOR =
112 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
113
114 /**
115 * Get the value of this version's {@link #PREDECESSOR} property.
116 * @return a CcVersion proxy for this version's predecessor.
117 * @throws WvcmException if property was not requested.
118 */
119 public CcVersion getPredecessor() throws WvcmException;
120
121 /**
122 * <p>
123 * The list of versions that were merged to create this version.
124 * This will be empty if this version was not created by a merge
125 * operation.
126 * </p>
127 */
128 PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST =
129 new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
130
131 /**
132 * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
133 * @return a list of the CcVersion proxies which represent merge contributors for this version.
134 * @throws WvcmException if property was not requested.
135 */
136 public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
137
138 /**
139 * Add the specified label to the version.
140 * @param label Label to be applied
141 * @param view View context
142 * @throws WvcmException
143 * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
144 */
145 public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;
146
147 /**
148 * Set the specified label on the version.
149 * @param label Label to be applied
150 * @param view View context
151 * @throws WvcmException
152 * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
153 */
154 public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;
155
156 /**
157 * Remove the specified label from the version.
158 * @param label Label to be removed
159 * @param view View context
160 * @throws WvcmException
161 * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
162 */
163 public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
164
165 /**
166 * Create a Merge hyperlink pointing from this version to the specified destination version.
167 * @param toVersion Destination version for the hyperlink
168 * @return A new proxy for this version, whose properties are specified by feedback.
169 */
170 public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
171 }