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.Permission;
029    
030    /**
031     * This class represents a set of Permissions.  It makes it easy to
032     * build a UI that would allow someone to add a group of Permissions
033     * to a Role.  It enforces that only
034     * Permission objects are allowed in the set and only relevant methods
035     * are available.
036     *
037     * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
038     * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
039     * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
040     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
041     * @version $Id: PermissionSet.java 1073174 2011-02-21 22:18:45Z tv $
042     */
043    public class PermissionSet
044        extends SecuritySet<Permission>
045    {
046        /** Serial version */
047            private static final long serialVersionUID = 7740960537240820226L;
048    
049            /**
050         * Constructs an empty PermissionSet
051         */
052        public PermissionSet()
053        {
054            super();
055        }
056    
057        /**
058         * Constructs a new PermissionSet with specified contents.
059         *
060         * If the given collection contains multiple objects that are
061         * identical WRT equals() method, some objects will be overwritten.
062         *
063         * @param permissions A collection of permissions to be contained in the set.
064         */
065        public PermissionSet(Collection<Permission> permissions)
066        {
067            super();
068            add(permissions);
069        }
070    
071        /**
072         * Adds a Permission to this PermissionSet.
073         *
074         * @param permission A Permission.
075         * @return True if Permission was added; false if PermissionSet
076         * already contained the Permission.
077         */
078        public boolean add(Permission permission)
079        {
080            boolean res = contains(permission);
081            nameMap.put(permission.getName(), permission);
082            idMap.put(permission.getIdAsObj(), permission);
083            return res;
084        }
085    
086        /**
087         * Adds the Permissions in a Collection to this PermissionSet.
088         *
089         * @param permissions A Collection of Permissions.
090         * @return True if this PermissionSet changed as a result; false
091         * if no change to this PermissionSet occurred (this PermissionSet
092         * already contained all members of the added PermissionSet).
093         */
094        public boolean add(Collection<Permission> permissions)
095        {
096            boolean res = false;
097            for (Permission p : permissions)
098            {
099                res |= add(p);
100            }
101            return res;
102        }
103    
104        /**
105         * Adds the Permissions in another PermissionSet to this
106         * PermissionSet.
107         *
108         * @param permissionSet A PermissionSet.
109         * @return True if this PermissionSet changed as a result; false
110         * if no change to this PermissionSet occurred (this PermissionSet
111         * already contained all members of the added PermissionSet).
112         */
113        public boolean add(PermissionSet permissionSet)
114        {
115            boolean res = false;
116            for(Permission p : permissionSet)
117            {
118                res |= add(p);
119            }
120            return res;
121        }
122    
123        /**
124         * Removes a Permission from this PermissionSet.
125         *
126         * @param permission A Permission.
127         * @return True if this PermissionSet contained the Permission
128         * before it was removed.
129         */
130        public boolean remove(Permission permission)
131        {
132            boolean res = contains(permission);
133            nameMap.remove(permission.getName());
134            idMap.remove(permission.getIdAsObj());
135            return res;
136        }
137    
138        /**
139         * Checks whether this PermissionSet contains a Permission.
140         *
141         * @param permission A Permission.
142         * @return True if this PermissionSet contains the Permission,
143         * false otherwise.
144         */
145        public boolean contains(Permission permission)
146        {
147            return nameMap.containsValue(permission);
148        }
149    
150        /**
151         * Returns a Permission with the given name, if it is contained in
152         * this PermissionSet.
153         *
154         * @param permissionName Name of Permission.
155         * @return Permission if argument matched a Permission in this
156         * PermissionSet; null if no match.
157         */
158        public Permission getPermissionByName(String permissionName)
159        {
160            return (StringUtils.isNotEmpty(permissionName))
161                    ? (Permission) nameMap.get(permissionName) : null;
162        }
163    
164        /**
165         * Returns a Permission with the given id, if it is contained in
166         * this PermissionSet.
167         *
168         * @param permissionId Id of the Permission.
169         * @return Permission if argument matched a Permission in this
170         * PermissionSet; null if no match.
171         */
172        public Permission getPermissionById(int permissionId)
173        {
174            return (permissionId != 0)
175                    ? (Permission) idMap.get(new Integer(permissionId)) : null;
176        }
177    
178        /**
179         * Returns an Array of Permissions in this PermissionSet.
180         *
181         * @return An Array of Permission Objects.
182         */
183        public Permission[] getPermissionsArray()
184        {
185            return getSet().toArray(new Permission[0]);
186        }
187    
188        /**
189         * Print out a PermissionSet as a String
190         *
191         * @returns The Permission Set as String
192         *
193         */
194        @Override
195        public String toString()
196        {
197            StringBuffer sb = new StringBuffer();
198            sb.append("PermissionSet: ");
199    
200            for(Iterator<Permission> it = iterator(); it.hasNext();)
201            {
202                Permission p = it.next();
203                sb.append('[');
204                sb.append(p.getName());
205                sb.append(" -> ");
206                sb.append(p.getIdAsObj());
207                sb.append(']');
208                if (it.hasNext())
209                {
210                    sb.append(", ");
211                }
212            }
213    
214            return sb.toString();
215        }
216    }