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 - 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*/
013package com.ibm.rational.wvcm.stp.cc;
014
015import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
016
017import java.util.List;
018import java.util.Map;
019
020import javax.wvcm.Feedback;
021import javax.wvcm.Resource;
022import javax.wvcm.PropertyNameList.PropertyName;
023import 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
042public 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}