001    /*
002    * file CcPolicy.java
003    *
004    * Licensed Materials - Property of IBM
005    * Restricted Materials of IBM
006    * 
007    * com.ibm.rational.wvcm.stp.cc.CcPolicy
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.PropertyNameList.PropertyName;
022    import javax.wvcm.Resource;
023    import javax.wvcm.ResourceList;
024    import javax.wvcm.WvcmException;
025    
026    /**
027     * <p>A proxy for a ClearCase policy.
028     * 
029     * <p>A policy has an Access Control List (ACL) for each controlled VOB metatype (such as UCM project, 
030     * branch type, element). The entries in a policy list a principal and its 
031     * granted permissions. Principals in a policy are usually roles, with the name of the role defined 
032     * by the ClearCase administrator. You can also put in specific users or groups as well, but we recommend 
033     * putting them into the rolemaps implementing the policy.
034     * 
035     * <p>Each ACL-enabled VOB has a default policy named <em>DefaultPolicy</em>.  This default 
036     * policy grants the VOB owner full access; nobody else has any access.
037     */
038    public interface CcPolicy extends CcTypeBase {
039    
040        /**
041         * Map of names of VOB object proxy types to lists of access control entries which make up the 
042         * permissions template this policy will apply to a rolemap.
043         */
044        PropertyName<Map<String, List<CcAccessControlEntry>>> ACL_MAP =
045            new PropertyName<Map<String, List<CcAccessControlEntry>>>(PROPERTY_NAMESPACE, "policy-acl-map");
046    
047        /**
048         * Get the value of this resource's {@link #ACL_MAP} property.
049         * 
050         * @return Map of names of VOB object proxy types to lists of access control entries 
051         * which make up the effective ACLs that this policy would generate when combined
052         * with a rolemap and applied to VOB objects.
053         * @throws WvcmException
054         */
055        Map<String, List<CcAccessControlEntry>> getAclMap() throws WvcmException;
056    
057        /**
058         * List of rolemaps which implement this policy.
059         */
060        PropertyName<ResourceList<CcRolemap>> ROLEMAP_LIST =
061                new PropertyName<ResourceList<CcRolemap>>(PROPERTY_NAMESPACE, "policy-rolemap-list");
062        
063        /**
064         * Get the value of this resource's {@link #ROLEMAP_LIST} property.
065         * 
066         * @return List of rolemaps which implement this policy.
067         * @throws WvcmException
068         */
069        ResourceList<CcRolemap> getRolemapList() throws WvcmException;
070        
071        /**
072         * Set the value of this proxy's {@link #ACL_MAP} property.
073         * This property may only be set for use with the 
074         * {@link #doCreateCcPolicy(com.ibm.rational.wvcm.stp.cc.CcTypeBase.TypeCreateFlag[], Feedback)}
075         * call.
076         * It cannot be written using {@link Resource#doWriteProperties(Feedback)}.
077         * @throws WvcmException
078         *         if this proxy doesn't define a value for this property.
079         */
080        void setAclMap(Map<String, List<CcAccessControlEntry>> aclMap) throws WvcmException;
081    
082        /**
083         * <p>
084         * Create a new policy at the location specified by this proxy. The
085         * location should be an object name selector specifying the policy's name
086         * and the repository (VOB) in which to create it.
087         * </p>
088         * <p>
089         * Set the optional {@link #ACL_MAP} property to specify the principals and access
090         * allowed for the proxy types in this policy.
091         * If this property is not set, the policy will not provide any permissions.
092         * 
093         * </p>
094         * You may optionally set the following additional properties prior to
095         * calling this method:
096         * <bl>
097         * <li> {@link #COMMENT} </li>
098         * <li> {@link CcTypeBase#SCOPE} <em>(Not yet supported.)</em>
099         * </bl>
100         * @param flags Resource-specific creation flags. <em>(The ACQUIRE flag is not yet supported.)</em>
101         */
102        public CcPolicy doCreateCcPolicy(TypeCreateFlag[] flags, Feedback feedback) throws WvcmException;
103        
104        /**
105         * <p>
106         * Modify an existing policy at the location specified by this proxy. The
107         * location should be an object name selector specifying the policy's name
108         * and the repository (VOB) in which to create it.
109         * </p>
110         * <p>
111         * Set the optional {@link #ACL_MAP} property to modify the principals and access
112         * allowed for the proxy types in this policy. If not specified,
113         * the existing map will not be changed.
114         * 
115         * </p>
116         * You may optionally set the following additional properties prior to
117         * calling this method:
118         * <bl>
119         * <li> {@link #COMMENT} Provides a comment for the policy modification, 
120         * without overriding the creation comment.</li>
121         * </bl>
122         * @param flags Resource-specific creation flags. <em>(The ACQUIRE flag is not yet supported.)</em>
123         */
124        public CcPolicy doModifyCcPolicy(TypeCreateFlag[] flags, Feedback feedback) throws WvcmException;
125    }