You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by sm...@apache.org on 2014/10/22 17:45:07 UTC
[48/51] [partial] Rename packages from org.openldap.fortress to
org.apache.directory.fortress.core. Change default suffix to org.apache.
Switch default ldap api from unbound to apache ldap.
http://git-wip-us.apache.org/repos/asf/directory-fortress-core/blob/687ee1ad/src/main/java/org/apache/directory/fortress/core/AdminMgr.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/directory/fortress/core/AdminMgr.java b/src/main/java/org/apache/directory/fortress/core/AdminMgr.java
new file mode 100755
index 0000000..bcd4624
--- /dev/null
+++ b/src/main/java/org/apache/directory/fortress/core/AdminMgr.java
@@ -0,0 +1,1041 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.directory.fortress.core;
+
+import org.apache.directory.fortress.core.rbac.PermObj;
+import org.apache.directory.fortress.core.rbac.Permission;
+import org.apache.directory.fortress.core.rbac.Role;
+import org.apache.directory.fortress.core.rbac.SDSet;
+import org.apache.directory.fortress.core.rbac.User;
+import org.apache.directory.fortress.core.rbac.UserRole;
+
+/**
+ * This class performs administrative functions to provision Fortress RBAC entities into the LDAP directory. These APIs
+ * map directly to similar named APIs specified by ANSI and NIST RBAC models.
+ * Many of the java doc function descriptions found below were taken directly from ANSI INCITS 359-2004.
+ * The RBAC Functional specification describes administrative operations for the creation
+ * and maintenance of RBAC element sets and relations; administrative review functions for
+ * performing administrative queries; and system functions for creating and managing
+ * RBAC attributes on user sessions and making access control decisions.
+ * <p/>
+ * <hr>
+ * <h4>RBAC0 - Core</h4>
+ * Many-to-many relationship between Users, Roles and Permissions. Selective role activation into sessions. API to add, update, delete identity data and perform identity and access control decisions during runtime operations.
+ * <p/>
+ * <img src="./doc-files/RbacCore.png">
+ * <hr>
+ * <h4>RBAC1 - General Hierarchical Roles</h4>
+ * Simplifies role engineering tasks using inheritance of one or more parent roles.
+ * <p/>
+ * <img src="./doc-files/RbacHier.png">
+ * <hr>
+ * <h4>RBAC2 - Static Separation of Duty (SSD) Relations</h4>
+ * Enforce mutual membership exclusions across role assignments. Facilitate dual control policies by restricting which roles may be assigned to users in combination. SSD provide added granularity for authorization limits which help enterprises meet strict compliance regulations.
+ * <p/>
+ * <img src="./doc-files/RbacSSD.png">
+ * <hr>
+ * <h4>RBAC3 - Dynamic Separation of Duty (DSD) Relations</h4>
+ * Control allowed role combinations to be activated within an RBAC session. DSD policies fine tune role policies that facilitate authorization dual control and two man policy restrictions during runtime security checks.
+ * <p/>
+ * <img src="./doc-files/RbacDSD.png">
+ * <hr>
+ * <p/>
+ * This interface's implementer will NOT be thread safe if parent instance variables ({@link Manageable#setContextId(String)} or {@link Manageable#setAdmin(org.apache.directory.fortress.core.rbac.Session)}) are set.
+ *
+ * @author Shawn McKinney
+ */
+public interface AdminMgr extends Manageable
+{
+ /**
+ * This command creates a new RBAC user. The command is valid only if the new user is
+ * not already a member of the USERS data set. The USER data set is updated. The new user
+ * does not own any session at the time of its creation.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * <li>{@link User#password} - used to authenticate the User</li>
+ * <li>{@link User#ou} - contains the name of an already existing User OU node</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link User#pwPolicy} - contains the name of an already existing OpenLDAP password policy node</li>
+ * <li>{@link User#cn} - maps to INetOrgPerson common name attribute</li>
+ * <li>{@link User#sn} - maps to INetOrgPerson surname attribute</li>
+ * <li>{@link User#description} - maps to INetOrgPerson description attribute</li>
+ * <li>{@link User#title} - maps to INetOrgPerson title attribute</li>
+ * <li>{@link User#employeeType} - maps to INetOrgPerson employeeType attribute</li>
+ * <li>{@link User#phones} * - multi-occurring attribute maps to organizationalPerson telephoneNumber attribute</li>
+ * <li>{@link User#mobiles} * - multi-occurring attribute maps to INetOrgPerson mobile attribute</li>
+ * <li>{@link User#emails} * - multi-occurring attribute maps to INetOrgPerson mail attribute</li>
+ * <li>{@link User#address} * - multi-occurring attribute maps to organizationalPerson postalAddress, st, l, postalCode, postOfficeBox attributes</li>
+ * <li>{@link User#beginTime} - HHMM - determines begin hour user may activate session</li>
+ * <li>{@link User#endTime} - HHMM - determines end hour user may activate session.</li>
+ * <li>{@link User#beginDate} - YYYYMMDD - determines date when user may sign on</li>
+ * <li>{@link User#endDate} - YYYYMMDD - indicates latest date user may sign on</li>
+ * <li>{@link User#beginLockDate} - YYYYMMDD - determines beginning of enforced inactive status</li>
+ * <li>{@link User#endLockDate} - YYYYMMDD - determines end of enforced inactive status</li>
+ * <li>{@link User#dayMask} - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day of user may sign on</li>
+ * <li>{@link User#timeout} - number in seconds of session inactivity time allowed</li>
+ * <li>{@link User#props} * - multi-occurring attribute contains property key and values are separated with a ':'. e.g. mykey1:myvalue1</li>
+ * <li>{@link User#roles} * - multi-occurring attribute contains the name of already existing role to assign to user</li>
+ * <li>{@link User#adminRoles} * - multi-occurring attribute contains the name of already existing adminRole to assign to user</li>
+ * </ul>
+ *
+ * @param user User entity must contain {@link User#userId} and {@link User#ou} (required) and optional {@link User#description},{@link User#roles} and many others.
+ * @return Returns entity containing user data that was added.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public User addUser(User user)
+ throws SecurityException;
+
+
+ /**
+ * This command deletes an existing user from the RBAC database. The command is valid
+ * if and only if the user to be deleted is a member of the USERS data set. The USERS and
+ * UA data sets and the assigned_users function are updated.
+ * Method performs a "soft" delete. It performs the following:
+ * - sets the user status to "deleted"
+ * - deassigns all roles from the user
+ * - locks the user's password in LDAP
+ * - revokes all perms that have been granted to user entity.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * </ul>
+ *
+ * @param user Contains the {@link User#userId} of the User targeted for deletion.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public void disableUser(User user)
+ throws SecurityException;
+
+
+ /**
+ * This command deletes an existing user from the RBAC database. The command is valid
+ * if and only if the user to be deleted is a member of the USERS data set. The USERS and
+ * UA data sets and the assigned_users function are updated.
+ * This method performs a "hard" delete. It completely removes all data associated with this user from the directory.
+ * User entity must exist in directory prior to making this call else exception will be thrown.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * </ul>
+ *
+ * @param user Contains the {@link User#userId} of the User targeted for deletion.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public void deleteUser(User user)
+ throws SecurityException;
+
+
+ /**
+ * This method performs an update on User entity in directory. Prior to making this call the entity must exist in
+ * directory.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link User#password} - used to authenticate the User</li>
+ * <li>{@link User#ou} - contains the name of an already existing User OU node</li>
+ * <li>{@link User#pwPolicy} - contains the name of an already existing OpenLDAP password policy node</li>
+ * <li>{@link User#cn} - maps to INetOrgPerson common name attribute</li>
+ * <li>{@link User#sn} - maps to INetOrgPerson surname attribute</li>
+ * <li>{@link User#description} - maps to INetOrgPerson description attribute</li>
+ * <li>{@link User#title} - maps to INetOrgPerson title attribute</li>
+ * <li>{@link User#employeeType} - maps to INetOrgPerson employeeType attribute</li>
+ * <li>{@link User#phones} * - multi-occurring attribute maps to organizationalPerson telephoneNumber attribute</li>
+ * <li>{@link User#mobiles} * - multi-occurring attribute maps to INetOrgPerson mobile attribute</li>
+ * <li>{@link User#emails} * - multi-occurring attribute maps to INetOrgPerson mail attribute</li>
+ * <li>{@link User#address} * - multi-occurring attribute maps to organizationalPerson postalAddress, st, l, postalCode, postOfficeBox attributes</li>
+ * <li>{@link User#beginTime} - HHMM - determines begin hour user may activate session</li>
+ * <li>{@link User#endTime} - HHMM - determines end hour user may activate session.</li>
+ * <li>{@link User#beginDate} - YYYYMMDD - determines date when user may sign on</li>
+ * <li>{@link User#endDate} - YYYYMMDD - indicates latest date user may sign on</li>
+ * <li>{@link User#beginLockDate} - YYYYMMDD - determines beginning of enforced inactive status</li>
+ * <li>{@link User#endLockDate} - YYYYMMDD - determines end of enforced inactive status</li>
+ * <li>{@link User#dayMask} - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day of user may sign on</li>
+ * <li>{@link User#timeout} - number in seconds of session inactivity time allowed</li>
+ * <li>{@link User#props} * - multi-occurring attribute contains property key and values are separated with a ':'. e.g. mykey1:myvalue1</li>
+ * <li>{@link User#roles} * - multi-occurring attribute contains the name of already existing role to assign to user</li>
+ * <li>{@link User#adminRoles} * - multi-occurring attribute contains the name of already existing adminRole to assign to user</li>
+ * </ul>
+ *
+ * @param user must contain {@link User#userId} and optional entity data to update i.e. desc, ou, properties, all attributes that are not set will be ignored.
+ * @return Updated user entity data.
+ * @throws SecurityException thrown in the event of validation or system error.
+ */
+ public User updateUser(User user)
+ throws SecurityException;
+
+
+ /**
+ * Method will change user's password. This method will evaluate user's password policies.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * <li>{@link User#password} - contains the User's old password</li>
+ * <li>newPassword - contains the User's new password</li>
+ * </ul>
+ *
+ * @param user contains {@link User#userId} and old user password {@link User#password}.
+ * @param newPassword contains new user password.
+ * @throws SecurityException will be thrown in the event of password policy violation or system error.
+ */
+ public void changePassword(User user, char[] newPassword)
+ throws SecurityException;
+
+
+ /**
+ * Method will lock user's password which will prevent the user from authenticating with directory.
+ * <p/>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * </ul>
+ *
+ * @param user entity contains {@link User#userId} of User to be locked.
+ * @throws SecurityException will be thrown in the event of pw policy violation or system error.
+ */
+ public void lockUserAccount(User user)
+ throws SecurityException;
+
+
+ /**
+ * Method will unlock user's password which will enable user to authenticate with directory.
+ * <p/>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * </ul>
+ *
+ * @param user entity contains {@link User#userId} of User to be unlocked.
+ * @throws SecurityException will be thrown in the event of pw policy violation or system error.
+ */
+ public void unlockUserAccount(User user)
+ throws SecurityException;
+
+
+ /**
+ * Method will reset user's password which will require user to change password before successful authentication with directory.
+ * This method will not evaluate password policies on the new user password as it must be changed before use.
+ * <p/>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * <li>newPassword - contains the User's new password</li>
+ * </ul>
+ *
+ * @param user entity contains {@link User#userId} of User to be reset.
+ * @throws SecurityException will be thrown in the event of pw policy violation or system error.
+ */
+ public void resetPassword(User user, char[] newPassword)
+ throws SecurityException;
+
+
+ /**
+ * Method will delete user's password policy designation.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link User#userId} - maps to INetOrgPerson uid</li>
+ * <li>newPassword - contains the User's new password</li>
+ * </ul>
+ *
+ * @param user contains {@link User#userId}.
+ * @throws SecurityException will be thrown in the event of password policy violation or system error.
+ */
+ public void deletePasswordPolicy(User user)
+ throws SecurityException;
+
+
+ /**
+ * This command creates a new role. The command is valid if and only if the new role is not
+ * already a member of the ROLES data set. The ROLES data set is updated.
+ * Initially, no user or permission is assigned to the new role.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Role#name} - contains the name to use for the Role to be created.</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link Role#description} - maps to description attribute on organizationalRole object class</li>
+ * <li>{@link Role#beginTime} - HHMM - determines begin hour role may be activated into user's RBAC session</li>
+ * <li>{@link Role#endTime} - HHMM - determines end hour role may be activated into user's RBAC session.</li>
+ * <li>{@link Role#beginDate} - YYYYMMDD - determines date when role may be activated into user's RBAC session</li>
+ * <li>{@link Role#endDate} - YYYYMMDD - indicates latest date role may be activated into user's RBAC session</li>
+ * <li>{@link Role#beginLockDate} - YYYYMMDD - determines beginning of enforced inactive status</li>
+ * <li>{@link Role#endLockDate} - YYYYMMDD - determines end of enforced inactive status</li>
+ * <li>{@link Role#dayMask} - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day role may be activated into user's RBAC session</li>
+ * </ul>
+ *
+ * @param role must contains {@link Role#name} (required) and optional {@link Role#description}.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public Role addRole(Role role)
+ throws SecurityException;
+
+
+ /**
+ * This command deletes an existing role from the RBAC database. The command is valid
+ * if and only if the role to be deleted is a member of the ROLES data set. This command will
+ * also deassign role from all users.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Role#name} - contains the name to use for the Role to be deleted.</li>
+ * </ul>
+ * @param role Must contain {@link Role#name} for Role to delete.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public void deleteRole(Role role)
+ throws SecurityException;
+
+
+ /**
+ * Method will update a Role entity in the directory. The role must exist in role container prior to this call.
+ *
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Role#name} - contains the name to use for the Role to be updated.</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link Role#description} - maps to description attribute on organizationalRole object class</li>
+ * <li>{@link Role#beginTime} - HHMM - determines begin hour role may be activated into user's RBAC session</li>
+ * <li>{@link Role#endTime} - HHMM - determines end hour role may be activated into user's RBAC session.</li>
+ * <li>{@link Role#beginDate} - YYYYMMDD - determines date when role may be activated into user's RBAC session</li>
+ * <li>{@link Role#endDate} - YYYYMMDD - indicates latest date role may be activated into user's RBAC session</li>
+ * <li>{@link Role#beginLockDate} - YYYYMMDD - determines beginning of enforced inactive status</li>
+ * <li>{@link Role#endLockDate} - YYYYMMDD - determines end of enforced inactive status</li>
+ * <li>{@link Role#dayMask} - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day role may be activated into user's RBAC session</li>
+ * </ul>
+ * @param role Must contains {@link Role#name} and may contain new description or {@link org.apache.directory.fortress.core.util.time.Constraint}
+ * @return Role contains reference to entity operated on.
+ * @throws SecurityException in the event of validation or system error.
+ */
+ public Role updateRole(Role role)
+ throws SecurityException;
+
+
+ /**
+ * This command assigns a user to a role.
+ * <p>
+ * <ul>
+ * <li> The command is valid if and only if:
+ * <li> The user is a member of the USERS data set
+ * <li> The role is a member of the ROLES data set
+ * <li> The user is not already assigned to the role
+ * <li> The SSD constraints are satisfied after assignment.
+ * </ul>
+ * </p>
+ * <p>
+ * Successful completion of this op, the following occurs:
+ * </p>
+ * <ul>
+ * <li> User entity (resides in people container) has role assignment added to aux object class attached to actual user record.
+ * <li> Role entity (resides in role container) has userId added as role occupant.
+ * <li> (optional) Temporal constraints may be associated with <code>ftUserAttrs</code> aux object class based on:
+ * <ul>
+ * <li> timeout - number in seconds of session inactivity time allowed.
+ * <li> beginDate - YYYYMMDD - determines date when role may be activated.
+ * <li> endDate - YYMMDD - indicates latest date role may be activated.
+ * <li> beginLockDate - YYYYMMDD - determines beginning of enforced inactive status
+ * <li> endLockDate - YYMMDD - determines end of enforced inactive status.
+ * <li> beginTime - HHMM - determines begin hour role may be activated in user's session.
+ * <li> endTime - HHMM - determines end hour role may be activated in user's session.*
+ * <li> dayMask - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day of week role may be activated.
+ * </ul>
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link UserRole#name} - contains the name for already existing Role to be assigned</li>
+ * <li>{@link UserRole#userId} - contains the userId for existing User</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link UserRole#beginTime} - HHMM - determines begin hour role may be activated into user's RBAC session</li>
+ * <li>{@link UserRole#endTime} - HHMM - determines end hour role may be activated into user's RBAC session.</li>
+ * <li>{@link UserRole#beginDate} - YYYYMMDD - determines date when role may be activated into user's RBAC session</li>
+ * <li>{@link UserRole#endDate} - YYYYMMDD - indicates latest date role may be activated into user's RBAC session</li>
+ * <li>{@link UserRole#beginLockDate} - YYYYMMDD - determines beginning of enforced inactive status</li>
+ * <li>{@link UserRole#endLockDate} - YYYYMMDD - determines end of enforced inactive status</li>
+ * <li>{@link UserRole#dayMask} - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day role may be activated into user's RBAC session</li>
+ * </ul>
+ *
+ * @param uRole must contain {@link UserRole#userId} and {@link UserRole#name} and optional {@code Constraints}.
+ * @throws SecurityException in the event of validation or system error.
+ */
+ public void assignUser(UserRole uRole)
+ throws SecurityException;
+
+
+ /**
+ * This command deletes the assignment of the User from the Role entities. The command is
+ * valid if and only if the user is a member of the USERS data set, the role is a member of
+ * the ROLES data set, and the user is assigned to the role.
+ * Any sessions that currently have this role activated will not be effected.
+ * Successful completion includes:
+ * User entity in USER data set has role assignment removed.
+ * Role entity in ROLE data set has userId removed as role occupant.
+ * (optional) Temporal constraints will be removed from user aux object if set prior to call.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link UserRole#name} - contains the name for already existing Role to be deassigned</li>
+ * <li>{@link UserRole#userId} - contains the userId for existing User</li>
+ * </ul>
+ * @param uRole must contain {@link org.apache.directory.fortress.core.rbac.UserRole#userId} and {@link UserRole#name}.
+ * @throws SecurityException - in the event data error in user or role objects or system error.
+ */
+ public void deassignUser(UserRole uRole)
+ throws SecurityException;
+
+
+ /**
+ * This method will add permission operation to an existing permission object which resides under {@code ou=Permissions,ou=RBAC,dc=yourHostName,dc=com} container in directory information tree.
+ * The perm operation entity may have {@link org.apache.directory.fortress.core.rbac.Role} or {@link org.apache.directory.fortress.core.rbac.User} associations. The target {@link Permission} must not exist prior to calling.
+ * A Fortress Permission instance exists in a hierarchical, one-many relationship between its parent and itself as stored in ldap tree: ({@link PermObj}*->{@link Permission}).
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Permission#objName} - contains the name of existing object being targeted for the permission add</li>
+ * <li>{@link Permission#opName} - contains the name of new permission operation being added</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link Permission#roles} * - multi occurring attribute contains RBAC Roles that permission operation is being granted to</li>
+ * <li>{@link Permission#users} * - multi occurring attribute contains Users that permission operation is being granted to</li>
+ * <li>{@link Permission#props} * - multi-occurring property key and values are separated with a ':'. e.g. mykey1:myvalue1</li>
+ * <li>{@link Permission#type} - any safe text</li>
+ * </ul>
+ *
+ * @param perm must contain the object, {@link org.apache.directory.fortress.core.rbac.Permission#objName}, and operation, {@link Permission#opName}, that identifies target along with optional other attributes..
+ * @return copy of Permission entity.
+ * @throws SecurityException - thrown in the event of perm object data or system error.
+ */
+ public Permission addPermission(Permission perm)
+ throws SecurityException;
+
+
+ /**
+ * This method will update permission operation pre-existing in target directory under {@code ou=Permissions,ou=RBAC,dc=yourHostName,dc=com} container in directory information tree.
+ * The perm operation entity may also contain {@link org.apache.directory.fortress.core.rbac.Role} or {@link org.apache.directory.fortress.core.rbac.User} associations to add or remove using this function.
+ * The perm operation must exist before making this call. Only non-null attributes will be updated.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Permission#objName} - contains the name of existing object being targeted for the permission update</li>
+ * <li>{@link Permission#opName} - contains the name of existing permission operation being updated</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link Permission#roles} * - multi occurring attribute contains RBAC Roles that permission operation is being granted to</li>
+ * <li>{@link Permission#users} * - multi occurring attribute contains Users that permission operation is being granted to</li>
+ * <li>{@link Permission#props} * - multi-occurring property key and values are separated with a ':'. e.g. mykey1:myvalue1</li>
+ * <li>{@link Permission#type} - any safe text</li>
+ * </ul>
+ *
+ * @param perm must contain the object, {@link Permission#objName}, and operation, {@link Permission#opName}, that identifies target and any optional data to update. Null or empty attributes will be ignored.
+ * @return copy of Permission entity.
+ * @throws SecurityException
+ * - thrown in the event of perm object data or system error.
+ */
+ public Permission updatePermission(Permission perm)
+ throws SecurityException;
+
+
+ /**
+ * This method will remove permission operation entity from permission object. A Fortress permission is (object->operation).
+ * The perm operation must exist before making this call.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Permission#objName} - contains the name of existing object being targeted for the permission delete</li>
+ * <li>{@link Permission#opName} - contains the name of existing permission operation being removed</li>
+ * </ul>
+ *
+ * @param perm must contain the object, {@link Permission#objName}, and operation, {@link Permission#opName}, that identifies target.
+ * @throws SecurityException - thrown in the event of perm object data or system error.
+ */
+ public void deletePermission(Permission perm)
+ throws SecurityException;
+
+
+ /**
+ * This method will add permission object to perms container in directory. The perm object must not exist before making this call.
+ * A {@link PermObj} instance exists in a hierarchical, one-many relationship between itself and children as stored in ldap tree: ({@link PermObj}*->{@link Permission}).
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link PermObj#objName} - contains the name of new object being added</li>
+ * <li>{@link PermObj#ou} - contains the name of an existing PERMS OrgUnit this object is associated with</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link PermObj#description} - any safe text</li>
+ * <li>{@link PermObj#type} - contains any safe text</li>
+ * <li>{@link PermObj#props} * - multi-occurring property key and values are separated with a ':'. e.g. mykey1:myvalue1</li>
+ * </ul>
+ *
+ * @param pObj must contain the {@link PermObj#objName} and {@link PermObj#ou}. The other attributes are optional.
+ * @return copy of PermObj entity.
+ * @throws SecurityException - thrown in the event of perm object data or system error.
+ */
+ public PermObj addPermObj(PermObj pObj)
+ throws SecurityException;
+
+
+ /**
+ * This method will update permission object in perms container in directory. The perm object must exist before making this call.
+ * A {@link PermObj} instance exists in a hierarchical, one-many relationship between itself and children as stored in ldap tree: ({@link PermObj}*->{@link Permission}).
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link PermObj#objName} - contains the name of existing object being updated</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link PermObj#ou} - contains the name of an existing PERMS OrgUnit this object is associated with</li>
+ * <li>{@link PermObj#description} - any safe text</li>
+ * <li>{@link PermObj#type} - contains any safe text</li>
+ * <li>{@link PermObj#props} * - multi-occurring property key and values are separated with a ':'. e.g. mykey1:myvalue1</li>
+ * </ul>
+ *
+ * @param pObj must contain the {@link PermObj#objName}. Only non-null attributes will be updated.
+ * @return copy of newly updated PermObj entity.
+ * @throws SecurityException
+ * - thrown in the event of perm object data or system error.
+ */
+ public PermObj updatePermObj(PermObj pObj)
+ throws SecurityException;
+
+
+ /**
+ * This method will remove permission object to perms container in directory. This method will also remove
+ * in associated permission objects that are attached to this object.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link PermObj#objName} - contains the name of existing object targeted for removal</li>
+ * </ul>
+ *
+ * @param pObj must contain the {@link PermObj#objName} of object targeted for removal.
+ * @throws SecurityException - thrown in the event of perm object data or system error.
+ */
+ public void deletePermObj(PermObj pObj)
+ throws SecurityException;
+
+
+ /**
+ * This command grants a role the permission to perform an operation on an object to a role.
+ * The command is implemented by granting permission by setting the access control list of
+ * the object involved.
+ * The command is valid if and only if the pair (operation, object) represents a permission,
+ * and the role is a member of the ROLES data set.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Permission#objName} - contains the object name</li>
+ * <li>{@link Permission#opName} - contains the operation name</li>
+ * <li>{@link Role#name} - contains the role name</li>
+ * </ul>
+ *
+ * @param perm must contain the object, {@link Permission#objName}, and operation, {@link Permission#opName}, that identifies target.
+ * @param role must contains {@link Role#name}.
+ * @throws SecurityException Thrown in the event of data validation or system error.
+ */
+ public void grantPermission(Permission perm, Role role)
+ throws SecurityException;
+
+
+ /**
+ * This command revokes the permission to perform an operation on an object from the set
+ * of permissions assigned to a role. The command is implemented by setting the access control
+ * list of the object involved.
+ * The command is valid if and only if the pair (operation, object) represents a permission,
+ * the role is a member of the ROLES data set, and the permission is assigned to that role.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Permission#objName} - contains the object name</li>
+ * <li>{@link Permission#opName} - contains the operation name</li>
+ * <li>{@link Role#name} - contains the role name</li>
+ * </ul>
+ *
+ * @param perm must contain the object, {@link Permission#objName}, and operation, {@link Permission#opName}, that identifies target.
+ * @param role must contains {@link Role#name}.
+ * @throws SecurityException Thrown in the event of data validation or system error.
+ */
+ public void revokePermission(Permission perm, Role role)
+ throws SecurityException;
+
+
+ /**
+ * This command grants a user the permission to perform an operation on an object to a role.
+ * The command is implemented by granting permission by setting the access control list of
+ * the object involved.
+ * The command is valid if and only if the pair (operation, object) represents a permission,
+ * and the user is a member of the USERS data set.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Permission#objName} - contains the object name</li>
+ * <li>{@link Permission#opName} - contains the operation name</li>
+ * <li>{@link User#userId} - contains the userId</li>
+ * </ul>
+ *
+ * @param perm must contain the object, {@link Permission#objName}, and operation, {@link Permission#opName}, that identifies target.
+ * @param user must contain {@link User#userId} of target User entity.
+ * @throws SecurityException Thrown in the event of data validation or system error.
+ */
+ public void grantPermission(Permission perm, User user)
+ throws SecurityException;
+
+
+ /**
+ * This command revokes the permission to perform an operation on an object from the set
+ * of permissions assigned to a user. The command is implemented by setting the access control
+ * list of the object involved.
+ * The command is valid if and only if the pair (operation, object) represents a permission,
+ * the user is a member of the USERS data set, and the permission is assigned to that user.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link Permission#objName} - contains the object name</li>
+ * <li>{@link Permission#opName} - contains the operation name</li>
+ * <li>{@link User#userId} - contains the userId</li>
+ * </ul>
+ *
+ * @param perm must contain the object, {@link Permission#objName}, and operation, {@link Permission#opName}, that identifies target.
+ * @param user must contain {@link User#userId} of target User entity.
+ * @throws SecurityException Thrown in the event of data validation or system error.
+ */
+ public void revokePermission(Permission perm, User user)
+ throws SecurityException;
+
+ /**
+ * This command creates a new role childRole, and inserts it in the role hierarchy as an immediate descendant of
+ * the existing role parentRole.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The childRole is not a member of the ROLES data set.
+ * <li> The parentRole is a member of the ROLES data set.
+ * </ul>
+ * </p>
+ * <p> This method:
+ * <ul>
+ * <li> Adds new role.
+ * <li> Assigns role relationship between new childRole and pre-existing parentRole.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>parentRole - {@link Role#name} - contains the name of existing Role to be parent</li>
+ * <li>childRole - {@link Role#name} - contains the name of new Role to be child</li>
+ * </ul>
+ * <h4>optional parameters childRole</h4>
+ * <ul>
+ * <li>childRole - {@link Role#description} - maps to description attribute on organizationalRole object class for new child</li>
+ * <li>childRole - {@link Role#beginTime} - HHMM - determines begin hour role may be activated into user's RBAC session for new child</li>
+ * <li>childRole - {@link Role#endTime} - HHMM - determines end hour role may be activated into user's RBAC session for new child</li>
+ * <li>childRole - {@link Role#beginDate} - YYYYMMDD - determines date when role may be activated into user's RBAC session for new child</li>
+ * <li>childRole - {@link Role#endDate} - YYYYMMDD - indicates latest date role may be activated into user's RBAC session for new child</li>
+ * <li>childRole - {@link Role#beginLockDate} - YYYYMMDD - determines beginning of enforced inactive status for new child</li>
+ * <li>childRole - {@link Role#endLockDate} - YYYYMMDD - determines end of enforced inactive status for new child</li>
+ * <li>childRole - {@link Role#dayMask} - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day role may be activated into user's RBAC session for new child</li>
+ * </ul>
+ *
+ * @param parentRole This entity must be present in ROLE data set. Success will add role rel with childRole.
+ * @param childRole This entity must not be present in ROLE data set. Success will add the new role entity to ROLE data set.
+ * @throws SecurityException
+ * thrown in the event of data validation or system error.
+ */
+ public void addDescendant(Role parentRole, Role childRole)
+ throws SecurityException;
+
+
+ /**
+ * This command creates a new role parentRole, and inserts it in the role hierarchy as an immediate ascendant of
+ * the existing role childRole.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The parentRole is not a member of the ROLES data set.
+ * <li> The childRole is a member of the ROLES data set.
+ * </ul>
+ * </p>
+ * <p> This method:
+ * <ul>
+ * <li> Adds new role.
+ * <li> Assigns role relationship between new parentRole and pre-existing childRole.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>childRole - {@link Role#name} - contains the name of existing child Role</li>
+ * <li>parentRole - {@link Role#name} - contains the name of new Role to be parent</li>
+ * </ul>
+ * <h4>optional parameters parentRole</h4>
+ * <ul>
+ * <li>parentRole - {@link Role#description} - maps to description attribute on organizationalRole object class for new parent</li>
+ * <li>parentRole - {@link Role#beginTime} - HHMM - determines begin hour role may be activated into user's RBAC session for new parent</li>
+ * <li>parentRole - {@link Role#endTime} - HHMM - determines end hour role may be activated into user's RBAC session for new parent</li>
+ * <li>parentRole - {@link Role#beginDate} - YYYYMMDD - determines date when role may be activated into user's RBAC session for new parent</li>
+ * <li>parentRole - {@link Role#endDate} - YYYYMMDD - indicates latest date role may be activated into user's RBAC session for new parent</li>
+ * <li>parentRole - {@link Role#beginLockDate} - YYYYMMDD - determines beginning of enforced inactive status for new parent</li>
+ * <li>parentRole - {@link Role#endLockDate} - YYYYMMDD - determines end of enforced inactive status for new parent</li>
+ * <li>parentRole - {@link Role#dayMask} - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day role may be activated into user's RBAC session for new parent</li>
+ * </ul>
+ *
+ * @param parentRole completion of op assigns new child relationship with childRole.
+ * @param childRole completion of op assigns new parent relationship with parentRole.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public void addAscendant(Role childRole, Role parentRole)
+ throws SecurityException;
+
+
+ /**
+ * This command establishes a new immediate inheritance relationship parentRole <<-- childRole between existing
+ * roles parentRole, childRole.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The parentRole and childRole are members of the ROLES data set.
+ * <li> The parentRole is not an immediate ascendant of childRole.
+ * <li> The childRole does not properly inherit parentRole (in order to avoid cycle creation).
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>parentRole - {@link Role#name} - contains the name of existing Role to be parent</li>
+ * <li>childRole - {@link Role#name} - contains the name of existing Role to be child</li>
+ * </ul>
+ *
+ * @param parentRole completion of op deassigns child relationship with childRole.
+ * @param childRole completion of op deassigns parent relationship with parentRole.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public void addInheritance(Role parentRole, Role childRole)
+ throws SecurityException;
+
+
+ /**
+ * This command deletes an existing immediate inheritance relationship parentRole <<-- childRole.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The roles parentRole and childRole are members of the ROLES data set.
+ * <li> The parentRole is an immediate ascendant of childRole.
+ * <li> The new inheritance relation is computed as the reflexive-transitive closure of the immediate inheritance
+ * relation resulted after deleting the relationship parentRole <<-- childRole.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>parentRole - {@link Role#name} - contains the name of existing Role to remove parent relationship</li>
+ * <li>childRole - {@link Role#name} - contains the name of existing Role to remove child relationship</li>
+ * </ul>
+ *
+ * @param parentRole completion of op removes child relationship with childRole.
+ * @param childRole completion of op removes parent relationship with parentRole.
+ * @throws SecurityException thrown in the event of data validation or system error.
+ */
+ public void deleteInheritance(Role parentRole, Role childRole)
+ throws SecurityException;
+
+
+ /**
+ * This command creates a named SSD set of roles and sets the cardinality n of its subsets
+ * that cannot have common users.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li>The name of the SSD set is not already in use.
+ * <li> All the roles in the SSD set are members of the ROLES data set.
+ * <li> n is a natural number greater than or equal to 2 and less than or equal to the cardinality of the SSD role set.
+ * <li> The SSD constraint for the new role set is satisfied.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of new SSD role set to be added</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#members} * - multi-occurring attribute contains the RBAC Role names to be added to this set</li>
+ * <li>{@link SDSet#cardinality} - default is 2 which is one more than maximum number of Roles that may be assigned to User from a particular set</li>
+ * <li>{@link SDSet#description} - contains any safe text</li>
+ * </ul>
+ *
+ * @param ssdSet contains an instantiated reference to new SSD set containing, name, members, and cardinality (default 2)
+ * @return reference to newly created SSDSet object.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet createSsdSet(SDSet ssdSet)
+ throws SecurityException;
+
+ /**
+ * This command updates existing SSD set of roles and sets the cardinality n of its subsets
+ * that cannot have common users.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li>The name of the SSD set already exists.
+ * <li> All the roles in the SSD set are members of the ROLES data set.
+ * <li> n is a natural number greater than or equal to 2 and less than or equal to the cardinality of the SSD role set.
+ * <li> The SSD constraint for the new role set is satisfied.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of existing SSD role set to be updated</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#members} * - multi-occurring attribute contains the RBAC Role names to be added to this set</li>
+ * <li>{@link SDSet#cardinality} - default is 2 which is one more than maximum number of Roles that may be assigned to User from a particular set</li>
+ * <li>{@link SDSet#description} - contains any safe text</li>
+ * </ul>
+ *
+ * @param ssdSet contains an instantiated reference to existing SSD set containing, name, members, and cardinality (default 2)
+ * @return reference to SSDSet object targeted for update.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet updateSsdSet(SDSet ssdSet)
+ throws SecurityException;
+
+ /**
+ * This command adds a role to a named SSD set of roles. The cardinality associated with the role set remains unchanged.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The SSD role set exists.
+ * <li> The role to be added is a member of the ROLES data set but not of a member of the SSD role set.
+ * <li> The SSD constraint is satisfied after the addition of the role to the SSD role set.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of SSD role set to be modified</li>
+ * <li>{@link Role#name} - contains the name of new {@link SDSet#members} to be added</li>
+ * </ul>
+ *
+ * @param ssdSet contains an instantiated reference to new SSD set containing, name
+ * @param role contains instantiated Role object with role name field set.
+ * @return reference to updated SSDSet object.
+ * @throws SecurityException
+ * in the event of data validation or system error.
+ */
+ public SDSet addSsdRoleMember(SDSet ssdSet, Role role)
+ throws SecurityException;
+
+ /**
+ * This command removes a role from a named SSD set of roles. The cardinality associated with the role set remains unchanged.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The SSD role set exists.
+ * <li> The role to be removed is a member of the SSD role set.
+ * <li> The cardinality associated with the SSD role set is less than the number of elements of the SSD role set.
+ * </ul>
+ * Note that the SSD constraint should be satisfied after the removal of the role from the SSD role set.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of SSD role set to be modified</li>
+ * <li>{@link Role#name} - contains the name of existing {@link SDSet#members} to be removed</li>
+ * </ul>
+ *
+ * @param ssdSet contains an instantiated reference to new SSD set containing name.
+ * @param role contains instantiated Role object with role name field set.
+ * @return reference to updated SSDSet object.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet deleteSsdRoleMember(SDSet ssdSet, Role role)
+ throws SecurityException;
+
+ /**
+ * This command deletes a SSD role set completely. The command is valid if and only if the SSD role set exists.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of SSD role set to be removed</li>
+ * </ul>
+ *
+ * @param ssdSet contains an instantiated reference to SSD set targeted for removal.
+ * @return reference to deleted SSDSet object.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet deleteSsdSet(SDSet ssdSet)
+ throws SecurityException;
+
+ /**
+ * This command sets the cardinality associated with a given SSD role set.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The SSD role set exists.
+ * <li> The new cardinality is a natural number greater than or equal to 2 and less than or equal to the number of elements of the SSD role set.
+ * <li> The SSD constraint is satisfied after setting the new cardinality.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of SSD role set to be modified</li>
+ * <li>cardinality - contains new cardinality setting for SSD</li>
+ * </ul>
+ *
+ * @param ssdSet contains an instantiated reference to new SSD set containing, name
+ * @param cardinality integer value contains new cardinality value for data set.
+ * @return reference to updated SSDSet object.
+ * @throws SecurityException
+ * in the event of data validation or system error.
+ */
+ public SDSet setSsdSetCardinality(SDSet ssdSet, int cardinality)
+ throws SecurityException;
+
+
+ /**
+ * This command creates a named DSD set of roles and sets an associated cardinality n.
+ * The DSD constraint stipulates that the DSD role set cannot contain n or more roles
+ * simultaneously active in the same session.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The name of the DSD set is not already in use.
+ * <li> All the roles in the DSD set are members of the ROLES data set.
+ * <li> n is a natural number greater than or equal to 2 and less than or equal to the cardinality of the DSD role set.
+ * <li> The DSD constraint for the new role set is satisfied.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of new DSD role set to be added</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#members} * - multi-occurring attribute contains the RBAC Role names to be added to this set</li>
+ * <li>{@link SDSet#cardinality} - default is 2 which is one more than maximum number of Roles that may be assigned to User from a particular set</li>
+ * <li>{@link SDSet#description} - contains any safe text</li>
+ * </ul>
+ *
+ * @param dsdSet contains an instantiated reference to new DSD set containing, name, members, and cardinality (default 2)
+ * @return reference to newly created SSDSet object.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet createDsdSet(SDSet dsdSet)
+ throws SecurityException;
+
+ /**
+ * This command updates existing DSD set of roles and sets the cardinality n of its subsets
+ * that cannot have common users.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li>The name of the DSD set already exists.
+ * <li> All the roles in the DSD set are members of the ROLES data set.
+ * <li> n is a natural number greater than or equal to 2 and less than or equal to the cardinality of the DSD role set.
+ * <li> The DSD constraint for the new role set is satisfied.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of existing DSD role set to be updated</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#members} * - multi-occurring attribute contains the RBAC Role names to be added to this set</li>
+ * <li>{@link SDSet#cardinality} - default is 2 which is one more than maximum number of Roles that may be assigned to User from a particular set</li>
+ * <li>{@link SDSet#description} - contains any safe text</li>
+ * </ul>
+ *
+ * @param dsdSet contains an instantiated reference to existing DSD set containing, name, members, and cardinality (default 2)
+ * @return reference to DSDSet object targeted for update.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet updateDsdSet(SDSet dsdSet)
+ throws SecurityException;
+
+ /**
+ * This command adds a role to a named DSD set of roles. The cardinality associated with
+ * the role set remains unchanged.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The DSD role set exists.
+ * <li> The role to be added is a member of the ROLES data set but not of a member of the DSD role set.
+ * <li> The DSD constraint is satisfied after the addition of the role to the SSD role set.
+ * </ul>
+ * </p>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of DSD role set to be modified</li>
+ * <li>{@link Role#name} - contains the name of new {@link SDSet#members} to be added</li>
+ * </ul>
+ * @param dsdSet contains an instantiated reference to new DSD set containing, name
+ * @param role contains instantiated Role object with role name field set.
+ * @return reference to updated DSDSet object.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet addDsdRoleMember(SDSet dsdSet, Role role)
+ throws SecurityException;
+
+ /**
+ * This command removes a role from a named DSD set of roles. The cardinality associated
+ * with the role set remains unchanged.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The DSD role set exists
+ * <li> The role to be removed is a member of the DSD role set.
+ * <li> The cardinality associated with the DSD role set is less than the number of elements of the DSD role set.
+ * </ul>
+ * Note that the DSD constraint should be satisfied after the removal of the role from the DSD role set.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of DSD role set to be modified</li>
+ * <li>{@link Role#name} - contains the name of existing {@link SDSet#members} to be removed</li>
+ * </ul>
+ *
+ * @param dsdSet contains an instantiated reference to new DSD set containing name.
+ * @param role contains instantiated Role object with role name field set.
+ * @return reference to updated DSDSet object.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet deleteDsdRoleMember(SDSet dsdSet, Role role)
+ throws SecurityException;
+
+ /**
+ * This command deletes a DSD role set completely. The command is valid if and only if the DSD role set exists.
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of DSD role set to be removed</li>
+ * </ul>
+ *
+ * @param dsdSet contains an instantiated reference to DSD set targeted for removal.
+ * @return reference to deleted DSDSet object.
+ * @throws SecurityException in the event of data validation or system error.
+ */
+ public SDSet deleteDsdSet(SDSet dsdSet)
+ throws SecurityException;
+
+ /**
+ * This command sets the cardinality associated with a given DSD role set.
+ * <p>
+ * The command is valid if and only if:
+ * <ul>
+ * <li> The SSD role set exists.
+ * <li> The new cardinality is a natural number greater than or equal to 2 and less than or equal to the number of elements of the SSD role set.
+ * <li> The SSD constraint is satisfied after setting the new cardinality.
+ * </ul>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link SDSet#name} - contains the name of DSD role set to be modified</li>
+ * <li>cardinality - contains new cardinality setting for SSD</li>
+ * </ul>
+ *
+ * @param dsdSet contains an instantiated reference to new DSD set containing, name
+ * @param cardinality integer value contains new cardinality value for data set.
+ * @return reference to updated DSDSet object.
+ * @throws SecurityException
+ * in the event of data validation or system error.
+ */
+ public SDSet setDsdSetCardinality(SDSet dsdSet, int cardinality)
+ throws SecurityException;
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/directory-fortress-core/blob/687ee1ad/src/main/java/org/apache/directory/fortress/core/AdminMgrFactory.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/directory/fortress/core/AdminMgrFactory.java b/src/main/java/org/apache/directory/fortress/core/AdminMgrFactory.java
new file mode 100755
index 0000000..e6cd9dc
--- /dev/null
+++ b/src/main/java/org/apache/directory/fortress/core/AdminMgrFactory.java
@@ -0,0 +1,114 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.directory.fortress.core;
+
+import org.apache.directory.fortress.core.cfg.Config;
+import org.apache.directory.fortress.core.rbac.AdminMgrImpl;
+import org.apache.directory.fortress.core.rbac.ClassUtil;
+import org.apache.directory.fortress.core.rbac.Session;
+import org.apache.directory.fortress.core.rest.AdminMgrRestImpl;
+import org.apache.directory.fortress.core.util.attr.VUtil;
+
+/**
+ * Creates an instance of the AdminMgr object.
+ * The factory allows deployments of Fortress override the default AdminMgrImpl component with another.
+ * <p/>
+ * The default class is specified as {@link AdminMgrImpl} but can be overridden by
+ * adding the {@link GlobalIds#ADMIN_IMPLEMENTATION} config property.
+ * <p/>
+
+ *
+ * @author Shawn McKinney
+ */
+public class AdminMgrFactory
+{
+ private static String adminClassName = Config.getProperty(GlobalIds.ADMIN_IMPLEMENTATION);
+ private static final String CLS_NM = AdminMgrFactory.class.getName();
+
+ /**
+ * Create and return a reference to {@link AdminMgr} object using HOME context.
+ *
+ * @return instance of {@link AdminMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AdminMgr createInstance()
+ throws SecurityException
+ {
+ return createInstance( GlobalIds.HOME );
+ }
+
+ /**
+ * Create and return a reference to {@link AdminMgr} object.
+ *
+ * @param contextId maps to sub-tree in DIT, for example ou=contextId, dc=jts, dc = com.
+ * @return instance of {@link AdminMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AdminMgr createInstance(String contextId)
+ throws SecurityException
+ {
+ VUtil.assertNotNull(contextId, GlobalErrIds.CONTEXT_NULL, CLS_NM + ".createInstance");
+ if (!VUtil.isNotNullOrEmpty(adminClassName))
+ {
+ if(GlobalIds.IS_REST)
+ {
+ adminClassName = AdminMgrRestImpl.class.getName();
+ }
+ else
+ {
+ adminClassName = AdminMgrImpl.class.getName();
+ }
+ }
+
+ AdminMgr adminMgr = (AdminMgr) ClassUtil.createInstance(adminClassName);
+ adminMgr.setContextId(contextId);
+ return adminMgr;
+ }
+
+ /**
+ * Create and return a reference to {@link AdminMgr} object using HOME context.
+ *
+ * @param adminSess contains a valid Fortress A/RBAC Session object.
+ * @return instance of {@link AdminMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AdminMgr createInstance(Session adminSess)
+ throws SecurityException
+ {
+ return createInstance( GlobalIds.HOME, adminSess );
+ }
+
+ /**
+ * Create and return a reference to {@link AdminMgr} object.
+ *
+ * @param contextId maps to sub-tree in DIT, for example ou=contextId, dc=jts, dc = com.
+ * @param adminSess contains a valid Fortress A/RBAC Session object.
+ * @return instance of {@link AdminMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AdminMgr createInstance(String contextId, Session adminSess)
+ throws SecurityException
+ {
+ AdminMgr adminMgr = createInstance(contextId);
+ adminMgr.setAdmin(adminSess);
+ return adminMgr;
+ }
+}
+
http://git-wip-us.apache.org/repos/asf/directory-fortress-core/blob/687ee1ad/src/main/java/org/apache/directory/fortress/core/AuditMgr.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/directory/fortress/core/AuditMgr.java b/src/main/java/org/apache/directory/fortress/core/AuditMgr.java
new file mode 100755
index 0000000..24538bb
--- /dev/null
+++ b/src/main/java/org/apache/directory/fortress/core/AuditMgr.java
@@ -0,0 +1,199 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.directory.fortress.core;
+
+import org.apache.directory.fortress.core.rbac.AuthZ;
+import org.apache.directory.fortress.core.rbac.Mod;
+import org.apache.directory.fortress.core.rbac.UserAudit;
+import org.apache.directory.fortress.core.rbac.Bind;
+
+import java.util.List;
+
+/**
+ * This interface prescribes methods used to search <a href="http://www.openldap.org/">OpenLDAP</a>'s slapd access log. The access log events are
+ * persisted in <a href="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">BDB</a> and available for inquiry via common LDAP protocols.
+ * Audit entries stored on behalf of Fortress operations correspond to runtime authentication {@link org.apache.directory.fortress.core.rbac.Bind}, authorization {@link org.apache.directory.fortress.core.rbac.AuthZ} and modification {@link org.apache.directory.fortress.core.rbac.Mod}
+ * events as they occur automatically on the server when audit is enabled.
+ * <h4>Audit Interrogator</h4>
+ * Provides an OpenLDAP access log retrieval mechanism that enables security event monitoring.
+ * <ol>
+ * <li>Authentication events:
+ * <li>Session enablement events
+ * <li>Authorization events
+ * <li>Entity mods and deletes
+ * </li>
+ * </ol>
+ * <img src="./doc-files/Audit.png">
+ * <p/>
+ * All events include Fortress context, see {@link org.apache.directory.fortress.core.rbac.FortEntity}.
+ * <p/>
+ * <h4>
+ * The following APIs generate events subsequently stored in this access log:
+ * </h4>
+ * <ul>
+ * <li> {@link AccessMgr}
+ * <li> {@link AdminMgr}
+ * <li> {@link AdminMgr}
+ * <li> {@link DelAdminMgr}
+ * <li> {@link org.apache.directory.fortress.cfg.ConfigMgr}
+ * <li> {@link PwPolicyMgr}
+ * </ul>
+ * <h4>
+ * The following reports are supported using search input: {@link org.apache.directory.fortress.core.rbac.UserAudit}
+ * </h4>
+ * <ul>
+ * <li>User Authentications: <code>List<{@link org.apache.directory.fortress.core.rbac.Bind}> {@link AuditMgr#searchBinds(org.apache.directory.fortress.core.rbac.UserAudit)}</code>
+ * <li>Invalid User AuthN: <code>List<{@link org.apache.directory.fortress.core.rbac.Bind}> {@link AuditMgr#searchInvalidUsers(org.apache.directory.fortress.core.rbac.UserAudit)} </code>
+ * <li>User Authorizations 1: <code>List<{@link org.apache.directory.fortress.core.rbac.AuthZ}> {@link AuditMgr#getUserAuthZs(org.apache.directory.fortress.core.rbac.UserAudit)} </code>
+ * <li>User Authorizations 2: <code>List<{@link org.apache.directory.fortress.core.rbac.AuthZ}> {@link AuditMgr#searchAuthZs(org.apache.directory.fortress.core.rbac.UserAudit)} </code>
+ * <li>User Session Activations: <code>List<{@link org.apache.directory.fortress.core.rbac.Mod}> {@link AuditMgr#searchUserSessions(org.apache.directory.fortress.core.rbac.UserAudit)} </code>
+ * <li>Entity Modifications: <code>List<{@link org.apache.directory.fortress.core.rbac.Mod}> {@link AuditMgr#searchAdminMods(org.apache.directory.fortress.core.rbac.UserAudit)} </code>
+ * </ul>
+ * <p/>
+ * This interface's implementer will NOT be thread safe if parent instance variables ({@link Manageable#setContextId(String)} or {@link Manageable#setAdmin(org.apache.directory.fortress.core.rbac.Session)}) are set.
+ *
+ * @author Shawn McKinney
+ */
+public interface AuditMgr extends Manageable
+{
+ /**
+ * This method returns a list of authorization events for a particular user {@link org.apache.directory.fortress.core.rbac.UserAudit#userId}
+ * and given timestamp field {@link org.apache.directory.fortress.core.rbac.UserAudit#beginDate}.<BR>
+ * Method also can discriminate between all events or failed only by setting {@link org.apache.directory.fortress.core.rbac.UserAudit#failedOnly}.
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link org.apache.directory.fortress.core.rbac.UserAudit#userId} - contains the target userId</li>
+ * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li>
+ * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li>
+ * </ul>
+ *
+ * @param uAudit This entity is instantiated and populated before invocation.
+ * @return a List of objects of type AuthZ. Each AuthZ object contains one authorization event.
+ * @throws SecurityException if a runtime system error occurs.
+ */
+ public List<AuthZ> getUserAuthZs(UserAudit uAudit)
+ throws SecurityException;
+
+ /**
+ * This method returns a list of authorization events for a particular user {@link org.apache.directory.fortress.core.rbac.UserAudit#userId},
+ * object {@link org.apache.directory.fortress.core.rbac.UserAudit#objName}, and given timestamp field {@link org.apache.directory.fortress.core.rbac.UserAudit#beginDate}.<BR>
+ * Method also can discriminate between all events or failed only by setting flag {@link UserAudit#failedOnly}..
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link UserAudit#userId} - contains the target userId<</li>
+ * <li>{@link UserAudit#objName} - contains the object (authorization resource) name</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li>
+ * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li>
+ * </ul>
+ *
+ * @param uAudit This entity is instantiated and populated before invocation.
+ * @return a List of objects of type AuthZ. Each AuthZ object contains one authorization event.
+ * @throws SecurityException
+ * if a runtime system error occurs.
+ */
+ public List<AuthZ> searchAuthZs(UserAudit uAudit)
+ throws SecurityException;
+
+ /**
+ * This method returns a list of authentication audit events for a particular user {@link org.apache.directory.fortress.core.rbac.UserAudit#userId},
+ * and given timestamp field {@link org.apache.directory.fortress.core.rbac.UserAudit#beginDate}.<BR>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link org.apache.directory.fortress.core.rbac.UserAudit#userId} - contains the target userId<</li>
+ * <li>{@link org.apache.directory.fortress.core.rbac.UserAudit#beginDate} - contains the date in which to begin search</li>
+ * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li>
+ * </ul>
+ *
+ * @param uAudit This entity is instantiated and populated before invocation.
+ * @return a List of objects of type Bind. Each Bind object contains one bind event.
+ * @throws SecurityException
+ * if a runtime system error occurs.
+ */
+ public List<Bind> searchBinds(UserAudit uAudit)
+ throws SecurityException;
+
+ /**
+ * This method returns a list of sessions created for a given user {@link UserAudit#userId},
+ * and timestamp {@link org.apache.directory.fortress.core.rbac.UserAudit#beginDate}.<BR>
+ * <h4>required parameters</h4>
+ * <ul>
+ * <li>{@link UserAudit#userId} - contains the target userId<</li>
+ * </ul>
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li>
+ * </ul>
+ *
+ * @param uAudit This entity is instantiated and populated before invocation.
+ * @return a List of objects of type Mod. Each Mod object in list corresponds to one update or delete event on directory.
+ * @throws SecurityException if a runtime system error occurs.
+ */
+ public List<Mod> searchUserSessions(UserAudit uAudit)
+ throws SecurityException;
+
+ /**
+ * This method returns a list of admin operations events for a particular entity {@link org.apache.directory.fortress.core.rbac.UserAudit#dn},
+ * object {@link UserAudit#objName} and timestamp {@link org.apache.directory.fortress.core.rbac.UserAudit#beginDate}. If the internal
+ * userId {@link org.apache.directory.fortress.core.rbac.UserAudit#internalUserId} is set it will limit search by that field.
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link UserAudit#dn} - contains the LDAP distinguished name for the updated object. For example if caller
+ * wants to find out what changes were made to John Doe's user object this would be 'uid=jdoe,ou=People,dc=example,dc=com'</li>
+ * <li>{@link UserAudit#objName} - contains the object (authorization resource) name corresponding to the event. For example if caller
+ * wants to return events where User object was modified, this would be 'updateUser'</li>
+ * <li>{@link org.apache.directory.fortress.core.rbac.UserAudit#internalUserId} - maps to the internalUserId of user who changed the record in LDAP. This maps to {@link org.apache.directory.fortress.core.rbac.User#internalId}.</li>
+ * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li>
+ * <li>{@link UserAudit#endDate} - contains the date in which to end search</li>
+ * </ul>
+ *
+ * @param uAudit This entity is instantiated and populated before invocation.
+ * @return a List of objects of type Mod. Each Mod object in list corresponds to one update or delete event on directory.
+ * @throws SecurityException
+ * if a runtime system error occurs.
+ */
+ public List<Mod> searchAdminMods(UserAudit uAudit)
+ throws SecurityException;
+
+ /**
+ * This method returns a list of failed authentication attempts on behalf of an invalid identity {@link org.apache.directory.fortress.core.rbac.UserAudit#userId},
+ * and given timestamp {@link UserAudit#beginDate}. If the {@link org.apache.directory.fortress.core.rbac.UserAudit#failedOnly} is true it will
+ * return only authentication attempts made with invalid userId. This event represents either User incorrectly entering userId during signon or
+ * possible fraudulent logon attempt by hostile agent.
+ * </p>
+ * This event is generated when Fortress looks up User record prior to LDAP bind operation.
+ * <h4>optional parameters</h4>
+ * <ul>
+ * <li>{@link UserAudit#userId} - contains the target userId</li>
+ * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li>
+ * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li>
+ * </ul>
+ *
+ * @param uAudit This entity is instantiated and populated before invocation.
+ * @return a List of objects of type AuthZ. Each AuthZ object contains one failed authentication event.
+ * @throws SecurityException
+ * if a runtime system error occurs.
+ */
+ public List<AuthZ> searchInvalidUsers(UserAudit uAudit)
+ throws SecurityException;
+
+}
http://git-wip-us.apache.org/repos/asf/directory-fortress-core/blob/687ee1ad/src/main/java/org/apache/directory/fortress/core/AuditMgrFactory.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/directory/fortress/core/AuditMgrFactory.java b/src/main/java/org/apache/directory/fortress/core/AuditMgrFactory.java
new file mode 100755
index 0000000..8a28dd0
--- /dev/null
+++ b/src/main/java/org/apache/directory/fortress/core/AuditMgrFactory.java
@@ -0,0 +1,111 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.directory.fortress.core;
+
+import org.apache.directory.fortress.core.cfg.Config;
+import org.apache.directory.fortress.core.rbac.AuditMgrImpl;
+import org.apache.directory.fortress.core.rbac.ClassUtil;
+import org.apache.directory.fortress.core.rbac.Session;
+import org.apache.directory.fortress.core.rest.AuditMgrRestImpl;
+import org.apache.directory.fortress.core.util.attr.VUtil;
+
+/**
+ * Creates an instance of the AuditMgr object.
+ * <p/>
+ * The default implementation class is specified as {@link AuditMgrImpl} but can be overridden by
+ * adding the {@link GlobalIds#AUDIT_IMPLEMENTATION} config property.
+ * <p/>
+ *
+ * @author Shawn McKinney
+ */
+public class AuditMgrFactory
+{
+ private static String auditClassName = Config.getProperty(GlobalIds.AUDIT_IMPLEMENTATION);
+ private static final String CLS_NM = AuditMgrFactory.class.getName();
+
+ /**
+ * Create and return a reference to {@link AuditMgr} object using HOME context.
+ *
+ * @return instance of {@link AuditMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AuditMgr createInstance()
+ throws SecurityException
+ {
+ return createInstance( GlobalIds.HOME );
+ }
+
+ /**
+ * Create and return a reference to {@link AuditMgr} object.
+ *
+ * @param contextId maps to sub-tree in DIT, for example ou=contextId, dc=jts, dc = com.
+ * @return instance of {@link AuditMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AuditMgr createInstance(String contextId)
+ throws SecurityException
+ {
+ VUtil.assertNotNull(contextId, GlobalErrIds.CONTEXT_NULL, CLS_NM + ".createInstance");
+ if (!VUtil.isNotNullOrEmpty(auditClassName))
+ {
+ if(GlobalIds.IS_REST)
+ {
+ auditClassName = AuditMgrRestImpl.class.getName();
+ }
+ else
+ {
+ auditClassName = AuditMgrImpl.class.getName();
+ }
+ }
+
+ AuditMgr auditMgr = (AuditMgr) ClassUtil.createInstance(auditClassName);
+ auditMgr.setContextId(contextId);
+ return auditMgr;
+ }
+
+ /**
+ * Create and return a reference to {@link AuditMgr} object using HOME context.
+ *
+ * @param adminSess contains a valid Fortress A/RBAC Session object.
+ * @return instance of {@link AuditMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AuditMgr createInstance(Session adminSess)
+ throws SecurityException
+ {
+ return createInstance( GlobalIds.HOME, adminSess );
+ }
+
+ /**
+ * Create and return a reference to {@link AuditMgr} object.
+ *
+ * @param contextId maps to sub-tree in DIT, for example ou=contextId, dc=jts, dc = com.
+ * @param adminSess contains a valid Fortress A/RBAC Session object.
+ * @return instance of {@link AuditMgr}.
+ * @throws SecurityException in the event of failure during instantiation.
+ */
+ public static AuditMgr createInstance(String contextId, Session adminSess)
+ throws SecurityException
+ {
+ AuditMgr auditMgr = createInstance(contextId);
+ auditMgr.setAdmin(adminSess);
+ return auditMgr;
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/directory-fortress-core/blob/687ee1ad/src/main/java/org/apache/directory/fortress/core/AuthorizationException.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/directory/fortress/core/AuthorizationException.java b/src/main/java/org/apache/directory/fortress/core/AuthorizationException.java
new file mode 100755
index 0000000..7641bc5
--- /dev/null
+++ b/src/main/java/org/apache/directory/fortress/core/AuthorizationException.java
@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.directory.fortress.core;
+
+
+/**
+ * This exception extends {@link SecurityException} and is thrown when administrative permission check fails.
+ * See the {@link GlobalErrIds} javadoc for list of error ids.
+ *
+ * @author Shawn McKinney
+ */
+public class AuthorizationException extends SecurityException
+{
+ /**
+ * Create an exception with an error code that maps to {@link GlobalErrIds} and message text.
+ *
+ * @param errorId see {@link GlobalErrIds} for list of valid error codes that can be set. Valid values between 0 & 100_000.
+ * @param msg contains textual information including method of origin and description of the root cause.
+ */
+ public AuthorizationException(int errorId, String msg)
+ {
+ super(errorId, msg);
+ }
+}
+
http://git-wip-us.apache.org/repos/asf/directory-fortress-core/blob/687ee1ad/src/main/java/org/apache/directory/fortress/core/BaseException.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/directory/fortress/core/BaseException.java b/src/main/java/org/apache/directory/fortress/core/BaseException.java
new file mode 100755
index 0000000..69d99af
--- /dev/null
+++ b/src/main/java/org/apache/directory/fortress/core/BaseException.java
@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.directory.fortress.core;
+
+/**
+ * Base exception class for checked exceptions thrown. This class wraps {@code java.lang.Exception}. The BaseException
+ * class adds int attribute which stores the necessary error code as required by all checked exceptions in this system.
+ * The BaseException class has been extended by {@link SecurityException} which is then declared thrown on most Fortress public APIs.
+ * See the {@link GlobalErrIds} javadoc for list of error ids that will be set.
+ *
+ * @author Shawn McKinney
+ */
+public abstract class BaseException extends Exception implements StandardException
+{
+ private final int errorId;
+
+ /**
+ * Create exception containing error code and message.
+ *
+ * @param errorId see {@link GlobalErrIds} for list of valid error codes that can be set. Valid values between 0 & 100_000.
+ * @param msg contains textual information including method of origin and description of the root cause.
+ */
+ BaseException(int errorId, String msg)
+ {
+ super(msg);
+ this.errorId = errorId;
+ }
+
+ /**
+ * Create exception containing error code, message and previous exception.
+ *
+ * @param errorId see {@link GlobalErrIds} for list of valid error codes that can be set. Valid values between 0 & 100_000.
+ * @param msg contains textual information including method of origin and description of the root cause.
+ * @param previousException contains reference to related exception which usually is system related, i.e. ldap.
+ */
+ BaseException(int errorId, String msg, Throwable previousException)
+ {
+ super(msg, previousException);
+ this.errorId = errorId;
+ }
+
+ /**
+ * Return the error id that is defined by this class {@link GlobalErrIds}.
+ *
+ * @return error id which is defined here {@link GlobalErrIds}. Valid values for Fortress error codes fall between 0 and 100_000.
+ */
+ public int getErrorId()
+ {
+ return errorId;
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/directory-fortress-core/blob/687ee1ad/src/main/java/org/apache/directory/fortress/core/BaseRuntimeException.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/directory/fortress/core/BaseRuntimeException.java b/src/main/java/org/apache/directory/fortress/core/BaseRuntimeException.java
new file mode 100755
index 0000000..106f7c7
--- /dev/null
+++ b/src/main/java/org/apache/directory/fortress/core/BaseRuntimeException.java
@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+package org.apache.directory.fortress.core;
+
+/**
+ * Base runtime exception class for Fortress runtime exceptions.
+ * See the {@link GlobalErrIds} javadoc for list of error ids.
+ *
+ * @author Shawn McKinney
+ */
+public abstract class BaseRuntimeException extends RuntimeException
+{
+
+ private final int errorId;
+ private final String[] msgParams;
+
+ /**
+ *
+ * @param errorId int contains the error id which is defined here {@link GlobalErrIds}.
+ * @param msgParam contains message pertaining to exception.
+ * @param previousException contains reference to related exception which usually is system related, i.e. ldap.
+ */
+ protected BaseRuntimeException(int errorId, String msgParam, Throwable previousException)
+ {
+ super(msgParam + ", errCode=" + errorId, previousException);
+ this.errorId = errorId;
+ this.msgParams = new String[1];
+ this.msgParams[0] = msgParam;
+ }
+
+ /**
+ *
+ * @param errorId int contains the error id which is defined here {@link GlobalErrIds}.
+ * @param msgParam contains message pertaining to exception.
+ */
+ protected BaseRuntimeException(int errorId, String msgParam)
+ {
+ super(msgParam + ", errCode=" + errorId);
+ this.errorId = errorId;
+ this.msgParams = new String[1];
+ this.msgParams[0] = msgParam;
+ }
+
+ /**
+ * Return the message for current exception.
+ *
+ * @return string contains the error message.
+ */
+ public String getMsg()
+ {
+ String msg = null;
+ if (this.msgParams != null)
+ msg = this.msgParams[0];
+ return msg;
+ }
+
+ /**
+ * Return the error id that is defined by this class {@link GlobalErrIds}.
+ *
+ * @return error id which is defined here {@link GlobalErrIds}.
+ */
+ public int getErrorId()
+ {
+ return errorId;
+ }
+}