View Javadoc

1   package org.apache.turbine.services.security.torque;
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.Iterator;
20  
21  import org.apache.torque.om.Persistent;
22  
23  import org.apache.turbine.om.security.Group;
24  import org.apache.turbine.om.security.Role;
25  import org.apache.turbine.om.security.User;
26  import org.apache.turbine.services.security.TurbineSecurity;
27  import org.apache.turbine.util.security.RoleSet;
28  import org.apache.turbine.util.security.TurbineSecurityException;
29  
30  /***
31   * This class represents a Group of Users in the system that are associated
32   * with specific entity or resource. The users belonging to the Group may
33   * have various Roles. The Permissions to perform actions upon the resource
34   * depend on the Roles in the Group that they are assigned. It is separated
35   * from the actual Torque peer object to be able to replace the Peer with an
36   * user supplied Peer (and Object)
37   *
38   * <a name="global">
39   * <p> Certain Roles that the Users may have in the system are not related
40   * to any specific resource nor entity.
41   * They are assigned within a special group named 'global' that can be
42   * referenced in the code as {@link #GLOBAL_GROUP_NAME}.
43   * <br>
44   *
45   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
46   * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
47   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
48   * @version $Id: TorqueGroup.java 264148 2005-08-29 14:21:04Z henning $
49   */
50  
51  public class TorqueGroup
52      extends TorqueObject
53      implements Group,
54                 Comparable
55  {
56      /***
57       * Constructs a new Group.
58       */
59      public TorqueGroup()
60      {
61          super();
62      }
63  
64      /***
65       * Constructs a new Group with the specified name.
66       *
67       * @param name The name of the new object.
68       */
69  
70      public TorqueGroup(String name)
71      {
72          super(name);
73      }
74  
75      /***
76       * The package private Constructor is used when the GroupPeerManager
77       * has retrieved a list of Database Objects from the peer and
78       * must 'wrap' them into TorqueGroup Objects.
79       * You should not use it directly!
80       *
81       * @param obj An Object from the peer
82       */
83      public TorqueGroup(Persistent obj)
84      {
85          super(obj);
86      }
87  
88      /***
89       * Returns the underlying Object for the Peer
90       *
91       * Used in the GroupPeerManager when building a new Criteria.
92       *
93       * @return The underlying persistent object
94       *
95       */
96  
97      public Persistent getPersistentObj()
98      {
99          if (obj == null)
100         {
101             obj = GroupPeerManager.newPersistentInstance();
102         }
103         return obj;
104     }
105 
106     /***
107      * Returns the name of this object.
108      *
109      * @return The name of the object.
110      */
111     public String getName()
112     {
113         return GroupPeerManager.getGroupName(getPersistentObj());
114     }
115 
116     /***
117      * Sets the name of this object.
118      *
119      * @param name The name of the object.
120      */
121     public void setName(String name)
122     {
123         GroupPeerManager.setGroupName(getPersistentObj(), name);
124     }
125 
126     /***
127      * Gets the Id of this object
128      *
129      * @return The Id of the object
130      */
131     public int getId()
132     {
133         return GroupPeerManager.getIdAsObj(getPersistentObj()).intValue();
134     }
135 
136     /***
137      * Gets the Id of this object
138      *
139      * @return The Id of the object
140      */
141     public Integer getIdAsObj()
142     {
143         return GroupPeerManager.getIdAsObj(getPersistentObj());
144     }
145 
146     /***
147      * Sets the Id of this object
148      *
149      * @param id The new Id
150      */
151     public void setId(int id)
152     {
153         GroupPeerManager.setId(getPersistentObj(), id);
154     }
155 
156     /***
157      * Provides a reference to the Group object that represents the
158      * <a href="#global">global group</a>.
159      *
160      * @return a Group object that represents the global group.
161      * @deprecated Please use the method in TurbineSecurity now.
162      */
163     public static Group getGlobalGroup()
164     {
165         return TurbineSecurity.getGlobalGroup();
166     }
167 
168     /***
169      * Creates a new Group in the system.
170      *
171      * @param name The name of the new Group.
172      * @return An object representing the new Group.
173      * @throws TurbineSecurityException if the Group could not be created.
174      * @deprecated Please use the createGroup method in TurbineSecurity now.
175      */
176     public static Group create(String name)
177         throws TurbineSecurityException
178     {
179         return TurbineSecurity.createGroup(name);
180     }
181 
182     // These following methods are wrappers around TurbineSecurity
183 
184     /***
185      * Makes changes made to the Group attributes permanent.
186      *
187      * @throws TurbineSecurityException if there is a problem while
188      *  saving data.
189      */
190     public void save()
191         throws TurbineSecurityException
192     {
193         TurbineSecurity.saveGroup(this);
194     }
195 
196     /***
197      * Removes a group from the system.
198      *
199      * @throws TurbineSecurityException if the Group could not be removed.
200      */
201     public void remove()
202         throws TurbineSecurityException
203     {
204         TurbineSecurity.removeGroup(this);
205     }
206 
207     /***
208      * Renames the role.
209      *
210      * @param name The new Group name.
211      * @throws TurbineSecurityException if the Group could not be renamed.
212      */
213     public void rename(String name)
214         throws TurbineSecurityException
215     {
216         TurbineSecurity.renameGroup(this, name);
217     }
218 
219     /***
220      * Grants a Role in this Group to an User.
221      *
222      * @param user An User.
223      * @param role A Role.
224      * @throws TurbineSecurityException if there is a problem while assigning
225      * the Role.
226      */
227     public void grant(User user, Role role)
228         throws TurbineSecurityException
229     {
230         TurbineSecurity.grant(user, this, role);
231     }
232 
233     /***
234      * Grants Roles in this Group to an User.
235      *
236      * @param user An User.
237      * @param roleSet A RoleSet.
238      * @throws TurbineSecurityException if there is a problem while assigning
239      * the Roles.
240      */
241     public void grant(User user, RoleSet roleSet)
242         throws TurbineSecurityException
243     {
244         Iterator roles = roleSet.iterator();
245         while (roles.hasNext())
246         {
247             TurbineSecurity.grant(user, this, (Role) roles.next());
248         }
249     }
250 
251     /***
252      * Revokes a Role in this Group from an User.
253      *
254      * @param user An User.
255      * @param role A Role.
256      * @throws TurbineSecurityException if there is a problem while unassigning
257      * the Role.
258      */
259     public void revoke(User user, Role role)
260         throws TurbineSecurityException
261     {
262         TurbineSecurity.revoke(user, this, role);
263     }
264 
265     /***
266      * Revokes Roles in this group from an User.
267      *
268      * @param user An User.
269      * @param roleSet a RoleSet.
270      * @throws TurbineSecurityException if there is a problem while unassigning
271      * the Roles.
272      */
273     public void revoke(User user, RoleSet roleSet)
274         throws TurbineSecurityException
275     {
276         Iterator roles = roleSet.iterator();
277         while (roles.hasNext())
278         {
279             TurbineSecurity.revoke(user, this, (Role) roles.next());
280         }
281     }
282 
283 }
284