001 /*
002 * file CcResource.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cc.CcResource
008 *
009 * (C) Copyright IBM Corporation 2004, 2014. 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
015 package com.ibm.rational.wvcm.stp.cc;
016
017 import javax.wvcm.Feedback;
018 import javax.wvcm.PropertyRequestItem;
019 import javax.wvcm.Resource;
020 import javax.wvcm.WvcmException;
021
022 import com.ibm.rational.wvcm.stp.StpResource;
023
024 /**
025 * <p>A proxy for a resource in a ClearCase VOB or view.
026 * </p>
027 */
028 public interface CcResource extends StpResource {
029
030 /**
031 * Construct a new proxy for this resource.
032 * This new proxy will be of the most correct, most derived class for this
033 * resource, based on currently available information in the resource's
034 * location, on the local client machine, and/or on the ClearCase server.
035 * In addition, this new proxy will have its identity
036 * correctly set so that its equals() and hashMap() methods will work
037 * correctly.
038 * <p>Unresolved resource proxies should not be used in situations where
039 * equality matters, especially in maps, lists, sets, and other collection
040 * classes.
041 * </p>
042 * @return a new proxy of the correct, most specific resource type
043 */
044 public CcResource doResolve() throws WvcmException;
045
046 /**
047 * Has this proxy already been resolved?
048 * @return true if this proxy has been resolved; else false
049 * @see #doResolve()
050 */
051 public boolean isResolved() throws WvcmException;
052
053 /**
054 * Get the ClearCase provider associated with this resource proxy.
055 * This is normally the network provider for the CCRC WAN server on which
056 * this remote resource resides, or a local provider if this is a local
057 * ClearCase resource.
058 */
059 CcProvider ccProvider();
060
061 /**
062 * Checks if this proxy contains valid values for the provided properties, if
063 * and only if, they are supported. Properties which are unsupported by the
064 * server are ignored.
065 *
066 * @param wantedProp A PropertyRequestItem, possibly with multiple nested
067 * properties, to check the value for. Cannot be
068 * <code>null</code>.
069 *
070 * @return <code>true</code> if there is an entry in this proxy for all
071 * server supported properties of the PropertyRequestItem,
072 * and those entries contain a valid value; <code>false</code> otherwise.
073 */
074 public boolean hasSupportedProperties(PropertyRequestItem wantedProp);
075
076 /**
077 * Persists property changes to this CcResource.
078 * An exception is thrown if any of properties cannot be written.
079 * If an exception is thrown, the properties that were set will not be written
080 * can be determined from {@link #updatedPropertyNameList}
081 * on this CcResource.
082 * Note that since doWriteProperties returns a new proxy whose properties are
083 * specified in the feedback argument, doWriteProperties is semantically identical
084 * to {@link #doReadProperties}.
085 * Properties are computed relative to the given context. For example, when
086 * working with automatic views, the
087 * {@link com.ibm.rational.wvcm.stp.cc.CcVobTag#IS_MOUNTED}
088 * property of a CcVobTag resource can only be modified in the
089 * context of a CcView. Hence, you would use this form of doWriteProperties
090 * to specify the CcView context that should be used.
091 *
092 * @param context An optional proxy (often CcView) providing context for the
093 * writing of certain properties. May be <b>null</b>.
094 * @param feedback Specifies optional feedback to the caller.
095 * @return a new proxy for this resource, whose properties are specified by feedback.
096 */
097 public Resource doWriteProperties(Resource context,
098 Feedback feedback) throws WvcmException;
099
100 /**
101 * Reads the CcResource's properties if they are available locally on the client machine.
102 * Any modified properties in this CcResource are first written to the resource before
103 * the properties are read from the resource. Note that this makes readProperties
104 * semantically identical to {@link #writeProperties}.
105 * @param feedback the properties to be available in the returned proxy,
106 * and any other feedback desired, such as progress indications.
107 * @return a {@link Resource} containing the wanted properties
108 * that are available locally on the client machine
109 * without communicating with the server.
110 *
111 * @see Resource#doReadProperties(Feedback) doReadProperties.
112 * @throws WvcmException
113 * <p>
114 * {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
115 * If the resource is not be known locally on the client machine.
116 */
117 public Resource readProperties(Feedback feedback) throws WvcmException;
118
119 /**
120 * Request the properties specified in <code>feedback</code> from the
121 * client resource represented by this proxy. A new proxy will be
122 * constructed whose property map contains just the requested properties.
123 * Any modified properties in this CcResource are first written to the resource before
124 * the properties are read from the resource. Note that this makes readProperties
125 * semantically identical to {@link #writeProperties}.
126 * <p>
127 * Properties are computed within the context of a given resource context.
128 * For example, the {@link com.ibm.rational.wvcm.stp.cc.CcVobTag#IS_MOUNTED}
129 * property of a CcVobTag for automatic views can be provided in the
130 * context of a CcView. Hence, you would use this form of readProperties
131 * to obtain the list of vob tags mounted for the specified view context.
132 *
133 * @param context An optional proxy (often CcView) providing context for the
134 * generation of certain properties in the returned report.
135 * May be <b>null</b>.
136 * @param feedback Provides optional feedback to the caller for a list of
137 * properties desired from the client. If the parameter is null or
138 * empty, a request is still made, and the returned proxy will have
139 * only the properties always requested from the client.
140 * @return A proxy containing the properties retrieved from the client (and
141 * error messages for those that could not be retrieved). The class
142 * of the returned proxy is the one most suited to the type of
143 * resource addressed.
144 *
145 * @throws WvcmException if failures occur
146 *
147 * @see CcResource#readProperties(Feedback)
148 */
149 public Resource readProperties(Resource context, Feedback feedback) throws WvcmException;
150
151 /**
152 * Resolve this ClearCase resource, but do not consult the ClearCase server.
153 * Unlike {@link CcResource#doResolve()}, use only information currently
154 * available information on the local client machine.
155 * @see CcResource#doResolve()
156 * @return a new ClearCase resource proxy of the correct, most specific resource type
157 * @throws WvcmException with NOT_FOUND reason code if this resource does not
158 * exist on the local machine.
159 */
160 public Resource resolve() throws WvcmException;
161
162 /**
163 * Persists property changes to this CcResource locally if they can be persisted locally.
164 * An exception is thrown if any of properties cannot be written.
165 * If an exception is thrown, the properties that were set will not be written
166 * can be determined from {@link #updatedPropertyNameList}
167 * on this CcResource.
168 * Note that since writeProperties returns a new proxy whose properties are
169 * specified in the feedback argument, writeProperties is semantically identical
170 * to {@link #readProperties}.
171 * @param feedback Specifies optional feedback to the caller.
172 * @return a new proxy for this resource, whose properties are specified by feedback.
173 * @see Resource#doWriteProperties(Feedback)
174 */
175 public Resource writeProperties(Feedback feedback) throws WvcmException;
176
177 /**
178 * Persists property changes to this CcResource locally if they can be persisted locally.
179 * An exception is thrown if any of properties cannot be written.
180 * If an exception is thrown, the properties that were set will not be written
181 * can be determined from {@link #updatedPropertyNameList}
182 * on this CcResource.
183 * Note that since writeProperties returns a new proxy whose properties are
184 * specified in the feedback argument, writeProperties is semantically identical
185 * to {@link #readProperties}.
186 * Properties are computed within the context of a given resource context. For example,
187 * when working with automatic views, the {@link com.ibm.rational.wvcm.stp.cc.CcVobTag#IS_MOUNTED}
188 * property of a CcVobTag resource can only be modified in the
189 * context of a CcView. Hence, you would use this form of writeProperties
190 * to specify the view context that should be used.
191 *
192 * @param context An optional proxy (often CcView) providing context for the
193 * writing of certain properties. May be <b>null</b>.
194 * @param feedback Specifies optional feedback to the caller.
195 * @return a new proxy for this resource, whose properties are specified by feedback.
196 */
197 public Resource writeProperties(Resource context, Feedback feedback) throws WvcmException;
198 }