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