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 }