View Javadoc

1   /**
2    *
3    * Copyright 2003-2004 The Apache Software Foundation
4    *
5    *  Licensed under the Apache License, Version 2.0 (the "License");
6    *  you may not use this file except in compliance with the License.
7    *  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   *  Unless required by applicable law or agreed to in writing, software
12   *  distributed under the License is distributed on an "AS IS" BASIS,
13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   *  See the License for the specific language governing permissions and
15   *  limitations under the License.
16   */
17  
18  //
19  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
22  //
23  
24  package javax.security.jacc;
25  
26  import java.security.AccessController;
27  import java.security.PrivilegedActionException;
28  import java.security.PrivilegedExceptionAction;
29  import java.security.SecurityPermission;
30  
31  /**
32   * Abstract factory and finder class for obtaining the instance of the class
33   * that implements the PolicyConfigurationFactory of a provider. The factory
34   * will be used to instantiate PolicyConfiguration objects that will be used
35   * by the deployment tools of the container to create and manage policy
36   * contexts within the Policy Provider.
37   *
38   * Implementation classes must have a public no argument constructor that may
39   * be used to create an operational instance of the factory implementation class.
40   * @see java.security.Permission
41   * @see PolicyConfiguration
42   * @see PolicyContextException
43   * @version $Rev: 240324 $ $Date: 2005-08-26 12:50:35 -0700 (Fri, 26 Aug 2005) $
44   */
45  public abstract class PolicyConfigurationFactory {
46  
47      private final static String FACTORY_NAME = "javax.security.jacc.PolicyConfigurationFactory.provider";
48      private static PolicyConfigurationFactory policyConfigurationFactory;
49  
50      /**
51       * This static method uses a system property to find and instantiate (via a
52       * public constructor) a provider specific factory implementation class.
53       * The name of the provider specific factory implementation class is
54       * obtained from the value of the system property,<p>
55       * <code>javax.security.jacc.PolicyConfigurationFactory.provider</code>.
56       * @return the singleton instance of the provider specific
57       * PolicyConfigurationFactory implementation class.
58       * @throws ClassNotFoundException when the class named by the system
59       * property could not be found including because the value of the system
60       * property has not be set.
61       * @throws PolicyContextException if the implementation throws a checked
62       * exception that has not been accounted for by the
63       * getPolicyConfigurationFactory method signature. The exception thrown by
64       * the implementation class will be encapsulated (during construction) in
65       * the thrown PolicyContextException
66       */
67      public static PolicyConfigurationFactory getPolicyConfigurationFactory() throws ClassNotFoundException, PolicyContextException {
68          SecurityManager sm = System.getSecurityManager();
69          if (sm != null) sm.checkPermission(new SecurityPermission("setPolicy"));
70  
71          if (policyConfigurationFactory != null) return policyConfigurationFactory;
72  
73          final String[] factoryClassName = { null };
74          try {
75              policyConfigurationFactory = (PolicyConfigurationFactory)AccessController.doPrivileged(new
76                  PrivilegedExceptionAction() {
77                      public Object run() throws Exception
78                      {
79                          factoryClassName[0] = System.getProperty(FACTORY_NAME);
80  
81                          if (factoryClassName[0] == null) throw new ClassNotFoundException("Property " + FACTORY_NAME + " not set");
82                          Thread currentThread = Thread.currentThread();
83                          ClassLoader tccl = currentThread.getContextClassLoader();
84                          return Class.forName(factoryClassName[0], true, tccl).newInstance();
85                      }
86                  });
87          } catch(PrivilegedActionException pae) {
88              if (pae.getException() instanceof ClassNotFoundException) {
89                  throw (ClassNotFoundException)pae.getException();
90              } else if (pae.getException() instanceof InstantiationException) {
91                  throw new ClassNotFoundException(factoryClassName[0] + " could not be instantiated");
92              } else if (pae.getException() instanceof IllegalAccessException) {
93                  throw new ClassNotFoundException("Illegal access to " + factoryClassName);
94              }
95              throw new PolicyContextException(pae.getException());
96          }
97  
98          return policyConfigurationFactory;
99      }
100 
101     /**
102      * This method is used to obtain an instance of the provider specific class
103      * that implements the PolicyConfiguration interface that corresponds to
104      * the identified policy context within the provider. The methods of the
105      * PolicyConfiguration interface are used to define the policy statements
106      * of the identified policy context.<p>
107      *
108      * If at the time of the call, the identified policy context does not exist
109      * in the provider, then the policy context will be created in the provider
110      * and the Object that implements the context's PolicyConfiguration
111      * Interface will be returned. If the state of the identified context is
112      * "deleted" or "inService" it will be transitioned to the "open" state as
113      * a result of the call. The states in the lifecycle of a policy context
114      * are defined by the PolicyConfiguration interface.<p>
115      *
116      * For a given value of policy context identifier, this method must always
117      * return the same instance of PolicyConfiguration and there must be at
118      * most one actual instance of a PolicyConfiguration with a given policy
119      * context identifier (during a process context). <p>
120      *
121      * To preserve the invariant that there be at most one PolicyConfiguration
122      * object for a given policy context, it may be necessary for this method
123      * to be thread safe.
124      * @param contextID A String identifying the policy context whose
125      * PolicyConfiguration interface is to be returned. The value passed to
126      * this parameter must not be null.
127      * @param remove A boolean value that establishes whether or not the policy
128      * statements of an existing policy context are to be removed before its
129      * PolicyConfiguration object is returned. If the value passed to this
130      * parameter is true, the policy statements of an existing policy context
131      * will be removed. If the value is false, they will not be removed.
132      * @return an Object that implements the PolicyConfiguration Interface
133      * matched to the Policy provider and corresponding to the identified
134      * policy context.
135      * @throws PolicyContextException if the implementation throws a checked
136      * exception that has not been accounted for by the getPolicyConfiguration
137      * method signature. The exception thrown by the implementation class will
138      * be encapsulated (during construction) in the thrown PolicyContextException.
139      */
140     public abstract javax.security.jacc.PolicyConfiguration getPolicyConfiguration(String contextID, boolean remove) throws PolicyContextException;
141 
142     /**
143      * This method determines if the identified policy context exists with
144      * state "inService" in the Policy provider associated with the factory.
145      * @param contextID A string identifying a policy context
146      * @return true if the identified policy context exists within the provider
147      * and its state is "inService", false otherwise.
148      * @throws PolicyContextException if the implementation throws a checked
149      * exception that has not been accounted for by the inService method
150      * signature. The exception thrown by the implementation class will be
151      * encapsulated (during construction) in the thrown PolicyContextException.
152      */
153     public abstract boolean inService(String contextID) throws PolicyContextException;
154 }