<commit_before>/*
 *   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.model.PermObj;
import org.apache.directory.fortress.core.model.Permission;
import org.apache.directory.fortress.core.model.PermissionAttribute;
import org.apache.directory.fortress.core.model.PermissionAttributeSet;
import org.apache.directory.fortress.core.model.Role;
import org.apache.directory.fortress.core.model.RoleConstraint;
import org.apache.directory.fortress.core.model.SDSet;
import org.apache.directory.fortress.core.model.User;
import org.apache.directory.fortress.core.model.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.
 * <hr>
 * <h3></h3>
 * <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" alt="">
 * <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" alt="">
 * <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" alt="">
 * <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" alt="">
 * <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.model.Session)}) are set.
 *
 * @author <a href="mailto:<EMAIL>">Apache Directory Project</a>
 */
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.
     * <h3></h3>
     * <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.
     */
    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:
     * <ul>
     *   <li>sets the user status to "deleted"</li>
     *   <li>deassigns all roles from the user</li>
     *   <li>locks the user's password in LDAP</li>
     *   <li>revokes all perms that have been granted to user entity.</li>
     * </ul>
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.
     */
    User updateUser( User user )
        throws SecurityException;


    /**
     * Method will change user's password.  This method will evaluate user's password policies.
     * <h3></h3>
     * <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.
     */
    void changePassword( User user, char[] newPassword )
        throws SecurityException;


    /**
     * Method will lock user's password which will prevent the user from authenticating with directory.
     * <h3></h3>
     * <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.
     */
    void lockUserAccount( User user )
        throws SecurityException;


    /**
     * Method will unlock user's password which will enable user to authenticate with directory.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.
     * @param newPassword The <PASSWORD>
     * @throws SecurityException will be thrown in the event of pw policy violation or system error.
     */
    void resetPassword( User user, char[] newPassword )
        throws SecurityException;


    /**
     * Method will delete user's password policy designation.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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}.
     * @return copy of the added Role 
     * @throws SecurityException thrown in the event of data validation or system error.
     */
    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.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.model.Constraint}
     * @return Role contains reference to entity operated on.
     * @throws SecurityException in the event of validation or system error.
     */
    Role updateRole( Role role )
        throws SecurityException;


    /**
     * This command assigns a user to a role.
     * <ul>
     *   <li> The command is valid if and only if:</li>
     *   <li>
     *     <ul>
     *       <li> The user is a member of the USERS data set</li>
     *       <li> The role is a member of the ROLES data set</li>
     *       <li> The user is not already assigned to the role</li>
     *       <li> The SSD constraints are satisfied after assignment.</li>
     *     </ul>
     *   </li>
     * </ul>
     * <p>
     * Successful completion of this op, the following occurs:
     * <ul>
     *   <li> 
     *     User entity (resides in people container) has role assignment added to aux object class attached to actual 
     *     user record.
     *   </li>
     *   <li> Role entity (resides in role container) has userId added as role occupant.</li>
     *   <li> (optional) Temporal constraints may be associated with <code>ftUserAttrs</code> aux object class based on:</li>
     *   <li>
     *     <ul>
     *       <li> timeout - number in seconds of session inactivity time allowed.</li>
     *       <li> beginDate - YYYYMMDD - determines date when role may be activated.</li>
     *       <li> endDate - YYMMDD - indicates latest date role may be activated.</li>
     *       <li> beginLockDate - YYYYMMDD - determines beginning of enforced inactive status</li>
     *       <li> endLockDate - YYMMDD - determines end of enforced inactive status.</li>
     *       <li> beginTime - HHMM - determines begin hour role may be activated in user's session.</li>
     *       <li> endTime - HHMM - determines end hour role may be activated in user's session.*</li>
     *       <li> dayMask - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day of week role may be activated.</li>
     *     </ul>
     *   </li>
     * </ul>
     * <h3></h3>
     * <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.
     */
    void assignUser( UserRole uRole )
        throws SecurityException;

    /**
     * This method adds a roleConstraint (ftRC) to the user ldap entry. (ftRC=ROLE_NAME$type$CONSTRAINT_TYPE$CONSTRAINT_PASETNAME$CONSTRAINT_VALUE)
     * <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>
     *   <li>{@link RoleConstraint#type} - contains the type of role constraint (filter, other)</li>
     *   <li>{@link RoleConstraint#value} - contains the value of the role constraint which is currently not validated in any way</li>
     *   <li>{@link RoleConstraint#paSetName} - contains the userId for existing User, contains the name of the permission attribute set this constraint is applicable for</li>
     * </ul>
     * 
     * @param uRole must contain {@link UserRole#userId} and {@link UserRole#name}
     * @param roleConstraint must contain {@link RoleConstraint#type} and {@link RoleConstraint#value} and {@link RoleConstraint#paSetName}
     * @return RoleConstraint that was added to user role assignment
     * @throws SecurityException in the event of validation or system error.
     */
    RoleConstraint addRoleConstraint( UserRole uRole, RoleConstraint roleConstraint )
    	throws SecurityException;
    
    /**
     * Thie method removes a roleConstraint (ftRC) from the user ldap entry.
     * <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>
     *   <li>{@link RoleConstraint#type} - contains the type of role constraint (filter, other)</li>
     *   <li>{@link RoleConstraint#value} - contains the value of the role constraint which is currently not validated in any way</li>
     *   <li>{@link RoleConstraint#paSetName} - contains the userId for existing User, contains the name of the permission attribute set this constraint is applicable for</li>
     * </ul>
     * 
     * @param uRole must contain {@link UserRole#userId} and {@link UserRole#name}
     * @param roleConstraint must contain {@link RoleConstraint#type} and {@link RoleConstraint#value} and {@link RoleConstraint#paSetName}   
     * @throws SecurityException in the event of validation or system error.
     */
    void removeRoleConstraint( UserRole uRole, RoleConstraint roleConstraint )
    	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:
     * <ul>
     *   <li>User entity in USER data set has role assignment removed.</li>
     *   <li>Role entity in ROLE data set has userId removed as role occupant.</li>
     *   <li>(optional) Temporal constraints will be removed from user aux object if set prior to call.</li>
     * </ul>
     * <h3></h3>
     * <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.model.UserRole#userId} and {@link UserRole#name}.
     * @throws SecurityException - in the event data error in user or role objects or system error.
     */
    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.model.Role} or 
     * {@link org.apache.directory.fortress.core.model.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}*-&gt;{@link Permission}).
     * <h3></h3>
     * <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.model.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.
     */
    Permission addPermission( Permission perm )
        throws SecurityException;

    
    /**
     * This method will create a new permission attribute set object with resides under the 
     * {@code ou=Constraints,ou=RBAC,dc=yourHostName,dc=com} container in directory information tree.
     * The attribute set may contain 0 to many {@link org.apache.directory.fortress.core.model.PermissionAttribute}
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttributeSet#name} - contains the name of the permission attribute set</li>
     * </ul>
     * 
     * @param permAttributeSet must contain {@link PermissionAttributeSet#name}
     * @return PermissionAttributeSet that was created
     * @throws SecurityException - thrown in the event of perm attribute set data or system error.
     */
    PermissionAttributeSet addPermissionAttributeSet( PermissionAttributeSet permAttributeSet )
    	throws SecurityException;
    
    /**
     * This method will delete a permission attribute set object.
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttributeSet#name} - contains the name of the permission attribute set</li>
     * </ul>
     * 
     * @param permAttributeSet must contain {@link PermissionAttributeSet#name}
     * @throws SecurityException - thrown in the event of perm attribute set data or system error.
     */
    void deletePermissionAttributeSet( PermissionAttributeSet permAttributeSet )
        throws SecurityException;
    
    /**
     * This method adds a permission attribute (ftPA) to a permission attribute set.
     * <h3></h3>
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#attributeName} - contains the name of existing object being targeted for the permission update</li>
     *   <li>{@link PermissionAttribute#dataType} - contains the data type of the permission attribute values (string,int,long,float)</li>   
     *   <li>attributeSetName - contains the name of existing permission attribute set being modified</li>
     * </ul>  
     * <h4>optional parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#required} - Flag to specify this attribute is required, defaults to false.</li>
     *   <li>{@link PermissionAttribute#operator} - Can specify an operator this attribute must use.</li>
     *   <li>{@link PermissionAttribute#validValues} - CSV of valid values. Currently up to interpreting application to understand these.</li>
     *   <li>{@link PermissionAttribute#defaultValue} - A default value for the attribute value if none is specified.</li>
     * </ul>
     *   
     * @param permAttribute must contain {@link PermissionAttribute#attributeName} and {@link PermissionAttribute#dataType}
     * @param attributeSetName The name of the permission attribute set this ftPA should be added.
     * @return PermissionAttribute entity created
     * @throws SecurityException - thrown in the event of data or system error
     */
    PermissionAttribute addPermissionAttributeToSet( PermissionAttribute permAttribute, String attributeSetName )
    	throws SecurityException;
    
    /**
     * This method removed a permission attribute (ftPA) from an existing permission attribute set.
     * <h3></h3>
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#attributeName} - contains the name of existing object being targeted for the permission update</li>
     *   <li>attributeSetName - contains the name of existing permission attribute set being modified</li>
     * </ul>     
	 *
     * @param permAttribute must contain {@link PermissionAttribute#attributeName}
     * @param attributeSetName The name of the permission attribute set this pa should be removed from
     * @throws SecurityException - thrown in the event of data or system error
     */
    void removePermissionAttributeFromSet( PermissionAttribute permAttribute, String attributeSetName )
    	throws SecurityException;
    
    /**
     * 
     * @param permAttribute must contain {@link PermissionAttribute#attributeName}
     * @param attributeSetName The name of the permission attribute set this pa should be removed from
     * @param replaceValidValues Set to true to replace all of the valid values and set to false to add to the existing valid values
     * @throws SecurityException - thrown in the event of data or system error
     */<commit_msg>FC-116 - cleanup javadoc on update<commit_after>/*
 *   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.model.PermObj;
import org.apache.directory.fortress.core.model.Permission;
import org.apache.directory.fortress.core.model.PermissionAttribute;
import org.apache.directory.fortress.core.model.PermissionAttributeSet;
import org.apache.directory.fortress.core.model.Role;
import org.apache.directory.fortress.core.model.RoleConstraint;
import org.apache.directory.fortress.core.model.SDSet;
import org.apache.directory.fortress.core.model.User;
import org.apache.directory.fortress.core.model.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.
 * <hr>
 * <h3></h3>
 * <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" alt="">
 * <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" alt="">
 * <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" alt="">
 * <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" alt="">
 * <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.model.Session)}) are set.
 *
 * @author <a href="mailto:<EMAIL>">Apache Directory Project</a>
 */
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.
     * <h3></h3>
     * <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.
     */
    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:
     * <ul>
     *   <li>sets the user status to "deleted"</li>
     *   <li>deassigns all roles from the user</li>
     *   <li>locks the user's password in LDAP</li>
     *   <li>revokes all perms that have been granted to user entity.</li>
     * </ul>
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.
     */
    User updateUser( User user )
        throws SecurityException;


    /**
     * Method will change user's password.  This method will evaluate user's password policies.
     * <h3></h3>
     * <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.
     */
    void changePassword( User user, char[] newPassword )
        throws SecurityException;


    /**
     * Method will lock user's password which will prevent the user from authenticating with directory.
     * <h3></h3>
     * <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.
     */
    void lockUserAccount( User user )
        throws SecurityException;


    /**
     * Method will unlock user's password which will enable user to authenticate with directory.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.
     * @param newPassword The new password to set
     * @throws SecurityException will be thrown in the event of pw policy violation or system error.
     */
    void resetPassword( User user, char[] newPassword )
        throws SecurityException;


    /**
     * Method will delete user's password policy designation.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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}.
     * @return copy of the added Role 
     * @throws SecurityException thrown in the event of data validation or system error.
     */
    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.
     * <h3></h3>
     * <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.
     */
    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.
     * <h3></h3>
     * <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.model.Constraint}
     * @return Role contains reference to entity operated on.
     * @throws SecurityException in the event of validation or system error.
     */
    Role updateRole( Role role )
        throws SecurityException;


    /**
     * This command assigns a user to a role.
     * <ul>
     *   <li> The command is valid if and only if:</li>
     *   <li>
     *     <ul>
     *       <li> The user is a member of the USERS data set</li>
     *       <li> The role is a member of the ROLES data set</li>
     *       <li> The user is not already assigned to the role</li>
     *       <li> The SSD constraints are satisfied after assignment.</li>
     *     </ul>
     *   </li>
     * </ul>
     * <p>
     * Successful completion of this op, the following occurs:
     * <ul>
     *   <li> 
     *     User entity (resides in people container) has role assignment added to aux object class attached to actual 
     *     user record.
     *   </li>
     *   <li> Role entity (resides in role container) has userId added as role occupant.</li>
     *   <li> (optional) Temporal constraints may be associated with <code>ftUserAttrs</code> aux object class based on:</li>
     *   <li>
     *     <ul>
     *       <li> timeout - number in seconds of session inactivity time allowed.</li>
     *       <li> beginDate - YYYYMMDD - determines date when role may be activated.</li>
     *       <li> endDate - YYMMDD - indicates latest date role may be activated.</li>
     *       <li> beginLockDate - YYYYMMDD - determines beginning of enforced inactive status</li>
     *       <li> endLockDate - YYMMDD - determines end of enforced inactive status.</li>
     *       <li> beginTime - HHMM - determines begin hour role may be activated in user's session.</li>
     *       <li> endTime - HHMM - determines end hour role may be activated in user's session.*</li>
     *       <li> dayMask - 1234567, 1 = Sunday, 2 = Monday, etc - specifies which day of week role may be activated.</li>
     *     </ul>
     *   </li>
     * </ul>
     * <h3></h3>
     * <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.
     */
    void assignUser( UserRole uRole )
        throws SecurityException;

    /**
     * This method adds a roleConstraint (ftRC) to the user ldap entry. (ftRC=ROLE_NAME$type$CONSTRAINT_TYPE$CONSTRAINT_PASETNAME$CONSTRAINT_VALUE)
     * <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>
     *   <li>{@link RoleConstraint#type} - contains the type of role constraint (filter, other)</li>
     *   <li>{@link RoleConstraint#value} - contains the value of the role constraint which is currently not validated in any way</li>
     *   <li>{@link RoleConstraint#paSetName} - contains the userId for existing User, contains the name of the permission attribute set this constraint is applicable for</li>
     * </ul>
     * 
     * @param uRole must contain {@link UserRole#userId} and {@link UserRole#name}
     * @param roleConstraint must contain {@link RoleConstraint#type} and {@link RoleConstraint#value} and {@link RoleConstraint#paSetName}
     * @return RoleConstraint that was added to user role assignment
     * @throws SecurityException in the event of validation or system error.
     */
    RoleConstraint addRoleConstraint( UserRole uRole, RoleConstraint roleConstraint )
    	throws SecurityException;
    
    /**
     * Thie method removes a roleConstraint (ftRC) from the user ldap entry.
     * <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>
     *   <li>{@link RoleConstraint#type} - contains the type of role constraint (filter, other)</li>
     *   <li>{@link RoleConstraint#value} - contains the value of the role constraint which is currently not validated in any way</li>
     *   <li>{@link RoleConstraint#paSetName} - contains the userId for existing User, contains the name of the permission attribute set this constraint is applicable for</li>
     * </ul>
     * 
     * @param uRole must contain {@link UserRole#userId} and {@link UserRole#name}
     * @param roleConstraint must contain {@link RoleConstraint#type} and {@link RoleConstraint#value} and {@link RoleConstraint#paSetName}   
     * @throws SecurityException in the event of validation or system error.
     */
    void removeRoleConstraint( UserRole uRole, RoleConstraint roleConstraint )
    	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:
     * <ul>
     *   <li>User entity in USER data set has role assignment removed.</li>
     *   <li>Role entity in ROLE data set has userId removed as role occupant.</li>
     *   <li>(optional) Temporal constraints will be removed from user aux object if set prior to call.</li>
     * </ul>
     * <h3></h3>
     * <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.model.UserRole#userId} and {@link UserRole#name}.
     * @throws SecurityException - in the event data error in user or role objects or system error.
     */
    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.model.Role} or 
     * {@link org.apache.directory.fortress.core.model.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}*-&gt;{@link Permission}).
     * <h3></h3>
     * <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.model.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.
     */
    Permission addPermission( Permission perm )
        throws SecurityException;

    
    /**
     * This method will create a new permission attribute set object with resides under the 
     * {@code ou=Constraints,ou=RBAC,dc=yourHostName,dc=com} container in directory information tree.
     * The attribute set may contain 0 to many {@link org.apache.directory.fortress.core.model.PermissionAttribute}
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttributeSet#name} - contains the name of the permission attribute set</li>
     * </ul>
     * 
     * @param permAttributeSet must contain {@link PermissionAttributeSet#name}
     * @return PermissionAttributeSet that was created
     * @throws SecurityException - thrown in the event of perm attribute set data or system error.
     */
    PermissionAttributeSet addPermissionAttributeSet( PermissionAttributeSet permAttributeSet )
    	throws SecurityException;
    
    /**
     * This method will delete a permission attribute set object.
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttributeSet#name} - contains the name of the permission attribute set</li>
     * </ul>
     * 
     * @param permAttributeSet must contain {@link PermissionAttributeSet#name}
     * @throws SecurityException - thrown in the event of perm attribute set data or system error.
     */
    void deletePermissionAttributeSet( PermissionAttributeSet permAttributeSet )
        throws SecurityException;
    
    /**
     * This method adds a permission attribute (ftPA) to a permission attribute set.
     * <h3></h3>
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#attributeName} - contains the name of existing object being targeted for the permission update</li>
     *   <li>{@link PermissionAttribute#dataType} - contains the data type of the permission attribute values (string,int,long,float)</li>   
     *   <li>attributeSetName - contains the name of existing permission attribute set being modified</li>
     * </ul>  
     * <h4>optional parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#required} - Flag to specify this attribute is required, defaults to false.</li>
     *   <li>{@link PermissionAttribute#operator} - Can specify an operator this attribute must use.</li>
     *   <li>{@link PermissionAttribute#validValues} - CSV of valid values. Currently up to interpreting application to understand these.</li>
     *   <li>{@link PermissionAttribute#defaultValue} - A default value for the attribute value if none is specified.</li>
     * </ul>
     *   
     * @param permAttribute must contain {@link PermissionAttribute#attributeName} and {@link PermissionAttribute#dataType}
     * @param attributeSetName The name of the permission attribute set this ftPA should be added.
     * @return PermissionAttribute entity created
     * @throws SecurityException - thrown in the event of data or system error
     */
    PermissionAttribute addPermissionAttributeToSet( PermissionAttribute permAttribute, String attributeSetName )
    	throws SecurityException;
    
    /**
     * This method removed a permission attribute (ftPA) from an existing permission attribute set.
     * <h3></h3>
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#attributeName} - contains the name of existing object being targeted for the permission update</li>
     *   <li>attributeSetName - contains the name of existing permission attribute set being modified</li>
     * </ul>     
	 *
     * @param permAttribute must contain {@link PermissionAttribute#attributeName}
     * @param attributeSetName The name of the permission attribute set this pa should be removed from
     * @throws SecurityException - thrown in the event of data or system error
     */
    void removePermissionAttributeFromSet( PermissionAttribute permAttribute, String attributeSetName )
    	throws SecurityException;

    /**
     * This method updates a permission attribute (ftPA) on a permission attribute set.
     * <h3></h3>
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#attributeName} - contains the name of existing object being targeted for the permission update</li>
     *   <li>{@link PermissionAttribute#dataType} - contains the data type of the permission attribute values (string,int,long,float)</li>
     *   <li>attributeSetName - contains the name of existing permission attribute set being modified</li>
     * </ul>
     * <h4>optional parameters</h4>
     * <ul>
     *   <li>{@link PermissionAttribute#required} - Flag to specify this attribute is required, defaults to false.</li>
     *   <li>{@link PermissionAttribute#operator} - Can specify an operator this attribute must use.</li>
     *   <li>{@link PermissionAttribute#validValues} - CSV of valid values. Currently up to interpreting application to understand these.</li>
     *   <li>{@link PermissionAttribute#defaultValue} - A default value for the attribute value if none is specified.</li>
     * </ul>
     *
     * @param permAttribute must contain {@link PermissionAttribute#attributeName} and {@link PermissionAttribute#dataType}
     * @param attributeSetName The name of the permission attribute set this ftPA should be updated.
     * @return PermissionAttribute entity created
     * @throws SecurityException - thrown in the event of data or system error
     */
{'fraction_non_alphanumeric': 0.0996114183231206, 'fraction_numerical': 0.005395307128979226, 'mean_word_length': 2.9519815722638945, 'pattern_counts': {'":': 0, '<': 968, '<?xml version=': 0, '>': 968, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5216292', 'n_tokens_mistral': 19041, 'n_tokens_neox': 18583, 'n_words': 7143}