001: /*
002: * File : $Source: /usr/local/cvs/opencms/src/org/opencms/db/I_CmsUserDriver.java,v $
003: * Date : $Date: 2008-02-27 12:05:42 $
004: * Version: $Revision: 1.62 $
005: *
006: * This library is part of OpenCms -
007: * the Open Source Content Management System
008: *
009: * Copyright (c) 2002 - 2008 Alkacon Software GmbH (http://www.alkacon.com)
010: *
011: * This library is free software; you can redistribute it and/or
012: * modify it under the terms of the GNU Lesser General Public
013: * License as published by the Free Software Foundation; either
014: * version 2.1 of the License, or (at your option) any later version.
015: *
016: * This library is distributed in the hope that it will be useful,
017: * but WITHOUT ANY WARRANTY; without even the implied warranty of
018: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: * Lesser General Public License for more details.
020: *
021: * For further information about Alkacon Software GmbH, please see the
022: * company website: http://www.alkacon.com
023: *
024: * For further information about OpenCms, please see the
025: * project website: http://www.opencms.org
026: *
027: * You should have received a copy of the GNU Lesser General Public
028: * License along with this library; if not, write to the Free Software
029: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
030: */
031:
032: package org.opencms.db;
033:
034: import org.opencms.db.generic.CmsSqlManager;
035: import org.opencms.file.CmsDataAccessException;
036: import org.opencms.file.CmsGroup;
037: import org.opencms.file.CmsProject;
038: import org.opencms.file.CmsResource;
039: import org.opencms.file.CmsUser;
040: import org.opencms.main.CmsInitException;
041: import org.opencms.security.CmsAccessControlEntry;
042: import org.opencms.security.CmsOrganizationalUnit;
043: import org.opencms.security.CmsPasswordEncryptionException;
044: import org.opencms.util.CmsUUID;
045:
046: import java.util.List;
047: import java.util.Map;
048:
049: /**
050: * Definitions of all required user driver methods. <p>
051: *
052: * @author Thomas Weckert
053: * @author Michael Emmerich
054: *
055: * @version $Revision: 1.62 $
056: *
057: * @since 6.0.0
058: */
059: public interface I_CmsUserDriver extends I_CmsDriver {
060:
061: /** The type ID to identify user driver implementations. */
062: int DRIVER_TYPE_ID = 2;
063:
064: /**
065: * Adds a resource to the given organizational unit.<p>
066: *
067: * @param dbc the current db context
068: * @param orgUnit the organizational unit to add the resource to
069: * @param resource the resource that is to be added to the organizational unit
070: *
071: * @throws CmsDataAccessException if something goes wrong
072: */
073: void addResourceToOrganizationalUnit(CmsDbContext dbc,
074: CmsOrganizationalUnit orgUnit, CmsResource resource)
075: throws CmsDataAccessException;
076:
077: /**
078: * Creates an access control entry.<p>
079: *
080: * @param dbc the current database context
081: * @param project the project to write the entry
082: * @param resource the id of the resource
083: * @param principal the id of the principal (user or group)
084: * @param allowed the bitset of allowed permissions
085: * @param denied the bitset of denied permissions
086: * @param flags flags
087: *
088: * @throws CmsDataAccessException if something goes wrong
089: */
090: void createAccessControlEntry(CmsDbContext dbc, CmsProject project,
091: CmsUUID resource, CmsUUID principal, int allowed,
092: int denied, int flags) throws CmsDataAccessException;
093:
094: /**
095: * Creates a new group.<p>
096: *
097: * @param dbc the current database context
098: * @param groupId the id of the new group
099: * @param groupFqn the fully qualified name of the new group
100: * @param description The description for the new group
101: * @param flags the flags for the new group
102: * @param parentGroupName the name of the parent group (or null if the group has no parent)
103: *
104: * @return the created group
105: * @throws CmsDataAccessException if something goes wrong
106: */
107: CmsGroup createGroup(CmsDbContext dbc, CmsUUID groupId,
108: String groupFqn, String description, int flags,
109: String parentGroupName) throws CmsDataAccessException;
110:
111: /**
112: * Creates a new organizational unit.<p>
113: *
114: * @param dbc the current db context
115: * @param name the name of the new organizational unit
116: * @param description the description of the new organizational unit
117: * @param flags the flags for the new organizational unit
118: * @param parent the parent organizational unit (or <code>null</code>)
119: * @param associationRootPath the first associated resource
120: *
121: * @return a <code>{@link CmsOrganizationalUnit}</code> object representing
122: * the newly created organizational unit
123: *
124: * @throws CmsDataAccessException if operation was not successful
125: */
126: CmsOrganizationalUnit createOrganizationalUnit(CmsDbContext dbc,
127: String name, String description, int flags,
128: CmsOrganizationalUnit parent, String associationRootPath)
129: throws CmsDataAccessException;
130:
131: /**
132: * Creates the default root organizational unit.<p>
133: *
134: * @param dbc the current database context
135: */
136: void createRootOrganizationalUnit(CmsDbContext dbc);
137:
138: /**
139: * Creates a new user.<p>
140: *
141: * @param dbc the current database context
142: * @param id the id of the user
143: * @param userFqn the fully qualified name of the new user
144: * @param password the already encripted user password
145: * @param firstname the user firstname
146: * @param lastname the user lastname
147: * @param email the user email
148: * @param lastlogin the user lastlogin time
149: * @param flags the user flags
150: * @param dateCreated the creation date
151: * @param additionalInfos the user additional infos
152: *
153: * @return the created user
154: *
155: * @throws CmsDataAccessException if something goes wrong
156: */
157: CmsUser createUser(CmsDbContext dbc, CmsUUID id, String userFqn,
158: String password, String firstname, String lastname,
159: String email, long lastlogin, int flags, long dateCreated,
160: Map additionalInfos) throws CmsDataAccessException;
161:
162: /**
163: * Adds a user to a group.<p>
164: *
165: * @param dbc the current database context
166: * @param userid the id of the user that is to be added to the group
167: * @param groupid the id of the group
168: *
169: * @throws CmsDataAccessException if operation was not successful
170: */
171: void createUserInGroup(CmsDbContext dbc, CmsUUID userid,
172: CmsUUID groupid) throws CmsDataAccessException;
173:
174: /**
175: * Deletes all access control entries (ACEs) belonging to a resource.<p>
176: *
177: * @param dbc the current database context
178: * @param project the project to delete the ACEs in
179: * @param resource the id of the resource to delete the ACEs from
180: *
181: * @throws CmsDataAccessException if something goes wrong
182: *
183: * @deprecated use {@link #removeAccessControlEntries(CmsDbContext, CmsProject, CmsUUID)} instead
184: */
185: void deleteAccessControlEntries(CmsDbContext dbc,
186: CmsProject project, CmsUUID resource)
187: throws CmsDataAccessException;
188:
189: /**
190: * Deletes a group.<p>
191: *
192: * Only groups that contain no subgroups can be deleted.<p>
193: *
194: * @param dbc the current database context
195: * @param groupFqn the fully qualified name of the group that is to be deleted
196: *
197: * @throws CmsDataAccessException if something goes wrong
198: */
199: void deleteGroup(CmsDbContext dbc, String groupFqn)
200: throws CmsDataAccessException;
201:
202: /**
203: * Deletes an organizational unit.<p>
204: *
205: * Only organizational units that contain no suborganizational unit can be deleted.<p>
206: *
207: * @param dbc the current db context
208: * @param organizationalUnit the organizational unit to delete
209: *
210: * @throws CmsDataAccessException if operation was not successful
211: */
212: void deleteOrganizationalUnit(CmsDbContext dbc,
213: CmsOrganizationalUnit organizationalUnit)
214: throws CmsDataAccessException;
215:
216: /**
217: * Deletes a user.<p>
218: *
219: * @param dbc the current database context
220: * @param userFqn the fully qualified name of the user to delete
221: *
222: * @throws CmsDataAccessException if something goes wrong
223: */
224: void deleteUser(CmsDbContext dbc, String userFqn)
225: throws CmsDataAccessException;
226:
227: /**
228: * Deletes the user additional information table.<p>
229: *
230: * @param dbc the current database context
231: * @param userId the id of the user to update
232: *
233: * @throws CmsDataAccessException if something goes wrong
234: */
235: void deleteUserInfos(CmsDbContext dbc, CmsUUID userId)
236: throws CmsDataAccessException;
237:
238: /**
239: * Removes a user from a group.<p>
240: *
241: * @param dbc the current database context
242: * @param userId the id of the user that is to be removed from the group
243: * @param groupId the id of the group
244: *
245: * @throws CmsDataAccessException if something goes wrong
246: */
247: void deleteUserInGroup(CmsDbContext dbc, CmsUUID userId,
248: CmsUUID groupId) throws CmsDataAccessException;
249:
250: /**
251: * Destroys this driver.<p>
252: *
253: * @throws Throwable if something goes wrong
254: */
255: void destroy() throws Throwable;
256:
257: /**
258: * Tests if a group with the specified name exists.<p>
259: *
260: * @param dbc the current database context
261: * @param groupFqn the fully qualified group name to be checked
262: *
263: * @return <code>true</code>, if a group with the specified name exists, <code>false</code> otherwise
264: *
265: * @throws CmsDataAccessException if something goes wrong
266: */
267: boolean existsGroup(CmsDbContext dbc, String groupFqn)
268: throws CmsDataAccessException;
269:
270: /**
271: * Tests if a user with the specified name exists.<p>
272: *
273: * @param dbc the current database context
274: * @param userFqn the fully qualified name of the user to be checked
275: *
276: * @return true, if a user with the specified name exists, false otherwise
277: * @throws CmsDataAccessException if something goes wrong
278: */
279: boolean existsUser(CmsDbContext dbc, String userFqn)
280: throws CmsDataAccessException;
281:
282: /**
283: * Initializes the default organizational units, users and groups.<p>
284: *
285: * @param dbc the current database context, be aware that this dbc has no runtime data!
286: *
287: * @throws CmsInitException if something goes wrong
288: */
289: void fillDefaults(CmsDbContext dbc) throws CmsInitException;
290:
291: /**
292: * Returns all groups of the given organizational unit.<p>
293: *
294: * @param dbc the current db context
295: * @param orgUnit the organizational unit to get all groups for
296: * @param includeSubOus flag to signalize the retrieval of groups of sub-organizational units too
297: * @param readRoles if to read roles or groups
298: *
299: * @return all <code>{@link CmsGroup}</code> objects in the organizational unit
300: *
301: * @throws CmsDataAccessException if operation was not successful
302: */
303: List getGroups(CmsDbContext dbc, CmsOrganizationalUnit orgUnit,
304: boolean includeSubOus, boolean readRoles)
305: throws CmsDataAccessException;
306:
307: /**
308: * Returns all child organizational units of the given parent organizational unit including
309: * hierarchical deeper organization units if needed.<p>
310: *
311: * @param dbc the current db context
312: * @param parent the parent organizational unit, or <code>null</code> for the root
313: * @param includeChildren if hierarchical deeper organization units should also be returned
314: *
315: * @return a list of <code>{@link CmsOrganizationalUnit}</code> objects
316: *
317: * @throws CmsDataAccessException if operation was not succesful
318: */
319: List getOrganizationalUnits(CmsDbContext dbc,
320: CmsOrganizationalUnit parent, boolean includeChildren)
321: throws CmsDataAccessException;
322:
323: /**
324: * Returns all resources of the given organizational unit.<p>
325: *
326: * @param dbc the current db context
327: * @param orgUnit the organizational unit to get all resources for
328: *
329: * @return all <code>{@link CmsResource}</code> objects in the organizational unit
330: *
331: * @throws CmsDataAccessException if operation was not successful
332: */
333: List getResourcesForOrganizationalUnit(CmsDbContext dbc,
334: CmsOrganizationalUnit orgUnit)
335: throws CmsDataAccessException;
336:
337: /**
338: * Returns the SqlManager of this driver.<p>
339: *
340: * @return the SqlManager of this driver
341: */
342: CmsSqlManager getSqlManager();
343:
344: /**
345: * Returns all users of the given organizational unit.<p>
346: *
347: * @param dbc the current db context
348: * @param orgUnit the organizational unit to get all users for
349: * @param recursive flag to signalize the retrieval of users of sub-organizational units too
350: *
351: * @return all <code>{@link CmsUser}</code> objects in the organizational unit
352: *
353: * @throws CmsDataAccessException if operation was not successful
354: */
355: List getUsers(CmsDbContext dbc, CmsOrganizationalUnit orgUnit,
356: boolean recursive) throws CmsDataAccessException;
357:
358: /**
359: * Initializes the SQL manager for this driver.<p>
360: *
361: * To obtain JDBC connections from different pools, further
362: * {online|offline|history} pool Urls have to be specified.<p>
363: *
364: * @param classname the classname of the SQL manager
365: *
366: * @return the SQL manager for this driver
367: */
368: org.opencms.db.generic.CmsSqlManager initSqlManager(String classname);
369:
370: /**
371: * Publish all access control entries of a resource from the given offline project to the online project.<p>
372: *
373: * Within the given project, the resource is identified by its offlineId, in the online project,
374: * it is identified by the given onlineId.<p>
375: *
376: * @param dbc the current database context
377: * @param offlineProject an offline project
378: * @param onlineProject the onlie project
379: * @param offlineId the offline resource id
380: * @param onlineId the online resource id
381: *
382: * @throws CmsDataAccessException if something goes wrong
383: */
384: void publishAccessControlEntries(CmsDbContext dbc,
385: CmsProject offlineProject, CmsProject onlineProject,
386: CmsUUID offlineId, CmsUUID onlineId)
387: throws CmsDataAccessException;
388:
389: /**
390: * Reads all relevant access control entries for a given resource.<p>
391: *
392: * @param dbc the current database context
393: * @param project the project to write the entry
394: * @param resource the id of the resource
395: * @param inheritedOnly flag to indicate that only inherited entries should be returned
396: *
397: * @return a list of <code>{@link CmsAccessControlEntry}</code> objects defining all permissions for the given resource
398: *
399: * @throws CmsDataAccessException if something goes wrong
400: */
401: List readAccessControlEntries(CmsDbContext dbc, CmsProject project,
402: CmsUUID resource, boolean inheritedOnly)
403: throws CmsDataAccessException;
404:
405: /**
406: * Reads an access control entry for a given principal that is attached to a resource.<p>
407: *
408: * @param dbc the current database context
409: * @param project the project to write the entry
410: * @param resource the id of the resource
411: * @param principal the id of the principal
412: *
413: * @return an access control entry that defines the permissions of the principal for the given resource
414: *
415: * @throws CmsDataAccessException if something goes wrong
416: */
417: CmsAccessControlEntry readAccessControlEntry(CmsDbContext dbc,
418: CmsProject project, CmsUUID resource, CmsUUID principal)
419: throws CmsDataAccessException;
420:
421: /**
422: * Reads all child groups of a group.<p>
423: *
424: * @param dbc the current database context
425: * @param groupFqn the fully qualified name of the group to read the child groups from
426: *
427: * @return a list of all child <code>{@link CmsGroup}</code> objects or <code>null</code>
428: *
429: * @throws CmsDataAccessException if operation was not succesful
430: */
431: List readChildGroups(CmsDbContext dbc, String groupFqn)
432: throws CmsDataAccessException;
433:
434: /**
435: * Reads a group based on the group id.<p>
436: *
437: * @param dbc the current database context
438: * @param groupId the id of the group that is to be read
439: *
440: * @return the group that was read
441: *
442: * @throws CmsDataAccessException if something goes wrong
443: */
444: CmsGroup readGroup(CmsDbContext dbc, CmsUUID groupId)
445: throws CmsDataAccessException;
446:
447: /**
448: * Reads a group based on the group name.<p>
449: *
450: * @param dbc the current database context
451: * @param groupFqn the fully qualified name of the group that is to be read
452: *
453: * @return the group that was read
454: *
455: * @throws CmsDataAccessException if something goes wrong
456: */
457: CmsGroup readGroup(CmsDbContext dbc, String groupFqn)
458: throws CmsDataAccessException;
459:
460: /**
461: * Reads all groups the given user is a member in.<p>
462: *
463: * @param dbc the current database context
464: * @param userId the id of the user
465: * @param ouFqn the fully qualified name of the organizational unit to restrict the result set for
466: * @param includeChildOus include groups of child organizational units
467: * @param remoteAddress the IP address to filter the groups in the result list
468: * @param readRoles if to read roles or groups
469: *
470: * @return a list of <code>{@link CmsGroup}</code> objects
471: *
472: * @throws CmsDataAccessException if something goes wrong
473: */
474: List readGroupsOfUser(CmsDbContext dbc, CmsUUID userId,
475: String ouFqn, boolean includeChildOus,
476: String remoteAddress, boolean readRoles)
477: throws CmsDataAccessException;
478:
479: /**
480: * Reads an organizational Unit based on its fully qualified name.<p>
481: *
482: * @param dbc the current db context
483: * @param ouFqn the fully qualified name of the organizational Unit to be read
484: *
485: * @return the organizational Unit with the provided fully qualified name
486: *
487: * @throws CmsDataAccessException if something goes wrong
488: */
489: CmsOrganizationalUnit readOrganizationalUnit(CmsDbContext dbc,
490: String ouFqn) throws CmsDataAccessException;
491:
492: /**
493: * Reads a user based on the user id.<p>
494: *
495: * @param dbc the current database context
496: * @param id the id of the user to read
497: *
498: * @return the user that was read
499: *
500: * @throws CmsDataAccessException if something goes wrong
501: */
502: CmsUser readUser(CmsDbContext dbc, CmsUUID id)
503: throws CmsDataAccessException;
504:
505: /**
506: * Reads a user based in the user fully qualified name.<p>
507: *
508: * @param dbc the current database context
509: * @param userFqn the fully qualified name of the user to read
510: *
511: * @return the user that was read
512: *
513: * @throws CmsDataAccessException if something goes wrong
514: */
515: CmsUser readUser(CmsDbContext dbc, String userFqn)
516: throws CmsDataAccessException;
517:
518: /**
519: * Reads a user from the database, only if the password is correct.<p>
520: *
521: * @param dbc the current database context
522: * @param userFqn the name of the user
523: * @param password the password of the user
524: * @param remoteAddress the remote address of the request, may be <code>null</code>
525: *
526: * @return the user that was read
527: *
528: * @throws CmsDataAccessException if something goes wrong
529: * @throws CmsPasswordEncryptionException if the password of the user could not be encrypted
530: */
531: CmsUser readUser(CmsDbContext dbc, String userFqn, String password,
532: String remoteAddress) throws CmsDataAccessException,
533: CmsPasswordEncryptionException;
534:
535: /**
536: * Reads the user additional information map.<p>
537: *
538: * @param dbc the current database context
539: * @param userId the id of the user to update
540: *
541: * @return the user additional information map
542: *
543: * @throws CmsDataAccessException if something goes wrong
544: */
545: Map readUserInfos(CmsDbContext dbc, CmsUUID userId)
546: throws CmsDataAccessException;
547:
548: /**
549: * Reads all users that are members of the given group.<p>
550: *
551: * @param dbc the current database context
552: * @param groupFqn the fully qualified name of the group to read the users from
553: * @param includeOtherOuUsers include users of other organizational units
554: *
555: * @return all <code>{@link CmsUser}</code> objects in the group
556: *
557: * @throws CmsDataAccessException if something goes wrong
558: */
559: List readUsersOfGroup(CmsDbContext dbc, String groupFqn,
560: boolean includeOtherOuUsers) throws CmsDataAccessException;
561:
562: /**
563: * Removes all access control entries belonging to a resource.<p>
564: *
565: * @param dbc the current database context
566: * @param project the project to write the entry
567: * @param resource the id of the resource
568: *
569: * @throws CmsDataAccessException if something goes wrong
570: */
571: void removeAccessControlEntries(CmsDbContext dbc,
572: CmsProject project, CmsUUID resource)
573: throws CmsDataAccessException;
574:
575: /**
576: * Removes all access control entries belonging to a principal.<p>
577: *
578: * @param dbc the current database context
579: * @param project the project to write the entry
580: * @param onlineProject the online project
581: * @param principal the id of the principal
582: *
583: * @throws CmsDataAccessException if something goes wrong
584: */
585: void removeAccessControlEntriesForPrincipal(CmsDbContext dbc,
586: CmsProject project, CmsProject onlineProject,
587: CmsUUID principal) throws CmsDataAccessException;
588:
589: /**
590: * Removes an access control entry.<p>
591: *
592: * @param dbc the current database context
593: * @param project the project to write the entry
594: * @param resource the id of the resource
595: * @param principal the id of the principal
596: *
597: * @throws CmsDataAccessException if something goes wrong
598: */
599: void removeAccessControlEntry(CmsDbContext dbc, CmsProject project,
600: CmsUUID resource, CmsUUID principal)
601: throws CmsDataAccessException;
602:
603: /**
604: * Removes a resource from the given organizational unit.<p>
605: *
606: * @param dbc the current db context
607: * @param orgUnit the organizational unit to remove the resource from
608: * @param resource the resource that is to be removed from the organizational unit
609: *
610: * @throws CmsDataAccessException if something goes wrong
611: */
612: void removeResourceFromOrganizationalUnit(CmsDbContext dbc,
613: CmsOrganizationalUnit orgUnit, CmsResource resource)
614: throws CmsDataAccessException;
615:
616: /**
617: * Moves an user to the given organizational unit.<p>
618: *
619: * @param dbc the current db context
620: * @param orgUnit the organizational unit to move the user to
621: * @param user the user that is to be moved to the given organizational unit
622: *
623: * @throws CmsDataAccessException if something goes wrong
624: */
625: void setUsersOrganizationalUnit(CmsDbContext dbc,
626: CmsOrganizationalUnit orgUnit, CmsUser user)
627: throws CmsDataAccessException;
628:
629: /**
630: * Writes an access control entry.<p>
631: *
632: * @param dbc the current database context
633: * @param project the project to write the entry
634: * @param acEntry the entry to write
635: *
636: * @throws CmsDataAccessException if something goes wrong
637: */
638: void writeAccessControlEntry(CmsDbContext dbc, CmsProject project,
639: CmsAccessControlEntry acEntry)
640: throws CmsDataAccessException;
641:
642: /**
643: * Writes an already existing group.<p>
644: *
645: * The group id has to be a valid OpenCms group id.<br>
646: *
647: * The group with the given id will be completely overriden
648: * by the given data.<p>
649: *
650: * @param dbc the current database context
651: * @param group the group to update
652: *
653: * @throws CmsDataAccessException if something goes wrong
654: */
655: void writeGroup(CmsDbContext dbc, CmsGroup group)
656: throws CmsDataAccessException;
657:
658: /**
659: * Writes an already existing organizational unit.<p>
660: *
661: * The organizational unit id has to be a valid OpenCms organizational unit id.<br>
662: *
663: * The organizational unit with the given id will be completely overriden
664: * by the given data.<p>
665: *
666: * @param dbc the current db context
667: * @param organizationalUnit the organizational unit that should be written
668: *
669: * @throws CmsDataAccessException if operation was not successful
670: */
671: void writeOrganizationalUnit(CmsDbContext dbc,
672: CmsOrganizationalUnit organizationalUnit)
673: throws CmsDataAccessException;
674:
675: /**
676: * Sets a new password for a user.<p>
677: *
678: * @param dbc the current database context
679: * @param userFqn the fullyqualified name of the user to set the password for
680: * @param oldPassword the current password
681: * @param newPassword the password to set
682: *
683: * @throws CmsDataAccessException if something goes wrong
684: * @throws CmsPasswordEncryptionException if the (new) password could not be encrypted
685: */
686: void writePassword(CmsDbContext dbc, String userFqn,
687: String oldPassword, String newPassword)
688: throws CmsDataAccessException,
689: CmsPasswordEncryptionException;
690:
691: /**
692: * Updates the user information. <p>
693: *
694: * The user id has to be a valid OpenCms user id.<p>
695: *
696: * The user with the given id will be completely overriden
697: * by the given data.<p>
698: *
699: * @param dbc the current database context
700: * @param user the user to update
701: *
702: * @throws CmsDataAccessException if something goes wrong
703: */
704: void writeUser(CmsDbContext dbc, CmsUser user)
705: throws CmsDataAccessException;
706:
707: /**
708: * Writes an user additional information entry.<p>
709: *
710: * @param dbc the current database context
711: * @param userId the id of the user to update
712: * @param key the key of the info to write
713: * @param value the value of the info to write
714: *
715: * @throws CmsDataAccessException if something goes wrong
716: */
717: void writeUserInfo(CmsDbContext dbc, CmsUUID userId, String key,
718: Object value) throws CmsDataAccessException;
719: }
|