001/*
002* file CcVobResource.java
003*
004* Licensed Materials - Property of IBM
005* Restricted Materials of IBM
006*
007* com.ibm.rational.wvcm.stp.cc.CcVobResource
008*
009* (C) Copyright IBM Corporation 2004, 2012.  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
014package com.ibm.rational.wvcm.stp.cc;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.util.List;
019
020import javax.wvcm.Feedback;
021import javax.wvcm.ResourceList;
022import javax.wvcm.WvcmException;
023import javax.wvcm.PropertyNameList.PropertyName;
024
025import com.ibm.rational.wvcm.stp.ccex.CcExFileList.RequestForMastershipFlag;
026import com.ibm.rational.wvcm.stpex.StpExEnumeration;
027
028/**
029 * <p>
030 * Base interface containing properties and methods common to
031 * all VOB-resident ClearCase resources.
032 * </p>
033 */
034public interface CcVobResource extends CcResource {
035
036    /** Flags for the doApplyAttribute method */
037    enum ApplyAttributeFlag implements StpExEnumeration {
038
039        /**
040         * Replace existing attribute instance.
041         */
042        REPLACE("replace"),
043
044        /**
045         * If the attribute type was created with a default value, uses
046         * that value for the attribute instead of the value specified in
047         * the call. An error occurs if the attribute type was not created 
048         * with a default value. 
049         */
050        DEFAULT("default");
051        
052        private String m_name;
053
054        private ApplyAttributeFlag(String name) { m_name = name; }
055
056        /* (non-Javadoc)
057         * @see java.lang.Object#toString()
058         */
059        public String toString() { return m_name; }
060    }
061
062    /**
063     * Apply the specified attribute to this VOB resource.
064     * @param flags array of flags which specify the behavior of the operation
065     * @param comment Comment (if any) to be used for operation.  Empty string if none.
066     * @param attributeName Name of an existing attribute type to be used to create 
067     * an instance will to be applied to this resource.
068     * @param attributeValue Value of attribute instance.  If the vtype of the attribute type is
069     * a string, it must be enclosed in additional quotes <em>within the string</em>.  For example, if
070     * specified as a constant it would appear as <code>"\"string value\""</code>.  If the
071     * vtype is not a string, this should be a string representation of the given value 
072     * (e.g. <code>"3.1415"</code>, <code>"0xa413"</code>, etc.).
073     * @param feedback 
074     * @return A new proxy for this resource, whose properties are specified by feedback.
075     * @throws WvcmException
076     */
077    CcVobResource doApplyAttribute(ApplyAttributeFlag[] flags, String comment, 
078            String attributeName, String attributeValue, Feedback feedback)
079    throws WvcmException;
080    
081    /**
082     * Remove the specified attribute from this VOB resource.
083     * @param comment Comment (if any) to be used for operation.  Empty string if none.
084     * @param attributeName Name of the attribute to be removed from this resource
085     * @param feedback 
086     * @return A new proxy for this resource, whose properties are specified by feedback.
087     * @throws WvcmException
088     */
089    CcVobResource doRemoveAttribute(String comment,  String attributeName, Feedback feedback)
090    throws WvcmException;
091    
092    /**
093     * Apply the specified rolemap to this VOB resource.
094     * @param comment Comment (if any) to be used for operation.  Empty string if none.
095     * @param rolemap The name of the rolemap to be applied to this resource.
096     * @throws WvcmException
097     */
098    void doApplyRolemap(String comment, String rolemap)
099    throws WvcmException;
100    
101    /**
102     * <p>
103     * Request for local mastership of this VOB resource.
104     * </p>
105     * <p>
106     * Note: this operation is only supported for CcBranch and CcBranchType resources.
107     * </p>
108     * @param flags array of flags which specify the behavior of the operation.
109     * @param comment Comment (if any) to be used for operation.  Empty string if none.
110     * @param feedback list of properties to fetch on this resource.
111     * @return new proxy with the requested properties available.
112     * @throws WvcmException
113     */
114    CcVobResource 
115    doRequestForMastership(RequestForMastershipFlag[] flags, String comment, Feedback feedback) 
116        throws WvcmException;
117
118    /** The VOB in which this VOB resource resides. */
119    PropertyName<CcVob> VOB =
120        new PropertyName<CcVob>(PROPERTY_NAMESPACE, "vob");
121
122    /**
123     * Get the value of this proxy's {@link #VOB} property.
124     * @return This resource's VOB. Will never be null.
125     * @throws WvcmException
126     */
127    public CcVob getVob() throws WvcmException;
128
129    /** List of attributes attached to this resource. */
130    public static final PropertyName<List<CcAttribute>> ATTRIBUTE_LIST =
131        new PropertyName<List<CcAttribute>>(PROPERTY_NAMESPACE, "attribute-list");
132    
133    /**
134     *  Get the value of this proxy's {@link #ATTRIBUTE_LIST} property.
135     *  @return List of CcAttribute proxies applied to this resource.  Empty list if none.
136     *  @throws WvcmException if this proxy doesn't define a value for this property.
137     */
138    public List<CcAttribute> getAttributeList() throws WvcmException;
139    
140    /** Replica in which this resource resides. */
141    public static final PropertyName<CcReplica> CURRENT_REPLICA =
142        new PropertyName<CcReplica>(PROPERTY_NAMESPACE, "current-replica");
143    
144    /**
145     * Returns the value of this proxy's {@link #CURRENT_REPLICA} property.
146     * 
147     * @return Replica in which the resource resides as a CcReplica instance.
148     * @throws WvcmException
149     *             if this proxy doesn't define a value for this property.
150     */
151    public CcReplica getCurrentReplica() throws WvcmException;
152
153    /** List of hyperlink resources attached to this resource. */
154    public static final PropertyName<ResourceList<CcHyperlink>> HYPERLINK_LIST =
155        new PropertyName<ResourceList<CcHyperlink>>(PROPERTY_NAMESPACE, "hyperlink-list");
156
157    /**
158     *  Get the value of this proxy's {@link #HYPERLINK_LIST} property.
159     *  @return List of CcHyperlink proxies applied to this resource.  Empty list if none.
160     *  @throws WvcmException if this proxy doesn't define a value for this property.
161     */
162    public ResourceList<CcHyperlink> getHyperlinkList() throws WvcmException;
163
164    /** CcLockInfo object contains the supported lock properties. */
165    public static final PropertyName<CcLockInfo> LOCK_INFO =
166        new PropertyName<CcLockInfo>(PROPERTY_NAMESPACE, "lock-info");
167
168    /**
169     * Returns the value of this proxy's {@link #LOCK_INFO} property.
170     * 
171     * @return the CcLockInfo object for the resource.
172     *         <code>null</code> if the object is not locked.
173     * @throws WvcmException
174     *             if this proxy doesn't define a value for this property.
175     */
176    public CcLockInfo getLockInfo() throws WvcmException;
177
178    /**
179     * Sets (or replaces) the lock on this proxy according to the
180     * {@link #LOCK_INFO} property.
181     * @param lockInfo lock information for the new lock, or <code>null</code>
182     *        to unlock the proxy.
183     */
184    public void setLockInfo(CcLockInfo lockInfo);
185
186    
187    /**
188     * Does this object have local mastership? If true, this object is mastered
189     * in the same replica as its VOB.  Otherwise, it is mastered at a replica
190     * remote from that of its VOB.
191     */
192    PropertyName<Boolean> HAS_LOCAL_MASTERSHIP =
193        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-local-mastership"); //$NON-NLS-1$
194
195    /**
196     * Get the value of this proxy's {@link #HAS_LOCAL_MASTERSHIP} property.
197     * @return true if this object has local mastership, else false
198     * @throws WvcmException if this proxy doesn't define a value for this property.
199     */
200    boolean getHasLocalMastership() throws WvcmException;
201
202    
203    /** Replica which has mastery of this resource. */
204    public static final PropertyName<CcReplica> CC_MASTER_REPLICA =
205        new PropertyName<CcReplica>(PROPERTY_NAMESPACE, "cc-master-replica");
206    
207    /**
208     * Returns the value of this proxy's {@link #CC_MASTER_REPLICA} property.
209     * 
210     * @return Replica in which the resource is mastered as a CcReplica instance.
211     *         null if resource cannot be mastered.
212     * @throws WvcmException
213     *             if this proxy doesn't define a value for this property.
214     */
215   public CcReplica getMasterReplica() throws WvcmException;
216 
217   /**
218    * <p>
219    * The permissions applied to this resource.
220    * </p>
221    */
222   PropertyName<CcPermissions> PERMISSIONS =
223       new PropertyName<CcPermissions>(PROPERTY_NAMESPACE, "cc-permissions");
224   
225   /**
226    * Get the value of this resource's {@link #PERMISSIONS} property.
227    * 
228    * @return A permissions object from which specific permissions 
229    * information can be extracted.
230    * @throws WvcmException
231    */
232   CcPermissions getPermissions() throws WvcmException;
233   
234   /**
235    * Set the value of this proxy's {@link #PERMISSIONS} property.
236    * 
237    * @param permissions  A permissions object.  Use the one returned
238    *                     by getPermissions and modify it.
239    * @throws WvcmException
240    *         if this proxy doesn't define a value for this property.
241    */
242   void setPermissions(CcPermissions permissions) throws WvcmException;
243   
244   /**
245    * Rolemap used to define the ACLs for this resource. 
246    */
247   PropertyName<CcRolemap> ROLEMAP =
248       new PropertyName<CcRolemap>(PROPERTY_NAMESPACE, "rolemap");
249
250   /**
251    * Get the value of this resource's {@link #ROLEMAP} property.
252    * 
253    * @return Rolemap used to define the ACLs for this resource.
254    * <code>null</code> if the resource has no rolemap.
255    * @throws WvcmException
256    */
257   CcRolemap getRolemap() throws WvcmException;
258   
259   /**
260    * List of access control entries which make up the effective ACLs for this resource.
261    */
262   PropertyName<List<CcAccessControlEntry>> EFFECTIVE_ACL =
263       new PropertyName<List<CcAccessControlEntry>>(PROPERTY_NAMESPACE, "effective-acl");
264
265   /**
266    * Get the value of this resource's {@link #EFFECTIVE_ACL} property.
267    * 
268    * @return List of access control entries which make up the effective ACLs for this resource.
269    * <code>null</code> if the resource does not support ACLs.
270    * @throws WvcmException
271    */
272   List<CcAccessControlEntry> getEffectiveAcl() throws WvcmException;
273
274   /**
275    * A permission string describing the operations the current user may performe on this
276    * resource.
277    */
278   PropertyName<String> MY_EFFECTIVE_ACCESS = 
279           new PropertyName<String>(PROPERTY_NAMESPACE, "my-effective-access");
280   
281   
282   /**
283    * Get the value of this resource's {@link #MY_EFFECTIVE_ACCESS} property.
284    * 
285    * @return A permission string describing the operations the current user may performe on this
286    * resource.
287    * <code>null</code> if the resource does not support ACLs.
288    * @throws WvcmException
289    */
290   String getMyEffectiveAccess() throws WvcmException;
291   
292   /**
293    * List of access control entries, affecting the current user, which make up the effective ACLs
294    * for this resource.
295    */
296   PropertyName<List<CcAccessControlEntry>> MY_EFFECTIVE_ACL =
297           new PropertyName<List<CcAccessControlEntry>>(PROPERTY_NAMESPACE, "my-effective-acl");
298
299   /**
300    * Get the value of this resource's {@link #MY_EFFECTIVE_ACL} property.
301    * 
302    * @return List of access control entries, affecting the current user, which make up the effective
303    * ACLs for this resource.
304    * <code>null</code> if the resource does not support ACLs.
305    * @throws WvcmException
306    */
307   List<CcAccessControlEntry> getMyEffectiveAcl() throws WvcmException;
308}