001    package org.apache.turbine.services.security.torque;
002    
003    /*
004     * Licensed to the Apache Software Foundation (ASF) under one
005     * or more contributor license agreements.  See the NOTICE file
006     * distributed with this work for additional information
007     * regarding copyright ownership.  The ASF licenses this file
008     * to you under the Apache License, Version 2.0 (the
009     * "License"); you may not use this file except in compliance
010     * with the License.  You may obtain a copy of the License at
011     *
012     *   http://www.apache.org/licenses/LICENSE-2.0
013     *
014     * Unless required by applicable law or agreed to in writing,
015     * software distributed under the License is distributed on an
016     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017     * KIND, either express or implied.  See the License for the
018     * specific language governing permissions and limitations
019     * under the License.
020     */
021    
022    import java.util.Iterator;
023    
024    import org.apache.torque.om.Persistent;
025    
026    import org.apache.turbine.om.security.Group;
027    import org.apache.turbine.om.security.Role;
028    import org.apache.turbine.om.security.User;
029    import org.apache.turbine.services.security.TurbineSecurity;
030    import org.apache.turbine.util.security.RoleSet;
031    import org.apache.turbine.util.security.TurbineSecurityException;
032    
033    /**
034     * This class represents a Group of Users in the system that are associated
035     * with specific entity or resource. The users belonging to the Group may
036     * have various Roles. The Permissions to perform actions upon the resource
037     * depend on the Roles in the Group that they are assigned. It is separated
038     * from the actual Torque peer object to be able to replace the Peer with an
039     * user supplied Peer (and Object)
040     *
041     * <a name="global">
042     * <p> Certain Roles that the Users may have in the system are not related
043     * to any specific resource nor entity.
044     * They are assigned within a special group named 'global' that can be
045     * referenced in the code as {@link #GLOBAL_GROUP_NAME}.
046     * <br>
047     *
048     * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
049     * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
050     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
051     * @version $Id: TorqueGroup.java 1096130 2011-04-23 10:37:19Z ludwig $
052     */
053    
054    public class TorqueGroup
055        extends TorqueObject
056        implements Group,
057                   Comparable
058    {
059    
060            /** Serial Version UID */
061            private static final long serialVersionUID = -2034684697021752888L;
062    
063        /**
064         * Constructs a new Group.
065         */
066        public TorqueGroup()
067        {
068            super();
069        }
070    
071        /**
072         * Constructs a new Group with the specified name.
073         *
074         * @param name The name of the new object.
075         */
076    
077        public TorqueGroup(String name)
078        {
079            super(name);
080        }
081    
082        /**
083         * The package private Constructor is used when the GroupPeerManager
084         * has retrieved a list of Database Objects from the peer and
085         * must 'wrap' them into TorqueGroup Objects.
086         * You should not use it directly!
087         *
088         * @param obj An Object from the peer
089         */
090        public TorqueGroup(Persistent obj)
091        {
092            super(obj);
093        }
094    
095        /**
096         * Returns the underlying Object for the Peer
097         *
098         * Used in the GroupPeerManager when building a new Criteria.
099         *
100         * @return The underlying persistent object
101         *
102         */
103    
104        public Persistent getPersistentObj()
105        {
106            if (obj == null)
107            {
108                obj = GroupPeerManager.newPersistentInstance();
109            }
110            return obj;
111        }
112    
113        /**
114         * Returns the name of this object.
115         *
116         * @return The name of the object.
117         */
118        public String getName()
119        {
120            return GroupPeerManager.getGroupName(getPersistentObj());
121        }
122    
123        /**
124         * Sets the name of this object.
125         *
126         * @param name The name of the object.
127         */
128        public void setName(String name)
129        {
130            GroupPeerManager.setGroupName(getPersistentObj(), name);
131        }
132    
133        /**
134         * Gets the Id of this object
135         *
136         * @return The Id of the object
137         */
138        public int getId()
139        {
140            return GroupPeerManager.getIdAsObj(getPersistentObj()).intValue();
141        }
142    
143        /**
144         * Gets the Id of this object
145         *
146         * @return The Id of the object
147         */
148        public Integer getIdAsObj()
149        {
150            return GroupPeerManager.getIdAsObj(getPersistentObj());
151        }
152    
153        /**
154         * Sets the Id of this object
155         *
156         * @param id The new Id
157         */
158        public void setId(int id)
159        {
160            GroupPeerManager.setId(getPersistentObj(), id);
161        }
162    
163        /**
164         * Provides a reference to the Group object that represents the
165         * <a href="#global">global group</a>.
166         *
167         * @return a Group object that represents the global group.
168         * @deprecated Please use the method in TurbineSecurity now.
169         */
170        public static Group getGlobalGroup()
171        {
172            return TurbineSecurity.getGlobalGroup();
173        }
174    
175        /**
176         * Creates a new Group in the system.
177         *
178         * @param name The name of the new Group.
179         * @return An object representing the new Group.
180         * @throws TurbineSecurityException if the Group could not be created.
181         * @deprecated Please use the createGroup method in TurbineSecurity now.
182         */
183        public static Group create(String name)
184            throws TurbineSecurityException
185        {
186            return TurbineSecurity.createGroup(name);
187        }
188    
189        // These following methods are wrappers around TurbineSecurity
190    
191        /**
192         * Makes changes made to the Group attributes permanent.
193         *
194         * @throws TurbineSecurityException if there is a problem while
195         *  saving data.
196         */
197        public void save()
198            throws TurbineSecurityException
199        {
200            TurbineSecurity.saveGroup(this);
201        }
202    
203        /**
204         * Removes a group from the system.
205         *
206         * @throws TurbineSecurityException if the Group could not be removed.
207         */
208        public void remove()
209            throws TurbineSecurityException
210        {
211            TurbineSecurity.removeGroup(this);
212        }
213    
214        /**
215         * Renames the role.
216         *
217         * @param name The new Group name.
218         * @throws TurbineSecurityException if the Group could not be renamed.
219         */
220        public void rename(String name)
221            throws TurbineSecurityException
222        {
223            TurbineSecurity.renameGroup(this, name);
224        }
225    
226        /**
227         * Grants a Role in this Group to an User.
228         *
229         * @param user An User.
230         * @param role A Role.
231         * @throws TurbineSecurityException if there is a problem while assigning
232         * the Role.
233         */
234        public void grant(User user, Role role)
235            throws TurbineSecurityException
236        {
237            TurbineSecurity.grant(user, this, role);
238        }
239    
240        /**
241         * Grants Roles in this Group to an User.
242         *
243         * @param user An User.
244         * @param roleSet A RoleSet.
245         * @throws TurbineSecurityException if there is a problem while assigning
246         * the Roles.
247         */
248        public void grant(User user, RoleSet roleSet)
249            throws TurbineSecurityException
250        {
251            Iterator roles = roleSet.iterator();
252            while (roles.hasNext())
253            {
254                TurbineSecurity.grant(user, this, (Role) roles.next());
255            }
256        }
257    
258        /**
259         * Revokes a Role in this Group from an User.
260         *
261         * @param user An User.
262         * @param role A Role.
263         * @throws TurbineSecurityException if there is a problem while unassigning
264         * the Role.
265         */
266        public void revoke(User user, Role role)
267            throws TurbineSecurityException
268        {
269            TurbineSecurity.revoke(user, this, role);
270        }
271    
272        /**
273         * Revokes Roles in this group from an User.
274         *
275         * @param user An User.
276         * @param roleSet a RoleSet.
277         * @throws TurbineSecurityException if there is a problem while unassigning
278         * the Roles.
279         */
280        public void revoke(User user, RoleSet roleSet)
281            throws TurbineSecurityException
282        {
283            Iterator roles = roleSet.iterator();
284            while (roles.hasNext())
285            {
286                TurbineSecurity.revoke(user, this, (Role) roles.next());
287            }
288        }
289    
290    }
291