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  ;
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   getContextID()
228         throws javax.security.jacc.PolicyContextException  ;
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   roleName, PermissionCollection permissions)
261         throws javax.security.jacc.PolicyContextException  ;
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   roleName, Permission permission)
294         throws javax.security.jacc.PolicyContextException  ;
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  ;
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  ;
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  ;
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  ;
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   roleName)
423         throws javax.security.jacc.PolicyContextException  ;
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  ;
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  ;
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   link)
513         throws javax.security.jacc.PolicyContextException  ;
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  ;
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  ;
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  ;
588 }
589 
590
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags