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 }