org.palo.api
Interface Dimension

All Superinterfaces:
NamedEntity, PaloObject, Writable

public interface Dimension
extends PaloObject

Dimension.

Dimensions are defined inside a database. Out of the set of defined dimensions of a database, cubes can be created by associating these dimensions to form a cube. A Cube is capable of storing data.

A single dimension can be shared in multiple cubes.

Within the scope of a single parent database, a dimension is uniquely identified by its name as returned by getName().

A dimension is made up of distinct Elements. Dimension-information and domain-objects can be retrieved from a dimensino instance by invoking the following methods.

Version:
$ID$
See Also:
PaloAPIException

Field Summary
static int DIMENSIONEXTENDEDTYPE_REGULAR
          Constants for dimension-type
static int DIMENSIONEXTENDEDTYPE_VIRTUAL
          Constants for dimension-type
 
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)
          Deprecated. use Hierarchy.addAttribute(String) instead.
 Element addElement(java.lang.String name, int type)
          Deprecated. use Hierarchy.addElement(String, int) instead.
 void addElements(java.lang.String[] names, int[] types)
          Deprecated. use {@link Hierarchy#addElements(String [], int []) instead.
 void addElements(java.lang.String[] names, int[] types, Element[][] children, double[][] weights)
           
 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
 void dumpElementsTree()
          Deprecated. for internal use only. Please do not use.
 ElementNode[] getAllElementNodes()
          Deprecated. use Hierarchy.getAllElementNodes() instead.
 Attribute getAttribute(java.lang.String id)
          Deprecated. use Hierarchy.getAttribute(String) instead.
 Attribute getAttributeByName(java.lang.String name)
          Deprecated. use Hierarchy.getAttributeByName(String) instead.
 Cube getAttributeCube()
          Deprecated. use Hierarchy.getAttributeCube() instead.
 Dimension getAttributeDimension()
          Deprecated. use Hierarchy.getAttributeHierarchy() instead.
 Attribute[] getAttributes()
          Deprecated. use Hierarchy.getAttributes() instead.
 java.lang.Object[] getAttributeValues(Attribute[] attributes, Element[] elements)
          Deprecated. use Hierarchy.getAttributeValues(Attribute [], Element []) instead.
 Cube[] getCubes()
          Returns all cubes which use this dimension.
 Database getDatabase()
          Returns the parent Database of this instance.
 Hierarchy getDefaultHierarchy()
          Returns the default hierarchy of this dimension.
 Element getElementAt(int index)
          Deprecated. use Hierarchy.getElementAt(int) instead.
 Element getElementById(java.lang.String id)
          Deprecated. use Hierarchy#getElementById() instead.
 Element getElementByName(java.lang.String name)
          Deprecated. use Hierarchy#getElementByName() instead.
 int getElementCount()
          Deprecated. use Hierarchy.getElementCount() instead.
 java.lang.String[] getElementNames()
          Deprecated. use Hierarchy.getElementNames() instead.
 Element[] getElements()
          Deprecated. use Hierarchy.getElements() instead.
 Element[] getElementsInOrder()
          Deprecated. use Hierarchy.getElementsInOrder() instead.
 ElementNode[] getElementsTree()
          Deprecated. use Hierarchy.getElementsTree() instead.
 int getExtendedType()
          Returns the extended-type of this Dimension.
 Hierarchy[] getHierarchies()
          Returns all hierarchies of this dimension.
 java.lang.String[] getHierarchiesIds()
          Returns the ids of all hierarchies of this dimension.
 Hierarchy getHierarchyAt(int index)
          Returns the hierarchy at the given index.
 Hierarchy getHierarchyById(java.lang.String id)
          Returns the hierarchy specified by the given id.
 Hierarchy getHierarchyByName(java.lang.String name)
          Returns the hierarchy with the specified name or null if no such hierarchy exists.
 int getHierarchyCount()
          Returns the number of hierarchies in this dimension.
 int getMaxDepth()
          Deprecated. use Hierarchy.getMaxDepth() instead.
 int getMaxLevel()
          Deprecated. use Hierarchy.getMaxLevel() instead.
 java.lang.String getName()
          Returns the name of this Dimension
 Element[] getRootElements()
          Deprecated. use Hierarchy.getRootElements() instead.
 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 dimension
 int getType()
          TODO please comment :)
 boolean isAttributeDimension()
          Checks if this Dimension is an attribute dimension, i.e.
 boolean isSubsetDimension()
          Deprecated. use Hierarchy.isSubsetHierarchy() instead.
 boolean isSystemDimension()
          Returns whether this dimension is a system dimension.
 boolean isUserInfoDimension()
          Returns whether this dimension is a user info dimension.
 Consolidation newConsolidation(Element element, Element parent, double weight)
          Deprecated. use Hierarchy.newConsolidation(Element, Element, double) instead.
 void reload(boolean fireEvents)
          Reloads the internal dimension structure from database.
 void removeAllAttributes()
          Deprecated. use Hierarchy.removeAllAttributes() instead.
 void removeAttribute(Attribute attribute)
          Deprecated. use Hierarchy.removeAttribute(Attribute) instead.
 void removeElement(Element element)
          Deprecated. use Hierarchy.removeElement(Element) instead.
 void removeElements(Element[] elements)
          Deprecated. use Hierarchy.removeElements(Element []) instead.
 void removeSubset(Subset subset)
          Removes the given subset from the dimension
 void rename(java.lang.String name)
          Renames this Dimension.
 void renameElement(Element element, java.lang.String newName)
          Deprecated. use Hierarchy.renameElement(Element, String) instead.
 void setAttributeValues(Attribute[] attributes, Element[] elements, java.lang.Object[] values)
          Deprecated. use Hierarchy.setAttributeValues(Attribute [], Element [], Object []) instead.
 void visitElementTree(ElementNodeVisitor visitor)
          Deprecated. use Hierarchy#visitElementTree() instead.
 
Methods inherited from interface org.palo.api.PaloObject
getId
 
Methods inherited from interface org.palo.api.Writable
canBeModified, canCreateChildren
 

Field Detail

DIMENSIONEXTENDEDTYPE_REGULAR

static final int DIMENSIONEXTENDEDTYPE_REGULAR
Constants for dimension-type

See Also:
Constant Field Values

DIMENSIONEXTENDEDTYPE_VIRTUAL

static final int DIMENSIONEXTENDEDTYPE_VIRTUAL
Constants for dimension-type

See Also:
Constant Field Values
Method Detail

getExtendedType

int getExtendedType()
Returns the extended-type of this Dimension.

Returns:
the extended-type of this Dimension.

getType

int getType()
Description copied from interface: PaloObject
TODO please comment :)

Specified by:
getType in interface PaloObject
Returns:
the type of this palo object

getName

java.lang.String getName()
Returns the name of this Dimension

Specified by:
getName in interface NamedEntity
Returns:
the name of this Dimension.

getDatabase

Database getDatabase()
Returns the parent Database of this instance.

Returns:
the parent Database of this instance.

getElementCount

int getElementCount()
Deprecated. use Hierarchy.getElementCount() instead.

Returns the number of Elements of this instance. Note that a single dimension with consolidated elements might consolidate a particular element more than once.

Returns:
the number of Elements of this instance.

getElementAt

Element getElementAt(int index)
Deprecated. use Hierarchy.getElementAt(int) instead.

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.

getElements

Element[] getElements()
Deprecated. use Hierarchy.getElements() instead.

Returns an array of Element instances available for this instance.

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

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

getElementNames

java.lang.String[] getElementNames()
Deprecated. use Hierarchy.getElementNames() instead.

Returns the names of the elements of this Dimension.

The returned array is a copy of the internal datastructure. 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)
Deprecated. use Hierarchy#getElementByName() instead.

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)
Deprecated. use Hierarchy#getElementById() instead.

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.

rename

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

Parameters:
name - the new name for this Dimension.

addElements

void addElements(java.lang.String[] names,
                 int[] types)
Deprecated. use {@link Hierarchy#addElements(String [], int []) instead.

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)

getRootElements

Element[] getRootElements()
Deprecated. use Hierarchy.getRootElements() instead.

Returns all root-elements (those without parents in the consolidation-hierarchy).

Returns:
all root elements of the dimension.

getElementsInOrder

Element[] getElementsInOrder()
Deprecated. use Hierarchy.getElementsInOrder() instead.

Returns all elements of the dimension 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 dimension in order.

getElementsTree

ElementNode[] getElementsTree()
Deprecated. use Hierarchy.getElementsTree() instead.

Returns the root-nodes of the element-tree.

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

visitElementTree

void visitElementTree(ElementNodeVisitor visitor)
Deprecated. use Hierarchy#visitElementTree() instead.

Visits the element-tree of this dimension.

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

getAllElementNodes

ElementNode[] getAllElementNodes()
Deprecated. use Hierarchy.getAllElementNodes() instead.

Returns an array of all element-nodes of the consolidation-hierarchy of this dimension.

Returns:
an array of all element-nodes of this dimension.

dumpElementsTree

void dumpElementsTree()
Deprecated. for internal use only. Please do not use.

Debug only method. Provides some unspecified feedback to std-err.


addElement

Element addElement(java.lang.String name,
                   int type)
Deprecated. use Hierarchy.addElement(String, int) instead.

Adds an Element to this Dimension.

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)
Deprecated. use Hierarchy.removeElement(Element) instead.

Removes the given Element from this Dimension

Parameters:
element - the Element to remove.

removeElements

void removeElements(Element[] elements)
Deprecated. use Hierarchy.removeElements(Element []) instead.

Removes the given Elements from this Dimension

Parameters:
elements - Elements to remove.

renameElement

void renameElement(Element element,
                   java.lang.String newName)
Deprecated. use Hierarchy.renameElement(Element, String) instead.

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)
Deprecated. use Hierarchy.newConsolidation(Element, Element, double) instead.

Creates a Consolidation for later use in this dimension.

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

isAttributeDimension

boolean isAttributeDimension()
Checks if this Dimension is an attribute dimension, i.e. its elements represent Attributes.

Returns:
true if dimension is an attribute dimension, false otherwise

addAttribute

Attribute addAttribute(java.lang.String name)
Deprecated. use Hierarchy.addAttribute(String) instead.

Creates a new Attribute and adds it to the dimension.

Note: adding an attribute to a dimension which is itself of type attribute dimension 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)
Deprecated. use Hierarchy.removeAttribute(Attribute) instead.

Removes the given Attribute from the dimension

Parameters:
attribute - the attribute instance to remove

removeAllAttributes

void removeAllAttributes()
Deprecated. use Hierarchy.removeAllAttributes() instead.

Removes all attributes from the dimension


getAttributes

Attribute[] getAttributes()
Deprecated. use Hierarchy.getAttributes() instead.

Returns all Attributes this dimension has.

Returns:
the Attributes of this dimension

getAttribute

Attribute getAttribute(java.lang.String id)
Deprecated. use Hierarchy.getAttribute(String) instead.

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)
Deprecated. use Hierarchy.getAttributeByName(String) instead.

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)
Deprecated. use Hierarchy.setAttributeValues(Attribute [], Element [], Object []) instead.

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)
Deprecated. use Hierarchy.getAttributeValues(Attribute [], Element []) instead.

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()
Deprecated. use Hierarchy.getAttributeCube() instead.

Returns the attribute Cube corresponding to this dimension 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

getAttributeDimension

Dimension getAttributeDimension()
Deprecated. use Hierarchy.getAttributeHierarchy() instead.

Returns the corresponding attribute Dimension or null if the attribute dimension 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 dimension

isSubsetDimension

boolean isSubsetDimension()
Deprecated. use Hierarchy.isSubsetHierarchy() instead.

Checks if this Dimension is a subset dimension, i.e. its elements represent Subsets.

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

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 dimension.

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 dimension

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

isSystemDimension

boolean isSystemDimension()
Returns whether this dimension is a system dimension.

Returns:
true if this dimension is a system dimension, false otherwise.

isUserInfoDimension

boolean isUserInfoDimension()
Returns whether this dimension is a user info dimension.

Returns:
true if this dimension is a user info dimension, false otherwise.

getMaxLevel

int getMaxLevel()
Deprecated. use Hierarchy.getMaxLevel() instead.

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

Returns:
maximum level of this dimension

getMaxDepth

int getMaxDepth()
Deprecated. use Hierarchy.getMaxDepth() instead.

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

Returns:
maximum depth of this dimension

getCubes

Cube[] getCubes()
Returns all cubes which use this dimension. Please note that the returned cubes do not contain any attribute, system or info cubes.

Returns:
all cubes which use this dimension

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

getHierarchies

Hierarchy[] getHierarchies()
Returns all hierarchies of this dimension.

Returns:
all hierarchies of this dimension.

getHierarchyCount

int getHierarchyCount()
Returns the number of hierarchies in this dimension. For palo connections, the number of hierarchies equals one, for xmla connections, the count may differ as dimensions may have more than one hierarchy.

Returns:
the number of hierarchies for this dimension.

getHierarchiesIds

java.lang.String[] getHierarchiesIds()
Returns the ids of all hierarchies of this dimension.

Returns:
the ids of all hierarchies of this dimension.

getHierarchyAt

Hierarchy getHierarchyAt(int index)
Returns the hierarchy at the given index.

Parameters:
index - the index of the hierarchy.
Returns:
the hierarchy at the specified index.

getHierarchyById

Hierarchy getHierarchyById(java.lang.String id)
Returns the hierarchy specified by the given id.

Parameters:
id - the id of the hierarchy.
Returns:
the hierarchy specified by the given id.

getHierarchyByName

Hierarchy getHierarchyByName(java.lang.String name)
Returns the hierarchy with the specified name or null if no such hierarchy exists.

Parameters:
name - the name of the hierarchy.
Returns:
the hierarchy with the specified name or null if no such hierarchy exists.

getDefaultHierarchy

Hierarchy getDefaultHierarchy()
Returns the default hierarchy of this dimension.

Returns:
the default hierarchy of this dimension.

reload

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

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