    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.Role;
    029
    030    /**
    031     * This class represents a set of Roles.  It makes it easy to build a
    032     * UI that would allow someone to add a group of Roles to a User.
    033     * It enforces that only Role objects are
    034     * allowed in the set and only relevant methods are available.
    035     *
    036     * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    037     * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
    038     * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
    039     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    040     * @version $Id: RoleSet.java 1073174 2011-02-21 22:18:45Z tv $
    041     */
    042    public class RoleSet
    043            extends SecuritySet<Role>
    044    {
    045        /** Serial version */
    046            private static final long serialVersionUID = 8122474203780997107L;
    047
    048            /**
    049         * Constructs an empty RoleSet
    050         */
    051        public RoleSet()
    052        {
    053            super();
    054        }
    055
    056        /**
    057         * Constructs a new RoleSet with specified contents.
    058         *
    059         * If the given collection contains multiple objects that are
    060         * identical WRT equals() method, some objects will be overwritten.
    061         *
    062         * @param roles A collection of roles to be contained in the set.
    063         */
    064        public RoleSet(Collection<Role> roles)
    065        {
    066            super();
    067            add(roles);
    068        }
    069
    070        /**
    071         * Adds a Role to this RoleSet.
    072         *
    073         * @param role A Role.
    074         * @return True if Role was added; false if RoleSet already
    075         * contained the Role.
    076         */
    077        public boolean add(Role role)
    078        {
    079            boolean res = contains(role);
    080            nameMap.put(role.getName(), role);
    081            idMap.put(role.getIdAsObj(), role);
    082            return res;
    083        }
    084
    085        /**
    086         * Adds the Roles in a Collection to this RoleSet.
    087         *
    088         * @param roles A Collection of Roles.
    089         * @return True if this RoleSet changed as a result; false
    090         * if no change to this RoleSet occurred (this RoleSet
    091         * already contained all members of the added RoleSet).
    092         */
    093        public boolean add(Collection<Role> roles)
    094        {
    095            boolean res = false;
    096            for (Role r : roles)
    097            {
    098                res |= add(r);
    099            }
    100            return res;
    101        }
    102
    103        /**
    104         * Adds the Roles in another RoleSet to this RoleSet.
    105         *
    106         * @param roleSet A RoleSet.
    107         * @return True if this RoleSet changed as a result; false
    108         * if no change to this RoleSet occurred (this RoleSet
    109         * already contained all members of the added RoleSet).
    110         */
    111        public boolean add(RoleSet roleSet)
    112        {
    113            boolean res = false;
    114            for(Role r : roleSet)
    115            {
    116                res |= add(r);
    117            }
    118            return res;
    119        }
    120
    121        /**
    122         * Removes a Role from this RoleSet.
    123         *
    124         * @param role A Role.
    125         * @return True if this RoleSet contained the Role
    126         * before it was removed.
    127         */
    128        public boolean remove(Role role)
    129        {
    130            boolean res = contains(role);
    131            nameMap.remove(role.getName());
    132            idMap.remove(role.getIdAsObj());
    133            return res;
    134        }
    135
    136        /**
    137         * Checks whether this RoleSet contains a Role.
    138         *
    139         * @param role A Role.
    140         * @return True if this RoleSet contains the Role,
    141         * false otherwise.
    142         */
    143        public boolean contains(Role role)
    144        {
    145            return nameMap.containsValue(role);
    146        }
    147
    148        /**
    149         * Returns a Role with the given name, if it is contained in
    150         * this RoleSet.
    151         *
    152         * @param roleName Name of Role.
    153         * @return Role if argument matched a Role in this
    154         * RoleSet; null if no match.
    155         */
    156        public Role getRoleByName(String roleName)
    157        {
    158            return (StringUtils.isNotEmpty(roleName))
    159                    ? (Role) nameMap.get(roleName) : null;
    160        }
    161
    162        /**
    163         * Returns a Role with the given id, if it is contained in this
    164         * RoleSet.
    165         *
    166         * @param roleId id of the Role.
    167         * @return Role if argument matched a Role in this RoleSet; null
    168         * if no match.
    169         */
    170        public Role getRoleById(int roleId)
    171        {
    172            return (roleId != 0)
    173                    ? (Role) idMap.get(new Integer(roleId)) : null;
    174        }
    175
    176        /**
    177         * Returns an Array of Roles in this RoleSet.
    178         *
    179         * @return An Array of Role objects.
    180         */
    181        public Role[] getRolesArray()
    182        {
    183            return getSet().toArray(new Role[0]);
    184        }
    185
    186        /**
    187         * Print out a RoleSet as a String
    188         *
    189         * @returns The Role Set as String
    190         *
    191         */
    192        @Override
    193        public String toString()
    194        {
    195            StringBuffer sb = new StringBuffer();
    196            sb.append("RoleSet: ");
    197
    198            for(Iterator<Role> it = iterator(); it.hasNext();)
    199            {
    200                Role r = it.next();
    201                sb.append('[');
    202                sb.append(r.getName());
    203                sb.append(" -> ");
    204                sb.append(r.getIdAsObj());
    205                sb.append(']');
    206                if (it.hasNext())
    207                {
    208                    sb.append(", ");
    209                }
    210            }
    211
    212            return sb.toString();
    213        }
    214    }