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 }