001    /*
002     * file StpAccessControlEntry.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.StpAccessControlEntry
008     *
009     * © Copyright IBM Corporation 2008.  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;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import javax.wvcm.WvcmException;
019    
020    import com.ibm.rational.wvcm.stp.cq.CqProvider;
021    import com.ibm.rational.wvcm.stp.cq.CqQueryFolder;
022    import com.ibm.rational.wvcm.stpex.StpExEnumeration;
023    import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
024    
025    /**
026     * The interface for an entry in a resource's access control list. Each access
027     * control entry denotes <i>access rights</i> to a specific resource granted to
028     * one or more <i>principals</i> (denoted by a group, user, or role).
029     * <p>
030     * In addition, each StpAccessControlEntry instance returned by this API
031     * specifies whether the entry represents an access right applied directly to
032     * the resource or an access right derived from access rights applied to one or
033     * more related resources. In most cases, the resource to which the effective
034     * access right is actually applied is also included in the
035     * StpAccessControlEntry returned from the API.
036     * <p>
037     * To add an access control entry to a resource an instance of
038     * StpAccessControlEntry is required. It can be constructed using
039     * {@link StpProvider#buildAccessControlEntry(StpPrincipal, com.ibm.rational.wvcm.stp.StpAccessControlEntry.AccessRight[])}
040     * if the access right is known a priori or by requesting the
041     * {@link CqQueryFolder#POSSIBLE_ACCESS_RIGHTS} property and selecting one of
042     * those. When adding an access control entry to a resource, only the access
043     * rights and principal fields of the StpAccessControlEntry object are
044     * significant.
045     * <p>
046     * Resources that may have access control lists applied them implement the 
047     * {@link StpAccessControlledResource} interface.
048     * <p>
049     * Resources that represent entities to which access rights may be granted 
050     * implement the {@link StpPrincipal} interface.
051     */
052    public interface StpAccessControlEntry
053    {
054        /**
055         * @return <b>true</b> iff this access control entry grants reading of the
056         *         controlled resource to the principal
057         */
058        boolean allowsRead();
059    
060        /**
061         * @return <b>true</b> iff this access control entry allows writing of the
062         *         controlled resource by the principal
063         */
064        boolean allowsWrite();
065    
066        /**
067         * @return The group, user, or role that is granted the access rights of
068         *         this entry to the controlled resource; <b>null</b> if no
069         *         principal has been associated with this permission.
070         */
071        StpPrincipal getPrincipal();
072    
073        /**
074         * @return The access rights granted by this entry to the principal on the
075         *         controlled resource. Will never be <b>null</b>.
076         */
077        AccessRight[] getAccessRights();
078    
079        /**
080         * An enumeration of the possible access rights that can be applied to a
081         * controlled resource. Not all resources will support all access rights.
082         */
083        public enum AccessRight implements StpExEnumeration
084        {
085            /** Principal has no access to the controlled resource */
086            NO_ACCESS("no-access"),
087            /** Principal can only read the controlled resource */
088            READ_ONLY("read-only"),
089            /** Principal can read and write the controlled resource */
090            READ_WRITE("read-write"),
091            /** Principal has limited read access to the controlled resource */
092            READ_LIMITED("read-limited"),
093            /** Principal can change access rights to the controlled resource */
094            CHANGE_PERMISSION("change-permission");
095    
096            /** The name of the access right for display purposes */
097            public String toString()
098            {
099                return m_name;
100            }
101    
102            private AccessRight(String name)
103            {
104                m_name = name;
105            }
106    
107            private String m_name;
108        };
109    
110        /**
111         * @return The resource whose access is controlled by this access control
112         *         entry; will be null if no resource has been associated with this
113         *         StpAccessControlEntry instance.
114         */
115        StpAccessControlledResource getControlledResource();
116    
117        /**
118         * Assigns a new value for the principal of this access control entry.
119         * 
120         * @param principal An StpResource proxy specifying the group, user, or role
121         *            identifying the principals granted access rights by this
122         *            entry. Not all resources accept all types of principals.
123         */
124        void setPrincipal(StpPrincipal principal);
125    
126        /**
127         * Defines a new value for the access rights granted by this entry.
128         * 
129         * @param accessRights An array of access right instances specifying the
130         *            access rights granted by this entry; must not be <b>null</b>
131         *            or empty.
132         */
133        void setAccessRights(AccessRight... accessRights);
134    
135        /**
136         * Assigns a new value to the controlled resource of this entry.
137         * 
138         * @param controlledResource An StpResource proxy specifying the resource to
139         *            be controlled by this entry. Not all resource types can be
140         *            controlled by an access control list.
141         */
142        void setControlledResource(StpAccessControlledResource controlledResource);
143    
144        /**
145         * An enumeration of the type of permission being reported
146         */
147        public enum EntryType implements StpExEnumeration
148        {
149            /**
150             * An entry applied explicitly to the controlled resource.
151             */
152            APPLIED,
153    
154            /**
155             * An effective entry derived from entries directly applied
156             * to one or more resources associated with the controlled resources.
157             */
158            EFFECTIVE;
159        };
160    
161        /**
162         * @return The type of access control entry being reported by this instance.
163         */
164        EntryType getEntryType();
165    
166        /**
167         * @return The resource to which this access control entry was actually
168         *         applied, if known; <b>null</b> otherwise.
169         */
170        StpAccessControlledResource getAppliedResource();
171    }