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    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import java.util.List;
019    
020    import javax.wvcm.Feedback;
021    import javax.wvcm.ResourceList;
022    import javax.wvcm.WvcmException;
023    import javax.wvcm.PropertyNameList.PropertyName;
024    
025    import com.ibm.rational.wvcm.stp.ccex.CcExFileList.RequestForMastershipFlag;
026    import 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     */
034    public 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    }