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    }