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