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    }