[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Getting Started

The following information should help you to get started with ORMLite. Android users should also look at the Android specific page after reading these pages here. See section Using With Android.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Downloading ORMLite Jar

To get started with ORMLite, you will need to download the jar files. The ORMLite release page is the default repository but the jars are also available from the central maven repository and from Sourceforge.

Users that are connecting to SQL databases via JDBC connections will need to download the ormlite-jdbc-4.48.jar and ormlite-core-4.48.jar files. For use with Android applications, you should download the ormlite-android-4.48.jar and ormlite-core-4.48.jar files instead. For either JDBC or Android you will also need the ormlite-core release which has the ORMLite backend implementations. ORMLite does not have any required external dependencies although there are some optional packages that you may want to use. See section External Dependencies. The code works with Java 5 or later.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Configuring a Class

The following is an example class that is configured to be persisted to a database using ORMLite annotations. The @DatabaseTable annotation configures the Account class to be persisted to the database table named accounts. The @DatabaseField annotations map the fields on the Account to the database columns with the same names.

The name field is configured as the primary key for the database table by using the id = true annotation field. Also, notice that a no-argument constructor is needed so the object can be returned by a query. For more information (JPA annotations and other ways to configure classes) see the class setup information later in the manual. See section Setting Up Your Classes.

 
@DatabaseTable(tableName = "accounts")
public class Account {
    
    @DatabaseField(id = true)
    private String name;
    @DatabaseField
    private String password;
    
    public Account() {
        // ORMLite needs a no-arg constructor 
    }
    public Account(String name, String password) {
        this.name = name;
        this.password = password;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getPassword() {
        return password;
    }
    public void setPassword(String password) {
        this.password = password;
    }
}

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Configuring a DAO

A typical Java pattern is to isolate the database operations in Data Access Objects (DAO) classes. Each DAO provides create, delete, update, etc. type of functionality and specializes in the handling a single persisted class. A simple way to build a DAO is to use the createDao static method on the DaoManager class. For example, to create a DAO for the Account class defined above you would do:

 
Dao<Account, String> accountDao =
  DaoManager.createDao(connectionSource, Account.class);
Dao<Order, Integer> orderDao =
  DaoManager.createDao(connectionSource, Order.class);

More information about setting up the DAOs is available later in the manual. See section Setting Up the DAOs.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Code Example

This example uses the native Java H2 database to create an in-memory test database. You will need to download and add the H2 jar file to your classpath if you want to run the example as-is. See the H2 home page. NOTE: Android users should see the Android specific documentation later in the manual. See section Using With Android. There are also complete code examples that can be used. See section Example Code.

The code performs the following steps.

 
public class AccountApp {

    public static void main(String[] args) throws Exception {

        // this uses h2 by default but change to match your database
        String databaseUrl = "jdbc:h2:mem:account";
        // create a connection source to our database
        ConnectionSource connectionSource =
            new JdbcConnectionSource(databaseUrl);

        // instantiate the dao
        Dao<Account, String> accountDao =
            DaoManager.createDao(connectionSource, Account.class);

        // if you need to create the 'accounts' table make this call
        TableUtils.createTable(connectionSource, Account.class);

Once we have configured our database objects, we can use them to persist an Account to the database and query for it from the database by its ID:

 
        // create an instance of Account
        Account account = new Account();
        account.setName("Jim Coakley");

        // persist the account object to the database
        accountDao.create(account);

        // retrieve the account from the database by its id field (name)
        Account account2 = accountDao.queryForId("Jim Coakley");
        System.out.println("Account: " + account2.getName());

        // close the connection source
        connectionSource.close();
    }
}

You should be able to get started using ORMLite by this point. To understand more of the functionality available with ORMLite, continue on with the next section. See section How to Use.

For more examples including working code and Android application projects see section Example Code.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Gray Watson on December 16, 2013 using texi2html 1.82.