org.palo.api
Interface Connection

All Superinterfaces:
Writable
All Known Implementing Classes:
ConnectionImpl

public interface Connection
extends Writable

Connection

Instances of this class represent a session/connection with a PALO server. Each session is independent from all other sessions.

Invoke reload() on a connection to rehash all of its internal datastructes.

Connection instances have an equals/hashcode behavior that is identity based. (This means Object.hashCode() and Object.equals(java.lang.Object) are both not overridden).

Instances of this class can only be obtained by means of the ConnectionFactory class.

Here is an example code snippet for retrieving a single datum from a PALO connection. First a connection is created by means of the ConnectionFactory. Then this connection is used to get a Database instance by its name. Next a Cube is selected by name and a single datum is retrieved in the two possible ways.

  Connection connection = ConnectionFactory.getInstance().newConnection(
      "localhost",
      "1234",
      "user",
      "pass");
      
  // retrieve Database instance.
  Database db = connection.getDatabaseByName("Demo");
  
  // retrieve Cube instance.
  Cube cube = db.getCubeByName("Sales");
  
  // get single datum from Cube.
  Object v0 = cube.getData(new String[] {
      "Desktop L",
      "Germany",
      "Jan",
      "2003",
      "Budget",
      "Units" });
  
  // alternatively use the Element Objects to retrieve the same datum
  // in another fashion.
  Object v1 = cube.getData(new Element[] {
      cube.getDimensionAt(0).getElementByName("Desktop L"),
      cube.getDimensionAt(1).getElementByName("Germany"),
      cube.getDimensionAt(2).getElementByName("Jan"),
      cube.getDimensionAt(3).getElementByName("2003"),
      cube.getDimensionAt(4).getElementByName("Budget"),
      cube.getDimensionAt(5).getElementByName("Units"),
      });
  connection.disconnect();

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

Click here for a class-diagram of the api's core entities.

Version:
$ID$
See Also:
PaloAPIException

Field Summary
static int DEFAULT_TIMEOUT
          the default timeout for connection is 30 seconds
static int TYPE_HTTP
          connection type http
static int TYPE_LEGACY
          connection type legacy
static int TYPE_WSS
          connection type wss
static int TYPE_XMLA
          connection type xmla
 
Method Summary
 void addConnectionListener(ConnectionListener connectionListener)
          This method adds a ConnectionListener to this connection.
 Database addDatabase(java.lang.String name)
          Adds a new database with the given name to this Connection.
 void addProperty(Property2 property)
          Adds the given property to the list of properties for this connection.
 void disconnect()
          Disconnects from the PALO server.
 java.lang.String[] getAllPropertyIds()
          Returns all ids of properties that can be set for this connection.
 ConnectionContext getContext()
          Returns the ConnectionContext which allows to retrieve further information about current connection
 java.lang.Object getData(java.lang.String id)
           API INTERNAL
 Database getDatabaseAt(int index)
          Returns the database stored at the given index.
 Database getDatabaseById(java.lang.String id)
          Returns the database stored under the given id or null if no such database exists.
 Database getDatabaseByName(java.lang.String name)
          Returns the database stored under the given name or null if no such database exists.
 int getDatabaseCount()
          Returns the number of databases.
 Database[] getDatabases()
          Returns an array of Database instances available for this connection.
 java.lang.String getFunctions()
          Returns all available Functions which are defined for this connection.
 java.lang.String getPassword()
          Returns the password used to login.
 Property2 getProperty(java.lang.String id)
          Returns the property identified by the given id.
 java.lang.String getServer()
          Returns the server name.
 java.lang.String getService()
          Returns the service name.
 Database[] getSystemDatabases()
          Returns an array of system Database instances available for this connection.
 int getType()
          Returns the connection type for this connection.
 java.lang.String getUsername()
          Returns the username.
 boolean isConnected()
          Checks if this connection is still connected to a PALO server.
 boolean isLegacy()
          Checks if connection uses the legacy palo server or not.
 FavoriteViewTreeNode loadFavoriteViews()
          Loads all favorite views stored with this connection and returns the root of the favorite view tree representing those views or null, if no favorite views were stored in this connection.
 boolean login(java.lang.String username, java.lang.String password)
          Logs into this connection with the specified user name and password.
 void ping()
          Tries to ping the palo server.
 void reload()
          Reloads all internal objects of the connection.
 void removeConnectionListener(ConnectionListener connectionListener)
          This method removes a ConnectionListener from this connection.
 void removeDatabase(Database database)
          Removes a database from this Connection.
 void removeProperty(java.lang.String id)
          Removes the given property from the list of properties for this connection.
 boolean save()
          Tells the Palo-Server to save everything on the server-side.
 void storeFavoriteViews(FavoriteViewTreeNode favoriteViews)
          Stores the favorite views for this connection.
 
Methods inherited from interface org.palo.api.Writable
canBeModified, canCreateChildren
 

Field Detail

TYPE_LEGACY

static final int TYPE_LEGACY
connection type legacy

See Also:
Constant Field Values

TYPE_HTTP

static final int TYPE_HTTP
connection type http

See Also:
Constant Field Values

TYPE_XMLA

static final int TYPE_XMLA
connection type xmla

See Also:
Constant Field Values

TYPE_WSS

static final int TYPE_WSS
connection type wss

See Also:
Constant Field Values

DEFAULT_TIMEOUT

static final int DEFAULT_TIMEOUT
the default timeout for connection is 30 seconds

See Also:
Constant Field Values
Method Detail

getServer

java.lang.String getServer()
Returns the server name.

Returns:
the server name.

getService

java.lang.String getService()
Returns the service name.

Returns:
the service name.

getUsername

java.lang.String getUsername()
Returns the username.

Returns:
the username.

getPassword

java.lang.String getPassword()
Returns the password used to login. Implementations may choose to return null or the empty string if configured to prevent password-retrieval

Returns:
the login password, the empty string or null.

reload

void reload()
Reloads all internal objects of the connection. Invoking this method can take some time. Afterwards the database, 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.


ping

void ping()
Tries to ping the palo server. Upon success the method returns silenty.


isConnected

boolean isConnected()
Checks if this connection is still connected to a PALO server.

Returns:
true if a connection to a PALO server is established, false otherwise

disconnect

void disconnect()
Disconnects from the PALO server. Afterwards the connection is not functional anymore and should not be used. Reconnecting is not supported. Create a new Connection instance instead.


getDatabaseCount

int getDatabaseCount()
Returns the number of databases.

Returns:
the number of databases.

getDatabaseAt

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

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

getDatabases

Database[] getDatabases()
Returns an array of Database instances available for this connection.

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

Returns:
an array of Database instances available for this connection.

getSystemDatabases

Database[] getSystemDatabases()
Returns an array of system Database instances available for this connection.

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

Returns:
an array of system Database instances available for this connection.

getDatabaseByName

Database getDatabaseByName(java.lang.String name)
Returns the database stored under the given name or null if no such database exists.

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

getDatabaseById

Database getDatabaseById(java.lang.String id)
Returns the database stored under the given id or null if no such database exists.

Parameters:
id - identifier of the database to look-up.
Returns:
the database stored under the given name or null if no such database exists.

addDatabase

Database addDatabase(java.lang.String name)
Adds a new database with the given name to this Connection. This operation fails if a database with the same name exists already.

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

removeDatabase

void removeDatabase(Database database)
Removes a database from this Connection.

Parameters:
database - the Database to remove from this Connection.

save

boolean save()
Tells the Palo-Server to save everything on the server-side. Effects are up to the palo-server.

Returns:
true if saving was successful, false otherwise

addConnectionListener

void addConnectionListener(ConnectionListener connectionListener)
This method adds a ConnectionListener to this connection. Note that connection-listeners are limited and do not proactively report changes made on the palo server.

Parameters:
connectionListener - the ConnectionListener to add.

removeConnectionListener

void removeConnectionListener(ConnectionListener connectionListener)
This method removes a ConnectionListener from this connection. Note that connection-listeners are limited and do not proactively report changes made on the palo server.

Parameters:
connectionListener - the ConnectionListener to remove.

isLegacy

boolean isLegacy()
Checks if connection uses the legacy palo server or not.

Returns:
true if the connection is bind to the legacy palo server, false otherwise

getType

int getType()
Returns the connection type for this connection. The return value will be one of the TYPE_xxx constants defined in this interface.

Returns:
the connection type

getFunctions

java.lang.String getFunctions()
Returns all available Functions which are defined for this connection.

Returns:
all functions

login

boolean login(java.lang.String username,
              java.lang.String password)
Logs into this connection with the specified user name and password. If the connection could not be established, false is returned. If the connection can successfully be established, true is returned.

Parameters:
username -
password -
Returns:
true if the connection could be established, false otherwise.

loadFavoriteViews

FavoriteViewTreeNode loadFavoriteViews()
Loads all favorite views stored with this connection and returns the root of the favorite view tree representing those views or null, if no favorite views were stored in this connection. Note that this method will throw a PaloAPIException if the user does not have sufficient rights to store favorite views (and thus cannot have any favorite views to load).

Returns:
the root of the favorite views tree attached to this connection or null if no favorite views were saved.

storeFavoriteViews

void storeFavoriteViews(FavoriteViewTreeNode favoriteViews)
Stores the favorite views for this connection. Any old favorite views that have been stored in this connection will be overwritten. Note that this method will throw a PaloAPIException if the user does not have sufficient rights to store favorite views.

Parameters:
favoriteViews - the root of a favorite views tree.

getAllPropertyIds

java.lang.String[] getAllPropertyIds()
Returns all ids of properties that can be set for this connection. If no properties are known to this connection, an empty array is returned.

Returns:
all property ids that are understood by this connection.

getProperty

Property2 getProperty(java.lang.String id)
Returns the property identified by the given id. All valid ids can be requested by a call to getAllPropertyIds.

Parameters:
id - the id of the property to read.
Returns:
the property for the given id.

addProperty

void addProperty(Property2 property)
Adds the given property to the list of properties for this connection.

Parameters:
property - the property to add.

removeProperty

void removeProperty(java.lang.String id)
Removes the given property from the list of properties for this connection. If the specified id was not set, the call is ignored.

Parameters:
id - the id of the property which is to be cleared.

getContext

ConnectionContext getContext()
Returns the ConnectionContext which allows to retrieve further information about current connection

Returns:
the ConnectionContext of current connection.

getData

java.lang.Object getData(java.lang.String id)
API INTERNAL