Package org.olap4j

Interface OlapConnection

  • All Superinterfaces:
    java.lang.AutoCloseable, java.sql.Connection, OlapWrapper, java.sql.Wrapper

    public interface OlapConnection
    extends java.sql.Connection, OlapWrapper
    Connection to an OLAP server.

    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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      Scenario createScenario()
      Creates a Scenario.
      OlapStatement createStatement()
      java.util.List<java.lang.String> getAvailableRoleNames()
      Returns a list of the names of roles that are available for this user to execute queries.
      java.lang.String getCatalog()
      Returns the Catalog name which is currently active for this connection.
      java.lang.String getDatabase()
      Returns the database name currently active for this connection.
      java.util.Locale getLocale()
      Returns this connection's locale.
      OlapDatabaseMetaData getMetaData()
      Catalog getOlapCatalog()
      Returns the current active Catalog of this connection.
      NamedList<Catalog> getOlapCatalogs()
      Returns a list of Catalog objects which belong to this connection's OLAP server.
      Database getOlapDatabase()
      Returns the current active Database of this connection.
      NamedList<Database> getOlapDatabases()
      Returns a list of Database objects which belong to this connection's OLAP server.
      Schema getOlapSchema()
      Returns the current active Schema of this connection.
      NamedList<Schema> getOlapSchemas()
      Returns a list of Schema objects which belong to this connection's OLAP server.
      MdxParserFactory getParserFactory()
      Returns the factory used to create MDX parsers in this connection.
      java.lang.String getRoleName()
      Returns the name of the role in which this connection executes queries.
      Scenario getScenario()
      Returns this connection's active Scenario, or null if there is no active Scenario.
      java.lang.String getSchema()
      Returns the Schema name that was selected for this connection, either through the JDBC URL or via setSchema(String).
      PreparedOlapStatement prepareOlapStatement​(java.lang.String mdx)
      Creates a prepared OLAP Statement.
      void setCatalog​(java.lang.String catalogName)
      Sets the name of the catalog that will be used for this connection.
      void setDatabase​(java.lang.String databaseName)
      Sets the name of the database that will be used for this connection.
      void setLocale​(java.util.Locale locale)
      Sets the current locale of this connection.
      void setRoleName​(java.lang.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 setSchema​(java.lang.String schemaName)
      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 java.sql.Wrapper

        isWrapperFor, unwrap
    • Method Detail

      • prepareOlapStatement

        PreparedOlapStatement prepareOlapStatement​(java.lang.String mdx)
                                            throws OlapException
        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
      • getDatabase

        java.lang.String getDatabase()
                              throws OlapException
        Returns the database name currently active for this connection. If no database name was specified either through the JDBC URL or through setDatabase(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

        void setDatabase​(java.lang.String databaseName)
                  throws OlapException
        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

        Database getOlapDatabase()
                          throws OlapException
        Returns the current active Database 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:
        setDatabase(String), getOlapDatabases()
      • getOlapDatabases

        NamedList<Database> getOlapDatabases()
                                      throws OlapException
        Returns a list of Database 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

        java.lang.String getCatalog()
                             throws OlapException
        Returns the Catalog 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 interface java.sql.Connection
        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

        void setCatalog​(java.lang.String catalogName)
                 throws OlapException
        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 interface java.sql.Connection
        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

        Catalog getOlapCatalog()
                        throws OlapException
        Returns the current active Catalog 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

        NamedList<Catalog> getOlapCatalogs()
                                    throws OlapException
        Returns a list of Catalog 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

        java.lang.String getSchema()
                            throws OlapException
        Returns the Schema name that was selected for this connection, either through the JDBC URL or via setSchema(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 interface java.sql.Connection
        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

        void setSchema​(java.lang.String schemaName)
                throws OlapException
        Sets the name of the active schema for this connection. Overrides the value passed, if any, through the JDBC URL.
        Specified by:
        setSchema in interface java.sql.Connection
        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

        Schema getOlapSchema()
                      throws OlapException
        Returns the current active Schema 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

        NamedList<Schema> getOlapSchemas()
                                  throws OlapException
        Returns a list of Schema 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

        void setLocale​(java.util.Locale locale)
        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()
      • setRoleName

        void setRoleName​(java.lang.String roleName)
                  throws OlapException
        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

        java.lang.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

        java.util.List<java.lang.String> getAvailableRoleNames()
                                                        throws OlapException
        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
      • setScenario

        void setScenario​(Scenario scenario)
                  throws OlapException
        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. See Scenario 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

        Scenario getScenario()
                      throws OlapException
        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