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
014 package com.ibm.rational.wvcm.stp;
015
016 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018 import javax.wvcm.PropertyNameList.PropertyName;
019 import javax.wvcm.WvcmException;
020
021 import com.ibm.rational.wvcm.stp.cc.CcActivity;
022 import com.ibm.rational.wvcm.stp.cq.CqRecord;
023 import 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 */
052 public 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 }