View Javadoc

1   package org.apache.turbine.util.security;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.Collection;
20  import java.util.Iterator;
21  
22  import org.apache.commons.lang.StringUtils;
23  
24  import org.apache.turbine.om.security.Role;
25  
26  /***
27   * This class represents a set of Roles.  It makes it easy to build a
28   * UI that would allow someone to add a group of Roles to a User.
29   * It enforces that only Role objects are
30   * allowed in the set and only relevant methods are available.
31   *
32   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
33   * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
34   * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
35   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
36   * @version $Id: RoleSet.java 278822 2005-09-05 19:53:05Z henning $
37   */
38  public class RoleSet
39          extends SecuritySet
40  {
41      /*** Serial Version UID */
42      private static final long serialVersionUID = -5521518890129125912L;
43  
44      /***
45       * Constructs an empty RoleSet
46       */
47      public RoleSet()
48      {
49          super();
50      }
51  
52      /***
53       * Constructs a new RoleSet with specified contents.
54       *
55       * If the given collection contains multiple objects that are
56       * identical WRT equals() method, some objects will be overwritten.
57       *
58       * @param roles A collection of roles to be contained in the set.
59       */
60      public RoleSet(Collection roles)
61      {
62          super();
63          add(roles);
64      }
65  
66      /***
67       * Adds a Role to this RoleSet.
68       *
69       * @param role A Role.
70       * @return True if Role was added; false if RoleSet already
71       * contained the Role.
72       */
73      public boolean add(Role role)
74      {
75          boolean res = contains(role);
76          nameMap.put(role.getName(), role);
77          idMap.put(role.getIdAsObj(), role);
78          return res;
79      }
80  
81      /***
82       * Adds the Roles in a Collection to this RoleSet.
83       *
84       * @param roles A Collection of Roles.
85       * @return True if this RoleSet changed as a result; false
86       * if no change to this RoleSet occurred (this RoleSet
87       * already contained all members of the added RoleSet).
88       */
89      public boolean add(Collection roles)
90      {
91          boolean res = false;
92          for (Iterator it = roles.iterator(); it.hasNext();)
93          {
94              Role r = (Role) it.next();
95              res |= add(r);
96          }
97          return res;
98      }
99  
100     /***
101      * Adds the Roles in another RoleSet to this RoleSet.
102      *
103      * @param roleSet A RoleSet.
104      * @return True if this RoleSet changed as a result; false
105      * if no change to this RoleSet occurred (this RoleSet
106      * already contained all members of the added RoleSet).
107      */
108     public boolean add(RoleSet roleSet)
109     {
110         boolean res = false;
111         for( Iterator it = roleSet.iterator(); it.hasNext();)
112         {
113             Role r = (Role) it.next();
114             res |= add(r);
115         }
116         return res;
117     }
118 
119     /***
120      * Removes a Role from this RoleSet.
121      *
122      * @param role A Role.
123      * @return True if this RoleSet contained the Role
124      * before it was removed.
125      */
126     public boolean remove(Role role)
127     {
128         boolean res = contains(role);
129         nameMap.remove(role.getName());
130         idMap.remove(role.getIdAsObj());
131         return res;
132     }
133 
134     /***
135      * Checks whether this RoleSet contains a Role.
136      *
137      * @param role A Role.
138      * @return True if this RoleSet contains the Role,
139      * false otherwise.
140      */
141     public boolean contains(Role role)
142     {
143         return nameMap.containsValue((Object) role);
144     }
145 
146     /***
147      * Returns a Role with the given name, if it is contained in
148      * this RoleSet.
149      *
150      * @param roleName Name of Role.
151      * @return Role if argument matched a Role in this
152      * RoleSet; null if no match.
153      * @deprecated Use <a href="#getRoleByName">getRoleByName</a> instead.
154      */
155     public Role getRole(String roleName)
156     {
157         return getRoleByName(roleName);
158     }
159 
160     /***
161      * Returns a Role with the given name, if it is contained in
162      * this RoleSet.
163      *
164      * @param roleName Name of Role.
165      * @return Role if argument matched a Role in this
166      * RoleSet; null if no match.
167      */
168     public Role getRoleByName(String roleName)
169     {
170         return (StringUtils.isNotEmpty(roleName))
171                 ? (Role) nameMap.get(roleName) : null;
172     }
173 
174     /***
175      * Returns a Role with the given id, if it is contained in this
176      * RoleSet.
177      *
178      * @param roleId id of the Role.
179      * @return Role if argument matched a Role in this RoleSet; null
180      * if no match.
181      */
182     public Role getRoleById(int roleId)
183     {
184         return (roleId != 0)
185                 ? (Role) idMap.get(new Integer(roleId)) : null;
186     }
187 
188     /***
189      * Returns an Array of Roles in this RoleSet.
190      *
191      * @return An Array of Role objects.
192      */
193     public Role[] getRolesArray()
194     {
195         return (Role[]) getSet().toArray(new Role[0]);
196     }
197 
198     /***
199      * Print out a RoleSet as a String
200      *
201      * @returns The Role Set as String
202      *
203      */
204     public String toString()
205     {
206         StringBuffer sb = new StringBuffer();
207         sb.append("RoleSet: ");
208 
209         for(Iterator it = iterator(); it.hasNext();)
210         {
211             Role r = (Role) it.next();
212             sb.append('[');
213             sb.append(r.getName());
214             sb.append(" -> ");
215             sb.append(r.getIdAsObj());
216             sb.append(']');
217             if (it.hasNext())
218             {
219                 sb.append(", ");
220             }
221         }
222 
223         return sb.toString();
224     }
225 }