001 /*
002 * file CcView.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cc.CcView
008 *
009 * (C) 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 static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018 import java.io.File;
019 import java.util.Map;
020
021 import javax.wvcm.Feedback;
022 import javax.wvcm.Resource;
023 import javax.wvcm.Stream;
024 import javax.wvcm.WvcmException;
025 import javax.wvcm.PropertyNameList.PropertyName;
026
027 import com.ibm.rational.wvcm.stp.StpActivity;
028 import com.ibm.rational.wvcm.stp.cc.CcFileAreaLockedCallback.CcFileAreaLockInfo;
029 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
030
031 /**
032 * <p>A proxy for a ClearCase view. ClearCase "view" and WVCM "workspace"
033 * are equivalent terms for the same type of resource.
034 * </p>
035 * <p>In this release, only ClearCase CCRC web views are supported.
036 * ClearCase dynamic and snapshot views are not currently supported.
037 * </p>
038 */
039 public interface CcView
040 extends CcDirectory, javax.wvcm.Workspace
041 {
042 /** Values for view text mode */
043 enum TextMode implements StpExEnumeration {
044
045 /**
046 * A transparent interop text mode. The line terminator for text files
047 * is a single <code>NL</code> character. The view does not transform
048 * text file line terminators in any way. This is the default text mode
049 * if no value is set upon view creation.
050 */
051 TRANSPARENT("transparent"),
052
053 /**
054 * An insert_cr interop text mode. The view converts <code>NL</code> line
055 * terminators to the <code>CR NL</code> sequence when reading from a VOB,
056 * and <code>CR NL</code> line terminators to single <code>NL</code>
057 * characters when writing to the VOB.
058 */
059 INSERT_CR("insert-cr"),
060
061 /**
062 * An nl_to_cr interop text mode. The view converts <code>NL</code> line
063 * terminators to <code>CR</code> characters when reading from a VOB, and
064 * <code>CR</code> line terminators to single <code>NL</code> characters
065 * wehn writing to the VOB.
066 */
067 NL_TO_CR("nl-to-cr"),
068
069 /**
070 * A strip_cr interop text mode. The view converts <code>CR NL</code> line
071 * terminators to <code>NL</code> when reading from a VOB, and <code>NL</code>
072 * line terminators back to the <code>CR NL</code> sequence when writing to the VOB.
073 */
074 STRIP_CR("strip-cr");
075
076 private String m_name;
077
078 private TextMode(String name) { m_name = name; }
079
080 /* (non-Javadoc)
081 * @see java.lang.Object#toString()
082 */
083 public String toString() { return m_name; }
084 }
085
086 /** Flags for the <code>doSynchronizeFileAreaDb</code> method */
087 enum SynchronizeFileAreaDbFlag implements StpExEnumeration {
088
089 /**
090 * Synchronize the view's client-side vob database with the
091 * correct information from the server. Specifying this flag
092 * requires a server connection.
093 */
094 FILE_AREA_VOB_DB("file-area-vob-db"),
095
096 /**
097 * Synchronize the view's client-side modified files database
098 * so that it correctly reflects files that have been modified
099 * as a result of checkouts or hijacks. Specifying this flag
100 * does <i>not</i> require a server connection.
101 */
102 FILE_AREA_MODIFIED_FILES_DB("file-area-modified-files-db");
103
104 private String m_name;
105
106 private SynchronizeFileAreaDbFlag(String name) { m_name = name; }
107
108 /* (non-Javadoc)
109 * @see java.lang.Object#toString()
110 */
111 public String toString() { return m_name; }
112 }
113
114 /**
115 *<p>
116 * Binds a CcActivity proxy to a CqRecord proxy without making the
117 * activity the current one for this view.
118 * </p>
119 * <p>
120 * NOTE: Unlike most API methods, the optional property request will be executed
121 * on the returned StpActivity, not the CcView proxy on which the method
122 * was invoked.
123 * </p>
124 *
125 * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
126 * <p>
127 * If <code>act</code> is a CcActivity proxy and the associated project is
128 * not CQ enabled, this operation simply executes the provided property
129 * request -- if any. If the project is CQ enabled, it additionally validates
130 * that the bound CQ record is in an active state.
131 * </p>
132 * <p>
133 * If <code>act</code> is a CqRecord proxy, this operation is more
134 * involved. First, <code>act</code> is automatically transitioned to an
135 * active state. If this transition involves required fields, the caller
136 * may be prompted to provide values for those fields. Next a CcActivity
137 * resource is created in this view's stream and is bound to
138 * <code>act</code>.
139 * </p>
140 * @param act the activity to work on - either a CqRecord or CcActivity
141 * @param feedback optional property request
142 * @return new proxy for the StpActivity, with requested properties
143 * @see javax.wvcm.Workspace#CURRENT_ACTIVITY
144 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY
145 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD
146 */
147 public StpActivity doBindActivity(StpActivity act, Feedback feedback) throws WvcmException;
148
149 /**
150 * <p>Create a new ClearCase web view based on this CcView proxy.
151 * </p>
152 * <p>
153 * Preconditions:
154 * </p>
155 * <ul>
156 * <li>This proxy must have a file-based location representing the desired
157 * path of the root directory of the file area on the local machine.
158 * The directory must not yet exist.</li>
159 * <li>The location's leaf name (the directory name) will be used as
160 * the view tag of the new view. A view having that view-tag must not
161 * already exist.</li>
162 * <li>To create a view associated with a UCM stream, specify that stream
163 * by setting this view proxy's STREAM property.</li>
164 * </ul>
165 * <p>
166 * Postconditions:
167 * </p>
168 * <ul>
169 * <li>A ClearCase web view is created, with the view tag
170 * and local file area as described above.</li>
171 * <li>If the view proxy's STREAM property was set, the view will be
172 * associated with that stream.</li>
173 * <li>If the view proxy's VIEW_TAG_STRING property was set, the view will
174 * be assigned that tag. Otherwise, the file area's root directory name
175 * will be used.</li>
176 * </ul>
177 * @throws WvcmException if the preconditions are not met, or if there is an
178 * error creating the view.
179 */
180 public CcView doCreateCcWebView(Feedback feedback) throws WvcmException;
181
182 /**
183 * <p>Upgrade this web view's file area.</p>
184 * <p>Preconditions:</p>
185 * <ul>
186 * <li>This web view's file area schema version must be older than the
187 * version supported by the currently running CM API file area management
188 * code.
189 * </li>
190 * </ul>
191 * <p>Postconditions:</p>
192 * <ul>
193 * <li>This web view's file area schema will be upgraded to the currently
194 * supported version.</li>
195 * </ul>
196 * <p>This operation has no effect on non-web views, and on web views that
197 * are already compatible.
198 * </p>
199 * @throws WvcmException if the preconditions are not met, or if there is an
200 * error upgrading the file area.
201 */
202 public CcView doUpgradeFileArea(Feedback feedback) throws WvcmException;
203
204 /**
205 * Work on the specified activity in this CC view.
206 * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
207 * <p>
208 * If <code>act</code> is a CcActivity proxy and the associated project is
209 * not CQ enabled, this operation simply makes it the current activity
210 * in this view. If the project is CQ enabled, it additionally validates
211 * that the bound CQ record is in an active state.
212 * </p>
213 * <p>
214 * If <code>act</code> is a CqRecord proxy, this operation is more
215 * involved. First, <code>act</code> is automatically transitioned to an
216 * active state. If this transition involves required fields, the caller
217 * may be prompted to provide values for those fields. Next a CcActivity
218 * resource is created in this view's stream and is bound to
219 * <code>act</code>. Finally, it makes the new CC activity resource the
220 * current activity in this view.
221 * </p>
222 * @param act the activity to work on - either a CqRecord or CcActivity
223 * @param feedback optional property request
224 * @return new proxy for this view, with requested properties
225 * @see javax.wvcm.Workspace#CURRENT_ACTIVITY
226 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY
227 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD
228 */
229 public CcView doWorkOnActivity(StpActivity act, Feedback feedback) throws WvcmException;
230
231 /**
232 * <p>
233 * Transitions the specified activity to the default completed state.
234 * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy.
235 * </p>
236 * <p>
237 * NOTE: Unlike most API methods, the optional property request will be executed
238 * on the returned StpActivity, not the CcView proxy on which the method
239 * was invoked.
240 * </p>
241 * <p>Preconditions:</p>
242 * <ul>
243 * <li><code>act</code> is a bound CqRecord/CcActivity pair in a CQ-enabled
244 * context.</li>
245 * </ul>
246 * <p>Postconditions:</p>
247 * <ul>
248 * <li>If <code>act</code>'s CcActivity has checkouts, the operation is
249 * cancelled and there is no change to the activity.</li>
250 * <li>Transitions <code>act</code>'s CqRecord to the default completed state.
251 * If this transition involves required fields, the caller may be prompted
252 * to provide values for those fields.</li>
253 * <li>Unsets <code>act</code>'s CcActivity from all views'
254 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} property.</li>
255 * </ul>
256 * @param act the activity to finish
257 * @param feedback optional property request for the activity
258 * @return new proxy for the activity, with requested properties
259 * @throws WvcmException if the preconditions are not met.
260 */
261 public StpActivity doFinishActivity(StpActivity act, Feedback feedback)
262 throws WvcmException;
263
264 /**
265 * <p>
266 * Synchronize this file area's local databases to accurately reflect the
267 * current state of the file area. The databases available to synchronize are:
268 * </p>
269 * <ul>
270 * <li>VOB database: This contains the loaded vobs in the view. A server connection
271 * is required to synchronize this database.</li>
272 * <li>Modified files database: This contains the checkouts and hijacks in the view.
273 * A server connection <i>not</i> required to synchronize this database.</li>
274 * </ul>
275 * @param flags array of flags which specify the databases to synchronize.
276 * @param feedback optional property request for the view
277 * @return A new proxy for this resource, whose properties are specified by feedback.
278 * @throws WvcmException
279 */
280 public CcView doSynchronizeFileAreaDb(SynchronizeFileAreaDbFlag[] flags, Feedback feedback)
281 throws WvcmException;
282
283 /**
284 * Register this local web view's file area in the local file area registry.
285 * Web views are registered automatically when created, but may need to be
286 * re-registered if the registry is accidentally deleted, etc.
287 */
288 public void registerFileArea() throws WvcmException;
289
290 /**
291 * Remove this local web view's file area from the local file area registry.
292 * Once removed, this view will no longer show up when listing local views.
293 * @see com.ibm.rational.wvcm.stp.cc.CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest)
294 */
295 public void unregisterFileArea() throws WvcmException;
296
297 /**
298 * If this is a local web view, the URL of the CM Server where this
299 * view's view database resides.
300 */
301 PropertyName<String> SERVER_URL =
302 new PropertyName<String>(PROPERTY_NAMESPACE, "server-url");
303
304 /**
305 * Get the value of this proxy's {@link #SERVER_URL} property.
306 * @return this view's server URL
307 * @throws WvcmException if this proxy doesn't define a value for this property.
308 */
309 public String getServerUrl() throws WvcmException;
310
311 /**
312 * Change the URL used to connect to the CM server on which this web view resides.
313 * Note: Web views cannot be moved from one CM server to another.
314 * Use this method only to change the server URL, not to try to connect to
315 * a different server.
316 * <p>
317 * This may be necessary if, for example:
318 * <ul>
319 * <li>The CM server administrator changes the CM server's port number</li>
320 * <li>The client needs a secure HTTP connection to the CM server:
321 * "https://..." instead of "http://..."</li>
322 * <li>The CM server is moved to a different internet subdomain</li>
323 * </ul>
324 * @param updatedUrl the updated URL of this web view's CM server
325 * @throws WvcmException
326 */
327 public void updateServerUrl(String updatedUrl) throws WvcmException;
328
329 /**
330 * This view's view tag as a string.
331 */
332 PropertyName<String> VIEW_TAG_STRING =
333 new PropertyName<String>(PROPERTY_NAMESPACE, "view-tag-string");
334
335 /**
336 * Get the value of this proxy's {@link #VIEW_TAG_STRING} property.
337 * @return this view's view tag
338 * @throws WvcmException if this proxy doesn't define a value for this property.
339 */
340 public String getViewTagString() throws WvcmException;
341
342 /**
343 * Set the value of this view's {@link #VIEW_TAG_STRING} property.
344 * This property may only be set at view creation time.
345 * @param viewTag the view tag for the new view
346 */
347 void setViewTagString(String viewTag);
348
349 /**
350 * This view's view tag as a {@link CcViewTag} resource.
351 */
352 PropertyName<CcViewTag> VIEW_TAG =
353 new PropertyName<CcViewTag>(PROPERTY_NAMESPACE, "view-tag");
354
355 /**
356 * Get the value of this proxy's {@link #VIEW_TAG} property.
357 * @return this view's view tag
358 * @throws WvcmException if this proxy doesn't define a value for this property.
359 */
360 public CcViewTag getViewTag() throws WvcmException;
361
362 /**
363 * Whereas a CcView resource's {@link javax.wvcm.Folder#CHILD_MAP} property
364 * returns the root directories of <i>all</i> VOBs, LOADED_CHILD_MAP only
365 * returns the root directories of VOBs that are partially or fully loaded
366 * in this view.
367 */
368 PropertyName<Map<String,Resource>> LOADED_CHILD_MAP =
369 new PropertyName<Map<String,Resource>>(PROPERTY_NAMESPACE, "loaded-child-map");
370
371 /**
372 * Get the value of this proxy's {@link #LOADED_CHILD_MAP} property.
373 * @return this view's loaded child map
374 * @throws WvcmException if this proxy doesn't define a value for this property.
375 */
376 public Map<String,Resource> getLoadedChildMap() throws WvcmException;
377
378 /**
379 * This view's file area root directory on the local machine.
380 * The value of this property will be null if this is not a web view,
381 * or if it does not have a file area on the local machine.
382 */
383 PropertyName<File> FILE_AREA_ROOT_DIRECTORY =
384 new PropertyName<File>(PROPERTY_NAMESPACE, "file-area-root-directory");
385
386 /**
387 * Returns the value of the {@link #FILE_AREA_ROOT_DIRECTORY} property.
388 * @return This view's copy area root directory, or null if it has
389 * no copy area on the local machine
390 * @throws WvcmException if this property is not defined by this proxy.
391 */
392 public File getFileAreaRootDirectory() throws WvcmException;
393
394 /**
395 * Is this view's local file area schema version older than the version
396 * supported by the running CM API file management code? If so, the file
397 * area needs to be upgraded before it can be used.
398 *
399 * @see com.ibm.rational.wvcm.stp.cc.CcView#doUpgradeFileArea(Feedback)
400 */
401 PropertyName<Boolean> FILE_AREA_NEEDS_UPGRADE =
402 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "file-area-needs-upgrade");
403
404 /**
405 * Get the value of this view's {@link #FILE_AREA_NEEDS_UPGRADE} property.
406 * @return true if this view's local file area needs upgrading; false otherwise.
407 * @throws WvcmException if this property is not defined by this proxy.
408 */
409 boolean getFileAreaNeedsUpgrade() throws WvcmException;
410
411 /**
412 * Is this view associated with a UCM stream?.
413 */
414 PropertyName<Boolean> IS_UCM_VIEW =
415 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-ucm-view");
416
417 /**
418 * Get the value of this view's {@link #IS_UCM_VIEW} property.
419 * @return true if this view represents a UCM view; false otherwise.
420 * @throws WvcmException if this property is not defined by this proxy.
421 */
422 boolean getIsUcmView() throws WvcmException;
423
424 /**
425 * This view's config spec.
426 */
427 PropertyName<CcConfigSpec> CONFIG_SPEC =
428 new PropertyName<CcConfigSpec>(PROPERTY_NAMESPACE, "config-spec");
429
430 /**
431 * Get the value of this view's {@link #CONFIG_SPEC} property.
432 * @return this view's config spec as a CcConfigSpec instance
433 */
434 CcConfigSpec getConfigSpec() throws WvcmException;
435
436 /**
437 * Set the value of this view's {@link #CONFIG_SPEC} property.
438 * @param configSpec the new config spec for this view
439 */
440 void setConfigSpec(CcConfigSpec configSpec);
441
442 /**
443 * The text mode of the view. The text mode specifies the line
444 * terminator sequence for text files in the view. If no value is
445 * set upon view creation, defaults to {@link TextMode#TRANSPARENT}.
446 */
447 PropertyName<TextMode> TEXT_MODE =
448 new PropertyName<TextMode>(PROPERTY_NAMESPACE, "text-mode");
449
450 /**
451 * Get the value of this view's {@link #TEXT_MODE} property.
452 * @return enumeration value representing this view's text mode.
453 * @throws WvcmException if this proxy doesn't define a value for this property.
454 */
455 TextMode getTextMode() throws WvcmException;
456
457 /**
458 * Set the value of this view's {@link #TEXT_MODE} property. This
459 * property may only be set at view creation time.
460 * @param textMode the text mode of the view.
461 */
462 void setTextMode(TextMode textMode);
463
464 /**
465 * Break a file area lock on this view with the given lock info.
466 * @param lockInfo information about the lock
467 * @return true if the lock was broken; false otherwise
468 * @throws WvcmException if a problem occurred breaking the lock
469 */
470 boolean breakFileAreaLock(CcFileAreaLockInfo lockInfo) throws WvcmException;
471
472 /**
473 * CcViewAccessInfo object contains the supported view access properties.
474 */
475 public static final PropertyName<CcViewAccessInfo> VIEW_ACCESS_INFO =
476 new PropertyName<CcViewAccessInfo>(PROPERTY_NAMESPACE, "view-access-info");
477
478 /**
479 * Returns the value of this proxy's {@link #VIEW_ACCESS_INFO} property.
480 *
481 * @return the CcViewAccessInfo object.
482 * @throws WvcmException
483 * if this proxy doesn't define a value for this property.
484 */
485 public CcViewAccessInfo getViewAccessInfo() throws WvcmException;
486
487 /**
488 * <p>
489 * The permissions applied to this resource.
490 * </p>
491 */
492 public static final PropertyName<CcPermissions> PERMISSIONS =
493 new PropertyName<CcPermissions>(PROPERTY_NAMESPACE, "cc-permissions");
494
495 /**
496 * Returns the value of this proxy's {@link #PERMISSIONS} property.
497 *
498 * @return A permissions object from which specific permissions
499 * information can be extracted.
500 * @throws WvcmException
501 * if this proxy doesn't define a value for this property.
502 */
503 public CcPermissions getPermissions() throws WvcmException;
504
505 /**
506 * Does this view have non-shareable derived objects?
507 */
508 public static final PropertyName<Boolean> IS_EXPRESS =
509 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-express");
510
511 /**
512 * Returns the value of this proxy's {@link #IS_EXPRESS} property.
513 *
514 * @return true if this view has non-shareable DOs; false otherwise.
515 * @throws WvcmException
516 * if this proxy doesn't define a value for this property.
517 */
518 public Boolean getIsExpress() throws WvcmException;
519
520 /**
521 * Are this view's permissions valid?
522 */
523 public static final PropertyName<Boolean> ARE_PERMISSIONS_VALID =
524 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "are-permissions-valid");
525
526 /**
527 * Returns the value of this proxy's {@link #ARE_PERMISSIONS_VALID} property.
528 *
529 * @return true if this view's permissions are valid; false otherwise.
530 * @throws WvcmException
531 * if this proxy doesn't define a value for this property.
532 */
533 public Boolean getArePermissionsValid() throws WvcmException;
534
535 /**
536 * Is this view read-only?
537 */
538 public static final PropertyName<Boolean> IS_READ_ONLY =
539 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-read-only");
540
541 /**
542 * Returns the value of this proxy's {@link #IS_READ_ONLY} property.
543 *
544 * @return true if this view is read-only; false otherwise.
545 * @throws WvcmException
546 * if this proxy doesn't define a value for this property.
547 */
548 public Boolean getIsReadOnly() throws WvcmException;
549
550 /**
551 * Set the {@link #STREAM} property.
552 *
553 * @param stream the {@link Stream} object that
554 * identifies the {@link #STREAM} for this Workspace.
555 * @see #getStream
556 */
557 public void setStream(Stream stream);
558 }