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 * © Copyright IBM Corporation 2004, 2008. 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.CcElement
041 * @see com.ibm.rational.wvcm.stp.cc.CcConfigSpec
042 * @see com.ibm.rational.wvcm.stp.cc.CcBranchType
043 */
044 public interface CcVersion
045 extends Version, CcVobResource
046 {
047 /**
048 * This version's element.
049 * @see javax.wvcm.Version#VERSION_HISTORY
050 */
051 PropertyName<CcElement> ELEMENT =
052 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
053
054 /**
055 * Get the value of this version's {@link #ELEMENT} property.
056 *
057 * @return a proxy for this version's element
058 * @throws WvcmException if property was not requested
059 */
060 public CcElement getElement() throws WvcmException;
061
062 /**
063 * <p>
064 * The view-relative path for this version, possibly including
065 * the version extension.
066 * </p>
067 * <p>
068 * NOTE: This property is only available if it is retrieved
069 * using a method with a view context, such as
070 * Resource.doReadProperties(CcView, PropertyRequest).
071 * ClearCase needs a view context to resolve version paths.
072 * </p>
073 */
074 PropertyName<String> VIEW_RELATIVE_PATH =
075 new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
076
077 /**
078 * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
079 *
080 * @return view-relative path
081 * @throws WvcmException
082 * if property was not requested, or if the view context
083 * was not provided
084 */
085 public String getViewRelativePath() throws WvcmException;
086
087 /**
088 * <p>
089 * The immediate predecessor of this version on this version's branch,
090 * or if this is the first version on the branch, the version from
091 * which the branch emanates. Will be <code>null</code> if this version
092 * is the <code>/main/0</code> version of its element.
093 * </p>
094 */
095 PropertyName<CcVersion> PREDECESSOR =
096 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
097
098 /**
099 * Get the value of this version's {@link #PREDECESSOR} property.
100 * @return a CcVersion proxy for this version's predecessor.
101 * @throws WvcmException if property was not requested.
102 */
103 public CcVersion getPredecessor() throws WvcmException;
104
105 /**
106 * <p>
107 * The list of versions that were merged to create this version.
108 * This will be empty if this version was not created by a merge
109 * operation.
110 * </p>
111 */
112 PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST =
113 new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
114
115 /**
116 * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
117 * @return a list of the CcVersion proxies which represent merge contributors for this version.
118 * @throws WvcmException if property was not requested.
119 */
120 public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
121
122 /**
123 * Add the specified label to the version.
124 * @param label Label to be applied
125 * @param view View context
126 * @throws WvcmException
127 * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
128 */
129 public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;
130
131 /**
132 * Set the specified label on the version.
133 * @param label Label to be applied
134 * @param view View context
135 * @throws WvcmException
136 * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
137 */
138 public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;
139
140 /**
141 * Remove the specified label from the version.
142 * @param label Label to be removed
143 * @param view View context
144 * @throws WvcmException
145 * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
146 */
147 public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
148
149 /**
150 * Create a Merge hyperlink pointing from this version to the specified destination version.
151 * @param toVersion Destination version for the hyperlink
152 * @return A new proxy for this version, whose properties are specified by feedback.
153 */
154 public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
155 }