1 package org.apache.turbine.util.security;
2
3
4 /*
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
20 * under the License.
21 */
22
23
24 import java.util.Collection;
25 import java.util.Iterator;
26
27 import org.apache.commons.lang.StringUtils;
28 import org.apache.turbine.om.security.Role;
29
30 /**
31 * This class represents a set of Roles. It makes it easy to build a
32 * UI that would allow someone to add a group of Roles to a User.
33 * It enforces that only Role objects are
34 * allowed in the set and only relevant methods are available.
35 *
36 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
37 * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
38 * @author <a href="mailto:marco@intermeta.de">Marco Knüttel</a>
39 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
40 * @version $Id: RoleSet.java 1073174 2011-02-21 22:18:45Z tv $
41 */
42 public class RoleSet
43 extends SecuritySet<Role>
44 {
45 /** Serial version */
46 private static final long serialVersionUID = 8122474203780997107L;
47
48 /**
49 * Constructs an empty RoleSet
50 */
51 public RoleSet()
52 {
53 super();
54 }
55
56 /**
57 * Constructs a new RoleSet with specified contents.
58 *
59 * If the given collection contains multiple objects that are
60 * identical WRT equals() method, some objects will be overwritten.
61 *
62 * @param roles A collection of roles to be contained in the set.
63 */
64 public RoleSet(Collection<Role> roles)
65 {
66 super();
67 add(roles);
68 }
69
70 /**
71 * Adds a Role to this RoleSet.
72 *
73 * @param role A Role.
74 * @return True if Role was added; false if RoleSet already
75 * contained the Role.
76 */
77 public boolean add(Role role)
78 {
79 boolean res = contains(role);
80 nameMap.put(role.getName(), role);
81 idMap.put(role.getIdAsObj(), role);
82 return res;
83 }
84
85 /**
86 * Adds the Roles in a Collection to this RoleSet.
87 *
88 * @param roles A Collection of Roles.
89 * @return True if this RoleSet changed as a result; false
90 * if no change to this RoleSet occurred (this RoleSet
91 * already contained all members of the added RoleSet).
92 */
93 public boolean add(Collection<Role> roles)
94 {
95 boolean res = false;
96 for (Role r : roles)
97 {
98 res |= add(r);
99 }
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 }