Package edu.internet2.middleware.grouper.app.graph

Class RelationGraph

java.lang.Object
edu.internet2.middleware.grouper.app.graph.RelationGraph
public class RelationGraph extends Object
Class to build a directed graph from Grouper relationships. The graph is initialized from a single starting node. From there it will branch to the node's parents and children recursively until exhausted. Nodes can be of a subset of GrouperObject types -- Group, Stem, Subject (as GrouperObjectSubjectWrapper). A pseudo-object for provisioners is also implemented in this package so that PSPNG provisioning targets can be represented as nodes. For stems, it will get the parents and children of all its child groups. Each node contains an underlying GrouperObject type. Edges contain the directed relationship from parent to child. The methods involved in building the graph are influenced by setup parameters. For example, a build can include or exclude showing stems, or can filter certain stems based on regular expressions. The build can also optionally count group memberships and include the results as extra data within the nodes. As the build recursively follows parents and children, it stored the distanec (number of hops) from each node to the start node. After the build, The full set of nodes, edges, the starting node, and other information can be retrieved from the graph object. There is a hard limit of 100 levels, as an emergency stop against unforeseen cycles that miss detection.

  • Field Details

  • Constructor Details

    • RelationGraph

      public RelationGraph()
      Create a new graph with default settings. Caller should call the various assign methods to set build parameters, and then call build() to construct the graph.

  • Method Details

    • assignStartObject

      public RelationGraph assignStartObject(GrouperObject theStartObject)
      sets the GrouperObject object to serve as the starting point of the graph
      Parameters:
      theStartObject - Group, Stem, or GrouperObjectSubjectWrapper object to start the tree from
      Returns:

    • assignStartObject

      public RelationGraph assignStartObject(Subject theStartSubject)
      sets the start object from a subject, by converting to a GrouperObjectSubjectWrapper
      Parameters:
      theStartSubject - subject to start the tree from
      Returns:

    • assignParentLevels

      public RelationGraph assignParentLevels(long theParentLevels)
      sets the maximum number of parent levels to include in the graph
      Parameters:
      theParentLevels - number of parent steps to include, or -1 to include all levels
      Returns:

    • assignChildLevels

      public RelationGraph assignChildLevels(long theChildLevels)
      sets the maximum number of child levels to include in the graph
      Parameters:
      theChildLevels - number of child steps to include, or -1 to include all levels
      Returns:

    • assignShowAllMemberCounts

      public RelationGraph assignShowAllMemberCounts(boolean theShowAllMemberCounts)
      flags whether to count memberships (direct and indirect) for groups
      Parameters:
      theShowAllMemberCounts - whether to count memberships for groups
      Returns:

    • assignShowDirectMemberCounts

      public RelationGraph assignShowDirectMemberCounts(boolean theShowDirectMemberCounts)
      flags whether to count direct memberships for groups
      Parameters:
      theShowDirectMemberCounts - whether to count direct memberships for groups
      Returns:

    • assignShowObjectTypes

      public RelationGraph assignShowObjectTypes(boolean theShowObjectTypes)
      flags whether to show the object type strings (e.g. ref, basis ...) for stems and groups
      Parameters:
      theShowObjectTypes - whether to count direct memberships for groups
      Returns:

    • assignShowLoaderJobs

      public RelationGraph assignShowLoaderJobs(boolean theShowLoaderJobs)
      flags whether to show the loader jobs that populate groups
      Parameters:
      theShowLoaderJobs - whether to include loader jobs
      Returns:

    • assignSubjectForIsMemberCheck

      public RelationGraph assignSubjectForIsMemberCheck(Subject theSubject)
      If we're checking whether a subject is a member of each group
      Parameters:
      theSearchSubject -
      Returns:

    • assignShowProvisionTargets

      public RelationGraph assignShowProvisionTargets(boolean theShowProvisionTargets)
      flags whether to show provisioner targets. If set, this requires that the attribute definition for etc:pspng:provision_to be created, otherwise an exception in the build will occur
      Parameters:
      theShowProvisionTargets - whether to include provisioner targets
      Returns:

    • assignShowStems

      public RelationGraph assignShowStems(boolean theShowStems)
      flags whether to show stems
      Parameters:
      theShowStems - whether to include stems
      Returns:

    • assignIncludeGroupsInMemberCounts

      public RelationGraph assignIncludeGroupsInMemberCounts(boolean includeGroupsInMemberCounts)
      flags whether to include groups in the count of group members
      Parameters:
      includeGroupsInMemberCounts - whether to consider groups when counting members
      Returns:

    • assignSkipFolderNamePatterns

      public RelationGraph assignSkipFolderNamePatterns(Set<String> theSkipFolderNamePatterns)
      Assigns patterns for stem names to be filtered out. Will not skip the starting node even if it matches.
      Parameters:
      theSkipFolderNamePatterns - the set of regular expressions to filter out matching stem names

    • assignSkipGroupNamePatterns

      public RelationGraph assignSkipGroupNamePatterns(Set<String> theSkipGroupNamePatterns)
      Assigns patterns for group names to be filtered out. Will not skip the starting node even if it matches.
      Parameters:
      theSkipGroupNamePatterns - the set of regular expressions to filter out matching group names

    • assignMaxSiblings

      public RelationGraph assignMaxSiblings(long theMaxSiblings)
      The maximum number of objects of the same type to add as parents/children, or a value zero or less to include all objects. Any more than this will be excluded from the graph. The same "type" refers to the role; e.g., both loader jobs and members will be parents of a group, but are different types.
      Parameters:
      theMaxSiblings - the maximum number of sibling objects before filtering out additional ones

    • getParentLevels

      public long getParentLevels()
      returns the number of parent levels to include in the graph
      Returns:
      the maximum number of parent levels to include in the graph
      See Also:

    • getChildLevels

      public long getChildLevels()
      returns the number of child levels to include in the graph
      Returns:
      the maximum number of child levels to include in the graph
      See Also:

    • isShowAllMemberCounts

      public boolean isShowAllMemberCounts()
      returns whether memberships are counted for Group nodes
      Returns:
      if memberships are counted for groups
      See Also:

    • isShowDirectMemberCounts

      public boolean isShowDirectMemberCounts()
      returns whether direct memberships are counted for Group nodes
      Returns:
      if direct memberships are counted for groups
      See Also:

    • isShowObjectTypes

      public boolean isShowObjectTypes()
      returns whether to show object types for stems and groups
      Returns:
      if showing object types
      See Also:

    • isShowLoaderJobs

      public boolean isShowLoaderJobs()
      returns whether loader jobs should be included as graph nodes
      Returns:
      if loader jobs should be included in the graph
      See Also:

    • isShowProvisionTargets

      public boolean isShowProvisionTargets()
      returns whether provisioner targets should be included as graph nodes
      Returns:
      if provisioners should be included in the graph
      See Also:

    • isShowStems

      public boolean isShowStems()
      returns whether stems should be included as graph nodes
      Returns:
      if stems should be included in the graph
      See Also:

    • isIncludeGroupsInMemberCounts

      public boolean isIncludeGroupsInMemberCounts()
      returns whether to include groups in the count of group members
      Returns:
      if groups are considered in the count of group members
      See Also:

    • getSkipFolderNamePatterns

      public Set<String> getSkipFolderNamePatterns()
      returns the filters for stems when building the graph
      Returns:
      the set of regular expressions to filter out matching stem names
      See Also:

    • getSkipGroupNamePatterns

      public Set<String> getSkipGroupNamePatterns()
      returns the filters for stems when building the graph
      Returns:
      the set of regular expressions to filter out matching stem names
      See Also:

    • getMaxSiblings

      public long getMaxSiblings()
      returns the maximum number of objects of the same type to be included as parents or children of an object
      Returns:
      the maximum number of objects of the same type to be included in relations
      See Also:

    • getStartNode

      public GraphNode getStartNode()
      The initializing object for the object, wrapped in a node
      Returns:
      the starting node

    • getEdges

      public Set<GraphEdge> getEdges()
      after building, returns the set of all edges
      Returns:
      The set of all edges in the built graph

    • getNodes

      public Collection<GraphNode> getNodes()
      after building, returns the set of all nodes
      Returns:
      The set of all nodes in the built graph

    • getNumSkippedFolders

      public long getNumSkippedFolders()
      after building, returns how many folders were skipped as the result of filters
      Returns:
      the number of folders skipped due to filters

    • getNumSkippedGroups

      public long getNumSkippedGroups()
      after building, returns how many groups were skipped as the result of filters
      Returns:
      the number of groups skipped due to filters

    • getNumLoaders

      public long getNumLoaders()
      after building, returns how many loader jobs were encountered
      Returns:
      the number of loader jobs in the graph

    • getNumGroupsFromLoaders

      public long getNumGroupsFromLoaders()
      after building, returns how many groups have memberships loaded from loader jobs
      Returns:
      the number of groups loaded from loader jobs

    • getNumProvisioners

      public long getNumProvisioners()
      after building, returns how many distinct provisioners were encountered
      Returns:
      the number of provisioning targets in the graph

    • getTotalMemberCount

      public long getTotalMemberCount()
      after building, the total of all memberships in all groups
      Returns:
      the total of all group memberships

    • getDirectMemberCount

      public long getDirectMemberCount()
      after building, the total of all direct memberships in all groups
      Returns:
      the total of direct group memberships

    • getSubjectForIsMemberCheck

      public Subject getSubjectForIsMemberCheck()
      If we're checking whether a subject is a member of each group
      Returns:
      the subject

    • getNumGroupsToProvisioners

      public long getNumGroupsToProvisioners()
      after building, returns how many groups have one or more provisioner targets
      Returns:
      the number of groups loaded from loader jobs

    • getMaxParentDistance

      public long getMaxParentDistance()
      After building, returns the highest parent distance from the starting node. This will always be a positive number, even though parents of the start node will have property distanceFromStartNode less than zero.
      Returns:
      the the maximum parent distance from the starting node

    • getMaxChildDistance

      public long getMaxChildDistance()
      After building, returns the highest child distance from the starting node. This will always be zero or greater.
      Returns:
      the the maximum child distance from the starting node

    • getLeafParentNodes

      public Set<GraphNode> getLeafParentNodes()
      returns all the top level parent nodes (nodes with no parents)
      Returns:
      all nodes which do not have parent nodes

    • getLeafChildNodes

      public Set<GraphNode> getLeafChildNodes()
      returns all the bottom level child nodes (nodes with no children)
      Returns:
      all nodes which do not have child nodes

    • getNode

      public GraphNode getNode(GrouperObject object)
      retrieve a graph node based on its contained Grouper object
      Parameters:
      object - the Grouper object to query
      Returns:
      the node containing this object, or null if not found

    • build

      public void build()
      Builds the directed graph. Beginning with the starting node, will recursively walk its parents and children. For stems, will visit the parents and children of all its child groups. If starting with a subject, will only visit the children.

    • getObjectTypesUsed

      public Set<String> getObjectTypesUsed()
      keep track of which types are used for legend
      Returns:
      the objectTypesUsed

    • getSqlLoaderAttributeDefName

      public static AttributeDefName getSqlLoaderAttributeDefName()
      should be only useful for GraphNode nodes needing the sql loader attribute within the context of the user session
      Returns: