View Javadoc

1   package org.apache.turbine.util.security;
2   
3   /*
4    * Copyright 2001-2004 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.Permission;
25  
26  /***
27   * This class represents a set of Permissions.  It makes it easy to
28   * build a UI that would allow someone to add a group of Permissions
29   * to a Role.  It enforces that only
30   * Permission objects are allowed in the set and only relevant methods
31   * are available.
32   *
33   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
34   * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
35   * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
36   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
37   * @version $Id: PermissionSet.java,v 1.10.2.2 2004/05/20 03:27:24 seade Exp $
38   */
39  public class PermissionSet
40      extends SecuritySet
41  {
42      /***
43       * Constructs an empty PermissionSet
44       */
45      public PermissionSet()
46      {
47          super();
48      }
49  
50      /***
51       * Constructs a new PermissionSet with specified contents.
52       *
53       * If the given collection contains multiple objects that are
54       * identical WRT equals() method, some objects will be overwritten.
55       *
56       * @param permissions A collection of permissions to be contained in the set.
57       */
58      public PermissionSet(Collection permissions)
59      {
60          super();
61          add(permissions);
62      }
63  
64      /***
65       * Adds a Permission to this PermissionSet.
66       *
67       * @param permission A Permission.
68       * @return True if Permission was added; false if PermissionSet
69       * already contained the Permission.
70       */
71      public boolean add(Permission permission)
72      {
73          boolean res = contains(permission);
74          nameMap.put(permission.getName(), permission);
75          idMap.put(permission.getIdAsObj(), permission);
76          return res;
77      }
78  
79      /***
80       * Adds the Permissions in a Collection to this PermissionSet.
81       *
82       * @param permissions A Collection of Permissions.
83       * @return True if this PermissionSet changed as a result; false
84       * if no change to this PermissionSet occurred (this PermissionSet
85       * already contained all members of the added PermissionSet).
86       */
87      public boolean add(Collection permissions)
88      {
89          boolean res = false;
90          for (Iterator it = permissions.iterator(); it.hasNext();)
91          {
92              Permission p = (Permission) it.next();
93              res |= add(p);
94          }
95          return res;
96      }
97  
98      /***
99       * Adds the Permissions in another PermissionSet to this
100      * PermissionSet.
101      *
102      * @param permissionSet A PermissionSet.
103      * @return True if this PermissionSet changed as a result; false
104      * if no change to this PermissionSet occurred (this PermissionSet
105      * already contained all members of the added PermissionSet).
106      */
107     public boolean add(PermissionSet permissionSet)
108     {
109         boolean res = false;
110         for( Iterator it = permissionSet.iterator(); it.hasNext();)
111         {
112             Permission p = (Permission) it.next();
113             res |= add(p);
114         }
115         return res;
116     }
117 
118     /***
119      * Removes a Permission from this PermissionSet.
120      *
121      * @param permission A Permission.
122      * @return True if this PermissionSet contained the Permission
123      * before it was removed.
124      */
125     public boolean remove(Permission permission)
126     {
127         boolean res = contains(permission);
128         nameMap.remove(permission.getName());
129         idMap.remove(permission.getIdAsObj());
130         return res;
131     }
132 
133     /***
134      * Checks whether this PermissionSet contains a Permission.
135      *
136      * @param permission A Permission.
137      * @return True if this PermissionSet contains the Permission,
138      * false otherwise.
139      */
140     public boolean contains(Permission permission)
141     {
142         return nameMap.containsValue((Object) permission);
143     }
144 
145     /***
146      * Returns a Permission with the given name, if it is contained in
147      * this PermissionSet.
148      *
149      * @param permissionName Name of Permission.
150      * @return Permission if argument matched a Permission in this
151      * PermissionSet; null if no match.
152      * @deprecated Use <a href="#getPermissionByName">getPermissionByName</a> instead.
153      */
154     public Permission getPermission(String permissionName)
155     {
156         return getPermissionByName(permissionName);
157     }
158 
159     /***
160      * Returns a Permission with the given name, if it is contained in
161      * this PermissionSet.
162      *
163      * @param permissionName Name of Permission.
164      * @return Permission if argument matched a Permission in this
165      * PermissionSet; null if no match.
166      */
167     public Permission getPermissionByName(String permissionName)
168     {
169         return (StringUtils.isNotEmpty(permissionName))
170                 ? (Permission) nameMap.get(permissionName) : null;
171     }
172 
173     /***
174      * Returns a Permission with the given id, if it is contained in
175      * this PermissionSet.
176      *
177      * @param permissionId Id of the Permission.
178      * @return Permission if argument matched a Permission in this
179      * PermissionSet; null if no match.
180      */
181     public Permission getPermissionById(int permissionId)
182     {
183         return (permissionId != 0) 
184                 ? (Permission) idMap.get(new Integer(permissionId)) : null;
185     }
186 
187     /***
188      * Returns an Array of Permissions in this PermissionSet.
189      *
190      * @return An Array of Permission Objects.
191      */
192     public Permission[] getPermissionsArray()
193     {
194         return (Permission[]) getSet().toArray(new Permission[0]);
195     }
196 
197     /***
198      * Print out a PermissionSet as a String
199      *
200      * @returns The Permission Set as String
201      *
202      */
203     public String toString()
204     {
205         StringBuffer sb = new StringBuffer();
206         sb.append("PermissionSet: ");
207 
208         for(Iterator it = iterator(); it.hasNext();)
209         {
210             Permission p = (Permission) it.next();
211             sb.append('[');
212             sb.append(p.getName());
213             sb.append(" -> ");
214             sb.append(p.getIdAsObj());
215             sb.append(']');
216             if (it.hasNext())
217             {
218                 sb.append(", ");
219             }
220         }
221 
222         return sb.toString();
223     }
224 }