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 }