org.palo.api
Interface Hierarchy

All Superinterfaces:
NamedEntity, PaloObject, Writable
All Known Implementing Classes:
HierarchyImpl

public interface Hierarchy
extends PaloObject

Hierarchy A hierarchy organizes dimensions with different element consolidations in a cube. For Palo, different consolidations in a dimension are not allowed and thus each hierarchy maps to exactly one dimension and they have identical ids. If a dimension is removed, renamed or added, the mapping stays consistent. In xmla, a dimension can contain several hierarchies. Since XMLA is currently read-only, hierarchies cannot be added or removed.

Version:
$Id: Hierarchy.html,v 1.6 2009/07/09 11:01:46 ArndHouben Exp $

Field Summary
 
Fields inherited from interface org.palo.api.PaloObject
TYPE_ATTRIBUTE, TYPE_NORMAL, TYPE_SYSTEM, TYPE_USER_INFO
 
Method Summary
 Attribute addAttribute(java.lang.String name)
          Creates a new Attribute and adds it to the hierarchy.
 Element addElement(java.lang.String name, int type)
          Adds an Element to this Hierarchy.
 void addElements(java.lang.String[] names, int[] types)
          Batch adds many elements.
 void addElements(java.lang.String[] names, int[] types, Element[][] children, double[][] weights)
          Available for Palo Server version 3 and above.
 void addElements(java.lang.String[] names, int type, Element[][] children, double[][] weights)
           
 Subset addSubset(java.lang.String name)
          Deprecated. old subsets are not supported anymore, please instead add subsets via getSubsetHandler() and its appropriate methods
 ElementNode[] getAllElementNodes()
          Returns an array of all element nodes of the consolidation hierarchy of this hierarchy.
 Attribute getAttribute(java.lang.String id)
          Returns the Attribute which corresponds to the given id or null if no Attribute with this id exists
 Attribute getAttributeByName(java.lang.String name)
          Returns the Attribute which corresponds to the given name or null if no Attribute with this name exists
 Cube getAttributeCube()
          Returns the attribute Cube corresponding to this hierarchy or null if the attribute cube couldn't be loaded or does not exist.
 Hierarchy getAttributeHierarchy()
          Returns the corresponding attribute Hierarchy or null if the attribute hierarchy couldn't be loaded or does not exist.
 Attribute[] getAttributes()
          Returns all Attributes this hierarchy has.
 java.lang.Object[] getAttributeValues(Attribute[] attributes, Element[] elements)
          Convenient method to receive the values from several Attributes in one go, i.e. the i.th object in the returned array is the i.th value of the i.th attribute for the i.th element.
 Dimension getDimension()
          Returns the parent dimension of this hierarchy.
 Element getElementAt(int index)
          Returns the Element stored at the given index.
 Element getElementById(java.lang.String id)
          Returns the Element stored under the given id or null if no such Element exists.
 Element getElementByName(java.lang.String name)
          Returns the Element stored under the given name or null if no such Element exists.
 int getElementCount()
          Returns the number of Elements of this instance.
 java.lang.String[] getElementNames()
          Returns the names of the elements of this Hierarchy.
 Element[] getElements()
          Returns an array of Element instances available for this instance.
 Element[] getElementsInOrder()
          Returns all elements of the hierarchy in an order that is determined by the consolidation hierarchy.
 ElementNode[] getElementsTree()
          Returns the root-nodes of the element-tree.
 int getMaxDepth()
          Returns the maximum depth of this hierarchy.
 int getMaxLevel()
          Returns the maximum level of this hierarchy.
 Element[] getRootElements()
          Returns all root-elements (those without parents in the consolidation-hierarchy).
 Subset getSubset(java.lang.String id)
          Returns the subset which is registered with the given id or null if no subset with this id could be found
 SubsetHandler getSubsetHandler()
          Returns the SubsetHandler for managing the new subsets.
 Subset[] getSubsets()
          Returns all subsets currently registered with this hierarchy
 boolean isAttributeHierarchy()
          Checks if this Hierarchy is an attribute hierarchy, i.e.
 boolean isNormal()
          Returns if this hierarchy is a normal hierarchy (as opposed to being a system hierarchy).
 boolean isSubsetHierarchy()
          Checks if this Hierarchy is a subset hierarchy, i.e.
 Consolidation newConsolidation(Element element, Element parent, double weight)
          Creates a Consolidation for later use in this hierarchy.
 void reload(boolean fireEvents)
          Reloads the internal hierarchy structure from database.
 void removeAllAttributes()
          Removes all attributes from the hierarchy
 void removeAttribute(Attribute attribute)
          Removes the given Attribute from the hierarchy
 void removeElement(Element element)
          Removes the given Element from this Hierarchy
 void removeElements(Element[] elements)
          Removes the given Elements from this Hierarchy
 void removeSubset(Subset subset)
          Removes the given subset from the dimension
 void rename(java.lang.String name)
          Renames this hierarchy.
 void renameElement(Element element, java.lang.String newName)
          Renames given Element.
 void setAttributeValues(Attribute[] attributes, Element[] elements, java.lang.Object[] values)
          Convenient method to set the values for several Attributes at once, i.e. the i.th value is assigned to the i.th attribute for the i.th element.
 void visitElementTree(ElementNodeVisitor visitor)
          Visits the element-tree of this hierarchy.
 
Methods inherited from interface org.palo.api.PaloObject
getId, getType
 
Methods inherited from interface org.palo.api.NamedEntity
getName
 
Methods inherited from interface org.palo.api.Writable
canBeModified, canCreateChildren
 

Method Detail

getDimension

Dimension getDimension()
Returns the parent dimension of this hierarchy.

Returns:
the parent dimension of this hierarchy.

isNormal

boolean isNormal()
Returns if this hierarchy is a normal hierarchy (as opposed to being a system hierarchy). A hierarchy is a system hierarchy, when its dimension is a system dimension.

Returns:
true if the hierarchy is a non-system hierarchy, false otherwise.

rename

void rename(java.lang.String name)
Renames this hierarchy.

Parameters:
name - the the name for the hierarchy.

getElementCount

int getElementCount()
Returns the number of Elements of this instance. Note that a single hierarchy with consolidated elements might consolidate a particular element more than once.

Returns:
the number of Elements of this instance.

getElements

Element[] getElements()
Returns an array of Element instances available for this instance.

The returned array is a copy of the internal data structure. Changing the returned array does not change this instance.

Returns:
an array of Element instances available for this Hierarchy.

visitElementTree

void visitElementTree(ElementNodeVisitor visitor)
Visits the element-tree of this hierarchy.

Parameters:
visitor - the visitor-callback to invoke during traversal.

getRootElements

Element[] getRootElements()
Returns all root-elements (those without parents in the consolidation-hierarchy).

Returns:
all root elements of the hierarchy.

getElementsTree

ElementNode[] getElementsTree()
Returns the root-nodes of the element-tree.

Returns:
the root-nodes of the element-tree.

getElementAt

Element getElementAt(int index)
Returns the Element stored at the given index. If the index does not correspond to a legal position in the internally managed array of elements of this instance, then null is returned.

Parameters:
index - the index
Returns:
the Element stored at the given index or null.

getElementNames

java.lang.String[] getElementNames()
Returns the names of the elements of this Hierarchy.

The returned array is a copy of the internal data structure. Changing the returned array does not change this instance.

Returns:
the names of the Elements instances available for this Dimension>.

getElementByName

Element getElementByName(java.lang.String name)
Returns the Element stored under the given name or null if no such Element exists.

Parameters:
name - the element-name to look-up.
Returns:
the Element stored under the given name or null if no such Element exists.

getElementById

Element getElementById(java.lang.String id)
Returns the Element stored under the given id or null if no such Element exists.

Parameters:
id - the element-id to look-up.
Returns:
the Element stored under the given id or null if no such Element exists.

addElements

void addElements(java.lang.String[] names,
                 int[] types)
Batch adds many elements.

Parameters:
names - the names of the elements to add.
types - the types of the elements to add.

addElements

void addElements(java.lang.String[] names,
                 int type,
                 Element[][] children,
                 double[][] weights)

addElements

void addElements(java.lang.String[] names,
                 int[] types,
                 Element[][] children,
                 double[][] weights)
Available for Palo Server version 3 and above.

Parameters:
names -
types -
children -
weights -

getElementsInOrder

Element[] getElementsInOrder()
Returns all elements of the hierarchy in an order that is determined by the consolidation hierarchy. Since elements can be consolidated multiple times, this order is not always the same as a pre-order traversal of the directed acyclic graph of consolidations, but similar.

Returns:
the elements of the hierarchy in order.

getAllElementNodes

ElementNode[] getAllElementNodes()
Returns an array of all element nodes of the consolidation hierarchy of this hierarchy.

Returns:
an array of all element nodes of this hierarchy.

addElement

Element addElement(java.lang.String name,
                   int type)
Adds an Element to this Hierarchy.

Parameters:
name - the name of the element to add.
type - the type of the element to add as defined by the constants in the Element class.

removeElement

void removeElement(Element element)
Removes the given Element from this Hierarchy

Parameters:
element - the Element to remove.

removeElements

void removeElements(Element[] elements)
Removes the given Elements from this Hierarchy

Parameters:
elements - Elements to remove.

renameElement

void renameElement(Element element,
                   java.lang.String newName)
Renames given Element.

Parameters:
element - the Element to rename.
newName - the new name for this Element.

newConsolidation

Consolidation newConsolidation(Element element,
                               Element parent,
                               double weight)
Creates a Consolidation for later use in this hierarchy.

Parameters:
element - the Element to consolidate.
parent - the parent-Element of the consolidation.
weight - the consolidation weight.
Returns:
the created Consolidation object.

getMaxLevel

int getMaxLevel()
Returns the maximum level of this hierarchy. Please refer to Element.getLevel() for an explanation of how the level is determined

Returns:
maximum level of this hierarchy

getMaxDepth

int getMaxDepth()
Returns the maximum depth of this hierarchy. Please refer to Element.getDepth() for an explanation of how the depth is determined

Returns:
maximum depth of this hierarchy

isAttributeHierarchy

boolean isAttributeHierarchy()
Checks if this Hierarchy is an attribute hierarchy, i.e. its elements represent Attributes.

Returns:
true if this hierarchy is an attribute hierarchy, false otherwise

isSubsetHierarchy

boolean isSubsetHierarchy()
Checks if this Hierarchy is a subset hierarchy, i.e. its elements represent Subsets.

Returns:
true if hierarchy is a subset hierarchy, false otherwise

addAttribute

Attribute addAttribute(java.lang.String name)
Creates a new Attribute and adds it to the hierarchy.

Note: adding an attribute to a hierarchy which is itself of type attribute hierarchy is prohibited and will result in a PaloAPIException.

Parameters:
name - the name of the new attribute
Returns:
the newly created Attribute

removeAttribute

void removeAttribute(Attribute attribute)
Removes the given Attribute from the hierarchy

Parameters:
attribute - the attribute instance to remove

removeAllAttributes

void removeAllAttributes()
Removes all attributes from the hierarchy


getAttributes

Attribute[] getAttributes()
Returns all Attributes this hierarchy has.

Returns:
the Attributes of this hierarchy

getAttribute

Attribute getAttribute(java.lang.String id)
Returns the Attribute which corresponds to the given id or null if no Attribute with this id exists

Parameters:
id - identifier of the Attribute to get
Returns:
the corresponding Attribute or null

getAttributeByName

Attribute getAttributeByName(java.lang.String name)
Returns the Attribute which corresponds to the given name or null if no Attribute with this name exists

Parameters:
name - the name of the Attribute to get
Returns:
the corresponding Attribute or null

setAttributeValues

void setAttributeValues(Attribute[] attributes,
                        Element[] elements,
                        java.lang.Object[] values)
Convenient method to set the values for several Attributes at once, i.e. the i.th value is assigned to the i.th attribute for the i.th element.
Note: if the attributes, elements and values arrays do not have same length an PaloAPIException is thrown.

Parameters:
attributes - the attributes to set the values for
elements - the effected elements
values - the new values

getAttributeValues

java.lang.Object[] getAttributeValues(Attribute[] attributes,
                                      Element[] elements)
Convenient method to receive the values from several Attributes in one go, i.e. the i.th object in the returned array is the i.th value of the i.th attribute for the i.th element.
Note: if the attributes and elements arrays do not have same length an PaloAPIException is thrown.

Parameters:
attributes - the attributes to get the values from
elements - the effected elements
Returns:
the attribute values

getAttributeCube

Cube getAttributeCube()
Returns the attribute Cube corresponding to this hierarchy or null if the attribute cube couldn't be loaded or does not exist.

Note: this is a convenient method to provide raw access to the internal attribute handling. Its usage is not recommended!!

Returns:
the attribute cube

getAttributeHierarchy

Hierarchy getAttributeHierarchy()
Returns the corresponding attribute Hierarchy or null if the attribute hierarchy couldn't be loaded or does not exist.

Note: this is a convenient method to provide raw access to the internal attribute handling. Its usage is not recommended!!

Returns:
the attribute hierarchy

addSubset

Subset addSubset(java.lang.String name)
Deprecated. old subsets are not supported anymore, please instead add subsets via getSubsetHandler() and its appropriate methods

Adds a new Subset with the given name to the hierarchy.

Parameters:
name - the name of the subset
Returns:
the new subset

removeSubset

void removeSubset(Subset subset)
Removes the given subset from the dimension

Parameters:
subset - the subset to remove

getSubsets

Subset[] getSubsets()
Returns all subsets currently registered with this hierarchy

Returns:
the registered subsets

getSubset

Subset getSubset(java.lang.String id)
Returns the subset which is registered with the given id or null if no subset with this id could be found

Parameters:
id - the subset id
Returns:
the corresponding subset instance

getSubsetHandler

SubsetHandler getSubsetHandler()
Returns the SubsetHandler for managing the new subsets. Please use Database.supportsNewSubsets() to check if new subsets are supported.

Returns:
the SubsetHandler for managing new subsets

reload

void reload(boolean fireEvents)
Reloads the internal hierarchy structure from database.

Parameters:
fireEvents - specify true to get event notification on hierarchy changes or false otherwise