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         * Note that there is an exception to this for automatic views, where a request to
111         * a connected automatic view may result in server communication to update local 
112         * cached data. 
113         * 
114         * @see Resource#doReadProperties(Feedback) doReadProperties.
115         * @throws WvcmException
116         * <p>
117         * {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
118         * If the resource is not be known locally on the client machine.
119         */
120        public Resource readProperties(Feedback feedback) throws WvcmException;
121        
122       /**
123         * Request the properties specified in <code>feedback</code> from the
124         * client resource represented by this proxy. A new proxy will be
125         * constructed whose property map contains just the requested properties.
126         * Any modified properties in this CcResource are first written to the resource before 
127         * the properties are read from the resource. Note that this makes readProperties 
128         * semantically identical to {@link #writeProperties}.
129         * <p>
130         * Properties are computed within the context of a given resource context. 
131         * For example, the {@link com.ibm.rational.wvcm.stp.cc.CcVobTag#IS_MOUNTED}
132         * property of a CcVobTag for automatic views can be provided in the
133         * context of a CcView. Hence, you would use this form of readProperties
134         * to obtain the list of vob tags mounted for the specified view context.
135         * 
136         * @param context An optional proxy (often CcView) providing context for the
137         *            generation of certain properties in the returned report. 
138         *            May be <b>null</b>.
139         * @param feedback Provides optional feedback to the caller for a list of 
140         *            properties desired from the client. If the parameter is null or
141         *            empty, a request is still made, and the returned proxy will have
142         *            only the properties always requested from the client.
143         * @return A proxy containing the properties retrieved from the client (and
144         *         error messages for those that could not be retrieved). The class
145         *         of the returned proxy is the one most suited to the type of
146         *         resource addressed.
147         * 
148         * @throws WvcmException if failures occur
149         * 
150         * @see CcResource#readProperties(Feedback)
151         */
152        public Resource readProperties(Resource context, Feedback feedback) throws WvcmException;
153    
154        /**
155         * Resolve this ClearCase resource, but do not consult the ClearCase server.
156         * Unlike {@link CcResource#doResolve()}, use only information currently
157         * available information on the local client machine.  
158         * @see CcResource#doResolve()
159         * @return a new ClearCase resource proxy of the correct, most specific resource type
160         * @throws WvcmException with NOT_FOUND reason code if this resource does not
161         *         exist on the local machine.
162         */
163        public Resource resolve() throws WvcmException;
164        
165        /**
166         * Persists property changes to this CcResource locally if they can be persisted locally.
167         * An exception is thrown if any of properties cannot be written.
168         * If an exception is thrown, the properties that were set will not be written
169         * can be determined from {@link #updatedPropertyNameList}
170         * on this CcResource.
171         * Note that since writeProperties returns a new proxy whose properties are
172         * specified in the feedback argument, writeProperties is semantically identical
173         * to {@link #readProperties}.
174         * @param feedback Specifies optional feedback to the caller.
175         * @return a new proxy for this resource, whose properties are specified by feedback.
176         * @see Resource#doWriteProperties(Feedback)
177         */
178        public Resource writeProperties(Feedback feedback) throws WvcmException;
179        
180        /**
181         * Persists property changes to this CcResource locally if they can be persisted locally.
182         * An exception is thrown if any of properties cannot be written.
183         * If an exception is thrown, the properties that were set will not be written
184         * can be determined from {@link #updatedPropertyNameList}
185         * on this CcResource.
186         * Note that since writeProperties returns a new proxy whose properties are
187         * specified in the feedback argument, writeProperties is semantically identical
188         * to {@link #readProperties}.
189         * Properties are computed within the context of a given resource context. For example,
190         * when working with automatic views, the {@link com.ibm.rational.wvcm.stp.cc.CcVobTag#IS_MOUNTED}
191         * property of a CcVobTag resource can only be modified in the
192         * context of a CcView. Hence, you would use this form of writeProperties
193         * to specify the view context that should be used.
194         * 
195         * @param context An optional proxy (often CcView) providing context for the
196         *            writing of certain properties. May be <b>null</b>.
197         * @param feedback Specifies optional feedback to the caller.
198         * @return a new proxy for this resource, whose properties are specified by feedback.
199         */
200        public Resource writeProperties(Resource context, Feedback feedback) throws WvcmException;
201    }