/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development * and Distribution License("CDDL") (collectively, the "License"). You * may not use this file except in compliance with the License. You can * obtain a copy of the License at * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html * or packager/legal/LICENSE.txt. See the License for the specific * language governing permissions and limitations under the License. * * When distributing the software, include this License Header Notice in each * file and include the License file at packager/legal/LICENSE.txt. * * GPL Classpath Exception: * Oracle designates this particular file as subject to the "Classpath" * exception as provided by Oracle in the GPL Version 2 section of the License * file that accompanied this code. * * Modifications: * If applicable, add the following below the License Header, with the fields * enclosed by brackets [] replaced by your own identifying information: * "Portions Copyright [year] [name of copyright owner]" * * Contributor(s): * If you wish your version of this file to be governed by only the CDDL or * only the GPL Version 2, indicate your decision by adding "[Contributor] * elects to include this software in this distribution under the [CDDL or GPL * Version 2] license." If you don't indicate a single choice of license, a * recipient has the option to distribute your version of this file under * either the CDDL, the GPL Version 2 or to extend the choice of license to * its licensees as provided above. However, if you add GPL Version 2 code * and therefore, elected the GPL Version 2 license, then the option applies * only if the new code is made subject to such option by the copyright * holder. */ package javax.security.jacc; import java.security.*; /** * The methods of this interface are used by containers to * create policy statements in a Policy provider. * An object that implements the PolicyConfiguration interface provides the * policy statement configuration interface for a corresponding policy context * within the corresponding Policy provider. *

* The life cycle of a policy context * is defined by three states; "open", "inService", and "deleted". A policy * context is in one of these three states. *

* A policy context in the "open" state is in the process of being * configured, and may be operated on by any of the methods of the * PolicyConfiguration interface. A policy context in the "open" state * must not be assimilated at Policy.refresh into the policy * statements used by the Policy provider in performing its access decisions. * In order for the policy statements of a policy context to be assimilated * by the associated provider, the policy context must be in the * "inService" state. A policy context in the "open" state is transitioned to * the "inService" state by calling the commit method. *

* A policy context in the "inService" state is available for assimilation * into the policy statements being used to perform access decisions by the * associated Policy provider. Providers assimilate policy contexts containing * policy statements when the refresh method of the provider is called. When * a provider's refresh method is called, it must assimilate only those policy * contexts whose state is "inService" and it must ensure that the policy * statements put into service for each policy context are only those defined * in the context at the time of the call to refresh. A policy context in the * "inService" state is not available for additional configuration and may be * returned to the "open" state by calling the getPolicyConfiguration method * of the PolicyConfigurationFactory. *

* A policy context in the "deleted" state is neither available for * configuration, nor is it available for assimilation into the Provider. A * policy context whose state is "deleted" may be reclaimed for subsequent * processing by calling the getPolicyConfiguration method of the associated * PolicyConfigurationFactory. A "deleted" policy context * is transitioned to the "open" state when it it returned as a result of * a call to getPolicyConfiguration. *

* The following table captures the correspondence between the policy context * life cycle and the methods of the PolicyConfiguration interface. * The rightmost 3 columns of the table correspond to the * PolicyConfiguration state identified at the head of the column. * The values in the cells of these columns indicate * the next state resulting from a call to the method * identifed in the leftmost column of the corresponding row, or that * calling the method is unsupported in the state * represented by the column (in which case the state will remain unchanged). * *

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
PolicyConfiguration State Table
* Method * Current State to Next State
deletedopeninService
addToExcludedPolicy * Unsupported Operation * open * Unsupported Operation
addToRole * Unsupported Operation * open * Unsupported Operation
addToUncheckedPolicy * Unsupported Operation * open * Unsupported Operation
commit * Unsupported Operation * inService * inService
delete * deleted * deleted * deleted
getContextID * deleted * open * inService
inService * deleted * open * inService
linkConfiguration * Unsupported Operation * open * Unsupported Operation
removeExcludedPolicy * Unsupported Operation * open * Unsupported Operation
removeRole * Unsupported Operation * open * Unsupported Operation
removeUncheckedPolicy * Unsupported Operation * open * Unsupported Operation
*

* For a provider implementation to be compatible with multi-threaded * environments, it may be necessary to synchronize the refresh method of * the provider with the methods of its PolicyConfiguration interface and * with the getPolicyConfiguration and inService methods of its * PolicyConfigurationFactory. * * @see java.security.Permission * @see java.security.PermissionCollection * @see javax.security.jacc.PolicyContextException * @see javax.security.jacc.PolicyConfigurationFactory * * @author Ron Monzillo * @author Gary Ellison */ public interface PolicyConfiguration { /** * This method returns this object's policy context identifier. * @return this object's policy context identifier. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the getContextID method signature. The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public String getContextID() throws javax.security.jacc.PolicyContextException; /** * Used to add permissions to a named role in this PolicyConfiguration. * If the named role does not exist in the PolicyConfiguration, it is * created as a result of the call to this function. *

* It is the job of the Policy provider to ensure that all the permissions * added to a role are granted to principals "mapped to the role". *

* @param roleName the name of the Role to which the permissions are * to be added. *

* @param permissions the collection of permissions to be added * to the role. The collection may be either a homogenous or * heterogenous collection. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the addToRole method signature. The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void addToRole(String roleName, PermissionCollection permissions) throws javax.security.jacc.PolicyContextException; /** * Used to add a single permission to a named role in this * PolicyConfiguration. * If the named role does not exist in the PolicyConfiguration, it is * created as a result of the call to this function. *

* It is the job of the Policy provider to ensure that all the permissions * added to a role are granted to principals "mapped to the role". *

* @param roleName the name of the Role to which the permission is * to be added. *

* @param permission the permission to be added * to the role. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the addToRole method signature. The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void addToRole(String roleName, Permission permission) throws javax.security.jacc.PolicyContextException; /** * Used to add unchecked policy statements to this PolicyConfiguration. *

* @param permissions the collection of permissions to be added * as unchecked policy statements. The collection may be either * a homogenous or heterogenous collection. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the addToUncheckedPolicy method signature. * The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void addToUncheckedPolicy(PermissionCollection permissions) throws javax.security.jacc.PolicyContextException; /** * Used to add a single unchecked policy statement to this * PolicyConfiguration. *

* @param permission the permission to be added * to the unchecked policy statements. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the addToUncheckedPolicy method signature. * The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void addToUncheckedPolicy(Permission permission) throws javax.security.jacc.PolicyContextException; /** * Used to add excluded policy statements to this PolicyConfiguration. *

* @param permissions the collection of permissions to be added * to the excluded policy statements. The collection may be either * a homogenous or heterogenous collection. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the addToExcludedPolicy method signature. * The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void addToExcludedPolicy(PermissionCollection permissions) throws javax.security.jacc.PolicyContextException; /** * Used to add a single excluded policy statement to this * PolicyConfiguration. *

* @param permission the permission to be added * to the excluded policy statements. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the addToExcludedPolicy method signature. * The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void addToExcludedPolicy(Permission permission) throws javax.security.jacc.PolicyContextException; /** * Used to remove a role and all its permissions from this * PolicyConfiguration. This method has no effect on the links * between this PolicyConfiguration and others. *

* @param roleName the name of the role to remove from this * PolicyConfiguration. If the value of the roleName parameter is "*" * and no role with name "*" exists in this PolicyConfiguration, * then all roles must be removed from this PolicyConfiguration. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the removeRole method signature. The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void removeRole(String roleName) throws javax.security.jacc.PolicyContextException; /** * Used to remove any unchecked policy statements from this * PolicyConfiguration. This method has no effect on the links * between this PolicyConfiguration and others. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the removeUncheckedPolicy method signature. * The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void removeUncheckedPolicy() throws javax.security.jacc.PolicyContextException; /** * Used to remove any excluded policy statements from this * PolicyConfiguration. This method has no effect on the links * between this PolicyConfiguration and others. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the removeExcludedPolicy method signature. * The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void removeExcludedPolicy() throws javax.security.jacc.PolicyContextException; /** * Creates a relationship between this configuration and another * such that they share the same principal-to-role mappings. * PolicyConfigurations are linked to apply a common principal-to-role * mapping to multiple seperately manageable PolicyConfigurations, * as is required when an application is composed of multiple * modules. *

* Note that the policy statements which comprise a role, or comprise * the excluded or unchecked policy collections in a PolicyConfiguration * are unaffected by the configuration being linked to another. *

* @param link a reference to a different PolicyConfiguration than this * PolicyConfiguration. *

* The relationship formed by this method is symetric, transitive * and idempotent. If the argument PolicyConfiguration does not have a * different Policy context identifier than this PolicyConfiguration * no relationship is formed, and an exception, as described below, is * thrown. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" or "inService" when this * method is called. * * @throws java.lang.IllegalArgumentException * if called with an argument PolicyConfiguration whose Policy context * is equivalent to that of this PolicyConfiguration. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the linkConfiguration method signature. The exception * thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void linkConfiguration(PolicyConfiguration link) throws javax.security.jacc.PolicyContextException; /** * Causes all policy statements to be deleted from this PolicyConfiguration * and sets its internal state such that calling any method, other than * delete, getContextID, or inService on the PolicyConfiguration will * be rejected and cause an UnsupportedOperationException to be thrown. *

* This operation has no affect on any linked PolicyConfigurations * other than removing any links involving the deleted PolicyConfiguration. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the delete method signature. The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void delete() throws javax.security.jacc.PolicyContextException; /** * This method is used to set to "inService" the state of the policy context * whose interface is this PolicyConfiguration Object. Only those policy * contexts whose state is "inService" will be included in the policy * contexts processed by the Policy.refresh method. A policy context whose * state is "inService" may be returned to the "open" state by calling the * getPolicyConfiguration method of the PolicyConfiguration factory * with the policy context identifier of the policy context. *

* When the state of a policy context is "inService", calling any method * other than commit, delete, getContextID, or inService on its * PolicyConfiguration Object will cause an UnsupportedOperationException * to be thrown. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws java.lang.UnsupportedOperationException * if the state of the policy context whose interface is this * PolicyConfiguration Object is "deleted" when this * method is called. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the commit method signature. The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public void commit() throws javax.security.jacc.PolicyContextException; /** * This method is used to determine if the policy context whose interface is * this PolicyConfiguration Object is in the "inService" state. * * @return true if the state of the associated policy context is * "inService"; false otherwise. * * @throws java.lang.SecurityException * if called by an AccessControlContext that has not been * granted the "setPolicy" SecurityPermission. * * @throws javax.security.jacc.PolicyContextException * if the implementation throws a checked exception that has not been * accounted for by the inService method signature. The exception thrown * by the implementation class will be encapsulated (during construction) * in the thrown PolicyContextException. */ public boolean inService() throws javax.security.jacc.PolicyContextException; }