libcore/luni/src/main/java/java/security/PolicySpi.java

   1 /*
   2  *  Licensed to the Apache Software Foundation (ASF) under one or more
   3  *  contributor license agreements.  See the NOTICE file distributed with
   4  *  this work for additional information regarding copyright ownership.
   5  *  The ASF licenses this file to You under the Apache License, Version 2.0
   6  *  (the "License"); you may not use this file except in compliance with
   7  *  the License.  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 package java.security;
  19
  20 /**
  21  * Represents the Service Provider Interface (SPI) for java.security.Policy
  22  * class.
  23  *
  24  * <p>If there is any class that wants to provide a Policy implementation, all
  25  * abstract methods in this SPI should be implemented.
  26  *
  27  * <p>The detailed implementations should offer a public constructor, in which a
  28  * Policy.Paramters implementation acts as an input parameter.If the
  29  * Policy.Paramters input cannot by understood by the constructor, an
  30  * IllegalArgumentException will be thrown.
  31  */
  32 public abstract class PolicySpi {
  33
  34     public PolicySpi() {
  35         // default constructor
  36     }
  37
  38     /**
  39      * Answers if the policy has granted a Permission to a
  40      * ProtectionDomain.
  41      *
  42      * @param domain -
  43      *            the domain to check.
  44      * @param permission -
  45      *            check whether this permission is granted to the specified
  46      *            domain.
  47      * @return - true if the permission is granted to the domain.
  48      *
  49      */
  50     protected abstract boolean engineImplies(ProtectionDomain domain,
  51             Permission permission);
  52
  53     /**
  54      * Refreshes/reloads the policy configuration. The behavior of this method
  55      * depends on the implementation. For example, calling refresh on a
  56      * file-based policy will cause the file to be re-read.
  57      *
  58      * The default implementation of this method does nothing. This method
  59      * should be overridden if a refresh operation is supported by the policy
  60      * implementation.
  61      *
  62      */
  63     protected void engineRefresh() {
  64         // do nothing in default implementation
  65     }
  66
  67     /**
  68      * Answers a PermissionCollection object containing the set of permissions
  69      * granted to the specified CodeSource.
  70      *
  71      * The default implementation of this method returns
  72      * Policy.UNSUPPORTED_EMPTY_COLLECTION object. This method can be overridden
  73      * if the policy implementation can return a set of permissions granted to a
  74      * CodeSource.
  75      *
  76      * @param codesource -
  77      *            the CodeSource to which the returned PermissionCollection has
  78      *            been granted.
  79      * @return a set of permissions granted to the specified CodeSource. If this
  80      *         operation is supported, the returned set of permissions must be a
  81      *         new mutable instance and it must support heterogeneous Permission
  82      *         types. If this operation is not supported,
  83      *         Policy.UNSUPPORTED_EMPTY_COLLECTION is returned.
  84      */
  85     protected PermissionCollection engineGetPermissions(CodeSource codesource) {
  86         return Policy.UNSUPPORTED_EMPTY_COLLECTION;
  87     }
  88
  89     /**
  90      * Answers a PermissionCollection object containing the set of permissions
  91      * granted to the specified ProtectionDomain.
  92      *
  93      * The default implementation of this method returns
  94      * Policy.UNSUPPORTED_EMPTY_COLLECTION object. This method can be overridden
  95      * if the policy implementation can return a set of permissions granted to a
  96      * ProtectionDomain.
  97      *
  98      * @param domain -
  99      *            the ProtectionDomain to which the returned
 100      *            PermissionCollection has been granted.
 101      * @return a set of permissions granted to the specified ProtectionDomain.
 102      *         If this operation is supported, the returned set of permissions
 103      *         must be a new mutable instance and it must support heterogeneous
 104      *         Permission types. If this operation is not supported,
 105      *         Policy.UNSUPPORTED_EMPTY_COLLECTION is returned.
 106      */
 107     protected PermissionCollection engineGetPermissions(ProtectionDomain domain) {
 108         return Policy.UNSUPPORTED_EMPTY_COLLECTION;
 109     }
 110 }