Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.birt.data.engine.api
Class DataEngine

    java.lang.Object
      org.eclipse.birt.data.engine.api.DataEngine

    public abstract class DataEngine

extends java.lang.Object

Data Engine API class.
Provides methods to define data sources and data sets, and to prepare a `IQueryDefinition`. An application typically needs only one instance of this class, which can be used to prepare and execute multiple data queries.

User of this class must always call the `shutdown` method when it is done with an instance of this class to ensure release of all data source connections and related resources.

Field Summary
`static java.lang.String` | `CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE` The fetch size on column and row edge in cube cursor.
`static java.lang.String` | `CUBECURSOR_FETCH_LIMIT_ON_LEVEL` Deprecated. use DataEngine.CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE and DataEngine.CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE instead
`static java.lang.String` | `CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE`
`static java.lang.String` | `DATA_SET_CACHE_DELTA_FILE`
`static java.lang.String` | `DATA_SET_CACHE_ROW_LIMIT` Indicates whether data set cache function need to be used: Negative integer: Enable data set cache.
`static java.lang.String` | `DATASET_CACHE_OPTION` Deprecated.
`static java.lang.String` | `IN_MEMORY_CUBE_SIZE` The size of cube to be saved in memory rather than in disk.
`static java.lang.String` | `INCREMENTAL_CACHE_CONFIG` data set incremental cache file URL.
`static java.lang.String` | `MEMORY_BUFFER_SIZE` Indicate the size of data cached for each result set.We only accept positive integer as input, the unit of which would be MB.
`static java.lang.String` | `MEMORY_DATA_SET_CACHE` Indicates whether memory data set cache function need to be used: Positive integer: Enable memory data set cache.

Constructor Summary
`DataEngine()`

Method Summary
`abstract void` | `addShutdownListener(IShutdownListener listener)` Add a shut down listener.
`abstract void` | `cancel()` Cancel this data engine execution
`abstract void` | `clearCache(IBaseDataSourceDesign dataSource, IBaseDataSetDesign dataSet)` If user wants to use the latest data from data set rather than local cache, user needs to call this clearCache method to delete the cache content from update local environment.
`abstract void` | `closeDataSource(java.lang.String dataSourceName)` Provides a hint to DtE that the consumer is done with the given data source, and that its resources can be safely released as appropriate.
`abstract void` | `defineDataSet(IBaseDataSetDesign dataSet)` Provides the definition of a data set to Data Engine.
`abstract void` | `defineDataSource(IBaseDataSourceDesign dataSource)` Provides the definition of a data source to Data Engine.
`abstract IResultMetaData` | `getCachedDataSetMetaData(IBaseDataSourceDesign dataSource, IBaseDataSetDesign dataSet)` This method will return NULL if the named data set is not cached.
`abstract IQueryResults` | `getQueryResults(java.lang.String queryResultID)` If and only if current mode is DataEngineContext.MODE_PRESENTATION, query result can be retrieved from report document.
`static DataEngine` | `newDataEngine(DataEngineContext context)` Creates a new instance of DataEngine, using the specified DataEngineContext as its running environment
`static DataEngine` | `newDataEngine(org.eclipse.birt.core.framework.PlatformConfig platformConfig, DataEngineContext dataContext)`
`static DataEngine` | `newDataEngine(org.mozilla.javascript.Scriptable sharedScope)` Deprecated. use newDataEngine( DataEngineContext context ) instead
`static DataEngine` | `newDataEngine(org.mozilla.javascript.Scriptable sharedScope, java.io.File homeDir)` Deprecated. Use newDataEngine(Scriptable) instead. Home Dir is no longer used.
`abstract org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery` | `prepare(org.eclipse.birt.data.engine.olap.api.query.ICubeQueryDefinition query, java.util.Map appContext)` Prepare the cube query definition, return an IPreparedCubeQuery instance
`abstract IPreparedQuery` | `prepare(IQueryDefinition querySpec)` Verifies the elements of a report query spec and provides a hint to the query to prepare and optimize an execution plan.
`abstract IPreparedQuery` | `prepare(IQueryDefinition querySpec, java.util.Map appContext)` Verifies the elements of a report query spec, and provides a hint and application context object(s) to the query to prepare and optimize an execution plan.
`abstract org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery` | `prepare(org.eclipse.birt.data.engine.olap.api.query.ISubCubeQueryDefinition query, java.util.Map appContext)` Prepare the sub cube query definition, return an IPreparedCubeQuery instance
`abstract void` | `registerQueries(IDataQueryDefinition[] queryDefns)` Optimize query execution by analyze a list of query definitions.
`abstract void` | `removeListener(IShutdownListener listener)` Remove a shut down listener.
`abstract void` | `shutdown()` Shuts down this instance of data engine, and releases all associated resources.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DATASET_CACHE_OPTION

    public static java.lang.String DATASET_CACHE_OPTION

  Deprecated.
  Indicates whether data set cache function needs to be used. If yes, put a true value of this property to appContext and set it by the method of prepare.

  See Also:
    `org.eclipse.birt.data.engine.api.DataEngine.prepare( IQueryDefinition querySpec, Map appContext)`

### DATA_SET_CACHE_ROW_LIMIT

    public static java.lang.String DATA_SET_CACHE_ROW_LIMIT

  Indicates whether data set cache function need to be used: Negative integer: Enable data set cache. The row limit will not be set and all data set rows are fetched. Positive integer: Enable data set cache. This row limit will be used for ALL data sets, regardless of settings on individual data set designs. Zero:Disable data set cache regardless of report design settings and DataEngineContext settings.

### MEMORY_BUFFER_SIZE

    public static java.lang.String MEMORY_BUFFER_SIZE

  Indicate the size of data cached for each result set.We only accept positive integer as input, the unit of which would be MB.

### DATA_SET_CACHE_DELTA_FILE

    public static java.lang.String DATA_SET_CACHE_DELTA_FILE

### MEMORY_DATA_SET_CACHE

    public static java.lang.String MEMORY_DATA_SET_CACHE

  Indicates whether memory data set cache function need to be used: Positive integer: Enable memory data set cache. This row limit will be used for ALL data sets, regardless of settings on individual data set designs. Zero:Disable memory data set cache regardless of report design settings and DataEngineContext settings.

### INCREMENTAL_CACHE_CONFIG

    public static java.lang.String INCREMENTAL_CACHE_CONFIG

  data set incremental cache file URL.

### CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE

    public static java.lang.String CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE

  The fetch size on column and row edge in cube cursor. Positive integer: the number setting on edge. Zero or Negative number:Disable the number setting on edge.

### CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE

    public static java.lang.String CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE

### CUBECURSOR_FETCH_LIMIT_ON_LEVEL

    public static java.lang.String CUBECURSOR_FETCH_LIMIT_ON_LEVEL

  Deprecated. use DataEngine.CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE and DataEngine.CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE instead
  The fetch size of the member numbers for all levels. Positive integer: the member numbers will be fetched from levels. Zero or Negative integer:Disable this number setting on levels.

### IN_MEMORY_CUBE_SIZE

    public static java.lang.String IN_MEMORY_CUBE_SIZE

  The size of cube to be saved in memory rather than in disk. The unit is MB. In case that the size of materialized cube exceed the assigned memory size, the disk will automatically be used.

Constructor Detail

### DataEngine

    public DataEngine()

Method Detail

### newDataEngine

    public static DataEngine newDataEngine(DataEngineContext context)

  Creates a new instance of DataEngine, using the specified DataEngineContext as its running environment

  Parameters:
    `context,` - When this value is null, a default context will be used. The default context is DataEngineContext.MODE_DIRECTPRESENT.
  Returns:
    an instance of DataEngine under specified context

### newDataEngine

    public static DataEngine newDataEngine(org.eclipse.birt.core.framework.PlatformConfig platformConfig,
                                           DataEngineContext dataContext)
                                    throws org.eclipse.birt.core.exception.BirtException

  Parameters:
    `context` -
  Returns:
  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### newDataEngine

    public static DataEngine newDataEngine(org.mozilla.javascript.Scriptable sharedScope)

  Deprecated. use newDataEngine( DataEngineContext context ) instead

  Creates a new instance of DataEngine, using the specified Javascript scope and home directory setting.

  Parameters:
    `sharedScope` - a Javascript scope to be used as the "shared" scope to evaluate Javascript expressions by the data engine.

### newDataEngine

    public static DataEngine newDataEngine(org.mozilla.javascript.Scriptable sharedScope,
                                           java.io.File homeDir)

  Deprecated. Use newDataEngine(Scriptable) instead. Home Dir is no longer used.

### getQueryResults

    public abstract IQueryResults getQueryResults(java.lang.String queryResultID)
                                           throws org.eclipse.birt.core.exception.BirtException

  If and only if current mode is DataEngineContext.MODE_PRESENTATION, query result can be retrieved from report document. Otherwise a BirtException will be thrown immediatelly.

  Parameters:
    `queryResultID` -
  Returns:
    an instanceof IQueryResults
  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### defineDataSource

    public abstract void defineDataSource(IBaseDataSourceDesign dataSource)
                                   throws org.eclipse.birt.core.exception.BirtException

  Provides the definition of a data source to Data Engine. A data source must be defined using this method prior to preparing any report query that uses such data source.
  Data sources are uniquely identified name. If specified data source has already been defined, its definition will be updated with the content of the provided definition object.

  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### defineDataSet

    public abstract void defineDataSet(IBaseDataSetDesign dataSet)
                                throws org.eclipse.birt.core.exception.BirtException

  Provides the definition of a data set to Data Engine. A data set must be defined using this method prior to preparing any report query that uses such data set.
  Data sets are uniquely identified name. If specified data set has already been defined, its definition will be updated with the content of the provided definition object.

  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### getCachedDataSetMetaData

    public abstract IResultMetaData getCachedDataSetMetaData(IBaseDataSourceDesign dataSource,
                                                             IBaseDataSetDesign dataSet)
                                                      throws org.eclipse.birt.core.exception.BirtException

  This method will return NULL if the named data set is not cached. Otherwise, it will return an IResultMetaData instance which provides at least the ColumnName and ColumnType information for all cached columns. Please note that the ParameterHint information will usually essential to the result of data set design is omitted for it has nothing to do with the metadata.

  Parameters:
    `dataSource` -
    `dataSet` -
    `parameterHints` -
  Returns:
  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### clearCache

    public abstract void clearCache(IBaseDataSourceDesign dataSource,
                                    IBaseDataSetDesign dataSet)
                             throws org.eclipse.birt.core.exception.BirtException

  If user wants to use the latest data from data set rather than local cache, user needs to call this clearCache method to delete the cache content from update local environment. After it is called, in the next time the data will be retrieved again from data source to update cache.

  Parameters:
    `dataSource,` - which is associated with the data set
    `dataSet,` - which cache needs to be cleared
  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### prepare

    public abstract IPreparedQuery prepare(IQueryDefinition querySpec)
                                    throws org.eclipse.birt.core.exception.BirtException

  Verifies the elements of a report query spec and provides a hint to the query to prepare and optimize an execution plan. The given querySpec could be a `IQueryDefinition` (raw data transform) spec based on static definition found in a report design.

  This report query spec could be further refined during engine execution after having resolved any related runtime condition. For example, a nested report item might not be rendered based on a runtime condition. Thus its associated data expression could be removed from the report query defn given to DtE to prepare.

  During prepare, the DTE does not open a data set. In other words, any `beforeOpen` script on a data set will not be evaluated at this stage.

  Parameters:
    `querySpec` - Specifies the data access and data transforms services needed from DtE to produce a set of query results.
  Returns:
    The `IPreparedQuery` object that contains a prepared query ready for execution.
  Throws:
    `org.eclipse.birt.data.engine.core.DataException` - if error occurs during the preparation of querySpec
    `org.eclipse.birt.core.exception.BirtException`

### prepare

    public abstract IPreparedQuery prepare(IQueryDefinition querySpec,
                                           java.util.Map appContext)
                                    throws org.eclipse.birt.core.exception.BirtException

  Verifies the elements of a report query spec, and provides a hint and application context object(s) to the query to prepare and optimize an execution plan.
  This has the same behavior as the prepare( IQueryDefinition querySpec ) method, with an additional argument for an application to pass in a context map to the underlying data provider, e.g. an ODA run-time driver.

  Parameters:
    `querySpec` - Specifies the data access and data transforms services needed from DtE to produce a set of query results.
    `appContext` - The application context map for preparation and execution of the querySpec; could be null.
  Returns:
    The `IPreparedQuery` object that contains a prepared query ready for execution.
  Throws:
    `org.eclipse.birt.core.exception.BirtException` - if error occurs during the preparation of querySpec
  Since:
    2.0

### registerQueries

    public abstract void registerQueries(IDataQueryDefinition[] queryDefns)
                                  throws org.eclipse.birt.data.engine.core.DataException

  Optimize query execution by analyze a list of query definitions.

  Parameters:
    `queryDefns` -
  Throws:
    `org.eclipse.birt.data.engine.core.DataException`

### closeDataSource

    public abstract void closeDataSource(java.lang.String dataSourceName)
                                  throws org.eclipse.birt.core.exception.BirtException

  Provides a hint to DtE that the consumer is done with the given data source, and that its resources can be safely released as appropriate. This tells DtE that there is to be no more query that uses such data source.

  Parameters:
    `dataSourceName` - The name of a data source. The named data source must have been previously defined.
  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### prepare

    public abstract org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery prepare(org.eclipse.birt.data.engine.olap.api.query.ICubeQueryDefinition query,
                                                                                     java.util.Map appContext)
                                                                              throws org.eclipse.birt.core.exception.BirtException

  Prepare the cube query definition, return an IPreparedCubeQuery instance

  Parameters:
    `query` -
    `appContext` -
  Returns:
  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### prepare

    public abstract org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery prepare(org.eclipse.birt.data.engine.olap.api.query.ISubCubeQueryDefinition query,
                                                                                     java.util.Map appContext)
                                                                              throws org.eclipse.birt.core.exception.BirtException

  Prepare the sub cube query definition, return an IPreparedCubeQuery instance

  Parameters:
    `query` -
    `appContext` -
  Returns:
  Throws:
    `org.eclipse.birt.core.exception.BirtException`

### addShutdownListener

    public abstract void addShutdownListener(IShutdownListener listener)

  Add a shut down listener. When the data engine shut down the listener will be notified.

### removeListener

    public abstract void removeListener(IShutdownListener listener)

  Remove a shut down listener.

  Parameters:
    `listener` -

### cancel

    public abstract void cancel()

  Cancel this data engine execution

### shutdown

    public abstract void shutdown()

  Shuts down this instance of data engine, and releases all associated resources. This method should be called when the caller is done with an instance of the data engine.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2008 Actuate Corp. All rights reserved.