001 //$HeadURL: svn+ssh://rbezema@svn.wald.intevation.org/deegree/base/branches/2.2_testing/src/org/deegree/security/drm/SecurityRegistry.java $
002 /*---------------- FILE HEADER ------------------------------------------
003
004 This file is part of deegree.
005 Copyright (C) 2001-2008 by:
006 EXSE, Department of Geography, University of Bonn
007 http://www.giub.uni-bonn.de/deegree/
008 lat/lon GmbH
009 http://www.lat-lon.de
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 You should have received a copy of the GNU Lesser General Public
022 License along with this library; if not, write to the Free Software
023 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024
025 Contact:
026
027 Andreas Poth
028 lat/lon GmbH
029 Aennchenstr. 19
030 53115 Bonn
031 Germany
032 E-Mail: poth@lat-lon.de
033
034 Prof. Dr. Klaus Greve
035 Department of Geography
036 University of Bonn
037 Meckenheimer Allee 166
038 53115 Bonn
039 Germany
040 E-Mail: greve@giub.uni-bonn.de
041
042 ---------------------------------------------------------------------------*/
043 package org.deegree.security.drm;
044
045 import java.util.Properties;
046
047 import org.deegree.security.GeneralSecurityException;
048 import org.deegree.security.drm.model.Group;
049 import org.deegree.security.drm.model.Privilege;
050 import org.deegree.security.drm.model.Right;
051 import org.deegree.security.drm.model.RightType;
052 import org.deegree.security.drm.model.Role;
053 import org.deegree.security.drm.model.SecurableObject;
054 import org.deegree.security.drm.model.SecuredObject;
055 import org.deegree.security.drm.model.User;
056
057
058 /**
059 * This is an interface for datastores that are able to stores the following
060 * object types and their relations:
061 * <ul>
062 * <li><code>User</code>
063 * <li><code>Group</code>
064 * <li><code>Role</code>
065 * <li><code>SecurableObject</code>
066 * <li><code>Right / RightType</code>
067 * <li><code>Privilege</code>
068 * </ul>
069 *
070 * @author <a href="mailto:mschneider@lat-lon.de">Markus Schneider </a>
071 * @version $Revision: 9346 $
072 */
073 public interface SecurityRegistry {
074
075 /**
076 * Initializes the <code>Registry</code> -instance according to the
077 * contents of the submitted <code>Properties</code>.
078 * <p>
079 * The supported keys and values depend on the concrete implementation.
080 *
081 * @param properties
082 * @throws GeneralSecurityException
083 */
084 void initialize(Properties properties) throws GeneralSecurityException;
085
086 /**
087 * Signals the <code>Registry</code> that a new transaction starts.
088 * <p>
089 * Only one transaction can be active at a time.
090 * @param transaction
091 *
092 * @throws GeneralSecurityException
093 */
094 void beginTransaction(SecurityTransaction transaction) throws GeneralSecurityException;
095
096 /**
097 * Signals the <code>Registry</code> that the current transaction ends.
098 * Changes made during the transaction are now made persistent.
099 * @param transaction
100 *
101 * @throws GeneralSecurityException
102 */
103 void commitTransaction(SecurityTransaction transaction) throws GeneralSecurityException;
104
105 /**
106 * Signals the <code>Registry</code> that the transaction shall be
107 * aborted. Changes made by the transaction are undone.
108 * @param transaction
109 *
110 * @throws GeneralSecurityException
111 */
112 void abortTransaction(SecurityTransaction transaction) throws GeneralSecurityException;
113
114 /**
115 * Deletes all data from the <code>Registry</code> and sets the default
116 * objects (SEC_ADMIN user, role and group) and standard rights and
117 * privileges.
118 *
119 * @param transaction
120 * @throws GeneralSecurityException
121 */
122 void clean(SecurityTransaction transaction) throws GeneralSecurityException;
123
124 /**
125 * Adds a new User-account to the <code>Registry</code>.
126 * @param transaction
127 * @param name
128 * @param password
129 * @param lastName
130 * @param firstName
131 * @param mailAddress
132 * @return
133 *
134 * @throws GeneralSecurityException
135 * this is a <code>DuplicateException</code> if the group
136 * already existed
137 */
138 User registerUser(SecurityTransaction transaction, String name, String password,
139 String lastName, String firstName, String mailAddress)
140 throws GeneralSecurityException;
141
142 /**
143 * Removes an existing <code>User<code> from the <code>Registry</code>.
144 * @param transaction
145 * @param user
146 *
147 * @throws GeneralSecurityException
148 */
149 void deregisterUser(SecurityTransaction transaction, User user)
150 throws GeneralSecurityException;
151
152 /**
153 * Updates the metadata (name, email, etc.) of a <code>User</code> in the
154 * <code>Registry</code>.
155 * @param transaction
156 * @param user
157 *
158 * @throws GeneralSecurityException
159 * this is a <code>DuplicateException</code> if a user with the
160 * new name already existed
161 */
162 void updateUser(SecurityTransaction transaction, User user)
163 throws GeneralSecurityException;
164
165 /**
166 * Retrieves a <code>User</code> from the <code>Registry</code>.
167 * @param securityAccess
168 * @param name
169 * @return
170 *
171 * @throws GeneralSecurityException
172 * this is an <code>UnknownException</code> if the user is not
173 * known to the <code>Registry</code>
174 */
175 User getUserByName(SecurityAccess securityAccess, String name)
176 throws GeneralSecurityException;
177
178 /**
179 * Retrieves a <code>User</code> from the <code>Registry</code>.
180 * @param securityAccess
181 * @param id
182 * @return
183 *
184 * @throws GeneralSecurityException
185 * this is an <code>UnknownException</code> if the user is not
186 * known to the <code>Registry</code>
187 */
188 User getUserById(SecurityAccess securityAccess, int id)
189 throws GeneralSecurityException;
190
191 /**
192 * Retrieves all <code>User</code> s from the <code>Registry</code>.
193 * @param securityAccess
194 * @return
195 *
196 * @throws GeneralSecurityException
197 */
198 User[] getAllUsers(SecurityAccess securityAccess)
199 throws GeneralSecurityException;
200
201 /**
202 * Retrieves all <code>Users</code> s from the <code>Registry</code>
203 * that are associated DIRECTLY (SecurityAccess securityAccess, i.e. not via
204 * group memberships) with a given <code>Role</code>.
205 * @param securityAccess
206 * @param role
207 * @return
208 *
209 * @throws GeneralSecurityException
210 */
211 User[] getUsersWithRole(SecurityAccess securityAccess, Role role)
212 throws GeneralSecurityException;
213
214 /**
215 * Retrieves all <code>User</code> s from the <code>Registry</code>
216 * belong to the given <code>Group</code>.
217 * @param securityAccess
218 * @param group
219 * @return
220 *
221 * @throws GeneralSecurityException
222 */
223 User[] getUsersInGroup(SecurityAccess securityAccess, Group group)
224 throws GeneralSecurityException;
225
226 /**
227 * Sets the <code>User</code> s that are members of a given
228 * <code>Group</code>.
229 * @param transaction
230 * @param group
231 * @param users
232 *
233 * @throws GeneralSecurityException
234 */
235 void setUsersInGroup(SecurityTransaction transaction, Group group,
236 User[] users) throws GeneralSecurityException;
237
238 /**
239 * Sets the <code>User</code> s that a given <code>Role</code> is
240 * associated to.
241 * @param transaction
242 * @param role
243 * @param users
244 *
245 * @throws GeneralSecurityException
246 */
247 void setUsersWithRole(SecurityTransaction transaction, Role role,
248 User[] users) throws GeneralSecurityException;
249
250 /**
251 * Adds a new Group-account to the <code>Registry</code>.
252 * @param transaction
253 * @param name
254 * @param title
255 * @return
256 *
257 * @throws GeneralSecurityException
258 * this is a <code>DuplicateException</code> if the group
259 * already existed
260 */
261 Group registerGroup(SecurityTransaction transaction, String name,
262 String title) throws GeneralSecurityException;
263
264 /**
265 * Removes an existing <code>Group</code> from the <code>Registry</code>
266 * (including its relations).
267 * @param transaction
268 * @param group
269 *
270 * @throws GeneralSecurityException
271 */
272 void deregisterGroup(SecurityTransaction transaction, Group group)
273 throws GeneralSecurityException;
274
275 /**
276 * Retrieves a <code>Group</code> from the <code>Registry</code>.
277 * @param securityAccess
278 * @param name
279 * @return
280 *
281 * @throws GeneralSecurityException
282 * this is an <code>UnknownException</code> if the group is
283 * not known to the <code>Registry</code>
284 */
285 Group getGroupByName(SecurityAccess securityAccess, String name)
286 throws GeneralSecurityException;
287
288 /**
289 * Retrieves a <code>Group</code> from the <code>Registry</code>.
290 * @param securityAccess
291 * @param id
292 * @return
293 *
294 * @throws GeneralSecurityException
295 * this is an <code>UnknownException</code> if the group is
296 * not known to the <code>Registry</code>
297 */
298 Group getGroupById(SecurityAccess securityAccess, int id)
299 throws GeneralSecurityException;
300
301 /**
302 * Retrieves all <code>Group</code> s from the <code>Registry</code>.
303 * @param securityAccess
304 * @return
305 *
306 * @throws GeneralSecurityException
307 */
308 Group[] getAllGroups(SecurityAccess securityAccess)
309 throws GeneralSecurityException;
310
311 /**
312 * Retrieves all <code>Group</code> s from the <code>Registry</code>
313 * that the given <code>User</code> belongs to.
314 * @param securityAccess
315 * @param user
316 * @return
317 *
318 * @throws GeneralSecurityException
319 */
320 Group[] getGroupsForUser(SecurityAccess securityAccess, User user)
321 throws GeneralSecurityException;
322
323 /**
324 * Retrieves all <code>Group</code> s from the <code>Registry</code>
325 * that the given <code>Group</code> belongs to.
326 * @param securityAccess
327 * @param group
328 * @return
329 *
330 * @throws GeneralSecurityException
331 */
332 Group[] getGroupsForGroup(SecurityAccess securityAccess, Group group)
333 throws GeneralSecurityException;
334
335 /**
336 * Retrieves all <code>Group</code> s from the <code>Registry</code>
337 * belong to the given <code>Group</code>.
338 * @param securityAccess
339 * @param group
340 * @return
341 *
342 * @throws GeneralSecurityException
343 */
344 Group[] getGroupsInGroup(SecurityAccess securityAccess, Group group)
345 throws GeneralSecurityException;
346
347 /**
348 * Retrieves all <code>Group</code> s from the <code>Registry</code>
349 * that are associated with a given <code>Role</code>.
350 * @param securityAccess
351 * @param role
352 * @return
353 *
354 * @throws GeneralSecurityException
355 */
356 Group[] getGroupsWithRole(SecurityAccess securityAccess, Role role)
357 throws GeneralSecurityException;
358
359 /**
360 * Sets the <code>Group</code> s that a given <code>User</code> is a
361 * DIRECT member of.
362 * @param transaction
363 * @param user
364 * @param groups
365 *
366 * @throws GeneralSecurityException
367 */
368 void setGroupsForUser(SecurityTransaction transaction, User user,
369 Group[] groups) throws GeneralSecurityException;
370
371 /**
372 * Sets the <code>Groups</code> s that are members of a given
373 * <code>Group</code>.
374 * @param transaction
375 * @param group
376 * @param groups
377 *
378 * @throws GeneralSecurityException
379 */
380 void setGroupsInGroup(SecurityTransaction transaction, Group group,
381 Group[] groups) throws GeneralSecurityException;
382
383 /**
384 * Sets the <code>Group</code> s that a given <code>Role</code> is
385 * associated to.
386 * @param transaction
387 * @param role
388 * @param groups
389 *
390 * @throws GeneralSecurityException
391 */
392 void setGroupsWithRole(SecurityTransaction transaction, Role role,
393 Group[] groups) throws GeneralSecurityException;
394
395 /**
396 * Sets the <code>Groups</code> s that a given <code>Group</code> is
397 * member of DIRECTLY (i.e. not via group membership).
398 * @param transaction
399 * @param group
400 * @param groups
401 *
402 * @throws GeneralSecurityException
403 */
404 void setGroupsForGroup(SecurityTransaction transaction, Group group,
405 Group[] groups) throws GeneralSecurityException;
406
407 /**
408 * Adds a new role to the <code>Registry</code>.
409 * @param transaction
410 * @param name
411 * @return
412 *
413 * @throws GeneralSecurityException
414 * this is a <code>DuplicateException</code> if the role
415 * already existed
416 */
417 Role registerRole(SecurityTransaction transaction, String name)
418 throws GeneralSecurityException;
419
420 /**
421 * Removes an existing <code>Role</code> from the <code>Registry</code>
422 * (including its relations).
423 * @param transaction
424 * @param role
425 *
426 * @throws GeneralSecurityException
427 */
428 void deregisterRole(SecurityTransaction transaction, Role role)
429 throws GeneralSecurityException;
430
431 /**
432 * Retrieves a <code>Role</code> from the <code>Registry</code>.
433 * @param securityAccess
434 * @param name
435 * @return
436 *
437 * @throws GeneralSecurityException
438 * this is an <code>UnknownException</code> if the role is not
439 * known to the <code>Registry</code>
440 */
441 Role getRoleByName(SecurityAccess securityAccess, String name)
442 throws GeneralSecurityException;
443
444 /**
445 * Retrieves all <code>Role</code> s from the <code>Registry</code> that
446 * have a certain namespace.
447 * @param securityAccess
448 * @param ns
449 * @return
450 *
451 * @throws GeneralSecurityException
452 */
453 Role[] getRolesByNS(SecurityAccess securityAccess, String ns)
454 throws GeneralSecurityException;
455
456 /**
457 * Retrieves a <code>Role</code> from the <code>Registry</code>.
458 * @param securityAccess
459 * @param id
460 * @return
461 *
462 * @throws GeneralSecurityException
463 * this is an <code>UnknownException</code> if the role is not
464 * known to the <code>Registry</code>
465 */
466 Role getRoleById(SecurityAccess securityAccess, int id)
467 throws GeneralSecurityException;
468
469 /**
470 * Retrieves all <code>Role</code> s from the <code>Registry</code>,
471 * except those that are only used internally (these end with a $ symbol);
472 * @param securityAccess
473 * @return
474 *
475 * @throws GeneralSecurityException
476 */
477 Role[] getAllRoles(SecurityAccess securityAccess)
478 throws GeneralSecurityException;
479
480 /**
481 * Retrieves all <code>Role</code> s from the <code>Registry</code> that
482 * are associated with a given <code>User</code> DIRECTLY (i.e. not via
483 * group memberships).
484 * @param securityAccess
485 * @param user
486 * @return
487 *
488 * @throws GeneralSecurityException
489 */
490 Role[] getRolesForUser(SecurityAccess securityAccess, User user)
491 throws GeneralSecurityException;
492
493 /**
494 * Retrieves all <code>Role</code> s from the <code>Registry</code> that
495 * are associated with a given <code>Group</code> DIRECTLY (i.e. not via
496 * group memberships).
497 * @param securityAccess
498 * @param group
499 * @return
500 *
501 * @throws GeneralSecurityException
502 */
503 Role[] getRolesForGroup(SecurityAccess securityAccess, Group group)
504 throws GeneralSecurityException;
505
506 /**
507 * Sets the <code>Role</code> s that a given <code>User</code> is
508 * directly associated to.
509 * @param transaction
510 * @param user
511 * @param roles
512 *
513 * @throws GeneralSecurityException
514 */
515 void setRolesForUser(SecurityTransaction transaction, User user,
516 Role[] roles) throws GeneralSecurityException;
517
518 /**
519 * Sets the <code>Role</code> s that a given <code>Group</code> is
520 * associated to.
521 * @param transaction
522 * @param group
523 * @param roles
524 *
525 * @throws GeneralSecurityException
526 */
527 void setRolesForGroup(SecurityTransaction transaction, Group group,
528 Role[] roles) throws GeneralSecurityException;
529
530 /**
531 * Adds a new <code>SecuredObject</code> to the <code>Registry</code>.
532 * @param transaction
533 * @param type
534 * @param name
535 * @param title
536 * @return
537 *
538 * @throws GeneralSecurityException
539 * this is a <code>DuplicateException</code> if the object
540 * already existed
541 */
542 SecuredObject registerSecuredObject(SecurityTransaction transaction,
543 String type, String name, String title) throws GeneralSecurityException;
544
545 /**
546 * Removes an existing <code>SecuredObject</code> from the
547 * <code>Registry</code> (including its associated rights).
548 * @param transaction
549 * @param object
550 *
551 * @throws GeneralSecurityException
552 */
553 void deregisterSecuredObject(SecurityTransaction transaction,
554 SecuredObject object) throws GeneralSecurityException;
555
556 /**
557 * Retrieves a <code>SecuredObject</code> from the <code>Registry</code>.
558 * @param securityAccess
559 * @param name
560 * @param type
561 * @return
562 *
563 * @throws GeneralSecurityException
564 * this is an <code>UnknownException</code> if the
565 * <code>SecuredObject</code> is not known to the
566 * <code>Registry</code>
567 */
568 SecuredObject getSecuredObjectByName(SecurityAccess securityAccess,
569 String name, String type) throws GeneralSecurityException;
570
571 /**
572 * Retrieves all <code>SecuredObject</code> s from the
573 * <code>Registry</code> that have a certain namespace.
574 * @param securityAccess
575 * @param ns
576 * @param type
577 * @return
578 *
579 * @throws GeneralSecurityException
580 */
581 SecuredObject[] getSecuredObjectsByNS(SecurityAccess securityAccess,
582 String ns, String type) throws GeneralSecurityException;
583
584 /**
585 * Retrieves a <code>SecuredObject</code> from the <code>Registry</code>.
586 * @param securityAccess
587 * @param id
588 * @return
589 *
590 * @throws GeneralSecurityException
591 * this is an <code>UnknownException</code> if the
592 * <code>SecuredObject</code> is not known to the
593 * <code>Registry</code>
594 */
595 SecuredObject getSecuredObjectById(SecurityAccess securityAccess, int id)
596 throws GeneralSecurityException;
597
598 /**
599 * Retrieves all <code>SecuredObject</code> s from the
600 * <code>Registry</code>.
601 * @param securityAccess
602 * @param type
603 * @return
604 *
605 * @throws GeneralSecurityException
606 */
607 SecuredObject[] getAllSecuredObjects(SecurityAccess securityAccess,
608 String type) throws GeneralSecurityException;
609
610 /**
611 * Adds a new <code>Privilege</code> to the <code>Registry</code>.
612 * @param transaction
613 * @param name
614 * @return
615 *
616 * @throws GeneralSecurityException
617 * this is a <code>DuplicateException</code> if the
618 * <code>Privilege</code> already existed
619 */
620 Privilege registerPrivilege(SecurityTransaction transaction, String name)
621 throws GeneralSecurityException;
622
623 /**
624 * Removes an existing</code> Privilege</code> from the <code>Registry
625 * </code> (including its relations).
626 * @param transaction
627 * @param privilege
628 *
629 * @throws GeneralSecurityException
630 */
631 void deregisterPrivilege(SecurityTransaction transaction,
632 Privilege privilege) throws GeneralSecurityException;
633
634 /**
635 * Retrieves a <code>Privilege</code> from the <code>Registry</code>.
636 * @param securityAccess
637 * @param name
638 * @return
639 *
640 * @throws GeneralSecurityException
641 * this is an <code>UnknownException</code> if the privilege
642 * is not known to the <code>Registry</code>
643 */
644 Privilege getPrivilegeByName(SecurityAccess securityAccess, String name)
645 throws GeneralSecurityException;
646
647 /**
648 * Retrieves all <code>Privileges</code> s from the <code>Registry</code>
649 * that are associated with a given <code>Role</code>.
650 * @param securityAccess
651 * @param role
652 * @return
653 *
654 * @throws GeneralSecurityException
655 */
656 Privilege[] getPrivilegesForRole(SecurityAccess securityAccess, Role role)
657 throws GeneralSecurityException;
658
659 /**
660 * Sets all <code>Privilege</code> s that are associated with a given
661 * <code>Role</code>.
662 * @param transaction
663 * @param role
664 * @param privileges
665 *
666 * @throws GeneralSecurityException
667 */
668 void setPrivilegesForRole(SecurityTransaction transaction, Role role,
669 Privilege[] privileges) throws GeneralSecurityException;
670
671 /**
672 * Adds a new <code>RightType</code> to the <code>Registry</code>.
673 * @param transaction
674 * @param name
675 * @return
676 *
677 * @throws GeneralSecurityException
678 * this is a <code>DuplicateException</code> if the
679 * <code>RightType</code> already existed
680 */
681 RightType registerRightType(SecurityTransaction transaction, String name)
682 throws GeneralSecurityException;
683
684 /**
685 * Removes an existing <code>RightType</code> from the
686 * <code>Registry</code> (including its relations).
687 * @param transaction
688 * @param type
689 *
690 * @throws GeneralSecurityException
691 */
692 void deregisterRightType(SecurityTransaction transaction, RightType type)
693 throws GeneralSecurityException;
694
695 /**
696 * Retrieves a <code>RightType</code> from the <code>Registry</code>.
697 * @param securityAccess
698 * @param name
699 * @return
700 *
701 * @throws GeneralSecurityException
702 * this is an <code>UnknownException</code> if the
703 * <code>RightType</code> is not known to the
704 * <code>Registry</code>
705 */
706 RightType getRightTypeByName(SecurityAccess securityAccess, String name)
707 throws GeneralSecurityException;
708
709 /**
710 * Retrieves the <code>Rights</code> from the <code>Registry</code> that
711 * are associated with a given <code>Role</code> and a
712 * <code>SecurableObject</code>.
713 * @param securityAccess
714 * @param object
715 * @param role
716 * @return
717 *
718 * @throws GeneralSecurityException
719 */
720 Right[] getRights(SecurityAccess securityAccess, SecurableObject object,
721 Role role) throws GeneralSecurityException;
722
723 /**
724 * Sets the <code>Rights</code> to be associated with a given
725 * <code>Role</code> and <code>SecurableObject</code>.
726 * @param transaction
727 * @param object
728 * @param role
729 * @param rights
730 *
731 * @throws GeneralSecurityException
732 */
733 void setRights(SecurityTransaction transaction, SecurableObject object,
734 Role role, Right[] rights) throws GeneralSecurityException;
735
736 /**
737 * Sets one <code>Right</code> to be associated with a given
738 * <code>Role</code> and all given <code>SecurableObjects</code>.
739 * @param transaction
740 * @param objects
741 * @param role
742 * @param right
743 *
744 * @throws GeneralSecurityException
745 */
746 void setRights(SecurityTransaction transaction, SecurableObject[] objects,
747 Role role, Right right) throws GeneralSecurityException;
748 }