Interface OlapConnection
- All Superinterfaces:
AutoCloseable
,Connection
,OlapWrapper
,Wrapper
OlapConnection is a subclass of Connection
. It can be pooled
by a connection pooling framework or obtained directly via the Java
standard DriverManager
. The JDBC URL prefix of olap connections
is dependent of the driver implementation. Such implementations are,
among others possible:
- Olap4j's XML/A driver
- Mondrian
Olap connections have a different metadata hierarchy than regular
JDBC. The connection's metadata is available using
getMetaData()
, and returns a specialized subclass
of DatabaseMetaData
. The objects at the root of the hierarchy
are Database
class objects.
A connection needs be bound to a database, a catalog and a schema. Implementations are expected to automatically discover these if no driver specific parameters indicated which ones to use.
- Since:
- Aug 22, 2006
- Author:
- jhyde
-
Field Summary
Fields inherited from interface java.sql.Connection
TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE
-
Method Summary
Modifier and TypeMethodDescriptionCreates a Scenario.Returns a list of the names of roles that are available for this user to execute queries.Returns theCatalog
name which is currently active for this connection.Returns the database name currently active for this connection.Returns this connection's locale.Returns the current activeCatalog
of this connection.Returns a list ofCatalog
objects which belong to this connection's OLAP server.Returns the current activeDatabase
of this connection.Returns a list ofDatabase
objects which belong to this connection's OLAP server.Returns the current activeSchema
of this connection.Returns a list ofSchema
objects which belong to this connection's OLAP server.Returns the factory used to create MDX parsers in this connection.Returns the name of the role in which this connection executes queries.Returns this connection's active Scenario, or null if there is no active Scenario.Returns theSchema
name that was selected for this connection, either through the JDBC URL or viasetSchema(String)
.Creates a prepared OLAP Statement.void
setCatalog
(String catalogName) Sets the name of the catalog that will be used for this connection.void
setDatabase
(String databaseName) Sets the name of the database that will be used for this connection.void
Sets the current locale of this connection.void
setRoleName
(String roleName) Sets the name of the role in which this connection executes queries.void
setScenario
(Scenario scenario) Sets the active Scenario of this connection.void
Sets the name of the active schema for this connection.Methods inherited from interface java.sql.Connection
abort, beginRequest, clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStruct, endRequest, getAutoCommit, getClientInfo, getClientInfo, getHoldability, getNetworkTimeout, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setClientInfo, setClientInfo, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid, setTransactionIsolation, setTypeMap
Methods inherited from interface org.olap4j.OlapWrapper
isWrapperFor, unwrap
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap
-
Method Details
-
getMetaData
- Specified by:
getMetaData
in interfaceConnection
- Throws:
OlapException
- if database error occurs
-
prepareOlapStatement
Creates a prepared OLAP Statement.This method is the equivalent, for OLAP, of the
Connection.prepareStatement(String)
JDBC method.- Parameters:
mdx
- MDX query string- Returns:
- prepared statement
- Throws:
OlapException
- if database error occurs
-
getParserFactory
MdxParserFactory getParserFactory()Returns the factory used to create MDX parsers in this connection.- Returns:
- MDX parser factory
-
createStatement
- Specified by:
createStatement
in interfaceConnection
- Throws:
OlapException
- if database error occurs
-
getDatabase
Returns the database name currently active for this connection. If no database name was specified either through the JDBC URL or throughsetDatabase(String)
, the driver will select the first one available.- Returns:
- The name of the database currently active for this connection.
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No databases exist on the server.
- The user specified a database name which does not exist on the server.
-
setDatabase
Sets the name of the database that will be used for this connection. Overrides the value passed, if any, through the JDBC URL.- Parameters:
databaseName
- The name of the database to use.- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- The user specified a database name which does not exist on the server.
-
getOlapDatabase
Returns the current activeDatabase
of this connection.If the user has not specified a database name to use for this connection, the driver will auto-select the first Database available.
- Returns:
- The currently active Database, or null of none are currently selected.
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No databases exist on the server.
- The user specified a database name which does not exist on the server.
- See Also:
-
getOlapDatabases
Returns a list ofDatabase
objects which belong to this connection's OLAP server.The caller should assume that the list is immutable; if the caller modifies the list, behavior is undefined.
- Returns:
- List of Database objects in this connection's OLAP server
- Throws:
OlapException
- if a database access error occurs
-
getCatalog
Returns theCatalog
name which is currently active for this connection.If the user has not specified a database name to use for this connection, the driver will automatically select the first one available. If the user has not specified a catalog name to use, the driver will also use the first one available on the server.
- Specified by:
getCatalog
in interfaceConnection
- Returns:
- The name of the catalog which is active for this connection.
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
- No catalog names were specified and no catalogs exist on the server.
- The user specified a catalog name which does not exist on the server.
-
setCatalog
Sets the name of the catalog that will be used for this connection. Overrides the value passed, if any, through the JDBC URL.- Specified by:
setCatalog
in interfaceConnection
- Parameters:
catalogName
- The name of the catalog to use for this connection.- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
- The user specified a catalog name which does not exist on the server.
-
getOlapCatalog
Returns the current activeCatalog
of this connection.If the user has not selected a Database and Catalog to use for this connection, the driver will auto-select the first Database and Catalog available on the server.
Any auto-discovery performed by implementations must take into account the specified database name and catalog name, if any.
- Returns:
- The currently active catalog, or null of none are currently selected.
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
- No catalog name was specified and no catalogs exist on the server.
- The user specified a catalog name which does not exist on the server.
-
getOlapCatalogs
Returns a list ofCatalog
objects which belong to this connection's OLAP server.If the user has not selected a Database to use for this connection, the implementation auto-selects the first Database available. Any auto-discovery performed by implementations must take into account the connection Database parameter.
The caller should assume that the list is immutable; if the caller modifies the list, behavior is undefined.
- Returns:
- List of Catalogs in this connection's OLAP server
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
-
getSchema
Returns theSchema
name that was selected for this connection, either through the JDBC URL or viasetSchema(String)
.If the user has not selected a Database, Catalog and Schema to use for this connection, the driver will auto-select the first Database, Catalog and Schema available.
Any auto-discovery performed by implementations must take into account the specified Database, Catalog and Schema names, if any.
- Specified by:
getSchema
in interfaceConnection
- Returns:
- The name of the schema currently selected for this connection.
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
- No catalog name was specified and no catalogs exist on the server.
- The user specified a catalog name which does not exist on the server.
- No schema name was specified and no schema exist on the server.
- The user specified a schema name which does not exist on the server.
-
setSchema
Sets the name of the active schema for this connection. Overrides the value passed, if any, through the JDBC URL.- Specified by:
setSchema
in interfaceConnection
- Parameters:
schemaName
- The name of the schema to use for this connection.- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
- No catalog name was specified and no catalogs exist on the server.
- The user specified a catalog name which does not exist on the server.
- No schema name was specified and no schema exist on the server.
- The user specified a schema name which does not exist on the server.
-
getOlapSchema
Returns the current activeSchema
of this connection.If the user has not selected a Database, Catalog and Schema to use for this connection, the driver will auto-select the first Database, Catalog and Schema available.
Any auto-discovery performed by implementations must take into account the specified Database, Catalog and Schema names, if any.
- Returns:
- The currently active schema
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
- No catalog name was specified and no catalogs exist on the server.
- The user specified a catalog name which does not exist on the server.
- No schema name was specified and no schema exist on the server.
- The user specified a schema name which does not exist on the server.
-
getOlapSchemas
Returns a list ofSchema
objects which belong to this connection's OLAP server.If the user has not selected a Database, Catalog and Schema to use for this connection, the driver will auto-select the first Database and Catalog available.
Any auto-discovery performed by implementations must take into account the specified Database, Catalog and Schema names, if any.
The caller should assume that the list is immutable; if the caller modifies the list, behavior is undefined.
- Returns:
- List of Catalogs in this connection's OLAP server
- Throws:
OlapException
- if any of these conditions are true:- A server error occurs.
- No database name was specified and no databases exist on the server.
- The user specified a database name which does not exist on the server.
- No catalog name was specified and no catalogs exist on the server.
- The user specified a catalog name which does not exist on the server.
- No schema name was specified and no schema exist on the server.
- The user specified a schema name which does not exist on the server.
-
setLocale
Sets the current locale of this connection. The value must not be null.If the locale is not set, the JDK's current locale is used (see
Locale.getDefault()
).Most drivers support a
Locale
connect-string property.- Parameters:
locale
- Locale- See Also:
-
getLocale
Locale getLocale()Returns this connection's locale. The value is never null.- Returns:
- locale of this connection
- See Also:
-
setRoleName
Sets the name of the role in which this connection executes queries. If the name of the role is null, the connection reverts to the default access control context.- Parameters:
roleName
- Name of role- Throws:
OlapException
- if role name is invalid
-
getRoleName
String getRoleName()Returns the name of the role in which this connection executes queries.- Returns:
- name of the role in which this connection executes queries
-
getAvailableRoleNames
Returns a list of the names of roles that are available for this user to execute queries.- Returns:
- a list of role names, or null if the available roles are not known
- Throws:
OlapException
- if database error occurs
-
createScenario
Creates a Scenario.It does not become the active scenario for the current connection. To do this, call
setScenario(Scenario)
.- Returns:
- a new Scenario
- Throws:
OlapException
- if database error occurs- See Also:
-
setScenario
Sets the active Scenario of this connection.After setting a scenario, the client may call
Cell.setValue(java.lang.Object, org.olap4j.AllocationPolicy, java.lang.Object...)
to change the value of cells returned from queries. The value of those cells is changed. This operation is referred to as 'writeback', and is used to perform 'what if' analysis, such as budgeting. SeeScenario
for more details.If
scenario
is null, the connection will have no active scenario, and writeback is not allowed.Scenarios are created using
createScenario()
.- Parameters:
scenario
- Scenario- Throws:
OlapException
- if database error occurs
-
getScenario
Returns this connection's active Scenario, or null if there is no active Scenario.- Returns:
- Active scenario, or null
- Throws:
OlapException
- if database error occurs
-