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
18package 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 */
32public 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}
111