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    }