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
014package com.ibm.rational.wvcm.stp.cc;
015
016import javax.wvcm.Activity;
017import javax.wvcm.Feedback;
018import javax.wvcm.PropertyNameList.PropertyName;
019import javax.wvcm.ResourceList;
020import javax.wvcm.Task;
021import javax.wvcm.Version;
022import javax.wvcm.WvcmException;
023
024import com.ibm.rational.wvcm.stp.StpActivity;
025import 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 */
047public 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}