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