Module io.ebean.api

Package io.ebean

Class Model

java.lang.Object

io.ebean.Model

public abstract class Model
extends Object

A MappedSuperclass base class that provides convenience methods for inserting, updating and deleting beans.

By having your entity beans extend this it provides a 'Active Record' style programming model for Ebean users.

Note that there is a ebean-mocker project that enables you to use Mockito or similar tools to still mock out the underlying 'default Database' for testing purposes.

You may choose not use this Model mapped superclass if you don't like the 'Active Record' style or if you believe it 'pollutes' your entity beans.

You can use Dependency Injection like Guice or Spring to construct and wire a Database instance and have that same instance used with this Model and Finder. The way that works is that when the DI container creates the Database instance it can be registered with DB. In this way the Database instance can be injected as per normal Guice / Spring dependency injection and that same instance also used to support the Model and Finder active record style.

If you choose to use the Model mapped superclass you will probably also chose to additionally add a Finder as a public static field to complete the active record pattern and provide a relatively nice clean way to write queries.

Typical common @MappedSuperclass

     // Typically there is a common base model that has some
     // common properties like the ones below

   @MappedSuperclass
   public class BaseModel extends Model {

     @Id Long id;

     @Version Long version;

     @WhenCreated Timestamp whenCreated;

     @WhenUpdated Timestamp whenUpdated;

     ...
   }
 

Extend the Model

     // Extend the mappedSuperclass

     @Entity @Table(name="o_account")
     public class Customer extends BaseModel {

       String name;
       ...
     }

 

Modal: save()

     // Active record style ... save(), delete() etc
     Customer customer = new Customer();
     customer.setName("AC234");

     // save() method inherited from Model
     customer.save();

 

Constructor Summary

Constructors

Constructor	Description
Model()	Create using the default database.
Model(String dbName)	Create with a named database (typically not the default database).

Method Summary

Modifier and Type	Method	Description
Database	db()	Return the underlying 'default' Database.
boolean	delete()	Delete this bean.
boolean	delete(Transaction transaction)	Delete this entity with an explicit transaction.
boolean	deletePermanent()	Delete a bean permanently without soft delete.
boolean	deletePermanent(Transaction transaction)	Delete a bean permanently without soft delete using an explicit transaction.
void	flush()	Flush any batched changes to the database.
void	insert()	Insert this entity.
void	insert(Transaction transaction)	Insert with an explicit transaction.
void	markAsDirty()	Marks the entity bean as dirty.
void	markPropertyUnset(String propertyName)	Mark the property as unset or 'not loaded'.
void	refresh()	Refreshes this entity from the database.
void	save()	Insert or update this entity depending on its state.
void	save(Transaction transaction)	Save this entity with an explicit transaction.
void	update()	Update this entity.
void	update(Transaction transaction)	Update this entity with an explicit transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Model

public Model()

Create using the default database.

Model

public Model(String dbName)

Create with a named database (typically not the default database).

Method Details

db

public Database db()

Return the underlying 'default' Database.

This provides full access to the API such as explicit transaction demarcation etc.

Example:

 try (Transaction transaction = Customer.db().beginTransaction()) {

   // turn off cascade persist for this transaction
   transaction.setPersistCascade(false);

   // extra control over jdbc batching for this transaction
   transaction.setBatchGetGeneratedKeys(false);
   transaction.setBatchMode(true);
   transaction.setBatchSize(20);

   Customer customer = new Customer();
   customer.setName("Roberto");
   customer.save();

   Customer otherCustomer = new Customer();
   otherCustomer.setName("Franko");
   otherCustomer.save();

   transaction.commit();

 }

 

markAsDirty

public void markAsDirty()

Marks the entity bean as dirty.

This is used so that when a bean that is otherwise unmodified is updated the version property is updated.

An unmodified bean that is saved or updated is normally skipped and this marks the bean as dirty so that it is not skipped.

 Customer customer = Customer.find.byId(id);

 // mark the bean as dirty so that a save() or update() will
 // increment the version property
 customer.markAsDirty();
 customer.save();

 

See Also:

• Database.markAsDirty(Object)

markPropertyUnset

public void markPropertyUnset(String propertyName)

Mark the property as unset or 'not loaded'.

This would be used to specify a property that we did not wish to include in a stateless update.

   // populate an entity bean from JSON or whatever
   User user = ...;

   // mark the email property as 'unset' so that it is not
   // included in a 'stateless update'
   user.markPropertyUnset("email");

   user.update();

 

Parameters:

propertyName - the name of the property on the bean to be marked as 'unset'

save

public void save()

Insert or update this entity depending on its state.

Ebean will detect if this is a new bean or a previously fetched bean and perform either an insert or an update based on that.

See Also:

• Database.save(Object)

save

public void save(Transaction transaction)

Save this entity with an explicit transaction.

flush

public void flush()

Flush any batched changes to the database.

When using JDBC batch flushing occurs automatically at commit() time or when the batch size is reached. This provides the ability to manually flush the batch.

update

public void update()

Update this entity.

See Also:

• Database.update(Object)

update

public void update(Transaction transaction)

Update this entity with an explicit transaction.

insert

public void insert()

Insert this entity.

See Also:

• Database.insert(Object)

insert

public void insert(Transaction transaction)

Insert with an explicit transaction.

delete

public boolean delete()

Delete this bean.

This will return true if the bean was deleted successfully or JDBC batch is being used.

If there is no current transaction one will be created and committed for you automatically.

If the Bean does not have a version property (or loaded version property) and the bean does not exist then this returns false indicating that nothing was deleted. Note that, if JDBC batch mode is used then this always returns true.

See Also:

• Database.delete(Object)

delete

public boolean delete(Transaction transaction)

Delete this entity with an explicit transaction.

deletePermanent

public boolean deletePermanent()

Delete a bean permanently without soft delete.

This is used when the bean contains a @SoftDelete property and we want to perform a hard/permanent delete.

See Also:

• Database.deletePermanent(Object)

deletePermanent

public boolean deletePermanent(Transaction transaction)

Delete a bean permanently without soft delete using an explicit transaction.

refresh

public void refresh()

Refreshes this entity from the database.

See Also:

• Database.refresh(Object)