001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.security.jacc;
023:
024: import java.security.Permission;
025: import java.security.PermissionCollection;
026:
027: /** The methods of this interface are used by containers to
028: create policy statements in a Policy provider.
029: An object that implements the PolicyConfiguration interface provides the
030: policy statement configuration interface for a corresponding policy context
031: within the corresponding Policy provider.
032:
033: The life cycle of a policy context is defined by three states; "open",
034: "inService", and "deleted". A policy context is in one of these three states.
035:
036: A policy context in the "open" state is in the process of being
037: configured, and may be operated on by any of the methods of the
038: PolicyConfiguration interface. A policy context in the "open" state
039: must not be assimilated at <code>Policy.refresh</code> into the policy
040: statements used by the Policy provider in performing its access decisions.
041: In order for the policy statements of a policy context to be assimilated
042: by the associated provider, the policy context must be in the
043: "inService" state. A policy context in the "open" state is transitioned to
044: the "inService" state by calling the commit method.
045:
046: A policy context in the "inService" state is available for assimilation
047: into the policy statements being used to perform access decisions by the
048: associated Policy provider. Providers assimilate policy contexts containing
049: policy statements when the refresh method of the provider is called. When
050: a provider's refresh method is called, it must assimilate only those policy
051: contexts whose state is "inService" and it must ensure that the policy
052: statements put into service for each policy context are only those defined
053: in the context at the time of the call to refresh. A policy context in the
054: "inService" state is not available for additional configuration and may be
055: returned to the "open" state by calling the getPolicyConfiguration method
056: of the PolicyConfigurationFactory.
057:
058: A policy context in the "deleted" state is neither available for
059: configuration, nor is it available for assimilation into the Provider. A
060: policy context whose state is "deleted" may be reclaimed for subsequent
061: processing by calling the getPolicyConfiguration method of the associated
062: PolicyConfigurationFactory. A "deleted" policy context
063: is transitioned to the "open" state when it it returned as a result of
064: a call to getPolicyConfiguration.
065:
066: The following table captures the correspondence between the policy context
067: life cycle and the methods of the PolicyConfiguration interface.
068: The rightmost 3 columns of the table correspond to the
069: PolicyConfiguration state identified at the head of the column.
070: The values in the cells of these columns indicate
071: the next state resulting from a call to the method
072: identifed in the leftmost column of the corresponding row, or that
073: calling the method is unsupported in the state
074: represented by the column (in which case the state will remain unchanged).
075:
076: <table border="1" width="90%" nosave="" align="center">
077: <caption>PolicyConfiguration State Table</caption>
078: <tr>
079: <th valign="middle" rowspan="2" colspan="1" align="center">
080: <font size="-2">Method</font></th>
081: <th valign="top" rowspan="1" colspan="3" align="center">
082: <font size="-2">Current State to Next State</font></th>
083: </tr>
084:
085: <tr>
086: <th width="25%" align="center"><font size="-2">deleted</font></th>
087: <th width="12%" align="center"><font size="-2">open</font></th>
088: <th width="25%" align="center"><font size="-2">inService</font></th>
089: </tr>
090: <tr>
091: <td width="28%"><font size="-2">addToExcludedPolicy</font></td>
092:
093: <td width="25%" align="center">
094: <font size="-2">Unsupported Operation</font></td>
095: <td width="12%" align="center">
096: <font size="-2">open</font></td>
097: <td width="25%" align="center">
098: <font size="-2">Unsupported Operation</font></td>
099: </tr>
100:
101: <tr>
102: <td width="28%"><font size="-2">addToRole</font></td>
103: <td width="25%" align="center">
104: <font size="-2">Unsupported Operation</font></td>
105: <td width="12%" align="center">
106: <font size="-2">open</font></td>
107: <td width="25%" align="center">
108:
109: <font size="-2">Unsupported Operation</font></td>
110: </tr>
111: <tr>
112: <td width="28%"><font size="-2">addToUncheckedPolicy</font></td>
113: <td width="25%" align="center">
114: <font size="-2">Unsupported Operation</font></td>
115: <td width="12%" align="center">
116:
117: <font size="-2">open</font></td>
118: <td width="25%" align="center">
119: <font size="-2">Unsupported Operation</font></td>
120: </tr>
121: <tr>
122: <td width="28%"><font size="-2">commit</font></td>
123: <td width="25%" align="center">
124:
125: <font size="-2">Unsupported Operation</font></td>
126: <td width="12%" align="center">
127: <font size="-2">inService</font></td>
128: <td width="25%" align="center">
129: <font size="-2">inService</font></td>
130: </tr>
131: <tr>
132:
133: <td width="28%"><font size="-2">delete</font></td>
134: <td width="25%" align="center">
135: <font size="-2">deleted</font></td>
136: <td width="12%" align="center">
137: <font size="-2">deleted</font></td>
138: <td width="25%" align="center">
139: <font size="-2">deleted</font></td>
140:
141: </tr>
142: <tr>
143: <td width="28%"><font size="-2">getContextID</font></td>
144: <td width="25%" align="center">
145: <font size="-2">deleted</font></td>
146: <td width="12%" align="center">
147: <font size="-2">open</font></td>
148:
149: <td width="25%" align="center">
150: <font size="-2">inService</font></td>
151: </tr>
152: <tr>
153: <td width="28%"><font size="-2">inService</font></td>
154: <td width="25%" align="center">
155: <font size="-2">deleted</font></td>
156:
157: <td width="12%" align="center">
158: <font size="-2">open</font></td>
159: <td width="25%" align="center">
160: <font size="-2">inService</font></td>
161: </tr>
162: <tr>
163: <td width="28%"><font size="-2">linkConfiguration</font></td>
164:
165: <td width="25%" align="center">
166: <font size="-2">Unsupported Operation</font></td>
167: <td width="12%" align="center">
168: <font size="-2">open</font></td>
169: <td width="25%" align="center">
170: <font size="-2">Unsupported Operation</font></td>
171: </tr>
172:
173: <tr>
174: <td width="28%"><font size="-2">removeExcludedPolicy</font></td>
175: <td width="25%" align="center">
176: <font size="-2">Unsupported Operation</font></td>
177: <td width="12%" align="center"><font size="-2">
178: open</font></td>
179: <td width="25%" align="center">
180:
181: <font size="-2">Unsupported Operation</font></td>
182: </tr>
183: <tr>
184: <td width="28%"><font size="-2">removeRole</font></td>
185: <td width="25%" align="center">
186: <font size="-2">Unsupported Operation</font></td>
187: <td width="12%" align="center">
188:
189: <font size="-2">open</font></td>
190: <td width="25%" align="center">
191: <font size="-2">Unsupported Operation</font></td>
192: </tr>
193: <tr>
194: <td width="28%"><font size="-2">removeUncheckedPolicy</font></td>
195: <td width="25%" align="center">
196:
197: <font size="-2">Unsupported Operation</font></td>
198: <td width="12%" align="center">
199: <font size="-2">open</font></td>
200: <td width="25%" align="center">
201: <font size="-2">Unsupported Operation</font></td>
202: </tr>
203: </table>
204:
205: For a provider implementation to be compatible with multi-threaded
206: environments, it may be necessary to synchronize the refresh method of
207: the provider with the methods of its PolicyConfiguration interface and
208: with the getPolicyConfiguration and inService methods of its
209: PolicyConfigurationFactory.
210:
211: * @see http://java.sun.com/j2ee/1.4/docs/api/
212: *
213: * @author Scott.Stark@jboss.org
214: * @author Ron Monzillo, Gary Ellison (javadoc)
215: * @version $Revision: 57196 $
216: */
217: public interface PolicyConfiguration {
218: /** Adds a single excluded permission to the PolicyConfiguration.
219: * @param permission
220: * @throws PolicyContextException
221: */
222: public void addToExcludedPolicy(Permission permission)
223: throws PolicyContextException;
224:
225: /** Adds a collection of excluded permissions to the PolicyConfiguration
226: *
227: * @param permissions
228: * @throws PolicyContextException
229: */
230: public void addToExcludedPolicy(PermissionCollection permissions)
231: throws PolicyContextException;
232:
233: /** Add a single permission to a named role in the PolicyConfiguration. If
234: * the named Role does not exist in the PolicyConfiguration, it is created
235: * as a result of the call to this function.
236: *
237: * @param roleName
238: * @param permission
239: * @throws PolicyContextException
240: */
241: public void addToRole(String roleName, Permission permission)
242: throws PolicyContextException;
243:
244: /** Add permissions to a named role in the PolicyConfiguration. If
245: * the named Role does not exist in the PolicyConfiguration, it is created
246: * as a result of the call to this function.
247: * @param roleName
248: * @param permissions
249: * @throws PolicyContextException
250: */
251: public void addToRole(String roleName,
252: PermissionCollection permissions)
253: throws PolicyContextException;
254:
255: /** Add a single unchecked permission to the PolicyConfiguration.
256: *
257: * @param permission
258: * @throws PolicyContextException
259: */
260: public void addToUncheckedPolicy(Permission permission)
261: throws PolicyContextException;
262:
263: /** Add unchecked permissions to the PolicyConfiguration.
264: *
265: * @param permissions
266: * @throws PolicyContextException
267: */
268: public void addToUncheckedPolicy(PermissionCollection permissions)
269: throws PolicyContextException;
270:
271: /** This method is used to set to "inService" the state of the policy context
272: * whose interface is this PolicyConfiguration Object. Only those policy
273: * contexts whose state is "inService" will be included in the policy
274: * contexts processed by the Policy.refresh method. A policy context whose
275: * state is "inService" may be returned to the "open" state by calling the
276: * getPolicyConfiguration method of the PolicyConfiguration factory with the
277: * policy context identifier of the policy context.
278: *
279: * When the state of a policy context is "inService", calling any method other
280: * than commit, delete, getContextID, or inService on its PolicyConfiguration
281: * Object will cause an UnsupportedOperationException to be thrown.
282: *
283: * @throws SecurityException - when the caller does not have a
284: * SecurityPermission("setPolicy") permission.
285: * @throws UnsupportedOperationException - if the state of the policy context
286: * whose interface is this PolicyConfiguration Object is "deleted" when this
287: * method is called.
288: * @throws PolicyContextException - if the implementation throws a checked
289: * exception that has not been accounted for by the commit method signature.
290: */
291: public void commit() throws PolicyContextException;
292:
293: /** Causes all policy statements to be deleted from this PolicyConfiguration
294: * and sets its internal state such that calling any method, other than
295: * delete, getContextID, or inService on the PolicyConfiguration will be
296: * rejected and cause an UnsupportedOperationException to be thrown.
297: *
298: * This operation has no affect on any linked PolicyConfigurations other than
299: * removing any links involving the deleted PolicyConfiguration.
300: *
301: * @throws SecurityException - when the caller does not have a
302: * SecurityPermission("setPolicy") permission.
303: * @throws PolicyContextException
304: */
305: public void delete() throws PolicyContextException;
306:
307: /** This method returns this object's policy context identifier.
308: *
309: * @return this object's policy context identifier.
310: *
311: * @throws SecurityException - when the caller does not have a
312: * SecurityPermission("setPolicy") permission.
313: * @throws PolicyContextException
314: */
315: public String getContextID() throws PolicyContextException;
316:
317: /** This method is used to determine if the policy context whose interface is
318: * this PolicyConfiguration Object is in the "inService" state.
319: *
320: * @return true if the state of the associated policy context is "inService",
321: * false otherwise.
322: * @throws PolicyContextException
323: */
324: public boolean inService() throws PolicyContextException;
325:
326: /** Creates a relationship between this configuration and another such that
327: * they share the same principal-to-role mappings. PolicyConfigurations are
328: * linked to apply a common principal-to-role mapping to multiple seperately
329: * manageable PolicyConfigurations, as is required when an application is
330: * composed of multiple modules.
331: *
332: * @param link - a reference to a different PolicyConfiguration than this
333: * PolicyConfiguration. The relationship formed by this method is symetric,
334: * transitive and idempotent. If the argument PolicyConfiguration does not
335: * have a different Policy context identifier than this PolicyConfiguration
336: * no relationship is formed, and an IllegalArgumentException is thrown.
337: *
338: * @throws SecurityException - when the caller does not have a
339: * SecurityPermission("setPolicy") permission.
340: * @throws IllegalArgumentException - if called with an argument
341: * PolicyConfiguration whose Policy context is equivalent to that of this
342: * PolicyConfiguration.
343: * @throws PolicyContextException
344: */
345: public void linkConfiguration(PolicyConfiguration link)
346: throws PolicyContextException;
347:
348: /** Used to remove any excluded policy statements from this PolicyConfiguration
349: *
350: * @throws SecurityException - when the caller does not have a
351: * SecurityPermission("setPolicy") permission.
352: * @throws UnsupportedOperationException - if the state of the policy context
353: * whose interface is this PolicyConfiguration Object is "deleted" or
354: * "inService" when this method is called.
355: * @throws PolicyContextException
356: */
357: public void removeExcludedPolicy() throws PolicyContextException;
358:
359: /** Used to remove a role and all its permissions from this PolicyConfiguration.
360: *
361: * @param roleName - the name of the Role to remove from this PolicyConfiguration.
362: *
363: * @throws SecurityException - when the caller does not have a
364: * SecurityPermission("setPolicy") permission.
365: * @throws UnsupportedOperationException - if the state of the policy context
366: * whose interface is this PolicyConfiguration Object is "deleted" or
367: * "inService" when this method is called.
368: * @throws PolicyContextException
369: */
370: public void removeRole(String roleName)
371: throws PolicyContextException;
372:
373: /** Used to remove any unchecked policy statements from this PolicyConfiguration.
374: *
375: * @throws SecurityException - when the caller does not have a
376: * SecurityPermission("setPolicy") permission.
377: * @throws UnsupportedOperationException - if the state of the policy context
378: * whose interface is this PolicyConfiguration Object is "deleted" or
379: * "inService" when this method is called.
380: * @throws PolicyContextException
381: */
382: public void removeUncheckedPolicy() throws PolicyContextException;
383: }
|