KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > security > jacc > PolicyConfiguration


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */

23
24 package javax.security.jacc;
25
26 import java.security.*;
27 import javax.security.jacc.PolicyContextException JavaDoc;
28
29 /**
30  * The methods of this interface are used by containers to
31  * create policy statements in a Policy provider.
32  * An object that implements the PolicyConfiguration interface provides the
33  * policy statement configuration interface for a corresponding policy context
34  * within the corresponding Policy provider.
35  * <P>
36  * The life cycle of a policy context
37  * is defined by three states; "open", "inService", and "deleted". A policy
38  * context is in one of these three states.
39  * <P>
40  * A policy context in the "open" state is in the process of being
41  * configured, and may be operated on by any of the methods of the
42  * PolicyConfiguration interface. A policy context in the "open" state
43  * must not be assimilated at <code>Policy.refresh</code> into the policy
44  * statements used by the Policy provider in performing its access decisions.
45  * In order for the policy statements of a policy context to be assimilated
46  * by the associated provider, the policy context must be in the
47  * "inService" state. A policy context in the "open" state is transitioned to
48  * the "inService" state by calling the commit method.
49  * <P>
50  * A policy context in the "inService" state is available for assimilation
51  * into the policy statements being used to perform access decisions by the
52  * associated Policy provider. Providers assimilate policy contexts containing
53  * policy statements when the refresh method of the provider is called. When
54  * a provider's refresh method is called, it must assimilate only those policy
55  * contexts whose state is "inService" and it must ensure that the policy
56  * statements put into service for each policy context are only those defined
57  * in the context at the time of the call to refresh. A policy context in the
58  * "inService" state is not available for additional configuration and may be
59  * returned to the "open" state by calling the getPolicyConfiguration method
60  * of the PolicyConfigurationFactory.
61  * <P>
62  * A policy context in the "deleted" state is neither available for
63  * configuration, nor is it available for assimilation into the Provider. A
64  * policy context whose state is "deleted" may be reclaimed for subsequent
65  * processing by calling the getPolicyConfiguration method of the associated
66  * PolicyConfigurationFactory. A "deleted" policy context
67  * is transitioned to the "open" state when it it returned as a result of
68  * a call to getPolicyConfiguration.
69  * <P>
70  * The following table captures the correspondence between the policy context
71  * life cycle and the methods of the PolicyConfiguration interface.
72  * The rightmost 3 columns of the table correspond to the
73  * PolicyConfiguration state identified at the head of the column.
74  * The values in the cells of these columns indicate
75  * the next state resulting from a call to the method
76  * identifed in the leftmost column of the corresponding row, or that
77  * calling the method is unsupported in the state
78  * represented by the column (in which case the state will remain unchanged).
79  *
80  * <br><br>
81  * <table border="1" width="90%" nosave="" align="center">
82  * <caption>PolicyConfiguration State Table</caption>
83  * <tr>
84  * <th valign="middle" rowspan="2" colspan="1" align="center">
85  * <font size="-2">Method</font></th>
86  * <th valign="top" rowspan="1" colspan="3" align="center">
87  * <font size="-2">Current State to Next State</font></th>
88  * </tr>
89  * <tr>
90  * <th width="25%" align="center"><font size="-2">deleted</font></th>
91  * <th width="12%" align="center"><font size="-2">open</font></th>
92  * <th width="25%" align="center"><font size="-2">inService</font></th>
93  * </tr>
94  * <tr>
95  * <td width="28%"><font size="-2">addToExcludedPolicy</font></td>
96  * <td width="25%" align="center">
97  * <font size="-2">Unsupported Operation</font></td>
98  * <td width="12%" align="center">
99  * <font size="-2">open</font></td>
100  * <td width="25%" align="center">
101  * <font size="-2">Unsupported Operation</font></td>
102  * </tr>
103  * <tr>
104  * <td width="28%"><font size="-2">addToRole</font></td>
105  * <td width="25%" align="center">
106  * <font size="-2">Unsupported Operation</font></td>
107  * <td width="12%" align="center">
108  * <font size="-2">open</font></td>
109  * <td width="25%" align="center">
110  * <font size="-2">Unsupported Operation</font></td>
111  * </tr>
112  * <tr>
113  * <td width="28%"><font size="-2">addToUncheckedPolicy</font></td>
114  * <td width="25%" align="center">
115  * <font size="-2">Unsupported Operation</font></td>
116  * <td width="12%" align="center">
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  * <font size="-2">Unsupported Operation</font></td>
125  * <td width="12%" align="center">
126  * <font size="-2">inService</font></td>
127  * <td width="25%" align="center">
128  * <font size="-2">inService</font></td>
129  * </tr>
130  * <tr>
131  * <td width="28%"><font size="-2">delete</font></td>
132  * <td width="25%" align="center">
133  * <font size="-2">deleted</font></td>
134  * <td width="12%" align="center">
135  * <font size="-2">deleted</font></td>
136  * <td width="25%" align="center">
137  * <font size="-2">deleted</font></td>
138  * </tr>
139  * <tr>
140  * <td width="28%"><font size="-2">getContextID</font></td>
141  * <td width="25%" align="center">
142  * <font size="-2">deleted</font></td>
143  * <td width="12%" align="center">
144  * <font size="-2">open</font></td>
145  * <td width="25%" align="center">
146  * <font size="-2">inService</font></td>
147  * </tr>
148  * <tr>
149  * <td width="28%"><font size="-2">inService</font></td>
150  * <td width="25%" align="center">
151  * <font size="-2">deleted</font></td>
152  * <td width="12%" align="center">
153  * <font size="-2">open</font></td>
154  * <td width="25%" align="center">
155  * <font size="-2">inService</font></td>
156  * </tr>
157  * <tr>
158  * <td width="28%"><font size="-2">linkConfiguration</font></td>
159  * <td width="25%" align="center">
160  * <font size="-2">Unsupported Operation</font></td>
161  * <td width="12%" align="center">
162  * <font size="-2">open</font></td>
163  * <td width="25%" align="center">
164  * <font size="-2">Unsupported Operation</font></td>
165  * </tr>
166  * <tr>
167  * <td width="28%"><font size="-2">removeExcludedPolicy</font></td>
168  * <td width="25%" align="center">
169  * <font size="-2">Unsupported Operation</font></td>
170  * <td width="12%" align="center"><font size="-2">
171  * open</font></td>
172  * <td width="25%" align="center">
173  * <font size="-2">Unsupported Operation</font></td>
174  * </tr>
175  * <tr>
176  * <td width="28%"><font size="-2">removeRole</font></td>
177  * <td width="25%" align="center">
178  * <font size="-2">Unsupported Operation</font></td>
179  * <td width="12%" align="center">
180  * <font size="-2">open</font></td>
181  * <td width="25%" align="center">
182  * <font size="-2">Unsupported Operation</font></td>
183  * </tr>
184  * <tr>
185  * <td width="28%"><font size="-2">removeUncheckedPolicy</font></td>
186  * <td width="25%" align="center">
187  * <font size="-2">Unsupported Operation</font></td>
188  * <td width="12%" align="center">
189  * <font size="-2">open</font></td>
190  * <td width="25%" align="center">
191  * <font size="-2">Unsupported Operation</font></td>
192  * </tr>
193  * </table>
194  * <br><P>
195  * For a provider implementation to be compatible with multi-threaded
196  * environments, it may be necessary to synchronize the refresh method of
197  * the provider with the methods of its PolicyConfiguration interface and
198  * with the getPolicyConfiguration and inService methods of its
199  * PolicyConfigurationFactory.
200  *
201  * @see java.security.Permission
202  * @see java.security.PermissionCollection
203  * @see javax.security.jacc.PolicyContextException
204  * @see javax.security.jacc.PolicyConfigurationFactory
205  *
206  * @author Ron Monzillo
207  * @author Gary Ellison
208  */

209
210 public interface PolicyConfiguration {
211     
212    /**
213     * This method returns this object's policy context identifier.
214     * @return this object's policy context identifier.
215     *
216     * @throws java.lang.SecurityException
217     * if called by an AccessControlContext that has not been
218     * granted the "setPolicy" SecurityPermission.
219     *
220     * @throws javax.security.jacc.PolicyContextException
221     * if the implementation throws a checked exception that has not been
222     * accounted for by the getContextID method signature. The exception thrown
223     * by the implementation class will be encapsulated (during construction)
224     * in the thrown PolicyContextException.
225     */

226
227     public String JavaDoc getContextID()
228         throws javax.security.jacc.PolicyContextException JavaDoc;
229
230    /**
231     * Used to add permissions to a named role in this PolicyConfiguration.
232     * If the named Role does not exist in the PolicyConfiguration, it is
233     * created as a result of the call to this function.
234     * <P>
235     * It is the job of the Policy provider to ensure that all the permissions
236     * added to a role are granted to principals "mapped to the role".
237     * <P>
238     * @param roleName the name of the Role to which the permissions are
239     * to be added.
240     * <P>
241     * @param permissions the collection of permissions to be added
242     * to the role. The collection may be either a homogenous or
243     * heterogenous collection.
244     *
245     * @throws java.lang.SecurityException
246     * if called by an AccessControlContext that has not been
247     * granted the "setPolicy" SecurityPermission.
248     *
249     * @throws java.lang.UnsupportedOperationException
250     * if the state of the policy context whose interface is this
251     * PolicyConfiguration Object is "deleted" or "inService" when this
252     * method is called.
253     *
254     * @throws javax.security.jacc.PolicyContextException
255     * if the implementation throws a checked exception that has not been
256     * accounted for by the addToRole method signature. The exception thrown
257     * by the implementation class will be encapsulated (during construction)
258     * in the thrown PolicyContextException.
259     */

260     public void addToRole(String JavaDoc roleName, PermissionCollection permissions)
261         throws javax.security.jacc.PolicyContextException JavaDoc;
262
263    /**
264     * Used to add a single permission to a named role in this
265     * PolicyConfiguration.
266     * If the named Role does not exist in the PolicyConfiguration, it is
267     * created as a result of the call to this function.
268     * <P>
269     * It is the job of the Policy provider to ensure that all the permissions
270     * added to a role are granted to principals "mapped to the role".
271     * <P>
272     * @param roleName the name of the Role to which the permission is
273     * to be added.
274     * <P>
275     * @param permission the permission to be added
276     * to the role.
277     *
278     * @throws java.lang.SecurityException
279     * if called by an AccessControlContext that has not been
280     * granted the "setPolicy" SecurityPermission.
281     *
282     * @throws java.lang.UnsupportedOperationException
283     * if the state of the policy context whose interface is this
284     * PolicyConfiguration Object is "deleted" or "inService" when this
285     * method is called.
286     *
287     * @throws javax.security.jacc.PolicyContextException
288     * if the implementation throws a checked exception that has not been
289     * accounted for by the addToRole method signature. The exception thrown
290     * by the implementation class will be encapsulated (during construction)
291     * in the thrown PolicyContextException.
292     */

293     public void addToRole(String JavaDoc roleName, Permission permission)
294         throws javax.security.jacc.PolicyContextException JavaDoc;
295
296    /**
297     * Used to add unchecked policy statements to this PolicyConfiguration.
298     * <P>
299     * @param permissions the collection of permissions to be added
300     * as unchecked policy statements. The collection may be either
301     * a homogenous or heterogenous collection.
302     *
303     * @throws java.lang.SecurityException
304     * if called by an AccessControlContext that has not been
305     * granted the "setPolicy" SecurityPermission.
306     *
307     * @throws java.lang.UnsupportedOperationException
308     * if the state of the policy context whose interface is this
309     * PolicyConfiguration Object is "deleted" or "inService" when this
310     * method is called.
311     *
312     * @throws javax.security.jacc.PolicyContextException
313     * if the implementation throws a checked exception that has not been
314     * accounted for by the addToUncheckedPolicy method signature.
315     * The exception thrown
316     * by the implementation class will be encapsulated (during construction)
317     * in the thrown PolicyContextException.
318     */

319     public void addToUncheckedPolicy(PermissionCollection permissions)
320         throws javax.security.jacc.PolicyContextException JavaDoc;
321
322    /**
323     * Used to add a single unchecked policy statement to this
324     * PolicyConfiguration.
325     * <P>
326     * @param permission the permission to be added
327     * to the unchecked policy statements.
328     *
329     * @throws java.lang.SecurityException
330     * if called by an AccessControlContext that has not been
331     * granted the "setPolicy" SecurityPermission.
332     *
333     * @throws java.lang.UnsupportedOperationException
334     * if the state of the policy context whose interface is this
335     * PolicyConfiguration Object is "deleted" or "inService" when this
336     * method is called.
337     *
338     * @throws javax.security.jacc.PolicyContextException
339     * if the implementation throws a checked exception that has not been
340     * accounted for by the addToUncheckedPolicy method signature.
341     * The exception thrown
342     * by the implementation class will be encapsulated (during construction)
343     * in the thrown PolicyContextException.
344     */

345     public void addToUncheckedPolicy(Permission permission)
346         throws javax.security.jacc.PolicyContextException JavaDoc;
347
348    /**
349     * Used to add excluded policy statements to this PolicyConfiguration.
350     * <P>
351     * @param permissions the collection of permissions to be added
352     * to the excluded policy statements. The collection may be either
353     * a homogenous or heterogenous collection.
354     *
355     * @throws java.lang.SecurityException
356     * if called by an AccessControlContext that has not been
357     * granted the "setPolicy" SecurityPermission.
358     *
359     * @throws java.lang.UnsupportedOperationException
360     * if the state of the policy context whose interface is this
361     * PolicyConfiguration Object is "deleted" or "inService" when this
362     * method is called.
363     *
364     * @throws javax.security.jacc.PolicyContextException
365     * if the implementation throws a checked exception that has not been
366     * accounted for by the addToExcludedPolicy method signature.
367     * The exception thrown
368     * by the implementation class will be encapsulated (during construction)
369     * in the thrown PolicyContextException.
370     */

371     public void addToExcludedPolicy(PermissionCollection permissions)
372         throws javax.security.jacc.PolicyContextException JavaDoc;
373
374    /**
375     * Used to add a single excluded policy statement to this
376     * PolicyConfiguration.
377     * <P>
378     * @param permission the permission to be added
379     * to the excluded policy statements.
380     *
381     * @throws java.lang.SecurityException
382     * if called by an AccessControlContext that has not been
383     * granted the "setPolicy" SecurityPermission.
384     *
385     * @throws java.lang.UnsupportedOperationException
386     * if the state of the policy context whose interface is this
387     * PolicyConfiguration Object is "deleted" or "inService" when this
388     * method is called.
389     *
390     * @throws javax.security.jacc.PolicyContextException
391     * if the implementation throws a checked exception that has not been
392     * accounted for by the addToExcludedPolicy method signature.
393     * The exception thrown
394     * by the implementation class will be encapsulated (during construction)
395     * in the thrown PolicyContextException.
396     */

397     public void addToExcludedPolicy(Permission permission)
398         throws javax.security.jacc.PolicyContextException JavaDoc;
399
400    /**
401     * Used to remove a role and all its permissions from this
402     * PolicyConfiguration.
403     * <P>
404     * @param roleName the name of the Role to remove from this
405     * PolicyConfiguration.
406     *
407     * @throws java.lang.SecurityException
408     * if called by an AccessControlContext that has not been
409     * granted the "setPolicy" SecurityPermission.
410     *
411     * @throws java.lang.UnsupportedOperationException
412     * if the state of the policy context whose interface is this
413     * PolicyConfiguration Object is "deleted" or "inService" when this
414     * method is called.
415     *
416     * @throws javax.security.jacc.PolicyContextException
417     * if the implementation throws a checked exception that has not been
418     * accounted for by the removeRole method signature. The exception thrown
419     * by the implementation class will be encapsulated (during construction)
420     * in the thrown PolicyContextException.
421     */

422     public void removeRole(String JavaDoc roleName)
423         throws javax.security.jacc.PolicyContextException JavaDoc;
424
425    /**
426     * Used to remove any unchecked policy statements from this
427     * PolicyConfiguration.
428     *
429     * @throws java.lang.SecurityException
430     * if called by an AccessControlContext that has not been
431     * granted the "setPolicy" SecurityPermission.
432     *
433     * @throws java.lang.UnsupportedOperationException
434     * if the state of the policy context whose interface is this
435     * PolicyConfiguration Object is "deleted" or "inService" when this
436     * method is called.
437     *
438     * @throws javax.security.jacc.PolicyContextException
439     * if the implementation throws a checked exception that has not been
440     * accounted for by the removeUncheckedPolicy method signature.
441     * The exception thrown
442     * by the implementation class will be encapsulated (during construction)
443     * in the thrown PolicyContextException.
444     */

445     public void removeUncheckedPolicy()
446         throws javax.security.jacc.PolicyContextException JavaDoc;
447
448    /**
449     * Used to remove any excluded policy statements from this
450     * PolicyConfiguration.
451     *
452     * @throws java.lang.SecurityException
453     * if called by an AccessControlContext that has not been
454     * granted the "setPolicy" SecurityPermission.
455     *
456     * @throws java.lang.UnsupportedOperationException
457     * if the state of the policy context whose interface is this
458     * PolicyConfiguration Object is "deleted" or "inService" when this
459     * method is called.
460     *
461     * @throws javax.security.jacc.PolicyContextException
462     * if the implementation throws a checked exception that has not been
463     * accounted for by the removeExcludedPolicy method signature.
464     * The exception thrown
465     * by the implementation class will be encapsulated (during construction)
466     * in the thrown PolicyContextException.
467     */

468     public void removeExcludedPolicy()
469         throws javax.security.jacc.PolicyContextException JavaDoc;
470
471    /**
472     * Creates a relationship between this configuration and another
473     * such that they share the same principal-to-role mappings.
474     * PolicyConfigurations are linked to apply a common principal-to-role
475     * mapping to multiple seperately manageable PolicyConfigurations,
476     * as is required when an application is composed of multiple
477     * modules.
478     * <P>
479     * Note that the policy statements which comprise a role, or comprise
480     * the excluded or unchecked policy collections in a PolicyConfiguration
481     * are unaffected by the configuration being linked to another.
482     * <P>
483     * @param link a reference to a different PolicyConfiguration than this
484     * PolicyConfiguration.
485     * <P>
486     * The relationship formed by this method is symetric, transitive
487     * and idempotent. If the argument PolicyConfiguration does not have a
488     * different Policy context identifier than this PolicyConfiguration
489     * no relationship is formed, and an exception, as described below, is
490     * thrown.
491     *
492     * @throws java.lang.SecurityException
493     * if called by an AccessControlContext that has not been
494     * granted the "setPolicy" SecurityPermission.
495     *
496     * @throws java.lang.UnsupportedOperationException
497     * if the state of the policy context whose interface is this
498     * PolicyConfiguration Object is "deleted" or "inService" when this
499     * method is called.
500     *
501     * @throws java.lang.IllegalArgumentException
502     * if called with an argument PolicyConfiguration whose Policy context
503     * is equivalent to that of this PolicyConfiguration.
504     *
505     * @throws javax.security.jacc.PolicyContextException
506     * if the implementation throws a checked exception that has not been
507     * accounted for by the linkConfiguration method signature. The exception
508     * thrown
509     * by the implementation class will be encapsulated (during construction)
510     * in the thrown PolicyContextException.
511     */

512     public void linkConfiguration(PolicyConfiguration JavaDoc link)
513         throws javax.security.jacc.PolicyContextException JavaDoc;
514
515    /**
516     * Causes all policy statements to be deleted from this PolicyConfiguration
517     * and sets its internal state such that calling any method, other than
518     * delete, getContextID, or inService on the PolicyConfiguration will
519     * be rejected and cause an UnsupportedOperationException to be thrown.
520     * <P>
521     * This operation has no affect on any linked PolicyConfigurations
522     * other than removing any links involving the deleted PolicyConfiguration.
523     *
524     * @throws java.lang.SecurityException
525     * if called by an AccessControlContext that has not been
526     * granted the "setPolicy" SecurityPermission.
527     *
528     * @throws javax.security.jacc.PolicyContextException
529     * if the implementation throws a checked exception that has not been
530     * accounted for by the delete method signature. The exception thrown
531     * by the implementation class will be encapsulated (during construction)
532     * in the thrown PolicyContextException.
533     */

534     public void delete()
535         throws javax.security.jacc.PolicyContextException JavaDoc;
536
537    /**
538     * This method is used to set to "inService" the state of the policy context
539     * whose interface is this PolicyConfiguration Object. Only those policy
540     * contexts whose state is "inService" will be included in the policy
541     * contexts processed by the Policy.refresh method. A policy context whose
542     * state is "inService" may be returned to the "open" state by calling the
543     * getPolicyConfiguration method of the PolicyConfiguration factory
544     * with the policy context identifier of the policy context.
545     * <P>
546     * When the state of a policy context is "inService", calling any method
547     * other than commit, delete, getContextID, or inService on its
548     * PolicyConfiguration Object will cause an UnsupportedOperationException
549     * to be thrown.
550     *
551     * @throws java.lang.SecurityException
552     * if called by an AccessControlContext that has not been
553     * granted the "setPolicy" SecurityPermission.
554     *
555     * @throws java.lang.UnsupportedOperationException
556     * if the state of the policy context whose interface is this
557     * PolicyConfiguration Object is "deleted" when this
558     * method is called.
559     *
560     * @throws javax.security.jacc.PolicyContextException
561     * if the implementation throws a checked exception that has not been
562     * accounted for by the commit method signature. The exception thrown
563     * by the implementation class will be encapsulated (during construction)
564     * in the thrown PolicyContextException.
565     */

566     public void commit()
567         throws javax.security.jacc.PolicyContextException JavaDoc;
568
569    /**
570     * This method is used to determine if the policy context whose interface is
571     * this PolicyConfiguration Object is in the "inService" state.
572     *
573     * @return true if the state of the associated policy context is
574     * "inService"; false otherwise.
575     *
576     * @throws java.lang.SecurityException
577     * if called by an AccessControlContext that has not been
578     * granted the "setPolicy" SecurityPermission.
579     *
580     * @throws javax.security.jacc.PolicyContextException
581     * if the implementation throws a checked exception that has not been
582     * accounted for by the inService method signature. The exception thrown
583     * by the implementation class will be encapsulated (during construction)
584     * in the thrown PolicyContextException.
585     */

586     public boolean inService()
587         throws javax.security.jacc.PolicyContextException JavaDoc;
588 }
589
590
Popular Tags