TemporaryFolder

The EmbeddedDerbyResource supports using a JUnit TemporaryFolder Rule as a parent directory for the database directory. When using a temporary folder:

• The EmbeddedDerbyResource will not call the #before() or #after() methods on the TemporaryFolder. If the temporary folder is configured using a JUnit @Rule or @ClassRule, the JUnit test runner will set that up, otherwise the calling class will have to ensure that it is initialized and de-initialized.
• The actual directory used is a sub directory in the TemporaryFolder created using the #newFolder() method.
• The EmbeddedDerbyResource will not try to use the TemporaryFolder until the #start() (or #before()) method is invoked on it, to allow both to be configured as JUnit @Rules or @ClassRules.

Important: If both TemporaryFolder and EmbeddedDerbyResource are used as JUnit @Rules or @ClassRule, it is imperative that both are configured using a RuleChain and the @Rule or @ClassRule annotation be present on the RuleChain with the TemporaryFolder being initialized before the EmbeddedDerbyResource.

private TemporaryFolder tempFolder = new TemporaryFolder();
private EmbeddedDerbyResource embeddedDerbyResource =
	new EmbeddedDerbyResource(DerbyResourceConfig.buildDefault(), tempFolder);

@Rule
public RuleChain derbyRuleChain = RuleChain.outerRule(tempFolder).around(embeddedDerbyResource);

java.io.File Directory

EmbeddedDerbyResource also supports accepting a java.io.File directory to use as a database directory. The File object for the database directory need not exist before the test execution, but should be a path that the user the test is running under should have enough privileges to create the directory (if it does not exist) and be able to write in it.

The EmbeddedDerbyResource does not clean up any content of the directory after the execution.

The following code snippet shows a sample to create a EmbeddedDerbyResource using a Java temporary file, faked as a folder:

File tempFile = File.createTempFile("junit-helper-derby", Long.toString(System.nanoTime()));
tempFile.delete();
tempFile.mkdir();

final EmbeddedDerbyResource embeddedDerbyResource = new EmbeddedDerbyResource(DerbyResourceConfig.buildDefault(), tempFile);

System Property Handling / Limitations

Apache Derby only allows the derby.system.home to be set up as a System property, and if the property is not set it uses the user.dir directory as the the database directory.

To set the selected database directory on Derby, the EmbeddedDerbyResource does the following:

• In the #start() (or #before()) method:
  • If a derby.system.home property is set, save it off
  • Set the value of the selected database directory as the derby.system.home property
• In the #close() (or #after()) method:
  • Unset the derby.system.home property
  • If an old value was saved in the #start() method, set that back to the derby.system.home

The additional consequence of this behavior of Derby is that only a single instance of Derby (and EmbeddedDerbyResource) can be running in a single JVM. See Managing Concurrency for options of running multiple instances.

Default

• Method to enable: #useDefaultErrorLogging()
• Enumeration Value: Default

This is the default setting; derby will write to derby.log file in the derby.system.home.

No Logging

• Method to enable: #useDevNullErrorLogging()
• Enumeration Value: Null

All error log entries will be eaten up using an OutputStream which simply ignores all writes (see DerbyUtils#DEV_NULL stream), equivalent to redirecting logs to /dev/null on a *nix system.

In Memory Database

• Method to enable: #useInMemoryDatabase() or #useInMemoryDatabase(String)
• Enumeration Value: Memory
• Derby JDBC URL prefix: jdbc:derby:memory:
• Additional Configurations: Database Name

Databases exist only in main memory and are not written to disk.

Database in Directory

• Method to enable: #useDatabaseInDirectory() or #useDatabaseInDirectory(String) or #useDatabaseInDirectory(String, boolean)
• Enumeration Value: Directory
• Derby JDBC URL prefix: jdbc:derby:directory:
• Additional Configurations: Database Path, Skip create attribute

The database runs in a specified directory, either a relative directory under the Derby System Directory or an absolute directory outside the system directory. See Connecting to databases in the Derby Development Reference for more information.

java.sql.SQLException: Failed to create database 'directory:/path/to/database', see the next exception for details.
	at org.apache.derby.impl.jdbc.SQLExceptionFactory.getSQLException(Unknown Source)
	... NN more
Caused by: ERROR XJ041: Failed to create database 'directory:/path/to/database', see the next exception for details.
	at org.apache.derby.iapi.error.StandardException.newException(Unknown Source)
	at org.apache.derby.impl.jdbc.SQLExceptionFactory.wrapArgsForTransportAcrossDRDA(Unknown Source)
	... 41 more
Caused by: ERROR XBM0J: Directory /derby/system/home//path/to/database already exists.
	at org.apache.derby.iapi.error.StandardException.newException(Unknown Source)
	... NN more

Database in a Jar

• Method to enable: #useJarSubSubProtocol(String, String)
• Enumeration Value: Jar
• Derby JDBC URL prefix: jdbc:derby:jar:
• Additional Configurations: Path to Jar file & Database Path

Derby supports creating and using Read Only databases; which may be pre-existing database setup and data that is used in tests. For instructions on how to create read only database, see the Derby documentation Creating Derby databases for read-only use. Though not required, but a read only database in a jar file may be created during a test execution and used in a future test as well; just make sure to completely shut down the derby system before creating the archive.

The read only database is run from the jar file specified in the jarFilePath location. The path may be absolute or relative. The relative path is resolved by the Derby system relative to the Derby System Directory.

The databasePath is the path of the database directory inside the jar file archive.

For further information on read only databases, see the Derby documentation at Accessing a read-only database in a zip/jar file and Accessing databases from a jar or zip file.

If a jar database is configured with values of jarFilePath and databasePath as /tmp/test/db.jar and /sample/product respectively, it will open a read-only database product in the directory sample in the jar file. The effective JDBC URL generated with these parameters is jdbc:derby:jar:(/tmp/test/db.jar)sample/product.

Due to lack of documentation on how to implement this, the tool currently does not support an empty or null databasePath; setting such a value will cause a IllegalArgumentException from the configuration class.

Database from the classpath

• Method to enable: #useClasspathSubSubProtocol(String)
• Enumeration Value: Classpath
• Derby JDBC URL prefix: jdbc:derby:classpath:
• Additional Configurations: Database Path

This is another type of Read Only database supported by Derby. The database exists on the classpath, either in a Jar file or directly in the classpath. The Database Path mentioned above designates the path to the database in the classpath. All databaseNames must begin with at least a slash, because you specify them relative to the classpath directory or archive. See also Syntax of database connection URLs for applications with embedded databases and Accessing databases within a jar file using the classpath.

The Derby development guide has more on Accessing databases from the classpath.