1 /*

     2  * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 

    27 package java.security;

    28 

    29 /**

    30  * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)

    31  * for the {@code Policy} class.

    32  * All the abstract methods in this class must be implemented by each

    33  * service provider who wishes to supply a Policy implementation.

    34  *

    35  * <p> Subclass implementations of this abstract class must provide

    36  * a public constructor that takes a {@code Policy.Parameters}

    37  * object as an input parameter.  This constructor also must throw

    38  * an IllegalArgumentException if it does not understand the

    39  * {@code Policy.Parameters} input.

    40  *

    41  *

    42  * @since 1.6

    43  */

    44 

    45 public abstract class PolicySpi {

    46 

    47     /**

    48      * Check whether the policy has granted a Permission to a ProtectionDomain.

    49      *

    50      * @param domain the ProtectionDomain to check.

    51      *

    52      * @param permission check whether this permission is granted to the

    53      *          specified domain.

    54      *

    55      * @return boolean true if the permission is granted to the domain.

    56      */

    57     protected abstract boolean engineImplies

    58         (ProtectionDomain domain, Permission permission);

    59 

    60     /**

    61      * Refreshes/reloads the policy configuration. The behavior of this method

    62      * depends on the implementation. For example, calling {@code refresh}

    63      * on a file-based policy will cause the file to be re-read.

    64      *

    65      * <p> The default implementation of this method does nothing.

    66      * This method should be overridden if a refresh operation is supported

    67      * by the policy implementation.

    68      */

    69     protected void engineRefresh() { }

    70 

    71     /**

    72      * Return a PermissionCollection object containing the set of

    73      * permissions granted to the specified CodeSource.

    74      *

    75      * <p> The default implementation of this method returns

    76      * Policy.UNSUPPORTED_EMPTY_COLLECTION object.  This method can be

    77      * overridden if the policy implementation can return a set of

    78      * permissions granted to a CodeSource.

    79      *

    80      * @param codesource the CodeSource to which the returned

    81      *          PermissionCollection has been granted.

    82      *

    83      * @return a set of permissions granted to the specified CodeSource.

    84      *          If this operation is supported, the returned

    85      *          set of permissions must be a new mutable instance

    86      *          and it must support heterogeneous Permission types.

    87      *          If this operation is not supported,

    88      *          Policy.UNSUPPORTED_EMPTY_COLLECTION is returned.

    89      */

    90     protected PermissionCollection engineGetPermissions

    91                                         (CodeSource codesource) {

    92         return Policy.UNSUPPORTED_EMPTY_COLLECTION;

    93     }

    94 

    95     /**

    96      * Return a PermissionCollection object containing the set of

    97      * permissions granted to the specified ProtectionDomain.

    98      *

    99      * <p> The default implementation of this method returns

   100      * Policy.UNSUPPORTED_EMPTY_COLLECTION object.  This method can be

   101      * overridden if the policy implementation can return a set of

   102      * permissions granted to a ProtectionDomain.

   103      *

   104      * @param domain the ProtectionDomain to which the returned

   105      *          PermissionCollection has been granted.

   106      *

   107      * @return a set of permissions granted to the specified ProtectionDomain.

   108      *          If this operation is supported, the returned

   109      *          set of permissions must be a new mutable instance

   110      *          and it must support heterogeneous Permission types.

   111      *          If this operation is not supported,

   112      *          Policy.UNSUPPORTED_EMPTY_COLLECTION is returned.

   113      */

   114     protected PermissionCollection engineGetPermissions

   115                                         (ProtectionDomain domain) {

   116         return Policy.UNSUPPORTED_EMPTY_COLLECTION;

   117     }

   118 }