Apache Derby Embedded Database (Aspire 2)

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

For Information on Aspire 3.1 Click Here


Apache Derby Embedded Database (Aspire 2)
Factory Name  com.searchtechnologies.aspire:aspire-derby
subType  default
Inputs  None
Outputs  'jdbc' document variable (when used as a pipeline stage)

The Apache Derby Embedded RDB - Pipeline Stage and Connection Pool Component stage maintains a connection pool to an embedded copy of the Apache Derby relational database using JDBC.

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 (see RDBMSConnectionPool.java)


Configuration

Configuration for Connecting to Remote Relational Databases

Element Type Default Description
derbyHome string ${ASPIRE_HOME} or the appBundle home directory if the component is in an appBundle The value (directory) to be used for derby.system.home.
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) Arbitrary JDBC connection properties (multiples allowed).
startup String none SQL commands to execute on startup. See RDBMS Connection for more details.
networkServer boolean false Starts the apache derby database as a network server so it's accessible from external processes (i.e. other JVM's).
networkServerInterface String 0.0.0.0 The network interface to listen on when in networkServer mode. If not specified or set to 0.0.0.0, the component will listen on all available interfaces. The interface can be set by hostname or IP Address.
rdbServer string none IP Address, hostname or FQDN of the server hosting an apache derby network server to connect to.

If used with "networkServer", then it will connect locally to the network server using the DerbyClient driver instead of the EmbeddedDriver.

port int 1527 Port number on which the network server will be configured if used with networkServer.

Port number to connect to if used with rdbServer.

dbName string none Name of the database hosted on the remote server (should be the same as the directory value used on the network server side). Used with rdbServer.


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">
    <startup>
      ignore errors;
      create table URLS (
          httpcode varchar(100),
          url varchar(100));
          
      notice errors;
      delete from URLs;
    </startup>
  </component>

Database Persisted on Disk

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

Complex

  <component name="EmbeddedDB" subType="default" factoryName="aspire-derby">
    <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>
  </component>

Network Server

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

Remote Connection

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

Usage Examples

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