com.ibm.pim.organization
Interface OrganizationHierarchy


public interface OrganizationHierarchy

Interface for the Hierarchy object representing a Hierarchy of organizations.

Since:
6.0.0

Field Summary
static java.lang.String copyright
           
 
Method Summary
 Organization createOrganization(java.lang.String parentOrganizationPath, java.lang.String delimiter, java.lang.String pathValue)
          Returns a new organization object.
 Organization createOrganization(java.lang.String parentOrganizationPath, java.lang.String delimiter, java.lang.String pathValue, java.lang.String primaryKeyValue)
          Returns a new organization object.
 Schedule deleteAsynchronous()
          Schedules a delete of this hierarchy.
 AccessControlGroup getAccessControlGroup()
          Returns the Access Control Group for this hierarchy
 AttributeDefinition getDisplayAttribute()
          Returns the display attribute for this hierarchy
 java.lang.String getName()
          Retrieves the name of this hierarchy.
 Organization getOrganizationByPath(java.lang.String path)
          Retrieves a Organization based upon Path name
 Organization getOrganizationByPath(java.lang.String path, java.lang.String delimiter)
          Retrieves a Organization based upon Path name
 Organization getOrganizationByPrimaryKey(java.lang.String primaryKey)
          Retrieves a Organization based upon Primary key
 PIMCollection<Organization> getOrganizations()
          Retrieves a collection of all the Organization objects in this hierarchy.
 PIMCollection<Organization> getOrganizationsAtLevel(int level)
          Retrieves a collection of all the Organization objects in this hierarchy residing at a particular level.
 java.util.Collection<Organization> getOrganizationsByPaths(java.util.Collection<java.lang.String> paths)
          Retrieves a collection of all the Organization objects in this hierarchy based upon their path names.
 java.util.Collection<Organization> getOrganizationsByPaths(java.util.Collection<java.lang.String> paths, java.lang.String delimiter)
          Retrieves a collection of all the Organization objects in this hierarchy based upon their path names.
 PIMCollection<Organization> getOrganizationsWithAttributeValue(java.lang.String attributeInstancePath, java.lang.Object attributeValue)
          Retrieves a collection of all the Organization objects in this hierarchy based upon a particular attribute value.
 AttributeDefinition getPathAttribute()
          Returns the path attribute for this hierarchy
 PrimarySpec getPrimarySpec()
          Retrieves the Primary spec for this hierarchy.
 Organization getRootOrganization()
          Returns the root organization for this Hierarchy
 AttributeCollection getUserDefinedAttributeCollection()
          Retrieves the User Defined Core Attribute Collection for this hierarchy
 java.util.List<ValidationErrors> save()
          Persist the changes to the given hierarchy object
 void setAccessControlGroup(AccessControlGroup acg)
          Sets the Access Control Group for this hierarchy
 void setDisplayAttribute(AttributeDefinition attribute)
          Set the attribute to be used as the display attribute for the hierarchy
 void setUserDefinedAttributeCollection(AttributeCollection attributeCollection)
          Associate the User defined Core Attribute collection with the hierarchy
 

Field Detail

copyright

static final java.lang.String copyright
See Also:
Constant Field Values
Method Detail

createOrganization

Organization createOrganization(java.lang.String parentOrganizationPath,
                                java.lang.String delimiter,
                                java.lang.String pathValue)
Returns a new organization object. The organization object must be persisted by calling save() on the containing hierarchy.

Parameters:
parentOrganizationPath - The path of the parent organization excluding the root name.
delimiter - The delimiter used in the provided parent Path. The delimiter consists of all characters in the delmiter string taken together.
pathValue - The value for the path attribute of the organization.
Returns:
Organization object
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ADD_HIERARCHY_NODES
PIMInvalidPathException - If the parent Path does not exist.
java.lang.IllegalArgumentException - if any of the parameters is null or if delimiter or pathValue is empty

createOrganization

Organization createOrganization(java.lang.String parentOrganizationPath,
                                java.lang.String delimiter,
                                java.lang.String pathValue,
                                java.lang.String primaryKeyValue)
Returns a new organization object. The organization object must be persisted by calling save() on the containing hierarchy.

Parameters:
parentOrganizationPath - The path of the parent organization excluding the root name.
delimiter - The delimiter used in the provided parent Path. The delimiter consists of all characters in the delmiter string taken together.
pathValue - The value for the path attribute of the organization.
primaryKeyValue - Primary key value for the organization
Returns:
Organization object
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ADD_HIERARCHY_NODES
PIMInvalidPathException - If the parent Path does not exist.
java.lang.IllegalArgumentException - if any of the parameters is null or if delimiter, pathValue or primaryKeyValue is empty

deleteAsynchronous

Schedule deleteAsynchronous()
Schedules a delete of this hierarchy. The Scheduled Job is run immediately and it's progress can be monitored, via the returned Schedule Object. Please note that subsequent to calling this method the Hierarchy object becomes invalid.

Returns:
A Job Schedule
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_DELETE

getAccessControlGroup

AccessControlGroup getAccessControlGroup()
Returns the Access Control Group for this hierarchy

Returns:
Access Control Group for this hierarchy
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES

getOrganizations

PIMCollection<Organization> getOrganizations()
Retrieves a collection of all the Organization objects in this hierarchy. This does not include the root organization.

Returns:
a PIMCollection of organization objects. Please note this is a lazily instantiated collection
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES
See Also:
for more info

getOrganizationsWithAttributeValue

PIMCollection<Organization> getOrganizationsWithAttributeValue(java.lang.String attributeInstancePath,
                                                               java.lang.Object attributeValue)
Retrieves a collection of all the Organization objects in this hierarchy based upon a particular attribute value. The attribute must be an indexed attribute.

Parameters:
attributeInstancePath - The Path of the attribute
attributeValue - The Value of the attribute instance.
Returns:
a PIMCollection of organization objects. Please note this is a lazily instantiated collection
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES
PIMInvalidPathException - If the given attribute path does not exist.
java.lang.IllegalArgumentException - if any of the parameters is null, or if attributeInstancePath is empty
See Also:
for more info

getOrganizationsAtLevel

PIMCollection<Organization> getOrganizationsAtLevel(int level)
Retrieves a collection of all the Organization objects in this hierarchy residing at a particular level.

Parameters:
level - the level in the hierarchy for which organizations to be returned. Level 1 will return all the organizations under root.
Returns:
a PIMCollection of organization objects. Please note this is a lazily instantiated collection
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES
java.lang.IllegalArgumentException - If the passed in level is not a positive non-zero number.
See Also:
for more info

getOrganizationsByPaths

java.util.Collection<Organization> getOrganizationsByPaths(java.util.Collection<java.lang.String> paths)
Retrieves a collection of all the Organization objects in this hierarchy based upon their path names. No exception is thrown if a path does not resolve to an existing organization.

Parameters:
paths - Organization paths excluding the root organization name
Returns:
a collection of organization objects
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES

getOrganizationsByPaths

java.util.Collection<Organization> getOrganizationsByPaths(java.util.Collection<java.lang.String> paths,
                                                           java.lang.String delimiter)
Retrieves a collection of all the Organization objects in this hierarchy based upon their path names. No exception is throw if a path does not resolve to an existing organization.

Parameters:
paths - Organization paths excluding the root organization name
delimiter - The delimiter used in the provided paths.
Returns:
a collection of organization objects
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES
java.lang.IllegalArgumentException - if any of the parameters is null or if delimiter is empty

getOrganizationByPath

Organization getOrganizationByPath(java.lang.String path)
Retrieves a Organization based upon Path name

Parameters:
path - organization path excluding the root organization name
Returns:
a organization object, or null if an organization with the given path is not found
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES
java.lang.IllegalArgumentException - if path is null

getOrganizationByPath

Organization getOrganizationByPath(java.lang.String path,
                                   java.lang.String delimiter)
Retrieves a Organization based upon Path name

Parameters:
path - organization path excluding the root organization name
delimiter - the delimiter used in the provided path, or null if an organization with the given path is not found
Returns:
a organization object
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES
java.lang.IllegalArgumentException - if any of the parameters is null or if delimiter is empty

getOrganizationByPrimaryKey

Organization getOrganizationByPrimaryKey(java.lang.String primaryKey)
Retrieves a Organization based upon Primary key

Parameters:
primaryKey - primary key
Returns:
a organization object, or null if an organization with the given primarykey is not found
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES
java.lang.IllegalArgumentException - if primaryKey is null or empty

getDisplayAttribute

AttributeDefinition getDisplayAttribute()
Returns the display attribute for this hierarchy

Returns:
The display attribute for this hierarchy
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES

getName

java.lang.String getName()
Retrieves the name of this hierarchy.

Returns:
String name
Throws:
PIMInternalException - If an internal error occurs

getPathAttribute

AttributeDefinition getPathAttribute()
Returns the path attribute for this hierarchy

Returns:
The path attribute for this hierarchy
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES

getPrimarySpec

PrimarySpec getPrimarySpec()
Retrieves the Primary spec for this hierarchy.

Returns:
String name
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES

getRootOrganization

Organization getRootOrganization()
Returns the root organization for this Hierarchy

Returns:
the root Organization oject for this OrganizationHierarchy
Throws:
PIMInternalException - if an internal exception occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_VIEW_HIERARCHY_NODES

getUserDefinedAttributeCollection

AttributeCollection getUserDefinedAttributeCollection()
                                                      throws PIMInternalException,
                                                             PIMAuthorizationException
Retrieves the User Defined Core Attribute Collection for this hierarchy

Returns:
the attribute collection, or null if no user defined attribute collection has been set.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES

save

java.util.List<ValidationErrors> save()
Persist the changes to the given hierarchy object

Returns:
A list of ValidionErrors objects each of which contain the validation errors for the organizations in this Hierarchy that were saved as part of this operation and failed validation. If none of the organizations had validation errors, then an empty list is returned.
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES

setAccessControlGroup

void setAccessControlGroup(AccessControlGroup acg)
Sets the Access Control Group for this hierarchy

Parameters:
acg - The access control group to associate with a hierarchy
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

setDisplayAttribute

void setDisplayAttribute(AttributeDefinition attribute)
Set the attribute to be used as the display attribute for the hierarchy

Parameters:
attribute - an attribute
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.

setUserDefinedAttributeCollection

void setUserDefinedAttributeCollection(AttributeCollection attributeCollection)
Associate the User defined Core Attribute collection with the hierarchy

Parameters:
attributeCollection - an attribute collection
Throws:
PIMInternalException - If an internal error occurs
PIMAuthorizationException - If the user does not have the equivalent of Permission.HIERARCHY_ATTRIBUTES
java.lang.IllegalArgumentException - if any of the parameters is null
java.lang.IllegalStateException - if any API object passed as a parameter that has not yet been saved.