    001    package org.apache.turbine.util.security;
    002
    003
    004    /*
    005     * Licensed to the Apache Software Foundation (ASF) under one
    006     * or more contributor license agreements.  See the NOTICE file
    007     * distributed with this work for additional information
    008     * regarding copyright ownership.  The ASF licenses this file
    009     * to you under the Apache License, Version 2.0 (the
    010     * "License"); you may not use this file except in compliance
    011     * with the License.  You may obtain a copy of the License at
    012     *
    013     *   http://www.apache.org/licenses/LICENSE-2.0
    014     *
    015     * Unless required by applicable law or agreed to in writing,
    016     * software distributed under the License is distributed on an
    017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    018     * KIND, either express or implied.  See the License for the
    019     * specific language governing permissions and limitations
    020     * under the License.
    021     */
    022
    023
    024    import java.util.Collection;
    025    import java.util.Iterator;
    026
    027    import org.apache.commons.lang.StringUtils;
    028    import org.apache.turbine.om.security.Permission;
    029
    030    /**
    031     * This class represents a set of Permissions.  It makes it easy to
    032     * build a UI that would allow someone to add a group of Permissions
    033     * to a Role.  It enforces that only
    034     * Permission objects are allowed in the set and only relevant methods
    035     * are available.
    036     *
    037     * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    038     * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
    039     * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
    040     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    041     * @version $Id: PermissionSet.java 1073174 2011-02-21 22:18:45Z tv $
    042     */
    043    public class PermissionSet
    044        extends SecuritySet<Permission>
    045    {
    046        /** Serial version */
    047            private static final long serialVersionUID = 7740960537240820226L;
    048
    049            /**
    050         * Constructs an empty PermissionSet
    051         */
    052        public PermissionSet()
    053        {
    054            super();
    055        }
    056
    057        /**
    058         * Constructs a new PermissionSet with specified contents.
    059         *
    060         * If the given collection contains multiple objects that are
    061         * identical WRT equals() method, some objects will be overwritten.
    062         *
    063         * @param permissions A collection of permissions to be contained in the set.
    064         */
    065        public PermissionSet(Collection<Permission> permissions)
    066        {
    067            super();
    068            add(permissions);
    069        }
    070
    071        /**
    072         * Adds a Permission to this PermissionSet.
    073         *
    074         * @param permission A Permission.
    075         * @return True if Permission was added; false if PermissionSet
    076         * already contained the Permission.
    077         */
    078        public boolean add(Permission permission)
    079        {
    080            boolean res = contains(permission);
    081            nameMap.put(permission.getName(), permission);
    082            idMap.put(permission.getIdAsObj(), permission);
    083            return res;
    084        }
    085
    086        /**
    087         * Adds the Permissions in a Collection to this PermissionSet.
    088         *
    089         * @param permissions A Collection of Permissions.
    090         * @return True if this PermissionSet changed as a result; false
    091         * if no change to this PermissionSet occurred (this PermissionSet
    092         * already contained all members of the added PermissionSet).
    093         */
    094        public boolean add(Collection<Permission> permissions)
    095        {
    096            boolean res = false;
    097            for (Permission p : permissions)
    098            {
    099                res |= add(p);
    100            }
    101            return res;
    102        }
    103
    104        /**
    105         * Adds the Permissions in another PermissionSet to this
    106         * PermissionSet.
    107         *
    108         * @param permissionSet A PermissionSet.
    109         * @return True if this PermissionSet changed as a result; false
    110         * if no change to this PermissionSet occurred (this PermissionSet
    111         * already contained all members of the added PermissionSet).
    112         */
    113        public boolean add(PermissionSet permissionSet)
    114        {
    115            boolean res = false;
    116            for(Permission p : permissionSet)
    117            {
    118                res |= add(p);
    119            }
    120            return res;
    121        }
    122
    123        /**
    124         * Removes a Permission from this PermissionSet.
    125         *
    126         * @param permission A Permission.
    127         * @return True if this PermissionSet contained the Permission
    128         * before it was removed.
    129         */
    130        public boolean remove(Permission permission)
    131        {
    132            boolean res = contains(permission);
    133            nameMap.remove(permission.getName());
    134            idMap.remove(permission.getIdAsObj());
    135            return res;
    136        }
    137
    138        /**
    139         * Checks whether this PermissionSet contains a Permission.
    140         *
    141         * @param permission A Permission.
    142         * @return True if this PermissionSet contains the Permission,
    143         * false otherwise.
    144         */
    145        public boolean contains(Permission permission)
    146        {
    147            return nameMap.containsValue(permission);
    148        }
    149
    150        /**
    151         * Returns a Permission with the given name, if it is contained in
    152         * this PermissionSet.
    153         *
    154         * @param permissionName Name of Permission.
    155         * @return Permission if argument matched a Permission in this
    156         * PermissionSet; null if no match.
    157         */
    158        public Permission getPermissionByName(String permissionName)
    159        {
    160            return (StringUtils.isNotEmpty(permissionName))
    161                    ? (Permission) nameMap.get(permissionName) : null;
    162        }
    163
    164        /**
    165         * Returns a Permission with the given id, if it is contained in
    166         * this PermissionSet.
    167         *
    168         * @param permissionId Id of the Permission.
    169         * @return Permission if argument matched a Permission in this
    170         * PermissionSet; null if no match.
    171         */
    172        public Permission getPermissionById(int permissionId)
    173        {
    174            return (permissionId != 0)
    175                    ? (Permission) idMap.get(new Integer(permissionId)) : null;
    176        }
    177
    178        /**
    179         * Returns an Array of Permissions in this PermissionSet.
    180         *
    181         * @return An Array of Permission Objects.
    182         */
    183        public Permission[] getPermissionsArray()
    184        {
    185            return getSet().toArray(new Permission[0]);
    186        }
    187
    188        /**
    189         * Print out a PermissionSet as a String
    190         *
    191         * @returns The Permission Set as String
    192         *
    193         */
    194        @Override
    195        public String toString()
    196        {
    197            StringBuffer sb = new StringBuffer();
    198            sb.append("PermissionSet: ");
    199
    200            for(Iterator<Permission> it = iterator(); it.hasNext();)
    201            {
    202                Permission p = it.next();
    203                sb.append('[');
    204                sb.append(p.getName());
    205                sb.append(" -> ");
    206                sb.append(p.getIdAsObj());
    207                sb.append(']');
    208                if (it.hasNext())
    209                {
    210                    sb.append(", ");
    211                }
    212            }
    213
    214            return sb.toString();
    215        }
    216    }