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
20import java.io.Serializable;
21
22/**
23 * {@code Permission} is the common base class of all permissions that
24 * participate in the access control security framework around
25 * {@link AccessController} and {@link AccessControlContext}. A permission
26 * constitutes of a name and associated actions.
27 */
28public abstract class Permission implements Guard, Serializable {
29
30    private static final long serialVersionUID = -5636570222231596674L;
31
32    private final String name;
33
34    /**
35     * Compares the specified object with this {@code Permission} for equality
36     * and returns {@code true} if the specified object is equal, {@code false}
37     * otherwise.
38     * <p>
39     * The {@link #implies(Permission)} method should be used for making access
40     * control checks.
41     *
42     * @param obj
43     *            object to be compared for equality with this {@code
44     *            Permission}.
45     * @return {@code true} if the specified object is equal to this {@code
46     *         Permission}, otherwise {@code false}.
47     */
48    @Override
49    public abstract boolean equals(Object obj);
50
51    /**
52     * Returns the hash code value for this {@code Permission}. Returns the same
53     * hash code for {@code Permission}s that are equal to each other as
54     * required by the general contract of {@link Object#hashCode}.
55     *
56     * @return the hash code value for this {@code Permission}.
57     * @see Object#equals(Object)
58     * @see Permission#equals(Object)
59     */
60    @Override
61    public abstract int hashCode();
62
63    /**
64     * Returns a comma separated string identifying the actions associated with
65     * this permission. The returned actions are in canonical form. For example:
66     *
67     * <pre>
68     * sp0 = new SocketPermission(&quot;www.example.com&quot;, &quot;connect,resolve&quot;)
69     * sp1 = new SocketPermission(&quot;www.example.com&quot;, &quot;resolve,connect&quot;)
70     * sp0.getActions().equals(sp1.getActions()) //yields true
71     * </pre>
72     *
73     * Both permissions return "connect,resolve" (in that order) if {@code
74     * #getActions()} is invoked. Returns an empty String, if no actions are
75     * associated with this permission.
76     *
77     * @return the actions associated with this permission or an empty string if
78     *         no actions are associated with this permission.
79     */
80    public abstract String getActions();
81
82    /**
83     * Indicates whether the specified permission is implied by this permission.
84     * The {@link AccessController} uses this method to check whether permission
85     * protected access is allowed with the present policy.
86     *
87     * @param permission
88     *            the permission to check against this permission.
89     * @return {@code true} if the specified permission is implied by this
90     *         permission, {@code false} otherwise.
91     */
92    public abstract boolean implies(Permission permission);
93
94    /**
95     * Constructs a new instance of {@code Permission} with its name.
96     *
97     * @param name
98     *            the name of the permission.
99     */
100    public Permission(String name) {
101        this.name = name;
102    }
103
104    /**
105     * Returns the name of this permission.
106     *
107     * @return the name of this permission.
108     */
109    public final String getName() {
110        return name;
111    }
112
113    /**
114     * Invokes {@link SecurityManager#checkPermission(Permission)} with this
115     * permission as its argument. This method implements the {@link Guard}
116     * interface.
117     *
118     * @param obj
119     *            as specified in {@link Guard#checkGuard(Object)} but ignored
120     *            in this implementation.
121     * @throws SecurityException
122     *             if this permission is not granted.
123     * @see Guard
124     * @see SecurityManager#checkPermission(Permission)
125     */
126    public void checkGuard(Object obj) throws SecurityException {
127        SecurityManager sm = System.getSecurityManager();
128        if (sm != null) {
129            sm.checkPermission(this);
130        }
131    }
132
133    /**
134     * Returns a specific {@link PermissionCollection} container for permissions
135     * of this type. Returns {@code null} if any permission collection can be
136     * used.
137     * <p>
138     * Subclasses may override this method to return an appropriate collection
139     * for the specific permissions they implement.
140     *
141     * @return an empty {@link PermissionCollection} or {@code null} if any
142     *         permission collection can be used.
143     */
144    public PermissionCollection newPermissionCollection() {
145        return null;
146    }
147
148    /**
149     * Returns a string containing a concise, human-readable description of the
150     * this {@code Permission} including its name and its actions.
151     *
152     * @return a printable representation for this {@code Permission}.
153     */
154    @Override
155    public String toString() {
156        String actions = getActions();
157        actions = (actions == null || actions.length() == 0) ? "" : " " //$NON-NLS-1$ //$NON-NLS-2$
158                + getActions();
159        return "(" + getClass().getName() + " " + getName() + actions + ")"; //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
160    }
161}
162