001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.security.jacc;
027    
028    import java.io.Serializable;
029    import java.security.Permission;
030    
031    /**
032     * Class for EJB <code>isCallerInRole(String reference)</code> permissions. An
033     * EJBRoleRefPermission is a named permission and has actions.<p>
034     *
035     * The name of an EJBRoleRefPermission contains the value of the ejb-name
036     * element in the application's deployment descriptor that identifies the EJB
037     * in whose context the permission is being evalutated.<p>
038     *
039     * The actions of an EJBRoleRefPermission identifies the role reference to
040     * which the permission applies. An EJBRoleRefPermission is checked to
041     * determine if the subject is a member of the role identified by the reference.
042     *
043     * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $
044     */
045    public final class EJBRoleRefPermission extends Permission implements Serializable {
046    
047        private transient int cachedHashCode = 0;
048        private String actions;
049    
050        /**
051         * Creates a new EJBRoleRefPermission with the specified name and actions.
052         * @param name the ejb-name that identifies the EJB in whose context the
053         * role references are to be evaluated.
054         * @param role identifies the role reference to which the permission
055         * pertains. The role reference is scoped to the EJB identified in the
056         * name parameter. The value of the role reference must not be null or
057         * the empty string.
058         */
059        public EJBRoleRefPermission(String name, String role) {
060            super(name);
061    
062            if (role == null || role.length() == 0)
063                throw new IllegalArgumentException("Role reference must not be null or the empty string");
064    
065            actions = role;
066        }
067    
068        /**
069         * Checks two EJBRoleRefPermission objects for equality. EJBRoleRefPermission
070         * objects are equivalent if they have case equivalent name and actions values.<p>
071         *
072         * Two Permission objects, P1 and P2, are equivalent if and only if P1.implies(P2) && P2.implies(P1).
073         * @param o the EJBRoleRefPermission object being tested for equality with this EJBRoleRefPermission.
074         * @return true if the argument EJBRoleRefPermission object is equivalent to this EJBRoleRefPermission.
075         */
076        public boolean equals(Object o) {
077            if (o == null || !(o instanceof EJBRoleRefPermission)) return false;
078    
079            EJBRoleRefPermission other = (EJBRoleRefPermission)o;
080            return getName().equals(other.getName()) && actions.equals(other.actions);
081        }
082    
083        /**
084         * Returns a canonical String representation of the actions of this EJBRoleRefPermission.
085         * @return a String containing the canonicalized actions of this EJBRoleRefPermission.
086         */
087        public String getActions() {
088            return actions;
089        }
090    
091        /**
092         * Returns the hash code value for this EJBRoleRefPermission. The properties
093         * of the returned hash code must be as follows:
094         * <ul>
095         * <li>During the lifetime of a Java application, the hashCode method must
096         * return the same integer value, every time it is called on a EJBRoleRefPermission
097         * object. The value returned by hashCode for a particular EJBRoleRefPermission
098         * need not remain consistent from one execution of an application to another.</li>
099         * <li>If two EJBRoleRefPermission objects are equal according to the equals
100         * method, then calling the hashCode method on each of the two Permission
101         * objects must produce the same integer result (within an application).</li>
102         * </ul>
103         * @return the integer hash code value for this object.
104         */
105        public int hashCode() {
106            if (cachedHashCode == 0) {
107                cachedHashCode = getName().hashCode() ^ actions.hashCode();
108            }
109            return cachedHashCode;
110        }
111    
112        /**
113         * Determines if the argument Permission is "implied by" this
114         * EJBRoleRefPermission. For this to be the case,
115         *
116         * <ul>
117         * <li>The argument must be an instanceof EJBRoleRefPermission</li>
118         * <li>with name equivalent to that of this EJBRoleRefPermission, and</li>
119         * <li>with the role reference equivalent to that of this EJBRoleRefPermission applies.</li>
120         * <ul>
121         * The name and actions comparisons described above are case sensitive.
122         * @param permission "this" EJBRoleRefPermission is checked to see if it implies the argument permission.
123         * @return true if the specified permission is implied by this object, false if not.
124         */
125        public boolean implies(Permission permission) {
126            return equals(permission);
127        }
128    }
129