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 * (C) 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
014package com.ibm.rational.wvcm.stp;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.WvcmException;
019
020import com.ibm.rational.wvcm.stp.cq.CqProvider;
021import com.ibm.rational.wvcm.stp.cq.CqQueryFolder;
022import com.ibm.rational.wvcm.stpex.StpExEnumeration;
023import 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 */
052public 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}