001/*
002 * file StpActivity.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM 
006 *
007 * com.ibm.rational.wvcm.stp.StpActivity
008 *
009 * (C) Copyright IBM Corporation 2007, 2011.  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;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.PropertyNameList.PropertyName;
019import javax.wvcm.WvcmException;
020
021import com.ibm.rational.wvcm.stp.cc.CcActivity;
022import com.ibm.rational.wvcm.stp.cq.CqRecord;
023import com.ibm.rational.wvcm.stpex.StpExEnumeration;
024
025/**
026 * <p>
027 * StpActivity is an interface for a proxy which may represent one of these
028 * three cases:
029 * </p>
030 * <ul>
031 * <li>A UCM-enabled CQ record not bound to a UCM activity, or</li>
032 * <li>A UCM activity not bound to a CQ record, or</li>
033 * <li>A UCM-enabled CQ record-UCM activity pair (bound together)</li>
034 * </ul>
035 * <p>
036 * It serves two purposes:
037 * </p>
038 * <ul>
039 * <li>It provides access to properties which are common to all of the above
040 * three cases</li>
041 * <li>It provides a means to access the CcActivity and/or CqRecord proxies for
042 * the persistent UCM activity or CQ record resources involved in the above
043 * three cases</li>
044 * </ul>
045 * <p>
046 * Although this interface extends StpResource, it is an abstraction. There is
047 * no factory method for constructing an instance of StpActivity, specifically.
048 * Proxies that implement this interface may be constructed only by constructing
049 * a CcActivity or a CqRecord. The location of an StpActivity will be that of
050 * a CcActivity or a CqRecord.
051 */
052public interface StpActivity extends StpResource {
053
054    enum CqUcmIntegrationState implements StpExEnumeration {
055
056        /**
057         * This is an unbound UCM activity in a non-ClearQuest-enabled project.
058         */
059        UNBOUND_CC_ACTIVITY,
060
061        /**
062         * This is an unbound ClearQuest record.
063         */
064        UNBOUND_CQ_RECORD,
065
066        /**
067         * This is a UCM-enabled CQ record and a UCM activity that are bound to
068         * each other.
069         */
070        BOUND_CC_ACTIVITY_CQ_RECORD_PAIR;
071    }
072
073    /**
074     * This activity's CQ-UCM integration state
075     */
076    PropertyName<CqUcmIntegrationState> CQ_UCM_INTEGRATION_STATE =
077        new PropertyName<CqUcmIntegrationState>(PROPERTY_NAMESPACE,
078                                                "cq-ucm-integration-state");
079
080    /**
081     * Returns the value of this proxy's {@link #CQ_UCM_INTEGRATION_STATE}
082     * property.
083     * 
084     * @return this activity's CQ-UCM integration state
085     * @throws WvcmException if this proxy doesn't define a value for this
086     *             property.
087     */
088    CqUcmIntegrationState getCqUcmIntegrationState() throws WvcmException;
089
090    /**
091     * The UCM activity to which this ClearQuest record is bound. In
092     * ClearQuest-enabled UCM projects, ClearQuest records may or may not be 
093     * bound.  In ClearQuest-enabled UCM projects the value of this property 
094     * may or may not be <b>null</b>.  In non-CQ-enabled projects the value of 
095     * this property will always be <b>null</b>.
096     * If this StpActivity represents a UCM Activity, the value of this
097     * property will be this StpActivity and always non-null.
098     */
099    PropertyName<CcActivity> BOUND_CC_ACTIVITY =
100        new PropertyName<CcActivity>(PROPERTY_NAMESPACE, "bound-cc-activity");
101
102    /**
103     * Returns the value of this proxy's {@link #BOUND_CC_ACTIVITY} property.
104     * 
105     * @return this activity's bound CQ record, or <b>null</b> if thi activity
106     *         is not bound to a CcActivity
107     * @throws WvcmException if this proxy doesn't define a value for this
108     *             property.
109     */
110    CcActivity getBoundCcActivity() throws WvcmException;
111
112    /**
113     * The location of UCM activity to which this ClearQuest record is bound. In
114     * ClearQuest-enabled UCM projects, ClearQuest records may or may not be 
115     * bound.  In ClearQuest-enabled UCM projects the value of this property 
116     * may or may not be <b>null</b>.  In non-CQ-enabled projects the value of 
117     * this property will always be <b>null</b>.
118     * If this StpActivity represents a UCM Activity, the value of this
119     * property will be this StpActivity's location and always non-null.
120     */
121    PropertyName<String> BOUND_CC_ACTIVITY_LOCATION =
122        new PropertyName<String>(PROPERTY_NAMESPACE, "bound-cc-activity-location");
123
124    /**
125     * Returns the value of this proxy's {@link #BOUND_CC_ACTIVITY_LOCATION} property.
126     * 
127     * @return bound activity's location as string, or <b>null</b> if this record
128     *         is not bound to a CcActivity
129     * @throws WvcmException if this proxy doesn't define a value for this
130     *             property.
131     */
132    String getBoundCcActivityLocation() throws WvcmException;
133    
134    /**
135     * The ClearQuest record to which this UCM activity is bound. In
136     * ClearQuest-enabled UCM projects, all UCM activities are bound and the
137     * value of this property will always be non-null. In non-CQ-enabled
138     * projects, the value of this property will always be <b>null</b>.
139     * If this StpActivity represents a ClearQuest record, the value of this
140     * property will be this StpActivity and always non-null.
141     */
142    PropertyName<CqRecord> BOUND_CQ_RECORD =
143        new PropertyName<CqRecord>(PROPERTY_NAMESPACE, "bound-cq-record");
144
145    /**
146     * Returns the value of this proxy's {@link #BOUND_CQ_RECORD} property.
147     * 
148     * @return this activity's bound CQ record, or <b>null</b> if activity is
149     *         not bound to a CQ record.
150     * @throws WvcmException if this proxy doesn't define a value for this
151     *             property.
152     */
153    CqRecord getBoundCqRecord() throws WvcmException;
154
155    /**
156     * A descriptive string - not necessarily unique - used to identify
157     * this activity when it appears in a GUI or in a report.
158     */
159    PropertyName<String> HEADLINE =
160        new PropertyName<String>(PROPERTY_NAMESPACE, "headline");
161
162    /**
163     * Returns the value of this proxy's {@link #HEADLINE} property.
164     * 
165     * @return A String containing the description of this StpActivity
166     * @throws WvcmException if this proxy doesn't define a value for this
167     *             property.
168     */
169    String getHeadline() throws WvcmException;
170
171    /**
172     * Defines a new value for the {@link #HEADLINE} property of this proxy.
173     * 
174     * @param headline The new headline string. Must not be <b>null</b>.
175     */
176    void setHeadline(String headline);
177
178    /**
179     * @deprecated 
180     * Use {@link #ID_SELECTOR} for a unique string to identify
181     * this activity.
182     * <br>
183     * Use {@link javax.wvcm.Resource#DISPLAY_NAME} for the activity name.
184     */
185    PropertyName<String> ID =
186        new PropertyName<String>(PROPERTY_NAMESPACE, "id");
187
188    /**
189     * @deprecated
190     */
191    String getId() throws WvcmException;
192    
193    /**
194     * A unique string to identify this activity.
195     */
196    PropertyName<String> ID_SELECTOR =
197        new PropertyName<String>(PROPERTY_NAMESPACE, "id-selector");
198    
199    /**
200     * Returns the value of this proxy's {@link #ID_SELECTOR} property.
201     * 
202     * @return A String containing the unique identifier for this StpActivity
203     * @throws WvcmException if this proxy doesn't define a value for this
204     *             property.
205     */
206    String getIdSelector() throws WvcmException;
207}