I_CmsUserDriver


1   /*
2    * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/db/I_CmsUserDriver.java,v $
3    * Date   : $Date: 2005/07/28 10:53:54 $
4    * Version: $Revision: 1.58 $
5    *
6    * This library is part of OpenCms -
7    * the Open Source Content Mananagement System
8    *
9    * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
10   *
11   * This library is free software; you can redistribute it and/or
12   * modify it under the terms of the GNU Lesser General Public
13   * License as published by the Free Software Foundation; either
14   * version 2.1 of the License, or (at your option) any later version.
15   *
16   * This library is distributed in the hope that it will be useful,
17   * but WITHOUT ANY WARRANTY; without even the implied warranty of
18   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19   * Lesser General Public License for more details.
20   *
21   * For further information about Alkacon Software GmbH, please see the
22   * company website: http://www.alkacon.com
23   *
24   * For further information about OpenCms, please see the
25   * project website: http://www.opencms.org
26   * 
27   * You should have received a copy of the GNU Lesser General Public
28   * License along with this library; if not, write to the Free Software
29   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
30   */
31  
32  package org.opencms.db;
33  
34  import org.opencms.db.generic.CmsSqlManager;
35  import org.opencms.file.CmsDataAccessException;
36  import org.opencms.file.CmsGroup;
37  import org.opencms.file.CmsProject;
38  import org.opencms.file.CmsUser;
39  import org.opencms.security.CmsAccessControlEntry;
40  import org.opencms.security.CmsPasswordEncryptionException;
41  import org.opencms.util.CmsUUID;
42  
43  import java.util.List  ;
44  import java.util.Map  ;
45  
46  /**
47   * Definitions of all required user driver methods. <p>
48   * 
49   * @author Thomas Weckert 
50   * @author Michael Emmerich 
51   * 
52   * @version $Revision: 1.58 $
53   * 
54   * @since 6.0.0 
55   */
56  public interface I_CmsUserDriver extends I_CmsDriver {
57  
58      /** The type ID to identify user driver implementations. */
59      int DRIVER_TYPE_ID = 2;
60  
61      /**
62       * Creates an access control entry.<p>
63       * 
64       * @param dbc the current database context
65       * @param project the project to write the entry
66       * @param resource the id of the resource
67       * @param principal the id of the principal (user or group)
68       * @param allowed the bitset of allowed permissions
69       * @param denied the bitset of denied permissions
70       * @param flags flags
71       * 
72       * @throws CmsDataAccessException if something goes wrong
73       */
74      void createAccessControlEntry(
75          CmsDbContext dbc,
76          CmsProject project,
77          CmsUUID resource,
78          CmsUUID principal,
79          int allowed,
80          int denied,
81          int flags) throws CmsDataAccessException;
82  
83      /**
84       * Creates a new group.<p>
85       * 
86       * @param dbc the current database context
87       * @param groupId the id of the new group
88       * @param groupName the name of the new group
89       * @param description The description for the new group
90       * @param flags the flags for the new group
91       * @param parentGroupName the name of the parent group (or null if the group has no parent)
92       * @param reservedParam reserved optional parameter, should be null on standard OpenCms installations
93       *
94       * @return the created group
95       * @throws CmsDataAccessException if something goes wrong
96       */
97      CmsGroup createGroup(
98          CmsDbContext dbc,
99          CmsUUID groupId,
100         String   groupName,
101         String   description,
102         int flags,
103         String   parentGroupName,
104         Object   reservedParam) throws CmsDataAccessException;
105 
106     /**
107      * Creates a new user.<p>
108      * 
109      * @param dbc the current database context
110      * @param name the user name
111      * @param password the user password
112      * @param description the user description
113      * @param firstname the user firstname
114      * @param lastname the user lastname
115      * @param email the user email
116      * @param lastlogin the user lastlogin time
117      * @param flags the user flags
118      * @param additionalInfos the user additional infos
119      * @param address the user default address
120      * @param type the user type
121      * 
122      * @return the created user
123      * @throws CmsDataAccessException if something goes wrong
124      * @throws CmsPasswordEncryptionException if the user password could not be encrypted
125      */
126     CmsUser createUser(
127         CmsDbContext dbc,
128         String   name,
129         String   password,
130         String   description,
131         String   firstname,
132         String   lastname,
133         String   email,
134         long lastlogin,
135         int flags,
136         Map   additionalInfos,
137         String   address,
138         int type) throws CmsDataAccessException, CmsPasswordEncryptionException;
139 
140     /**
141      * Adds a user to a group.<p>
142      *
143      * @param dbc the current database context
144      * @param userid the id of the user that is to be added to the group
145      * @param groupid the id of the group
146      * @param reservedParam reserved optional parameter, should be null on standard OpenCms installations
147      * 
148      * @throws CmsDataAccessException if operation was not succesfull
149      */
150     void createUserInGroup(CmsDbContext dbc, CmsUUID userid, CmsUUID groupid, Object   reservedParam)
151     throws CmsDataAccessException;
152 
153     /**
154      * Deletes all access control entries (ACEs) belonging to a resource.<p>
155      * 
156      * @param dbc the current database context
157      * @param project the project to delete the ACEs in
158      * @param resource the id of the resource to delete the ACEs from
159      * 
160      * @throws CmsDataAccessException if something goes wrong
161      */
162     void deleteAccessControlEntries(CmsDbContext dbc, CmsProject project, CmsUUID resource)
163     throws CmsDataAccessException;
164 
165     /**
166      * Deletes a group.<p>
167      * 
168      * Only groups that contain no subgroups can be deleted.<p>
169      * 
170      * @param dbc the current database context
171      * @param name the name of the group that is to be deleted
172      *
173      * @throws CmsDataAccessException if something goes wrong
174      */
175     void deleteGroup(CmsDbContext dbc, String   name) throws CmsDataAccessException;
176 
177     /**
178      * Deletes a user.<p>
179      * 
180      * @param dbc the current database context
181      * @param userName the name of the user to delete
182      * 
183      * @throws CmsDataAccessException if something goes wrong
184      */
185     void deleteUser(CmsDbContext dbc, String   userName) throws CmsDataAccessException;
186 
187     /**
188      * Removes a user from a group.<p>
189      * 
190      * @param dbc the current database context
191      * @param userId the id of the user that is to be removed from the group
192      * @param groupId the id of the group
193      * 
194      * @throws CmsDataAccessException if something goes wrong
195      */
196     void deleteUserInGroup(CmsDbContext dbc, CmsUUID userId, CmsUUID groupId) throws CmsDataAccessException;
197 
198     /**
199      * Destroys this driver.<p>
200      * 
201      * @throws Throwable if something goes wrong
202      */
203     void destroy() throws Throwable  ;
204 
205     /**
206      * Tests if a group with the specified name exists.<p>
207      * 
208      * @param dbc the current database context
209      * @param groupname the user name to be checked
210      * @param reservedParam reserved optional parameter, should be null on standard OpenCms installations
211      * 
212      * @return true, if a group with the specified name exists, false otherwise
213      * @throws CmsDataAccessException if something goes wrong
214      */
215     boolean existsGroup(CmsDbContext dbc, String   groupname, Object   reservedParam) throws CmsDataAccessException;
216 
217     /**
218      * Tests if a user with the specified name exists.<p>
219      * 
220      * @param dbc the current database context
221      * @param username the user name to be checked
222      * @param usertype the type of the user
223      * @param reservedParam reserved optional parameter, should be null on standard OpenCms installations
224      * 
225      * @return true, if a user with the specified name exists, false otherwise
226      * @throws CmsDataAccessException if something goes wrong
227      */
228     boolean existsUser(CmsDbContext dbc, String   username, int usertype, Object   reservedParam)
229     throws CmsDataAccessException;
230 
231     /**
232      * Returns the SqlManager of this driver.<p>
233      * 
234      * @return the SqlManager of this driver
235      */
236     CmsSqlManager getSqlManager();
237 
238     /**
239      * Creates a new user by import.<p>
240      * 
241      * @param dbc the current database context
242      * @param id the id of the user
243      * @param name the new name for the user
244      * @param password the new password for the user
245      * @param description the description for the user
246      * @param firstname the firstname of the user
247      * @param lastname the lastname of the user
248      * @param email the email of the user
249      * @param lastlogin the user lastlogin time
250      * @param flags the flags for a user (e.g. <code>{@link org.opencms.security.I_CmsPrincipal#FLAG_ENABLED}</code>)
251      * @param additionalInfos a <code>{@link Map}</code> with additional infos for the user. These
252      *                      infos may be stored into the Usertables (depending on the implementation).
253      * @param address the address of the user
254      * @param type the type of the user
255      * @param reservedParam reserved optional parameter, should be <code>null</code> on standard OpenCms installations
256      *
257      * @return a new <code>{@link CmsUser}</code> object representing the added user
258      *
259      * @throws CmsDataAccessException if operation was not successful
260      */
261     CmsUser importUser(
262         CmsDbContext dbc,
263         CmsUUID id,
264         String   name,
265         String   password,
266         String   description,
267         String   firstname,
268         String   lastname,
269         String   email,
270         long lastlogin,
271         int flags,
272         Map   additionalInfos,
273         String   address,
274         int type,
275         Object   reservedParam) throws CmsDataAccessException;
276 
277     /**
278      * Initializes the SQL manager for this driver.<p>
279      * 
280      * To obtain JDBC connections from different pools, further 
281      * {online|offline|backup} pool Urls have to be specified.<p>
282      * 
283      * @param classname the classname of the SQL manager
284      * 
285      * @return the SQL manager for this driver
286      */
287     org.opencms.db.generic.CmsSqlManager initSqlManager(String   classname);
288 
289     /**
290      * Publish all access control entries of a resource from the given offline project to the online project.<p>
291      * 
292      * Within the given project, the resource is identified by its offlineId, in the online project,
293      * it is identified by the given onlineId.<p>
294      * 
295      * @param dbc the current database context
296      * @param offlineProject an offline project
297      * @param onlineProject the onlie project
298      * @param offlineId the offline resource id
299      * @param onlineId the online resource id
300      * 
301      * @throws CmsDataAccessException if something goes wrong
302      */
303     void publishAccessControlEntries(
304         CmsDbContext dbc,
305         CmsProject offlineProject,
306         CmsProject onlineProject,
307         CmsUUID offlineId,
308         CmsUUID onlineId) throws CmsDataAccessException;
309 
310     /**
311      * Reads all relevant access control entries for a given resource.<p>
312      * 
313      * @param dbc the current database context
314      * @param project the project to write the entry
315      * @param resource the id of the resource
316      * @param inheritedOnly flag to indicate that only inherited entries should be returned
317      * 
318      * @return a list of <code>{@link CmsAccessControlEntry}</code> objects defining all permissions for the given resource
319      * 
320      * @throws CmsDataAccessException if something goes wrong
321      */
322     List   readAccessControlEntries(CmsDbContext dbc, CmsProject project, CmsUUID resource, boolean inheritedOnly)
323     throws CmsDataAccessException;
324 
325     /**
326      * Reads an access control entry for a given principal that is attached to a resource.<p>
327      * 
328      * @param dbc the current database context
329      * @param project the project to write the entry
330      * @param resource the id of the resource
331      * @param principal the id of the principal
332      * 
333      * @return an access control entry that defines the permissions of the principal for the given resource
334      * @throws CmsDataAccessException if something goes wrong
335      */
336     CmsAccessControlEntry readAccessControlEntry(
337         CmsDbContext dbc,
338         CmsProject project,
339         CmsUUID resource,
340         CmsUUID principal) throws CmsDataAccessException;
341 
342     /**
343      * Reads all child groups of a group.<p>
344      *
345      * @param dbc the current database context
346      * @param groupname the name of the group to read the child groups from
347      * 
348      * @return a list of all child <code>{@link CmsGroup}</code> objects or <code>null</code>
349      * 
350      * @throws CmsDataAccessException if operation was not succesful
351      */
352     List   readChildGroups(CmsDbContext dbc, String   groupname) throws CmsDataAccessException;
353 
354     /**
355      * Reads a group based on the group id.<p>
356      * 
357      * @param dbc the current database context
358      * @param groupId the id of the group that is to be read
359      * 
360      * @return the group that was read
361      * 
362      * @throws CmsDataAccessException if something goes wrong
363      */
364     CmsGroup readGroup(CmsDbContext dbc, CmsUUID groupId) throws CmsDataAccessException;
365 
366     /**
367      * Reads a group based on the group name.<p>
368      * 
369      * @param dbc the current database context
370      * @param groupName the name of the group that is to be read
371      * 
372      * @return the group that was read
373      * 
374      * @throws CmsDataAccessException if something goes wrong
375      */
376     CmsGroup readGroup(CmsDbContext dbc, String   groupName) throws CmsDataAccessException;
377 
378     /**
379      * Reads all existing groups.<p>
380      *
381      * @param dbc the current database context
382      * 
383      * @return a list of all <code>{@link CmsGroup}</code> objects
384      * 
385      * @throws CmsDataAccessException if something goes wrong
386      */
387     List   readGroups(CmsDbContext dbc) throws CmsDataAccessException;
388 
389     /**
390      * Reads all groups the given user is a member in.<p>
391      *
392      * @param dbc the current database context
393      * @param userId the id of the user
394      * @param paramStr additional parameter
395      * 
396      * @return a list of <code>{@link CmsGroup}</code> objects
397      * 
398      * @throws CmsDataAccessException if something goes wrong
399      */
400     List   readGroupsOfUser(CmsDbContext dbc, CmsUUID userId, String   paramStr) throws CmsDataAccessException;
401 
402     /**
403      * Reads a user based on the user id.<p>
404      * 
405      * @param dbc the current database context
406      * @param id the id of the user to read
407      *
408      * @return the user that was read
409      * 
410      * @throws CmsDataAccessException if something goes wrong
411      */
412     CmsUser readUser(CmsDbContext dbc, CmsUUID id) throws CmsDataAccessException;
413 
414     /**
415      * Reads a user based in the user name and user type.<p>
416      * 
417      * @param dbc the current database context
418      * @param name the name of the user to read
419      * @param type the type of the user to read
420      *
421      * @return the user that was read
422      * 
423      * @throws CmsDataAccessException if something goes wrong
424      */
425     CmsUser readUser(CmsDbContext dbc, String   name, int type) throws CmsDataAccessException;
426 
427     /**
428      * Reads a user from the database, only if the password is correct.<p>
429      *
430      * If the user/pwd pair is not valid a <code>{@link CmsDataAccessException}</code> is thrown.<p>
431      * 
432      * @param dbc the current database context
433      * @param name the name of the user
434      * @param password the password of the user
435      * @param type the type of the user
436      * 
437      * @return the user that was read
438      * 
439      * @throws CmsDataAccessException if something goes wrong
440      * @throws CmsPasswordEncryptionException if the password of the user could not be encrypted
441      */
442     CmsUser readUser(CmsDbContext dbc, String   name, String   password, int type)
443     throws CmsDataAccessException, CmsPasswordEncryptionException;
444 
445     /**
446      * Reads a user from the database, only if the password is correct.<p>
447      *
448      * @param dbc the current database context
449      * @param name the name of the user
450      * @param password the password of the user
451      * @param remoteAddress the remote address of the request
452      * @param type the type of the user
453      * 
454      * @return the user that was read
455      * 
456      * @throws CmsDataAccessException if something goes wrong
457      * @throws CmsPasswordEncryptionException if the password of the user could not be encrypted
458      */
459     CmsUser readUser(CmsDbContext dbc, String   name, String   password, String   remoteAddress, int type)
460     throws CmsDataAccessException, CmsPasswordEncryptionException;
461 
462     /**
463      * Reads all existing users of the given type.<p>
464      *
465      * @param dbc the current database context
466      * @param type the type to read the users for
467      * 
468      * @return a list of all <code>{@link CmsUser}</code> objects of the given type
469      * 
470      * @throws CmsDataAccessException if something goes wrong
471      */
472     List   readUsers(CmsDbContext dbc, int type) throws CmsDataAccessException;
473 
474     /**
475      * Reads all users that are members of the given group.<p>
476      *
477      * @param dbc the current database context
478      * @param name the name of the group to read the users from
479      * @param type the type of the users to read
480      * 
481      * @return all <code>{@link CmsUser}</code> objects in the group
482      * 
483      * @throws CmsDataAccessException if something goes wrong
484      */
485     List   readUsersOfGroup(CmsDbContext dbc, String   name, int type) throws CmsDataAccessException;
486 
487     /**
488      * Removes all access control entries belonging to a resource.<p>
489      * 
490      * @param dbc the current database context
491      * @param project the project to write the entry
492      * @param resource the id of the resource
493      * 
494      * @throws CmsDataAccessException if something goes wrong
495      */
496     void removeAccessControlEntries(CmsDbContext dbc, CmsProject project, CmsUUID resource)
497     throws CmsDataAccessException;
498 
499     /**
500      * Removes all access control entries belonging to a principal.<p>
501      * 
502      * @param dbc the current database context
503      * @param project the project to write the entry
504      * @param onlineProject the online project 
505      * @param principal the id of the principal
506      * 
507      * @throws CmsDataAccessException if something goes wrong
508      */
509     void removeAccessControlEntriesForPrincipal(
510         CmsDbContext dbc,
511         CmsProject project,
512         CmsProject onlineProject,
513         CmsUUID principal) throws CmsDataAccessException;
514 
515     /**
516      * Removes an access control entry.<p>
517      * 
518      * @param dbc the current database context
519      * @param project the project to write the entry
520      * @param resource the id of the resource
521      * @param principal the id of the principal
522      * 
523      * @throws CmsDataAccessException if something goes wrong
524      */
525     void removeAccessControlEntry(CmsDbContext dbc, CmsProject project, CmsUUID resource, CmsUUID principal)
526     throws CmsDataAccessException;
527 
528     /**
529      * Writes an access control entry.<p>
530      * 
531      * @param dbc the current database context
532      * @param project the project to write the entry
533      * @param acEntry the entry to write
534      * 
535      * @throws CmsDataAccessException if something goes wrong
536      */
537     void writeAccessControlEntry(CmsDbContext dbc, CmsProject project, CmsAccessControlEntry acEntry)
538     throws CmsDataAccessException;
539 
540     /**
541      * Writes an already existing group.<p>
542      *
543      * The group id has to be a valid OpenCms group id.<br>
544      * 
545      * The group with the given id will be completely overriden
546      * by the given data.<p>
547      * 
548      * @param dbc the current database context
549      * @param group the group to update
550      *
551      * @throws CmsDataAccessException if something goes wrong
552      */
553     void writeGroup(CmsDbContext dbc, CmsGroup group) throws CmsDataAccessException;
554 
555     /**
556      * Sets a new password for a user.<p>
557      * 
558      * @param dbc the current database context
559      * @param userName the user to set the password for
560      * @param type the type of the user
561      * @param oldPassword the current password
562      * @param newPassword the password to set
563      *
564      * @throws CmsDataAccessException if something goes wrong
565      * @throws CmsPasswordEncryptionException if the (new) password could not be encrypted
566      */
567     void writePassword(CmsDbContext dbc, String   userName, int type, String   oldPassword, String   newPassword)
568     throws CmsDataAccessException, CmsPasswordEncryptionException;
569 
570     /**
571      * Updates the user information. <p>
572      * 
573      * The user id has to be a valid OpenCms user id.<br>
574      * 
575      * The user with the given id will be completely overriden
576      * by the given data.<p>
577      *
578      * @param dbc the current database context
579      * @param user the user to update
580      *
581      * @throws CmsDataAccessException if something goes wrong
582      */
583     void writeUser(CmsDbContext dbc, CmsUser user) throws CmsDataAccessException;
584 
585     /**
586      * Changes the user type of the given user.<p>
587      * 
588      * @param dbc the current database context
589      * @param userId the id of the user to change
590      * @param userType the new type of the user
591      *
592      * @throws CmsDataAccessException if something goes wrong
593      */
594     void writeUserType(CmsDbContext dbc, CmsUUID userId, int userType) throws CmsDataAccessException;
595 
596 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags