Get Started with Ebean

1. Put ebean-x.jar and persistence.jar in your classpath

You need to put the ebean and persistence jar in the classpath. You can do this manually or via maven or ivy using the www.avaje.org maven repository. Goto the DOWNLOAD page for details.

2. Configure ebean.properties file

create an ebean.properties file and put it in your classpath or working directory. You can use the example below as a starting point.

You need to change the DataSource parameters to suite your own environment.

# -------------------------------------------------------------
# Load (Dev/Test/Prod) properties external to your war/jar
# -------------------------------------------------------------
# You can use load.properties to load the properties from a
# file external to your war/jar. 
#load.properties.override=${CATALINA_HOME}/conf/myapp.ebean.properties


ebean.ddl.generate=false
ebean.ddl.run=false

ebean.debug.sql=true
ebean.debug.lazyload=false


# -------------------------------------------------------------
# Transaction Logging
# -------------------------------------------------------------

# Use java util logging to log transaction details
#ebean.loggingToJavaLogger=true

# General logging level: (none, explicit, all)
ebean.logging=all

# Sharing log files: (none, explicit, all)
ebean.logging.logfilesharing=all

# location of transaction logs 
ebean.logging.directory=logs
#ebean.logging.directory=${catalina.base}/logs/trans

# Specific Log levels (none, summary, binding, sql)
ebean.logging.iud=sql
ebean.logging.query=sql
ebean.logging.sqlquery=sql

ebean.logging.txnCommit=none

# -------------------------------------------------------------
# DataSources (If using default Ebean DataSourceFactory)
# ------------------------------------------------------------- 
# You can specify many DataSources (one per EbeanServer)  and 
# one of them is defined as the default/primary DataSource

# specify the default/primary DataSource
datasource.default=h2

datasource.h2.username=sa
datasource.h2.password=
datasource.h2.databaseUrl=jdbc:h2:mem:tests;DB_CLOSE_DELAY=-1
datasource.h2.databaseDriver=org.h2.Driver
datasource.h2.minConnections=1
datasource.h2.maxConnections=25
datasource.h2.heartbeatsql=select 1
datasource.h2.isolationlevel=read_committed

datasource.mysql.username=test
datasource.mysql.password=test
datasource.mysql.databaseUrl=jdbc:mysql://127.0.0.1:3306/test
datasource.mysql.databaseDriver=com.mysql.jdbc.Driver
datasource.mysql.minConnections=1
datasource.mysql.maxConnections=25
#datasource.mysql.heartbeatsql=select 1
datasource.mysql.isolationlevel=read_committed

#datasource.ora.username=test
#datasource.ora.password=test
#datasource.ora.databaseUrl=jdbc:oracle:thin:@127.0.0.1:1521:XE
#datasource.ora.databaseDriver=oracle.jdbc.driver.OracleDriver
#datasource.ora.minConnections=1
#datasource.ora.maxConnections=25
#datasource.ora.heartbeatsql=select count(*) from dual
#datasource.ora.isolationlevel=read_committed

#datasource.pg.username=test
#datasource.pg.password=test
#datasource.pg.databaseUrl=jdbc:postgresql://127.0.0.1:5433/test
#datasource.pg.databaseDriver=org.postgresql.Driver
#datasource.pg.heartbeatsql=select 1

3. Try a simple test

Create a java class with a main method. Include code like that below but use a table name in your environment.

This will test that Ebean can find and use the DataSource.

package test.model;

import com.avaje.ebean.Ebean;
import com.avaje.ebean.SqlRow;
import com.avaje.ebean.config.GlobalProperties;

public class CheckDataSource {

        public static void main(String[] args) {
                
                String sql = "select count(*) as count from dual";
                SqlRow row = 
                        Ebean.createSqlQuery(sql)
                        .findUnique();
                
                Integer i = row.getInteger("count");
                
                System.out.println("Got "+i+"  - DataSource good.");
        }
}

4. Create an entity bean

Create a very simple entity bean.

package test.model;

import java.sql.Timestamp;

import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.persistence.Version;

/**
 * A simple entity bean. This table does not have to exist if
 * you use Ebean's DDL generation.
 */
@Entity
@Table(name="e_junktable")
public class EBasicVer {
    
    @Id
    Integer id;
    
    String name;
    
    String description;
    
    @Version
    Timestamp lastUpdate;
    
    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public Timestamp getLastUpdate() {
        return lastUpdate;
    }

    public void setLastUpdate(Timestamp lastUpdate) {
        this.lastUpdate = lastUpdate;
    }

}

5. Configure DDL generation

Change ebean.properties to turn on DDL generation.

# in ebean.properties
ebean.ddl.generate=true
ebean.ddl.run=true

The next time Ebean is run it will generate the DDL and run it. This includes drop table statements which will fail on first run.

6. Try to insert, update, query, delete

package test;

import test.model.ESimple;

import com.avaje.ebean.Ebean;
import com.avaje.ebean.config.GlobalProperties;


public class CheckIUDAndQuery {

        public static void main(String[] args) {
                
                //System.setProperty("catalina.base", "D:/apps/tomcat6");
                //System.setProperty("ebean.props.file", "D:/apps/tomcat6/conf/zsite.ebean.properties");
                //GlobalProperties.put("ebean.debug.sql", "true");
                
                ESimple e = new ESimple();
                e.setName("test");
                e.setDescription("something");
                
                // will insert
                Ebean.save(e);
                
                e.setDescription("changed");
                
                // this will update
                Ebean.save(e);
                
                // find the inserted entity by its id
                ESimple e2 = Ebean.find(ESimple.class, e.getId());
                System.out.println("Got "+e2.getDescription());
                
                Ebean.delete(e);
                // can use delete by id when you don't have the bean
                //Ebean.delete(ESimple.class, e.getId());
                
        }
}

7. Check Transaction logs

After this you should find the 'transaction logs' and have a look so that you can see the statements Ebean generated and the bind values used etc.

...
1/03/2010 08:51:39 com.avaje.ebean.server.transaction.TransactionLogManager <init>
INFO: Transaction logs in: D:/apps/tomcat6/logs/trans
...

Ebean will log out the directory where the transaction logs are getting written to. You should see something like the above in your logs.

When you find the transaction logs you should find content like the snippet shown below. This shows you the transaction ids and the statements, bind values and a summary entry. The transaction logs are very useful for you to follow exactly what Ebean is doing.

trans[1001], 08:51:39.430, insert into e_basicver (name, description, last_update) values (?,?,?) 
trans[1001], 08:51:39.508, Binding Insert [e_basicver]  set[name=test, description=something, lastUpdate=2010-03-01 08:51:39.502, ] 
trans[1001], 08:51:39.510, Inserted [ESimple] [1] 
trans[1002], 08:51:39.514, update e_basicver set name=?, description=?, last_update=? where id=? and last_update=? 
trans[1002], 08:51:39.516, Binding Update [e_basicver]  set[name=test, description=changed, lastUpdate=2010-03-01 08:51:39.515, ] where[id=1, lastUpdate=2010-03-01 08:51:39.502, ] 
trans[1002], 08:51:39.548, Updated [ESimple] [1] 
trans[1003], 08:51:39.579, select e.id c0, e.name c1, e.description c2, e.last_update c3  from e_basicver e where e.id = ?   
trans[1003], 08:51:39.585, FindById exeMicros[4530] rows[1] type[ESimple] bind[1] 
trans[1004], 08:51:39.587, delete from e_basicver where id=? and last_update=? 
trans[1004], 08:51:39.587, Binding Delete [e_basicver] where[id=1, lastUpdate=2010-03-01 08:51:39.515, ] 
trans[1004], 08:51:39.587, Deleted [ESimple] [1] 
Introduction User Guide (pdf) Install/Configure Public JavaDoc Whitepapers
General Database Specific Byte Code Deployment Annotations Features
Top Bugs Top Enhancements
woResponse