This method can be used to register one or more listeners. On such listener can listen for one or more events.

For a single listener, you can pass a listener object literal with the following structure:

{
    events: ...event name or array of event names...,
    handler: ...function or array of functions...,
    scope: object
}

You can use event as an alias for events. Likewise, you can use handlers as an alias for handler.

Alternatively, you can pass the element as separate arguments instead of as an object literal: addListener(name, func, scope) where name is a valid event name, func is the function that is to be called when the event occurs. The last argument is optional and can be used to specify the scope that will be used as context for executing the function.

To register multiple listeners, pass an array of listener objects: addListener([listener1, ..., listenerN])

Alternatively, pass multiple listener objects as separate arguments: addListener(listener1, ..., listenerN)

Or, pass a single object literal with event names as keys and listener objects or functions as values:

addListener({
        discover: function() {
            ...handle discover event...
        },
        error: {
            handler: function() {
               ...handle error event...
            },
            scope: obj
        },
        scope: defaultscope
    })

Below is a more detailed description of the listener object and its components:

events

string|string[] REQUIRED. The event or events to listen to. You can specify a single event by using one of the EVENT_XXX string constant values. You can specify multiple events by using an array of EVENT_XXX string constant values. You can also use one of the predefined EVENT_XXX array constant values, or use array concatenation and compose a custom list of event names. To listen to all events, either use EVENT_ALL, or otherwise the string value "all".

event

string|string[] Alias for events

handler

function|function[] REQUIRED. This function will be called and notified whenever one of the specified events occurs. The function has the following signature: boolean handler(string eventName, object eventData, Xmla xmla) You can also pass in an array of functions if you want multiple functions to be called when the event occurs. The function is called in scope of the scope property of the listener object. If no scope is specified, a global function is assumed. The handler function has the following arguments:

eventName

string The event for which notification is given. This is useful to distinguish between events in case the same handler function is used for multiple events. In this case, use the EVENT_XXX constants to check the eventName.

eventData

Object An object that conveys event-specific data.

xmla

Xmla A reference to this Xmla instance that is the source of the event. Listeners can obtain the response as well as the original SOAP message sent to the server through this instance. This allows one listener to be shared across multiple Xmla instances without managing the context manually.

For events that are cancelable, the handler should return a boolean. If the handler returns false the respective operation will be canceled. Otherwise, the operation continues (but may be canceled by another handler). Currently, the following events are cancelable: EVENT_DISCOVER, EVENT_EXECUTE, and EVENT_REQUEST.

handlers

function|function[] Alias for handler

scope

Object OPTIONAL When specified, this object is used as the this object when calling the handler. When not specified, the global window is used.

Sends a request to invoke the XML/A Discover method and returns a schema rowset specified by the requestType option. Options are passed using a generic options object. Applicable properties of the options object are:

• requestType - {string} Indicates the kind of schema rowset to retrieve. You can use one of the following predefined XML for Analysis Schema Rowset constants:
  • DISCOVER_DATASOURCES
  • DISCOVER_ENUMERATORS
  • DISCOVER_KEYWORDS
  • DISCOVER_LITERALS
  • DISCOVER_PROPERTIES
  • DISCOVER_SCHEMA_ROWSETS
  Or one of the applicable OLE DB Schema Rowset constants:
  • DBSCHEMA_CATALOGS
  • DBSCHEMA_COLUMNS
  • DBSCHEMA_PROVIDER_TYPES
  • DBSCHEMA_SCHEMATA
  • DBSCHEMA_TABLES
  • DBSCHEMA_TABLES_INFO
  Or one of the applicable OLE DB for OLAP Schema Rowset constants:
  • MDSCHEMA_ACTIONS
  • MDSCHEMA_CUBES
  • MDSCHEMA_DIMENSIONS
  • MDSCHEMA_FUNCTIONS
  • MDSCHEMA_HIERARCHIES
  • MDSCHEMA_MEASURES
  • MDSCHEMA_MEMBERS
  • MDSCHEMA_PROPERTIES
  • MDSCHEMA_SETS
  You can also dymically discover which values for requestType are supported by the XML/A provider. To do that, refer to the SchemaName column of the DISCOVER_SCHEMA_ROWSETS rowset (see: discoverMDSchemaRowsets()).
• url {string} REQUIRED the url of the XML/A service or XML/A datasource. If the value for the requestType option is one of the predefined XML/A DISCOVER_XXX constants, then this should be the url of the XML/A service.
• properties {Object} XML/A properties. The appropriate types and values of XML/A properties are dependent upon the value passed as requestType. The XML/A standard defines a set of pre-defined properties. The Xmla class defines a static final property for each of these (see the PROP_XXX constants). The list of all valid properties can be obtained from the DISCOVER_PROPERTIES schema rowset (see discoverProperties()). Each javascript property of the properties object is mapped literally to a XML/A property.
• restrictions {Object} XML/A restrictions. These are used to specify a filter that will be applied to the data in the schema rowset. Each javascript property of the restrictions object is mapped to a column of the requested schema rowset. The value for the restriction is sent with the request, and processed by the XML/A server to only return matching rows from the requested schema dataset. The name, types and values of the restrictions are dependent upon which schema rowset is requested. The available restrictions are specified by the Restrictions column of the DISCOVER_SCHEMA_ROWSETS schema rowset. For a number of schema rowsets, the available restrictions are pre-defined. These are documented together with each particular discoverXXX() method.
• async {boolean} Determines how the request is performed:
  • true: The request is performed asynchronously: the call to request() will not block and return immediately. In this case, the return value of the request() method is not defined, and the response must be received by registering a listener (see addListener()).
  • false: The request is performed synchronously: the call to execute() will block until it receives a response from the XML/A server or times out. In this case, a Resultset is returned that represents the multi-dimensional data set. If you registered any REQUEST_XXX and/or EXECUTE_XXX listeners (see addListener()), then these will still be notified.

Instead of calling this method directly, consider calling or one of the specialized discoverXXX() methods to obtain a particular schema rowset.

Invokes the discover() method using as value for the requestType, and retrieves the DISCOVER_DATASOURCES schema rowset. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DBSCHEMA_CATALOGS schema rowset. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DBSCHEMA_COLUMNS schema rowset. Provides column information for all columns meeting the provided restriction criteria. The rowset has the following columns:

The rowset is sorted on TABLECATALOG, TABLESCHEMA, TABLE_NAME.

Invokes the discover() method using as value for the requestType, and retrieves the DBSCHEMAPROVIDERTYPES schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DBSCHEMA_SCHEMATA schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DBSCHEMA_TABLES schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DBSCHEMATABLESINFO schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DISCOVER_ENUMERATORS schema rowset. This rowset lists the names, data types, and enumeration values of enumerators supported by the XMLA Provider for a specific data source. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DISCOVER_KEYWORDS schema rowset. This rowset is a list of reserved words for this XML/A provider. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DISCOVER_LITERALS schema rowset. This rowset is a list of reserved words for this XML/A provider. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_ACTIONS schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_CUBES schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_DIMENSIONS schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_FUNCTIONS schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_HIERARCHIES schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_LEVELS schema rowset. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_MEASURES schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_MEMBERS schema rowset. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_PROPERTIES schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the MDSCHEMA_SETS schema rowset. ...todo... The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DISCOVER_PROPERTIES schema rowset. This rowset provides information on the properties that are supported by the XML/A provider. The rowset has the following columns:

Invokes the discover() method using as value for the requestType, and retrieves the DISCOVERSCHEMAROWSETS schema rowset. This rowset lists all possible request types supported by this provider. The rowset has the following columns:

Sends an MDX query to a XML/A DataSource to invoke the XML/A Execute method and obtain the multi-dimensional resultset. Options are passed using a generic options object. Applicable properties of the options object are:

• url {string} REQUIRED the URL of a XML/A datasource. This should be a value obtained from the URL column of the DISCOVER_DATASOURCES rowset (see: discoverDataSources()).
• statement - {string} The MDX query to send to the server.
• properties {Object} XML/A properties. The list of all valid properties can be obtained from the DISCOVER_PROPERTIES schema rowset (see discoverProperties()). Typically, execute() requires these properties:

  DataSourceInfo property

  Identifies a data source managed by the XML/A server. To specify this property, you can use the static final constant PROP_DATASOURCEINFO as key in the properties object of the options object passed to the execute() method. Valid values for this property should be obtained from the DataSourceInfo column of the DISCOVER_DATASOURCES schema rowset (see: discoverDataSources()). Note that the values for the DataSourceInfo property and the url must both be taken from the same row of the DISCOVER_DATASOURCES schema rowset.

  Catalog property

  Identifies a catalog applicable for the datasource. To specify this property, you can use the static final constant PROP_CATALOG as key in the properties object of the options object passed to the execute() method. Valid values for this property should be obtained from the CATALOG_NAME column of the DBSCHEMA_CATALOGS schema rowset (see: discoverDBCatalogs()).

• async {boolean} Determines how the request is performed:
  • true: The request is performed asynchronously: the call to request() will not block and return immediately. In this case, the return value of the request() method is not defined, and the response must be received by registering a listener (see addListener()).
  • false: The request is performed synchronously: the call to execute() will block until it receives a response from the XML/A server or times out. In this case, a Resultset is returned that represents the multi-dimensional data set. If you registered any REQUEST_XXX and/or EXECUTE_XXX listeners (see addListener()), then these will still be notified.

Sends an MDX query to a XML/A DataSource to invoke the PROPFORMATMULTIDIMENSIONAL as value for the PROPFORMAT property. In this case, the result is available only as XML text or XML document in the responseText and responseXML properties.

Sends an MDX query to a XML/A DataSource to invoke the execute() method using PROPFORMATTABULAR as value for the PROP_FORMAT property. This has the effect of obtaining the multi-dimensional resultset as a Rowset.

Sends a request to the XML/A server. This method is rather low-level and allows full control over the request by passing an options object. General properties of the options object are:

• method {string} REQUIRED the XML/A method to invoke. This should be one of the following constants:

  METHOD_DISCOVER

  This method is used to obtain metadata from the XML/A service or XML/A provider. Metadata is returned in a tabular format called Schema Rowsets, which are represented by an instance of the Xmla.Rowset class. For these types of requests, you must pass the requestType option to specify which schema rowset you want to obtain. In addition, you can specify a restrictions object that is used as filter criteria to restrict which rows will be returned in the rowset.

  Instead of explicitly passing METHOD_DISCOVER as the requestType, you can also call the discover() method (which requires you to explictly pass a requestType option). Finally, you can also call one of the discoverXXX() methods in order to request a particular schema rowset.

  METHOD_EXECUTE

  This method is used to send an MDX quey to the XML/A provider. Query results are returned in a multidimentsional format which is represented by an instance of the Xmla.Dataset class. For these types of requests, you must pass the statement option to specify the MDX query.

  Instead of explicitly passing METHOD_EXECUTE as the requestType, you can also call the execute() method.

• url {string} REQUIRED the URL of XML/A service, or of a XML/A datasource. Typically, you first use the URL of a XML/A service (like http://your.pentaho.server:8080/pentaho/Xmla?userid=joe&password=password) and use that to retrieve the DISCOVER_DATASOURCES rowset. Then, you can connect to a XML/A datasource using the value returned by the URL column of the DISCOVER_DATASOURCES rowset (typically, you also have to set a DataSourceInfo property using the value found in the DataSourceInfo column of the DISCOVER_DATASOURCES rowset).
• properties {Object} XML/A properties. The appropriate types and values of XML/A properties are dependent upon the specific method and requestType. The XML/A standard defines a set of pre-defined properties. The Xmla class defines a static final property for each of these (see the PROP_XXX constants). The list of all valid properties can be obtained from the DISCOVER_PROPERTIES schema rowset (see discoverProperties()). Each javascript property of the properties object is mapped literally to a XML/A property.
• async {boolean} Determines how the request is performed:
  • true: The request is performed asynchronously: the call to request() will not block and return immediately. In this case, the return value of the request() method is not defined, and the response must be received by registering a listener. (see addListener()). As an alternative to using listeners, you can also pass success, error and callback callback functions. Callbacks are described in more detail below.
  • false: The request is performed synchronously: the call to request() will block until it receives a response from the XML/A server or times out. In this case, the request() method returns a Rowset (for Discover requests) or a Resultset (for Execute requests). If you registered any listeners (see addListener()), then these will still be notified of any events (such as receiving the response).
• success (function) A function that is to be called after the requests is executed and a successful response is receieved. Any listeners appropriate for the request are called after this handler is executed.
• error (function) A function that is to be called after the requests is executed and an error was encountered. Any listeners appropriate for the request are called after this handler is executed.
• callback (function) A function that is to be called after the requests is executed and the response is receieved, and after calling any listeners that are appropriate for the request. This function will be called both in case of success and of error. If the options also contain a success and/or error handler, then callback will be called after those more specific handlers are called.

Other parts of the options object are method-specific.

• The following options are applicable in case the method is METHOD_DISCOVER:
  • requestType - {string} Applies to the Discover method and indicates the kind of schema rowset to retrieve. You can use one of the DISCOVER_XXX, DBSCHEMA_XXX or MDSCHEMA_XXX constants for this property. You can also dymically discover which values for requestType are supported by the XML/A provider using the DISCOVER_SCHEMA_ROWSETS rowset (see: discoverMDSchemaRowsets()). See the discover() method for more information.
  • restrictions {Object} XML/A restrictions are used to filter the requested schema rowset. For more information on restrictions, see the discover() method.
• The following options are applicable in case the method is METHOD_EXECUTE:
  • statement - {string} Applies to the Execute method and specifies the MDX query to send to the server.

Instead of calling this method directly, consider calling discover() (to obtain a schema rowset), execute() (to issue a MDX query), or one of the specialized discoverXXX() methods (to obtain a particular schema rowset).

This method can be used to set a number of default options for the Xmla instance. This is especially useful if you don't want to pass each and every option to each method call all the time. Where appropriate, information that is missing from the parameter objects passed to the methods of the Xmla object may be augmented with the values set through this method. For example, if you plan to do a series of requests pertaining to one particular datasource, you can set the mandatory options like url, async, datasource and catalog just once:

    xml.setOptions({
        url: "http://localhost:8080/pentaho/Xmla",
        async: true,
        properties: {
            DataSourceInfo: "Pentaho Analysis Services",
            Catalog: "Foodmart"
        }
    });

Then, a subsequent