001 /*
002 * file CcActivity.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cc.CcActivity
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 javax.wvcm.Activity;
017 import javax.wvcm.Feedback;
018 import javax.wvcm.ResourceList;
019 import javax.wvcm.Version;
020 import javax.wvcm.WvcmException;
021 import javax.wvcm.PropertyNameList.PropertyName;
022
023 import com.ibm.rational.wvcm.stp.StpActivity;
024 import com.ibm.rational.wvcm.stpex.StpExBase;
025
026 /**
027 * <p>A proxy for a ClearCase UCM activity.
028 * </p>
029 * <p>UCM activities collect the logically-related changes (versions) made in a
030 * given UCM stream, and are the basic unit of <i>change flow </i> between
031 * streams. When a developer begins working on a new task within a particular
032 * UCM stream, he typically creates a new UCM activity for that task. At
033 * checkout time, each new version is added to the activity's <i>change set</i>.
034 * </p>
035 * <p>If the UCM project in which the user working is <i>ClearQuest-enabled</i>,
036 * all UCM activities in that project are managed by the <i>ClearQuest
037 * Integration </i>. Rather than creating a new UCM activity directly, the user
038 * selects or creates the ClearQuest record he wants to work on and performs a
039 * <i>WorkOn </i> operation. ClearQuest creates a corresponding UCM activity and
040 * binds it to the ClearQuest record.
041 * </p>
042 * <p>See the "Developing Software with ClearCase" manual for more information
043 * about working with UCM activities.
044 * </p>
045 */
046 public interface CcActivity
047 extends Activity, StpActivity, CcVobResource
048 {
049 /**
050 * <p>Create a new UCM activity at the location identified by this proxy. The
051 * location should be an object name selector specifying the activity's name
052 * and the repository (project VOB) in which to create it.
053 * </p>
054 * <p>Set the {@link #STREAM} property to specify the new activity's stream
055 * (required). The stream's repository must match the repository specified
056 * in this activity's location.
057 * </p>
058 * <p>Set the {@link #HEADLINE} property to specify the new activity's headline
059 * (optional).
060 * </p>
061 * <p>Set the {@link #COMMENT} property to specify a creation comment for the
062 * new activity (optional).
063 * </p>
064 * <p>This method fails if the stream is ClearQuest-enabled. In a CQ-enabled
065 * stream, activities can only be created indirectly by working on a CQ
066 * entity in the context of a view associated with that stream.
067 * </p>
068 */
069 public CcActivity doCreateCcActivity(Feedback feedback) throws WvcmException;
070
071 /**
072 * <p>Create a new UCM activity, allowing the provider to choose the
073 * new activity's name.
074 * The provider may use the client-specified location if it is valid,
075 * but can select a different location if the location is not valid
076 * or already identifies an activity.
077 * </p>
078 * @see #doCreateCcActivity(Feedback)
079 */
080 public CcActivity doCreateGeneratedCcActivity(Feedback feedback) throws WvcmException;
081
082
083 /** The UCM stream in which this activity resides. */
084 static final PropertyName<CcStream> STREAM =
085 new PropertyName<CcStream>(StpExBase.PROPERTY_NAMESPACE, "act-stream");
086
087 /**
088 * Get the value of this proxy's {@link #STREAM} property.
089 * @return this activity's stream
090 * @throws WvcmException if this proxy doesn't define a value for this property.
091 */
092 CcStream getStream() throws WvcmException;
093
094 /**
095 * Set the value of this activity's {@link #STREAM} property.
096 * This property can only be set at activity creation time.
097 * @param stream proxy for the stream in which the new activity will reside
098 */
099 void setStream(CcStream stream);
100
101 /**
102 * Return true if the activity is an "integration activity", that is
103 * one created by UCM during a deliver or rebase operation.
104 */
105 static final PropertyName<Boolean> IS_INTEGRATION_ACTIVITY =
106 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-integration-activity");
107
108 /**
109 * Get the value of this proxy's {@link #IS_INTEGRATION_ACTIVITY} property.
110 * @return true if this proxy represents an integration activity, false otherwise
111 * @throws WvcmException if this proxy doesn't define a value for this property.
112 */
113 boolean getIsIntegrationActivity() throws WvcmException;
114
115 /** A view for resolving names of versions in the activity's change set. */
116 static final PropertyName<CcView> NAME_RESOLVER_VIEW =
117 new PropertyName<CcView>(StpExBase.PROPERTY_NAMESPACE, "name-resolver-view");
118
119 /**
120 * Get the value of this proxy's {@link #NAME_RESOLVER_VIEW} property.
121 * @return A view on the activity's stream.
122 * @throws WvcmException if this proxy doesn't define a value for this property.
123 */
124 CcView getNameResolverView() throws WvcmException;
125
126 /** The latest version for each element in a change set. */
127 static final PropertyName<ResourceList<Version>> LATEST_VERSION_LIST =
128 new PropertyName<ResourceList<Version>>(StpExBase.PROPERTY_NAMESPACE, "latest-version-list");
129
130 /**
131 * Get the value of this proxy's {@link #LATEST_VERSION_LIST} property.
132 * @return The latest version of each element in a change set.
133 * @throws WvcmException if this proxy doesn't define a value for this property.
134 */
135 ResourceList<Version> getLatestVersionList() throws WvcmException;
136
137 /** Returns true if there are checkouts under this activity. */
138 static final PropertyName<Boolean> HAS_CHECKOUTS =
139 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "has-checkouts");
140
141 /**
142 * Get the value of this proxy's {@link #HAS_CHECKOUTS} proerty.
143 * @return true if there are checkouts under the activity represented by this proxy, false otherwise.
144 * @throws WvcmException if this proxy doesn't define a value for this property.
145 */
146 boolean getHasCheckouts() throws WvcmException;
147 }