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ü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 }