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.accenture.aspire.rdb.RDBSConnectionPool" interface (see RDBMSConnectionPool.java)
| Apache Derby Embedded Database | |
|---|---|
| Factory Name | com.accenture.aspire:aspire-derby |
| subType | default |
| Inputs | None |
| Outputs | 'jdbc' document variable (when used as a pipeline stage) |
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.
Overview
Content Tools