001    /*
002    * file CcRolemap.java
003    *
004    * Licensed Materials - Property of IBM
005    * Restricted Materials of IBM
006    * 
007    * com.ibm.rational.wvcm.stp.cc.CcRolemap
008    *
009    * (C) Copyright IBM Corporation 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    package com.ibm.rational.wvcm.stp.cc;
014    
015    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
016    
017    import java.util.List;
018    import java.util.Map;
019    
020    import javax.wvcm.Feedback;
021    import javax.wvcm.Resource;
022    import javax.wvcm.PropertyNameList.PropertyName;
023    import javax.wvcm.WvcmException;
024    
025    /**
026     * <p>A proxy for a ClearCase rolemap.
027     * 
028     * <p>A rolemap specifies the principals (users, groups, etc) that take on roles listed in a 
029     * policy.  In combination with a policy, it defines the access controls for one or more VOB objects. 
030     * 
031     * <p>The intention is that a small number of policies can be defined that determine ‘how’ 
032     * permissions are applied to objects. Defining a number of rolemaps for each policy 
033     * describes ‘who’ takes on the roles in the policy. By splitting the ‘how’ and the ‘who’, 
034     * policies can be reused multiple times to reduce the complexity of security administration.
035     * 
036     * Each VOB with access control lists (ACLs) enables has a default rolemap named <em>DefaultRolemap</em>.  
037     * This default rolemap is empty. The default rolemap controls all objects in the VOB until new objects are 
038     * created with a reference to some other rolemap, or until an existing object is reprotected 
039     * to use a new rolemap.
040     */
041    
042    public interface CcRolemap extends CcTypeBase {
043        
044        /**
045         * Map of names of VOB object proxy types to lists of access control entries which make up the 
046         * effective ACLs that this rolemap would generate when applied to VOB objects.
047         */
048        PropertyName<Map<String, List<CcAccessControlEntry>>> ALL_EFFECTIVE_ACL =
049            new PropertyName<Map<String, List<CcAccessControlEntry>>>(PROPERTY_NAMESPACE, "rolemap-all-eacl");
050    
051        /**
052         * Get the value of this resource's {@link #ALL_EFFECTIVE_ACL} property.
053         * 
054         * @return Map of names of VOB object proxy types to lists of access control entries 
055         * which make up the effective ACLs that this rolemap would generate when applied 
056         * to VOB objects.
057         * <code>null</code> if the resource does not support ACLs.
058         * @throws WvcmException
059         */
060        Map<String, List<CcAccessControlEntry>> getAllEffectiveAcl() throws WvcmException;
061      
062        /**
063         * Is this rolemap in use? <code>true</code> if the rolemap
064         * is currently applied to one or more objects, <code>false</code> otherwise.
065         */
066        PropertyName<Boolean> IS_IN_USE = new PropertyName<Boolean>(PROPERTY_NAMESPACE, "rolemap-in-use");
067        
068        /**
069         * Get the value of this resource's {@link #IS_IN_USE} property.
070         * 
071         * @return <code>true</code> if the rolemap is currently applied to one or 
072         * more objects, <code>false</code> otherwise.
073         * @throws WvcmException
074         */
075        boolean getIsInUse() throws WvcmException;
076        
077        /**
078         * Policy used to define the ACLs for this rolemap.
079         */
080        PropertyName<CcPolicy> POLICY =
081            new PropertyName<CcPolicy>(PROPERTY_NAMESPACE, "rolemap-policy");
082    
083        /**
084         * Get the value of this resource's {@link #POLICY} property.
085         * 
086         * @return Policy used to define the ACLs for this rolemap.
087         * @throws WvcmException
088         */
089        CcPolicy getPolicy() throws WvcmException;
090        
091        /**
092         * Set the value of this proxy's {@link #POLICY} property.
093         * This property may only be set for use with the 
094         * {@link #doCreateCcRolemap(com.ibm.rational.wvcm.stp.cc.CcTypeBase.TypeCreateFlag[], Feedback)}
095         * or {@link #doModifyCcRolemap(com.ibm.rational.wvcm.stp.cc.CcTypeBase.TypeCreateFlag[], Feedback)} 
096         * calls.  It cannot be written using {@link Resource#doWriteProperties(Feedback)}.
097         * @throws WvcmException
098         *         if this proxy doesn't define a value for this property.
099         */
100        void setPolicy(CcPolicy policy) throws WvcmException;
101      
102        /**
103         * List of role-to-principal bindings which define this rolemap
104         */
105        PropertyName<List<CcRolemapEntry>> ROLEMAP_ENTRIES =
106            new PropertyName<List<CcRolemapEntry>>(PROPERTY_NAMESPACE, "rolemap-entries");
107    
108        /**
109         * Get the value of this resource's {@link #ROLEMAP_ENTRIES} property.
110         * 
111         * @return List of role-to-principal bindings which define this rolemap
112         * @throws WvcmException
113         */
114        List<CcRolemapEntry> getRolemapEntries() throws WvcmException;
115    
116        /**
117         * Set the value of this proxy's {@link #ROLEMAP_ENTRIES} property.
118         * This property may only be set for use with the 
119         * {@link #doCreateCcRolemap(com.ibm.rational.wvcm.stp.cc.CcTypeBase.TypeCreateFlag[], Feedback)}
120         * or {@link #doModifyCcRolemap(com.ibm.rational.wvcm.stp.cc.CcTypeBase.TypeCreateFlag[], Feedback)} calls.  
121         * It cannot be written using {@link Resource#doWriteProperties(Feedback)}.
122         * @throws WvcmException
123         *         if this proxy doesn't define a value for this property.
124         */
125        void setRolemapEntries(List<CcRolemapEntry> rolemapEntries) throws WvcmException;
126            
127        /**
128         * <p>
129         * Create a new rolemap at the location specified by this proxy. The
130         * location should be an object name selector specifying the rolemap's name
131         * and the repository (VOB) in which to create it.
132         * </p>
133         * <p>
134         * Set the required {@link #POLICY} property to specify the policy
135         * with which the rolemap should be associated.
136         * </p>
137         * <p>
138         * Set the optional {@link #ROLEMAP_ENTRIES} property to specify the role-to-principal bindings for
139         * this rolemap.  If this property is not set, the rolemap will be created with an empty
140         * binding list.
141         * </p>
142         * You may optionally set the following additional properties prior to
143         * calling this method:
144         * <bl>
145         * <li> {@link #COMMENT} </li>
146         * <li> {@link CcTypeBase#SCOPE} <em>(Not yet supported.)</em>
147         * </bl>
148         * @param flags Resource-specific creation flags. <em>(The ACQUIRE flag is not yet supported.)</em>
149         */
150        public CcRolemap doCreateCcRolemap(TypeCreateFlag[] flags, Feedback feedback) throws WvcmException;
151    
152        /**
153         * <p>
154         * Modify an existing rolemap at the location specified by this proxy. The
155         * location should be an object name selector specifying the rolemap's name
156         * and the repository (VOB) in which it is defined.
157         * </p>
158         * <p>
159         * Set the optional {@link #POLICY} property to modify the policy
160         * with which the rolemap should be associated.  If not specified, 
161         * the existing policy will be left unchanged.
162         * </p>
163         * <p>
164         * Set the optional {@link #ROLEMAP_ENTRIES} property to specify the role-to-principal bindings for
165         * this rolemap.  If this property is not set, the existing rolemap entries
166         * will be left unchanged.
167         * </p>
168         * You may optionally set the following additional properties prior to
169         * calling this method:
170         * <bl>
171         * <li> {@link #COMMENT} Provides a comment for the rolemap modification, 
172         * without overriding the creation comment.</li>
173         * </bl>
174         * @param flags Resource-specific modification flags. <em>(The ACQUIRE flag is not yet supported.)</em>
175         */
176        public CcRolemap doModifyCcRolemap(TypeCreateFlag[] flags, Feedback feedback) throws WvcmException;
177    }