src/main/java/org/apache/directory/fortress/core/impl/PsoUtil.java [112:248]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Set<String> getDescendants( String name, String contextId )
    {
        return HierUtil.getDescendants( name, getGraph( contextId ) );
    }


    /**
     * Recursively traverse the {@link org.apache.directory.fortress.core.model.OrgUnit.Type#USER} graph and return all of the ascendants of a given child ou.
     *
     * @param name      maps to logical {@link org.apache.directory.fortress.core.model.OrgUnit#name} on 'ftOrgUnit' object class.
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @return Set of ou names that are ascendants of given child.
     */
    Set<String> getAscendants( String name, String contextId )
    {
        return HierUtil.getAscendants( name, getGraph( contextId ) );
    }


    /**
     * Traverse one level of the {@link org.apache.directory.fortress.core.model.OrgUnit} graph and return all of the children (direct descendants) of a given parent {@link org.apache.directory.fortress.core.model.OrgUnit#name}.
     *
     * @param name      {@link org.apache.directory.fortress.core.model.OrgUnit#name} maps on 'ftOrgUnit' object class.
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @return Set of names of children {@link org.apache.directory.fortress.core.model.OrgUnit}s of given parent.
     */
    public Set<String> getChildren( String name, String contextId )
    {
        return HierUtil.getChildren( name, getGraph( contextId ) );
    }


    /**
     * Traverse one level of the {@link org.apache.directory.fortress.core.model.OrgUnit.Type#USER} graph and return all of the parents (direct ascendants) of a given child ou.
     *
     * @param name      maps to logical {@link org.apache.directory.fortress.core.model.OrgUnit#name} on 'ftOrgUnit' object class.
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @return Set of ou names that are parents of given child.
     */
    Set<String> getParents( String name, String contextId )
    {
        return HierUtil.getParents( name, getGraph( contextId ) );
    }


    /**
     * Recursively traverse the {@link org.apache.directory.fortress.core.model.OrgUnit.Type#PERM} graph and return number of children a given parent ou has.
     *
     * @param name      maps to logical {@link org.apache.directory.fortress.core.model.OrgUnit#name} on 'ftOrgUnit' object class.
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @return int value contains the number of children of a given parent ou.
     */
    int numChildren( String name, String contextId )
    {
        return HierUtil.numChildren( name, getGraph( contextId ) );
    }


    /**
     * Return Set of {@link org.apache.directory.fortress.core.model.OrgUnit#name}s ascendants contained within {@link org.apache.directory.fortress.core.model.OrgUnit.Type#PERM}.
     *
     * @param ous       contains list of {@link org.apache.directory.fortress.core.model.OrgUnit}s.
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @return contains Set of all descendants.
     */
    Set<String> getInherited( List<OrgUnit> ous, String contextId )
    {
        // create Set with case insensitive comparator:
        Set<String> iOUs = new TreeSet<>( String.CASE_INSENSITIVE_ORDER );
        if ( CollectionUtils.isNotEmpty( ous ) )
        {
            for ( OrgUnit ou : ous )
            {
                String name = ou.getName();
                iOUs.add( name );
                Set<String> parents = HierUtil.getAscendants( name, getGraph( contextId ) );

                if ( CollectionUtils.isNotEmpty( parents ) )
                {
                    iOUs.addAll( parents );
                }
            }
        }
        return iOUs;
    }


    /**
     * This api is used by {@link DelAdminMgrImpl} to determine parentage for Permission OU processing.
     * It calls {@link HierUtil#validateRelationship(org.jgrapht.graph.SimpleDirectedGraph, String, String, boolean)} to evaluate three OU relationship expressions:
     * <ol>
     * <li>If child equals parent</li>
     * <li>If mustExist true and parent-child relationship exists</li>
     * <li>If mustExist false and parent-child relationship does not exist</li>
     * </ol>
     * Method will throw {@link org.apache.directory.fortress.core.ValidationException} if rule check fails meaning caller failed validation
     * attempt to add/remove hierarchical relationship failed.
     *
     * @param child     contains {@link org.apache.directory.fortress.core.model.OrgUnit#name} of child.
     * @param parent    contains {@link org.apache.directory.fortress.core.model.OrgUnit#name} of parent.
     * @param mustExist boolean is used to specify if relationship must be true.
     * @throws org.apache.directory.fortress.core.ValidationException
     *          in the event it fails one of the 3 checks.
     */
    void validateRelationship( OrgUnit child, OrgUnit parent, boolean mustExist )
        throws ValidationException
    {
        HierUtil.validateRelationship( getGraph( child.getContextId() ), child.getName(), parent.getName(), mustExist );
    }


    /**
     * This api allows synchronized access to allow updates to hierarchical relationships.
     * Method will update the hierarchical data set and reload the JGraphT simple digraph with latest.
     *
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @param relationship contains parent-child relationship targeted for addition.
     * @param op   used to pass the ldap op {@link org.apache.directory.fortress.core.model.Hier.Op#ADD}, {@link org.apache.directory.fortress.core.model.Hier.Op#MOD}, {@link org.apache.directory.fortress.core.model.Hier.Op#REM}
     * @throws org.apache.directory.fortress.core.SecurityException in the event of a system error.
     */
    void updateHier( String contextId, Relationship relationship, Hier.Op op ) throws SecurityException
    {
        HierUtil.updateHier( getGraph( contextId ), relationship, op );
    }


    /**
     * Read this ldap record,{@code cn=Hierarchies, ou=OS-P} into this entity, {@link Hier}, before loading into this collection class,{@code org.jgrapht.graph.SimpleDirectedGraph}
     * using 3rd party lib, <a href="http://www.jgrapht.org/">JGraphT</a>.
     *
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @return handle to simple digraph containing perm ou hierarchies.
     */
    private synchronized SimpleDirectedGraph<String, Relationship> loadGraph( String contextId )
    {
        Hier inHier = new Hier( Hier.Type.ROLE );
        inHier.setContextId( contextId );
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -



src/main/java/org/apache/directory/fortress/core/impl/UsoUtil.java [116:249]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Set<String> getDescendants( String name, String contextId )
    {
        return HierUtil.getDescendants( name, getGraph( contextId ) );
    }


    /**
     * Recursively traverse the {@link org.apache.directory.fortress.core.model.OrgUnit.Type#USER} graph and return all of the ascendants of a given child ou.
     *
     * @param name maps to logical {@link org.apache.directory.fortress.core.model.OrgUnit#name} on 'ftOrgUnit' object class.
     * @return Set of ou names that are ascendants of given child.
     */
    Set<String> getAscendants( String name, String contextId )
    {
        return HierUtil.getAscendants( name, getGraph( contextId ) );
    }


    /**
     * Traverse one level of the {@link org.apache.directory.fortress.core.model.OrgUnit} graph and return all of the children (direct descendants) of a given parent {@link org.apache.directory.fortress.core.model.OrgUnit#name}.
     *
     * @param name {@link org.apache.directory.fortress.core.model.OrgUnit#name} maps on 'ftOrgUnit' object class.
     * @return Set of names of children {@link org.apache.directory.fortress.core.model.OrgUnit}s of given parent.
     */
    public Set<String> getChildren( String name, String contextId )
    {
        return HierUtil.getChildren( name, getGraph( contextId ) );
    }


    /**
     * Traverse one level of the {@link org.apache.directory.fortress.core.model.OrgUnit.Type#USER} graph and return all of the parents (direct ascendants) of a given child ou.
     *
     * @param name maps to logical {@link org.apache.directory.fortress.core.model.OrgUnit#name} on 'ftOrgUnit' object class.
     * @return Set of ou names that are parents of given child.
     */
    Set<String> getParents( String name, String contextId )
    {
        return HierUtil.getParents( name, getGraph( contextId ) );
    }


    /**
     * Recursively traverse the {@link org.apache.directory.fortress.core.model.OrgUnit.Type#USER} graph and return number of children a given parent ou has.
     *
     * @param name maps to logical {@link org.apache.directory.fortress.core.model.OrgUnit#name} on 'ftOrgUnit' object class.
     * @return int value contains the number of children of a given parent ou.
     */
    int numChildren( String name, String contextId )
    {
        return HierUtil.numChildren( name, getGraph( contextId ) );
    }


    /**
     * Return Set of {@link org.apache.directory.fortress.core.model.OrgUnit#name}s ascendants contained within {@link org.apache.directory.fortress.core.model.OrgUnit.Type#USER}.
     *
     * @param ous contains list of {@link org.apache.directory.fortress.core.model.OrgUnit}s.
     * @return contains Set of all descendants.
     */
    Set<String> getInherited( List<OrgUnit> ous, String contextId )
    {
        // create Set with case insensitive comparator:
        Set<String> iOUs = new TreeSet<>( String.CASE_INSENSITIVE_ORDER );
        
        if ( CollectionUtils.isNotEmpty( ous ) )
        {
            for ( OrgUnit ou : ous )
            {
                String name = ou.getName();
                iOUs.add( name );
                Set<String> parents = HierUtil.getAscendants( name, getGraph( contextId ) );
                
                if ( CollectionUtils.isNotEmpty( parents ) )
                {
                    iOUs.addAll( parents );
                }
            }
        }
        
        return iOUs;
    }


    /**
     * This api is used by {@link DelAdminMgrImpl} to determine parentage for User OU processing.
     * It calls {@link HierUtil#validateRelationship(org.jgrapht.graph.SimpleDirectedGraph, String, String, boolean)} to evaluate three OU relationship expressions:
     * <ol>
     * <li>If child equals parent</li>
     * <li>If mustExist true and parent-child relationship exists</li>
     * <li>If mustExist false and parent-child relationship does not exist</li>
     * </ol>
     * Method will throw {@link org.apache.directory.fortress.core.ValidationException} if rule check fails meaning caller failed validation
     * attempt to add/remove hierarchical relationship failed.
     *
     * @param child     contains {@link org.apache.directory.fortress.core.model.OrgUnit#name} of child.
     * @param parent    contains {@link org.apache.directory.fortress.core.model.OrgUnit#name} of parent.
     * @param mustExist boolean is used to specify if relationship must be true.
     * @throws org.apache.directory.fortress.core.ValidationException
     *          in the event it fails one of the 3 checks.
     */
    void validateRelationship( OrgUnit child, OrgUnit parent, boolean mustExist )
        throws ValidationException
    {
        HierUtil.validateRelationship( getGraph( child.getContextId() ), child.getName(), parent.getName(), mustExist );
    }


    /**
     * This api allows synchronized access to allow updates to hierarchical relationships.
     * Method will update the hierarchical data set and reload the JGraphT simple digraph with latest.
     *
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @param relationship contains parent-child relationship targeted for addition.
     * @param op   used to pass the ldap op {@link org.apache.directory.fortress.core.model.Hier.Op#ADD}, {@link org.apache.directory.fortress.core.model.Hier.Op#MOD}, {@link org.apache.directory.fortress.core.model.Hier.Op#REM}
     * @throws org.apache.directory.fortress.core.SecurityException in the event of a system error.
     */
    void updateHier( String contextId, Relationship relationship, Hier.Op op ) throws SecurityException
    {
        HierUtil.updateHier( getGraph( contextId ), relationship, op );
    }


    /**
     * Read this ldap record,{@code cn=Hierarchies, ou=OS-P} into this entity, {@link Hier}, before loading into this collection class,{@code org.jgrapht.graph.SimpleDirectedGraph}
     * using 3rd party lib, <a href="http://www.jgrapht.org/">JGraphT</a>.
     *
     * @param contextId maps to sub-tree in DIT, e.g. ou=contextId, dc=example, dc=com.
     * @return handle to simple digraph containing user ou hierarchies.
     */
    private synchronized SimpleDirectedGraph<String, Relationship> loadGraph( String contextId )
    {
        Hier inHier = new Hier( Hier.Type.ROLE );
        inHier.setContextId( contextId );
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -