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
015package com.ibm.rational.wvcm.stp.cc;
016
017import java.io.OutputStream;
018
019import javax.wvcm.Feedback;
020import javax.wvcm.PropertyRequestItem;
021import javax.wvcm.Resource;
022import javax.wvcm.WvcmException;
023import javax.wvcm.WvcmException.ReasonCode;
024
025import com.ibm.rational.wvcm.stp.StpResource;
026
027/**
028 * <p>A proxy for a resource in a ClearCase VOB or view.
029 * </p>
030 */
031public 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}