public class DB extends Object
Database
by name.
DB additionally provides a convenient way to use the 'default' Database.
One of the Database instances can be registered as the "default database"
and can be obtained using DB.getDefault()
Database database = DB.getDefault();
Multiple database instances can be registered with DB and we can obtain them
using DB.byName()
Database hrDatabase = DB.byName("hr");
DB has methods like find(Class)
and save(Object)
which are
just convenience for using the default database.
// fetch using the default database
Order order = DB.find(Order.class, 10);
// is the same as
Database database = DB.getDefault();
Order order = database.find(Order.class, 10);
Modifier and Type | Method and Description |
---|---|
static Transaction |
beginTransaction()
Start a transaction with 'REQUIRED' semantics.
|
static Transaction |
beginTransaction(io.ebean.annotation.TxIsolation isolation)
Start a transaction additionally specifying the isolation level.
|
static Transaction |
beginTransaction(TxScope scope)
Start a transaction typically specifying REQUIRES_NEW or REQUIRED semantics.
|
static Database |
byName(String name)
Return the database for the given name.
|
static Set<Property> |
checkUniqueness(Object bean)
This method checks the uniqueness of a bean.
|
static Set<Property> |
checkUniqueness(Object bean,
Transaction transaction)
Same as
checkUniqueness(Object) . |
static void |
commitTransaction()
Commit the current transaction.
|
static CallableSql |
createCallableSql(String sql)
Create a CallableSql to execute a given stored procedure.
|
static <T> CsvReader<T> |
createCsvReader(Class<T> beanType)
Create a CsvReader for a given beanType.
|
static <T> Query<T> |
createNamedQuery(Class<T> beanType,
String namedQuery)
Create a named query.
|
static <T> Query<T> |
createQuery(Class<T> beanType)
Create a query for a type of entity bean.
|
static <T> Query<T> |
createQuery(Class<T> beanType,
String eql)
Parse the Ebean query language statement returning the query which can then
be modified (add expressions, change order by clause, change maxRows, change
fetch and select paths etc).
|
static SqlQuery |
createSqlQuery(String sql)
This is an alias for
sqlQuery(String) . |
static SqlUpdate |
createSqlUpdate(String sql)
This is an alias for
sqlUpdate(String) . |
static <T> Update<T> |
createUpdate(Class<T> beanType,
String ormUpdate)
Create a orm update where you will supply the insert/update or delete
statement (rather than using a named one that is already defined using the
@NamedUpdates annotation).
|
static Transaction |
currentTransaction()
Returns the current transaction or null if there is no current transaction in scope.
|
static int |
delete(Class<?> beanType,
Object id)
Delete the bean given its type and id.
|
static boolean |
delete(Object bean)
Delete the bean.
|
static int |
deleteAll(Class<?> beanType,
Collection<?> ids)
Delete several beans given their type and id values.
|
static int |
deleteAll(Collection<?> beans)
Delete all the beans in the Collection.
|
static int |
deleteAllPermanent(Class<?> beanType,
Collection<?> ids)
Delete permanent several beans given their type and id values.
|
static int |
deleteAllPermanent(Collection<?> beans)
Delete permanent all the beans in the Collection (will not use soft delete).
|
static int |
deletePermanent(Class<?> beanType,
Object id)
Delete permanent the bean given its type and id.
|
static boolean |
deletePermanent(Object bean)
Delete the bean in permanent fashion (will not use soft delete).
|
static Map<String,ValuePair> |
diff(Object a,
Object b)
Return a map of the differences between two objects of the same type.
|
static void |
endTransaction()
If the current transaction has already been committed do nothing otherwise
rollback the transaction.
|
static void |
execute(Runnable r)
Execute a Runnable in a Transaction with the default scope.
|
static void |
execute(TxScope scope,
Runnable r)
Execute a TxRunnable in a Transaction with an explicit scope.
|
static <T> T |
executeCall(Callable<T> c)
Execute a Callable in a Transaction with the default scope.
|
static <T> T |
executeCall(TxScope scope,
Callable<T> c)
Execute a Callable in a Transaction with an explicit scope.
|
static void |
externalModification(String tableName,
boolean inserts,
boolean updates,
boolean deletes)
Inform Ebean that tables have been modified externally.
|
static <T> Filter<T> |
filter(Class<T> beanType)
Create a filter for sorting and filtering lists of entities locally without
going back to the database.
|
static <T> Query<T> |
find(Class<T> beanType)
Create a query for a type of entity bean.
|
static <T> T |
find(Class<T> beanType,
Object id)
Find a bean using its unique id.
|
static <T> DtoQuery<T> |
findDto(Class<T> dtoType,
String sql)
Create a Query for DTO beans.
|
static <T> Query<T> |
findNative(Class<T> beanType,
String nativeSql)
Create a query using native SQL.
|
static void |
flush()
The batch will be flushing automatically but you can use this to explicitly
flush the batch if you like.
|
static BackgroundExecutor |
getBackgroundExecutor()
Return the BackgroundExecutor service for asynchronous processing of
queries.
|
static BeanState |
getBeanState(Object bean)
Return the BeanState for a given entity bean.
|
static Database |
getDefault()
Return the default database.
|
static ExpressionFactory |
getExpressionFactory()
Return the ExpressionFactory from the default database.
|
static <T> T |
getReference(Class<T> beanType,
Object id)
Get a reference object.
|
static ServerCacheManager |
getServerCacheManager()
Return the manager of the level 2 cache ("L2" cache).
|
static void |
insert(Object bean)
Insert the bean.
|
static void |
insertAll(Collection<?> beans)
Insert a collection of beans.
|
static JsonContext |
json()
Return the JsonContext for reading/writing JSON.
|
static void |
markAsDirty(Object bean)
Marks the entity bean as dirty.
|
static void |
merge(Object bean)
Merge the bean using the default merge options.
|
static void |
merge(Object bean,
MergeOptions options)
Merge the bean using the given merge options.
|
static Object |
nextId(Class<?> beanType)
Return the next identity value for a given bean type.
|
static void |
refresh(Object bean)
Refresh the values of a bean.
|
static void |
refreshMany(Object bean,
String manyPropertyName)
Refresh a 'many' property of a bean.
|
static void |
register(TransactionCallback transactionCallback)
Register a TransactionCallback on the currently active transaction.
|
static void |
rollbackTransaction()
Rollback the current transaction.
|
static void |
save(Object bean)
Either Insert or Update the bean depending on its state.
|
static int |
saveAll(Collection<?> beans)
Save all the beans from a Collection.
|
static void |
setRollbackOnly()
Mark the current transaction as rollback only.
|
static <T> void |
sort(List<T> list,
String sortByClause)
Sort the list using the sortByClause which can contain a comma delimited
list of property names and keywords asc, desc, nullsHigh and nullsLow.
|
static SqlQuery |
sqlQuery(String sql)
Look to execute a native sql query that does not returns beans but instead
returns SqlRow or direct access to ResultSet (see
SqlQuery.findList(RowMapper) . |
static SqlUpdate |
sqlUpdate(String sql)
Look to execute a native sql insert update or delete statement.
|
static <T> UpdateQuery<T> |
update(Class<T> beanType)
Create an Update query to perform a bulk update.
|
static void |
update(Object bean)
Saves the bean using an update.
|
static void |
updateAll(Collection<?> beans)
Update the beans in the collection.
|
public static Database getDefault()
public static Database byName(String name)
name
- The name of the databasepublic static ExpressionFactory getExpressionFactory()
The ExpressionFactory is used internally by the query and ExpressionList to build the WHERE and HAVING clauses. Alternatively you can use the ExpressionFactory directly to create expressions to add to the query where clause.
Alternatively you can use the Expr
as a shortcut to the
ExpressionFactory of the 'Default' database.
You generally need to the an ExpressionFactory (or Expr
) to build
an expression that uses OR like Expression e = Expr.or(..., ...);
public static Object nextId(Class<?> beanType)
This will only work when a IdGenerator is on this bean type such as a DB sequence or UUID.
For DB's supporting getGeneratedKeys and sequences such as Oracle10 you do not need to use this method generally. It is made available for more complex cases where it is useful to get an ID prior to some processing.
public static Transaction beginTransaction()
With REQUIRED semantics if an active transaction already exists that transaction will be used.
The transaction is stored in a ThreadLocal variable and typically you only need to use the returned Transaction IF you wish to do things like use batch mode, change the transaction isolation level, use savepoints or log comments to the transaction log.
Example of using a transaction to span multiple calls to find(), save() etc.
try (Transaction transaction = DB.beginTransaction()) {
Order order = DB.find(Order.class, 42);
order.setStatus(Status.COMPLETE);
order.save();
transaction.commit();
}
If you want to externalise the transaction management then you should be able to do this via Database. Specifically with Database you can pass the transaction to the various find() and save() execute() methods. This gives you the ability to create the transactions yourself externally from Ebean and pass those transactions through to the various methods available on Database.
public static Transaction beginTransaction(io.ebean.annotation.TxIsolation isolation)
isolation
- the Transaction isolation levelpublic static Transaction beginTransaction(TxScope scope)
Note that this provides an try finally alternative to using executeCall(TxScope, Callable)
or
execute(TxScope, Runnable)
.
// Start a new transaction. If there is a current transaction
// suspend it until this transaction ends
try (Transaction txn = DB.beginTransaction(TxScope.requiresNew())) {
...
// commit the transaction
txn.commit();
}
// start a new transaction if there is not a current transaction
try (Transaction txn = DB.beginTransaction(TxScope.required())) {
...
// commit the transaction if it was created or
// do nothing if there was already a current transaction
txn.commit();
}
public static Transaction currentTransaction()
public static void flush()
Flushing occurs automatically when:
public static void register(TransactionCallback transactionCallback) throws javax.persistence.PersistenceException
transactionCallback
- the transaction callback to be registered with the current transactionjavax.persistence.PersistenceException
- if there is no currently active transactionpublic static void commitTransaction()
public static void rollbackTransaction()
public static void endTransaction()
It is preferable to use try with resources rather than this.
Useful to put in a finally block to ensure the transaction is ended, rather than a rollbackTransaction() in each catch block.
Code example:
DB.beginTransaction();
try {
// do some fetching and or persisting
// commit at the end
DB.commitTransaction();
} finally {
// if commit didn't occur then rollback the transaction
DB.endTransaction();
}
public static void setRollbackOnly()
public static Map<String,ValuePair> diff(Object a, Object b)
When null is passed in for b, then the 'OldValues' of a is used for the difference comparison.
public static void save(Object bean) throws javax.persistence.OptimisticLockException
If there is no current transaction one will be created and committed for you automatically.
Save can cascade along relationships. For this to happen you need to specify a cascade of CascadeType.ALL or CascadeType.PERSIST on the OneToMany, OneToOne or ManyToMany annotation.
When a save cascades via a OneToMany or ManyToMany Ebean will automatically set the 'parent' object to the 'detail' object. In the example below in saving the order and cascade saving the order details the 'parent' order will be set against each order detail when it is saved.
javax.persistence.OptimisticLockException
public static void insert(Object bean)
public static void insertAll(Collection<?> beans)
public static void markAsDirty(Object bean) throws javax.persistence.OptimisticLockException
This is used so that when a bean that is otherwise unmodified is updated with the version property 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 = DB.find(Customer, id);
// mark the bean as dirty so that a save() or update() will
// increment the version property
DB.markAsDirty(customer);
DB.save(customer);
javax.persistence.OptimisticLockException
public static void update(Object bean) throws javax.persistence.OptimisticLockException
Stateless updates: Note that the bean does not have to be previously fetched to call update().You can create a new instance and set some of its properties programmatically for via JSON/XML marshalling etc. This is described as a 'stateless update'.
Optimistic Locking: Note that if the version property is not set when update() is called then no optimistic locking is performed (internally ConcurrencyMode.NONE is used).
ServerConfig.setUpdatesDeleteMissingChildren(boolean)
: When cascade saving to a
OneToMany or ManyToMany the updatesDeleteMissingChildren setting controls if any other children
that are in the database but are not in the collection are deleted.
ServerConfig.setUpdateChangesOnly(boolean)
: The updateChangesOnly setting
controls if only the changed properties are included in the update or if all the loaded
properties are included instead.
// A 'stateless update' example
Customer customer = new Customer();
customer.setId(7);
customer.setName("ModifiedNameNoOCC");
database.update(customer);
javax.persistence.OptimisticLockException
ServerConfig.setUpdatesDeleteMissingChildren(boolean)
,
ServerConfig.setUpdateChangesOnly(boolean)
public static void updateAll(Collection<?> beans) throws javax.persistence.OptimisticLockException
javax.persistence.OptimisticLockException
public static void merge(Object bean)
bean
- The bean to mergepublic static void merge(Object bean, MergeOptions options)
bean
- The bean to mergeoptions
- The options to control the mergepublic static int saveAll(Collection<?> beans) throws javax.persistence.OptimisticLockException
javax.persistence.OptimisticLockException
@Nonnull public static Set<Property> checkUniqueness(Object bean)
Note: This method queries the DB for uniqueness of all indices, so do not use it in a batch update.
Note: This checks only the root bean!
// there is a unique constraint on title
Document doc = new Document();
doc.setTitle("One flew over the cuckoo's nest");
doc.setBody("clashes with doc1");
Set<Property> properties = DB.checkUniqueness(doc);
if (properties.isEmpty()) {
// it is unique ... carry on
} else {
// build a user friendly message
// to return message back to user
String uniqueProperties = properties.toString();
StringBuilder msg = new StringBuilder();
properties.forEach((it)-> {
Object propertyValue = it.getVal(doc);
String propertyName = it.getName();
msg.append(" property["+propertyName+"] value["+propertyValue+"]");
});
// uniqueProperties > [title]
// custom msg > property[title] value[One flew over the cuckoo's nest]
}
bean
- The entity bean to check uniqueness on@Nonnull public static Set<Property> checkUniqueness(Object bean, Transaction transaction)
checkUniqueness(Object)
. but with given transaction.public static boolean delete(Object bean) throws javax.persistence.OptimisticLockException
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 is configured with @SoftDelete
then this will perform a soft
delete rather than a hard/permanent delete.
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.
javax.persistence.OptimisticLockException
public static boolean deletePermanent(Object bean) throws javax.persistence.OptimisticLockException
javax.persistence.OptimisticLockException
public static int delete(Class<?> beanType, Object id)
public static int deletePermanent(Class<?> beanType, Object id)
public static int deleteAll(Class<?> beanType, Collection<?> ids)
public static int deleteAllPermanent(Class<?> beanType, Collection<?> ids)
public static int deleteAll(Collection<?> beans) throws javax.persistence.OptimisticLockException
javax.persistence.OptimisticLockException
public static int deleteAllPermanent(Collection<?> beans) throws javax.persistence.OptimisticLockException
javax.persistence.OptimisticLockException
public static void refresh(Object bean)
Note that this resets OneToMany and ManyToMany properties so that if they are accessed a lazy load will refresh the many property.
public static void refreshMany(Object bean, String manyPropertyName)
Order order = ...;
...
// refresh the order details...
DB.refreshMany(order, "details");
bean
- the entity bean containing the List Set or Map to refresh.manyPropertyName
- the property name of the List Set or Map to refresh.public static <T> T getReference(Class<T> beanType, Object id)
This is sometimes described as a proxy (with lazy loading).
Product product = DB.getReference(Product.class, 1);
// You can get the id without causing a fetch/lazy load
Integer productId = product.getId();
// If you try to get any other property a fetch/lazy loading will occur
// This will cause a query to execute...
String name = product.getName();
beanType
- the type of entity beanid
- the id valuepublic static <T> void sort(List<T> list, String sortByClause)
If you leave off any keywords the defaults are ascending order and treating nulls as high values.
Note that the sorting uses a Comparator and Collections.sort(); and does not invoke a DB query.
// find orders and their customers
List<Order> list = DB.find(Order.class)
.fetch("customer")
.orderBy("id")
.findList();
// sort by customer name ascending, then by order shipDate
// ... then by the order status descending
DB.sort(list, "customer.name, shipDate, status desc");
// sort by customer name descending (with nulls low)
// ... then by the order id
DB.sort(list, "customer.name desc nullsLow, id");
list
- the list of entity beanssortByClause
- the properties to sort the list by@Nullable public static <T> T find(Class<T> beanType, Object id)
// Fetch order 1
Order order = DB.find(Order.class, 1);
If you want more control over the query then you can use createQuery() and Query.findOne();
// ... additionally fetching customer, customer shipping address,
// order details, and the product associated with each order detail.
// note: only product id and name is fetch (its a "partial object").
// note: all other objects use "*" and have all their properties fetched.
Query<Order> query = DB.find(Order.class)
.setId(1)
.fetch("customer")
.fetch("customer.shippingAddress")
.fetch("details")
.query();
// fetch associated products but only fetch their product id and name
query.fetch("details.product", "name");
// traverse the object graph...
Order order = query.findOne();
Customer customer = order.getCustomer();
Address shippingAddress = customer.getShippingAddress();
List<OrderDetail> details = order.getDetails();
OrderDetail detail0 = details.get(0);
Product product = detail0.getProduct();
String productName = product.getName();
beanType
- the type of entity bean to fetchid
- the id valuepublic static SqlQuery sqlQuery(String sql)
SqlQuery.findList(RowMapper)
.
Refer to DtoQuery
for native sql queries returning DTO beans.
Refer to findNative(Class, String)
for native sql queries returning entity beans.
public static SqlQuery createSqlQuery(String sql)
sqlQuery(String)
.public static SqlUpdate sqlUpdate(String sql)
Use this to execute a Insert Update or Delete statement. The statement will be native to the database and contain database table and column names.
See SqlUpdate
for example usage.
public static SqlUpdate createSqlUpdate(String sql)
sqlUpdate(String)
.public static CallableSql createCallableSql(String sql)
CallableSql
public static <T> Update<T> createUpdate(Class<T> beanType, String ormUpdate)
The orm update differs from the sql update in that it you can use the bean name and bean property names rather than table and column names.
An example:
// The bean name and properties - "topic","postCount" and "id"
// will be converted into their associated table and column names
String updStatement = "update topic set postCount = :pc where id = :id";
Update<Topic> update = DB.createUpdate(Topic.class, updStatement);
update.set("pc", 9);
update.set("id", 3);
int rows = update.execute();
System.out.println("rows updated:" + rows);
public static <T> CsvReader<T> createCsvReader(Class<T> beanType)
public static <T> Query<T> createNamedQuery(Class<T> beanType, String namedQuery)
For RawSql the named query is expected to be in ebean.xml.
T
- The type of entity beanbeanType
- The type of entity beannamedQuery
- The name of the querypublic static <T> Query<T> createQuery(Class<T> beanType)
You can use the methods on the Query object to specify fetch paths, predicates, order by, limits etc.
You then use findList(), findSet(), findMap() and findOne() to execute the query and return the collection or bean.
Note that a query executed by Query.findList()
etc will execute against
the same database from which is was created.
beanType
- the class of entity to be fetchedpublic static <T> Query<T> createQuery(Class<T> beanType, String eql)
// Find order additionally fetching the customer, details and details.product name.
String eql = "fetch customer fetch details fetch details.product (name) where id = :orderId ";
Query<Order> query = DB.createQuery(Order.class, eql);
query.setParameter("orderId", 2);
Order order = query.findOne();
// This is the same as:
Order order = DB.find(Order.class)
.fetch("customer")
.fetch("details")
.fetch("detail.product", "name")
.setId(2)
.findOne();
T
- The type of the entity beanbeanType
- The type of bean to fetcheql
- The Ebean querypublic static <T> Query<T> find(Class<T> beanType)
This is actually the same as createQuery(Class)
. The reason it
exists is that people used to JPA will probably be looking for a
createQuery method (the same as entityManager).
beanType
- the type of entity bean to findpublic static <T> Query<T> findNative(Class<T> beanType, String nativeSql)
The native SQL can contain named parameters or positioned parameters.
String sql = "select c.id, c.name from customer c where c.name like ? order by c.name";
Query<Customer> query = database.findNative(Customer.class, sql);
query.setParameter(1, "Rob%");
List<Customer> customers = query.findList();
beanType
- The type of entity bean to fetchnativeSql
- The SQL that can contain named or positioned parameterspublic static <T> DtoQuery<T> findDto(Class<T> dtoType, String sql)
DTO beans are just normal bean like classes with public constructor(s) and setters. They do not need to be registered with Ebean before use.
T
- The type of the DTO bean.dtoType
- The type of the DTO bean the rows will be mapped into.sql
- The SQL query to execute.public static <T> UpdateQuery<T> update(Class<T> beanType)
int rows = DB.update(Customer.class)
.set("status", Customer.Status.ACTIVE)
.set("updtime", new Timestamp(System.currentTimeMillis()))
.where()
.gt("id", 1000)
.update();
T
- The type of entity beanbeanType
- The type of entity bean to updatepublic static <T> Filter<T> filter(Class<T> beanType)
This produces and returns a new list with the sort and filters applied.
Refer to Filter
for an example of its use.
public static void execute(TxScope scope, Runnable r)
The scope can control the transaction type, isolation and rollback semantics.
// set specific transactional scope settings
TxScope scope = TxScope.requiresNew().setIsolation(TxIsolation.SERIALIZABLE);
DB.execute(scope, new TxRunnable() {
public void run() {
User u1 = DB.find(User.class, 1);
...
}
});
public static void execute(Runnable r)
The default scope runs with REQUIRED and by default will rollback on any exception (checked or runtime).
DB.execute(() -> {
User u1 = DB.find(User.class, 1);
User u2 = DB.find(User.class, 2);
u1.setName("u1 mod");
u2.setName("u2 mod");
DB.save(u1);
DB.save(u2);
});
public static <T> T executeCall(TxScope scope, Callable<T> c)
The scope can control the transaction type, isolation and rollback semantics.
// set specific transactional scope settings
TxScope scope = TxScope.requiresNew().setIsolation(TxIsolation.SERIALIZABLE);
DB.executeCall(scope, new Callable<String>() {
public String call() {
User u1 = DB.find(User.class, 1);
...
return u1.getEmail();
}
});
public static <T> T executeCall(Callable<T> c)
The default scope runs with REQUIRED and by default will rollback on any exception (checked or runtime).
This is basically the same as TxRunnable except that it returns an Object (and you specify the return type via generics).
DB.executeCall(() -> {
User u1 = DB.find(User.class, 1);
User u2 = DB.find(User.class, 2);
u1.setName("u1 mod");
u2.setName("u2 mod");
DB.save(u1);
DB.save(u2);
return u1.getEmail();
});
public static void externalModification(String tableName, boolean inserts, boolean updates, boolean deletes)
If you use DB.execute(UpdateSql) then the table modification information is automatically deduced and you do not need to call this method yourself.
This information is used to invalidate objects out of the cache and potentially text indexes. This information is also automatically broadcast across the cluster.
If there is a transaction then this information is placed into the current transactions event information. When the transaction is committed this information is registered (with the transaction manager). If this transaction is rolled back then none of the transaction event information registers including the information you put in via this method.
If there is NO current transaction when you call this method then this information is registered immediately (with the transaction manager).
tableName
- the name of the table that was modifiedinserts
- true if rows where inserted into the tableupdates
- true if rows on the table where updateddeletes
- true if rows on the table where deletedpublic static BeanState getBeanState(Object bean)
This will return null if the bean is not an enhanced entity bean.
public static ServerCacheManager getServerCacheManager()
public static BackgroundExecutor getBackgroundExecutor()
public static JsonContext json()
Copyright © 2019. All rights reserved.