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*/
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.PropertyNameList.PropertyName;
022import javax.wvcm.Resource;
023import javax.wvcm.ResourceList;
024import 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 */
038public 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}