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("www.example.com", "connect,resolve") 69 * sp1 = new SocketPermission("www.example.com", "resolve,connect") 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