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 }