Apache Derby Embedded Database 0.4

From wiki.searchtechnologies.com
Jump to: navigation, search

For Information on Aspire 3.1 Click Here

Aspire / Aspire Components / Apache Derby Embedded RDB - Pipeline Stage and Connection Pool Component

Apache Derby Embedded RDB - Pipeline Stage and Connection Pool Component
Description: Maintains a connection pool to an embedded copy of the Apache Derby relational database using JDBC.
Inputs: None
Outputs: 'jdbc' document variable (when used as a pipeline stage)
Factory: aspire-derby
Sub Type: default
Object Type: AspireDocument

Each instance of an aspire-derby <component> will create a new copy of an embedded Apache Derby database. Each database operates independently.

Databases can either be in memory or persisted on disk in a file-system directory.

If in memory, the database "name" will automatically be the same as the component name. This means that every configured aspire-derby component is a unique in-memory database.

If on disk, the <directory> parameter below will specify the file system directory where the database will be stored.

The aspire-derby component is derived from aspire-rdb, and so it supports most of the methods that aspire-rdb supports. It maintains an RDB connection pool with the standard aspire-rdb methods for purging connections from this pool.

Like aspire-rdb, when used as a pipeline stage, the stage will fetch a connection from the connection pool and attach it to the job's document (using the 'jdbc' variable). The connection will be automatically returned to the pool when the job completes.

When used as an independent component, the component supports the "com.searchtechnologies.aspire.rdb.RDBSConnectionPool" interface.


Configuration

Configuration for Connecting to Remote Relational Databases

Element Type Default Description
directory string none The directory, relative to derby.system.home, where the Derby database is persisted to disk.

If this field is missing, it is assumed that the Derby database will be an in-memory database.

create boolean true If true, automatically creates the database on startup, if it it doesn't already exist. If the database already exists, does nothing.
shutdownOnRestart boolean true This parameter specifies if the database will be shutdown when the component is restarted.

If the database is an in-memory database, this means that the database should be completely wiped out on restart. Databases persisted on disk will be flushed but not removed. It is assumed that databases on disk will be removed manually (via file-system command) if you need to start them from scratch.

jdbcProperties/property/@name
jdbcProperties/property
string N/A (Optional) Arbitary jdbc connection properties (multiples allowed)
startup String none SQL commands to execute on startup. See RDBMS Connection for more details.


Configuration for controlling the connection pool

These parameters are the same as for aspire-rdb.

Element Type Default Description
timeout int 0
(= connections never closed)
The time in ms after which a connection in the pool should be considered for closing and purging from the pool. NOTE: the connection will not actually be closed until the next purge, so still could be reused if a request for a connection is received before the next purge occurs.
purgeThreshold int 0
(= infinite connections)
The minimum number of available connections in the pool before a purge will take place. It is not guaranteed that the pool will ever have this many connections available, but the pool will not be purged unless it does.
purgePoll int 60000
(= 60s)
The period in ms between purges of the connection pool.

Configuration Notes

Multiple components can not be configured to use the same database file. If you need to do this, put the component into a common area and refer to it from multiple places using component references such as /common/MyDerbyDb.

Example Configuration

In-Memory Database

  <component name="MyDB" subType="default" factoryName="aspire-derby">
    <config>
      <startup>
        ignore errors;
        create table URLS (
            httpcode varchar(100),
            url varchar(100));
            
        notice errors;
        delete from URLs;
      </startup>
    </config>
  </component>

Database Persisted on Disk

  <!-- Create an in-memory Aspire Derby Database -->
  <component name="EmbeddedDB" subType="default" factoryName="aspire-derby">
    <config>
      <directory>data/MyDerbyDb</directory>
      <create>false</create>
    </config>
  </component>

Complex

  <component name="EmbeddedDB" subType="default" factoryName="aspire-derby">
    <config>
      <directory>data/MyDerbyDb</directory>
      <create>false</create>
      <timeout>60000</timeout>
      <purgePoll>300000</purgePoll>
      <purgeThreshold>10</purgeThreshold>
      <timeout>${rdbConnectionTimeout}</timeout>
      <jdbcProperties>
        <property name="logDevice">data/MyDerbyLog</property>
      </jdbcProperties>
    </config>
  </component>

Network Server

  <component name="NetworkServerDb" subType="default" factoryName="aspire-derby">
    <config>
      <networkServer>true</networkServer>
      <port>2000</port>
      <directory>data/MyDerbyDb</directory>
      <create>true</create>
    </config>
  </component>

Remote Connection

  <component name="RemoteConnectionDb" subType="default" factoryName="aspire-derby">
    <config>
      <rdbServer>aspiredb.searchtechnologies.com</rdbServer>
      <port>2000</port>
      <dbName>data/MyDerbyDb</dbName>
    </config>
  </component>

Usage Examples

See aspire-rdb for examples on how aspire-derby can be used in pipelines and Groovy scripts.