org.palo.api
Interface Database

All Superinterfaces:
NamedEntity, PaloObject, Writable

public interface Database
extends PaloObject

Database

Instances of this class represent a database on a PALO server. Instances are obtained from a parent Connection instance.

Different instances of this class may refer to the same logical PALO database. If two different parent connections are used, the returned database instances are always different, as instances of Database are associated with the Connection instance they originate from. A reference to this owner Connection is obtained by invoking getConnection().

A Database is a container and namespace for two distinct domain objects, namely Cube and Dimension. A Database is uniquely identified within a palo-server by its name as returned by getName().

Dimension-information and domain-objects can be retrieved from a database instance by invoking the following methods.

Cube-information and domain-objects can be retrieved from a database instance by invoking the following methods.

The returned Dimension and Cube instances are pooled internally and kept identical throughout a connection lifetime as long as they refer to the same logical database. Thus these objects can be used inside domain-models during the lifetime of a connection.

In addition to reading information, a database can also be manipulated. Dimensions and Cubes can be added and removed from the Database by invoking.

All operations of the PALO-API in this package potentially throw the exception PaloAPIException or other runtime exceptions.

Version:
$ID$

Field Summary
 
Fields inherited from interface org.palo.api.PaloObject
TYPE_ATTRIBUTE, TYPE_NORMAL, TYPE_SYSTEM, TYPE_USER_INFO
 
Method Summary
 Cube addCube(java.lang.String name, Dimension[] dimensions)
          Adds a new cube with the given name to this Database.
 Cube addCube(VirtualCubeDefinition definition)
           
 Dimension addDimension(java.lang.String name)
          Adds a new dimension with the given name to this Database.
 Cube addUserInfoCube(java.lang.String name, Dimension[] dimensions)
           
 Dimension addUserInfoDimension(java.lang.String name)
           
 void endBatchUpdate()
          Ends the batch update mode.
 Connection getConnection()
          Returns the parent Connection of this instance.
 Cube getCubeAt(int index)
          Returns the Cube stored at the given index.
 Cube getCubeById(java.lang.String id)
           
 Cube getCubeByName(java.lang.String name)
          Returns the Cube stored under the given name or null if no such Cube exists.
 int getCubeCount()
          Returns the number of Cubes of this instance.
 Cube[] getCubes()
          Returns an array of Cube instances available for this instance.
 Cube[] getCubes(int typeMask)
          Returns all cubes that are of one of the types specified in the type mask.
 Dimension getDimensionAt(int index)
          Returns the Dimension stored at the given index.
 Dimension getDimensionById(java.lang.String id)
           
 Dimension getDimensionByName(java.lang.String name)
          Returns the Dimension stored under the given name or null if no such Dimension exists.
 int getDimensionCount()
          Returns the number of Dimensions of this instance.
 Dimension[] getDimensions()
          Returns an array of Dimension instances available for this instance.
 Dimension[] getDimensions(int typeMask)
          Returns all dimensions that are of one of the types specified in the type mask.
 java.lang.String getName()
          Returns the name of this Database
 Rights getRights()
          Deprecated. Subject to change, please don't use.
 SubsetStorageHandler getSubsetStorageHandler()
          Returns the storage handler for loading and storing Subset2s NOTE: API INTERNAL METHOD
 boolean isSystem()
           
 java.lang.String parseRule(Cube cube, java.lang.String definition, java.lang.String functions)
          Parses the given rule definition for the given Cube NOTE: INTERNAL USAGE ONLY!!
 void reload()
          Reloads all internal objects of the database.
 void removeCube(Cube cube)
          Removes a cube from this Database.
 void removeDimension(Dimension dimension)
          Removes a dimension from this Database.
 boolean save()
          Tells the Palo-Server to save the database.
 void startBatchUpdate()
          Starts the batch update mode for better performance when adding or removing many palo objects in a single go.
 boolean supportsNewSubsets()
          Checks if new subsets are supported by this database.
 
Methods inherited from interface org.palo.api.PaloObject
getId, getType
 
Methods inherited from interface org.palo.api.Writable
canBeModified, canCreateChildren
 

Method Detail

getName

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

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

getConnection

Connection getConnection()
Returns the parent Connection of this instance.

Returns:
the parent Connection of this instance.

reload

void reload()
Reloads all internal objects of the database. Invoking this method can take some time. Afterwards the dimension, cube, element and consolidation objects that can be retrieved from this instance are identical to earlier results if the objects represent the same palo domain objects. This behavior is achieved by caching objects throughout the life-time of the connection.


startBatchUpdate

void startBatchUpdate()
Starts the batch update mode for better performance when adding or removing many palo objects in a single go.

Note that while batch mode is active some methods will return null instead of returning the palo domain objects. (like Dimension.addElement(String, int)).

Batch mode MUST be ended with a call to endBatchUpdate() before proceeding with regular API usage.


endBatchUpdate

void endBatchUpdate()
Ends the batch update mode.

Note that while batch mode is active some methods will return null instead of returning the palo domain objects. (like Dimension.addElement(String, int)).


getDimensionCount

int getDimensionCount()
Returns the number of Dimensions of this instance.

Returns:
the number of Dimensions of this instance.

getDimensionAt

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

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

getDimensions

Dimension[] getDimensions()
Returns an array of Dimension 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 Dimension instances available for this connection.

getDimensions

Dimension[] getDimensions(int typeMask)
Returns all dimensions that are of one of the types specified in the type mask. The type mask is a bitwise-or of all possible types as defined in the Dimension interface.

Parameters:
typeMask - the mask representing all types of dimensions that are to be returned.
Returns:
all dimensions of the specified type(s).

getDimensionByName

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

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

getDimensionById

Dimension getDimensionById(java.lang.String id)

getCubeCount

int getCubeCount()
Returns the number of Cubes of this instance.

Returns:
the number of Cubes of this instance.

getCubeAt

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

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

getCubes

Cube[] getCubes()
Returns an array of Cube 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 Cube instances available for this connection.

getCubes

Cube[] getCubes(int typeMask)
Returns all cubes that are of one of the types specified in the type mask. The type mask is a bitwise-or of all possible types as defined in the Cube interface.

Parameters:
typeMask - the mask representing all types of cubes that are to be returned.
Returns:
all cubes of the specified type(s).

getCubeByName

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

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

getCubeById

Cube getCubeById(java.lang.String id)

addDimension

Dimension addDimension(java.lang.String name)
Adds a new dimension with the given name to this Database. This operation fails if a dimension with the same name exists already.

Parameters:
name - the name of the new Dimension.
Returns:
the created Dimension.

addUserInfoDimension

Dimension addUserInfoDimension(java.lang.String name)

removeDimension

void removeDimension(Dimension dimension)
Removes a dimension from this Database.

Parameters:
dimension - the Dimension to remove from this Database.

addCube

Cube addCube(java.lang.String name,
             Dimension[] dimensions)
Adds a new cube with the given name to this Database. This operation fails if a cube with the same name exists already. The cube is created with the specified dimensions, which must refer to dimensions of this Database.

Parameters:
name - the name of the new Cube.
dimensions - the Dimensions of the Cube.
Returns:
the created Cube.

addUserInfoCube

Cube addUserInfoCube(java.lang.String name,
                     Dimension[] dimensions)

removeCube

void removeCube(Cube cube)
Removes a cube from this Database.

Parameters:
cube - the Cube to remove from this Database.

save

boolean save()
Tells the Palo-Server to save the database.

Returns:
true if saving was successful, false otherwise

addCube

Cube addCube(VirtualCubeDefinition definition)

parseRule

java.lang.String parseRule(Cube cube,
                           java.lang.String definition,
                           java.lang.String functions)
Parses the given rule definition for the given Cube NOTE: INTERNAL USAGE ONLY!! WILL CHANGE WITH FUTURE VERSIONS!!!

Parameters:
cube -
definition -
functions -

isSystem

boolean isSystem()

getSubsetStorageHandler

SubsetStorageHandler getSubsetStorageHandler()
Returns the storage handler for loading and storing Subset2s

NOTE: API INTERNAL METHOD

Returns:

supportsNewSubsets

boolean supportsNewSubsets()
Checks if new subsets are supported by this database.

Returns:
true if new subsets are supported, false otherwise

getRights

Rights getRights()
Deprecated. Subject to change, please don't use.