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    }