Download & Dependencies

The best way to use Empire-db is to use Maven for dependency management. However for getting started it may be convenient to download the full distribution in order to run and debug the examples. Or even better: Fork us on Github.

Download distribution

In order to download the Apache Empire-db distribution files please pick between one of the following formats:
File Size PGP SHA256
apache-empire-db-3.2.0-dist.tar.gz 3.6 MB
apache-empire-db-3.2.0-dist.zip 4.1 MB

We recommend that you verify the integrity of the downloaded files using the PGP or SHA signatures. The PGP signatures can be verified using PGP or GPG after downloading the KEYS file. We recommend that you use a web of trust if possible, to confirm the identity of these keys. For more information, please see the Apache Release FAQ.

Dependencies

The Empire-db core component has (only) the following dependencies

Maven

To use Apache Empire-db in your project add the following dependency to your project's pom file:
mvnrepository.com/artifact/org.apache.empire-db/empire-db
<dependency>
    <groupId>org.apache.empire-db</groupId>
    <artifactId>empire-db</artifactId>
    <version>3.1.0</version>
</dependency>

To use Apache empire-db-jsf2-extensions in your project add the following dependency to your project's pom file:
mvnrepository.com/artifact/org.apache.empire-db/empire-db-jsf2
<dependency>
    <groupId>org.apache.empire-db</groupId>
    <artifactId>empire-db-jsf2</artifactId>
    <version>3.1.0</version>
</dependency>
Show previous releases
Hide previous releases

Getting started

The truth is in the code! The best way to understand Empire-db is to run and debug our example projects.

Here's what we've got:

Basic Example

Here you learn the basics like creating a context, creating and opening a database, performing queries and working with Records, Readers, DataLists, and Java Beans.

Verdict:Bread and Butter

Advanced Example

This shows more advanced stuff like advanced Data Model setup, using Command parameters, data modification techniques, Rollback handling, DDL changes at runtime, Batch processing and more.

Verdict:4 native SQL speakers

JSF Web Example

This is an example of how to use Empire-db server-side with JavaServerFaces to build a Web frontend. The example uses our Empire-db-JSF-extensions module which provides special composite components in order to build input controls automatically from Metadata as well as some other useful stuff. Check it out.

Verdict:Metadata rocks

JSON / REST / Vue Example

This shows how to generate data and metadata as JSON objects and serve them via a REST service to a Vue Frontend. The Vue client then generates suitable input controls using the Metadata to provide basic CRUD functionality.

Verdict:Very Cool!


Database first (How-to)

Most of our examples use - for obvious reasons - a code first approach creating a HyperSQL (HSQLDB) database for the example on startup.

An example of how to generate the data model code from an existing database is however provided with the empire-db-example-codegen module.

In the example you will also learn how to configure the code generation process for your needs.

The generation process can be customized in many ways like e.g.:
  • Name of the database class and optionally for base classes of table, view and record
  • Separate package names for database, tables, view and records
  • Pre- and suffixes for names of tables, views and columns
  • Option to create nested classes for table and/or views inside the database class
  • Option to create record classes for the entity types
  • Option to create Java style getter and setter functions on the records

In order to perform the code generation, there are two approaches which we recommend:

1. Generate from your code...

First, add the empire-db-codegen dependency to your project
.../artifact/org.apache.empire-db/empire-db-codegen
<dependencies>
    <dependency>
        <groupId>org.apache.empire-db</groupId>
        <artifactId>empire-db-codegen</artifactId>
    </dependency>
    <dependency>
        <!-- add your JDBC-Driver here -->
        <groupId>com.oracle.database.jdbc</groupId>
        <artifactId>ojdbc8</artifactId>
    </dependency> 
</dependencies>
Then call the generator from code e.g. like this
Java
// create the config
CodeGenConfig config = new CodeGenConfig();
// init via API or load from file using config.init("config.xml")
config.setPackageName("com.mycompany.myproject.database");
config.setDbClassName("MyDatabase");
config.set...(...)
// get the DBMS
DBMSHandler dbms = new DBMSHandlerOracle();
// get the JDBC-Connection
Connection conn = getJDBCConnection(config);
// Generate code from database
CodeGenerator app = new CodeGenerator();
app.generate(dbms, conn, config);

2. ...or use the empire-db-maven-plugin

Add the empire-db-maven-plugin to your project's build section
.../artifact/org.apache.empire-db/empire-db-maven-plugin
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.empire-db</groupId>
            <artifactId>empire-db-maven-plugin</artifactId>
            <version>3.1.0</version>
            <configuration>
                <!-- add config-file (see example-codegen for details) -->
                <configFile>codegen-config.xml</configFile>
            </configuration>
            <dependencies>
                <dependency>
                    <!-- add your JDBC-Driver here -->
                    <groupId>com.oracle.database.jdbc</groupId>
                    <artifactId>ojdbc8</artifactId>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
In order to start the code generation, run this from a command prompt
> mvn empire-db:codegen

Please look at the empire-db-example-codegen project for further details.