CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <title>Persist - Ebean ORM</title> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <script async defer src="https://buttons.github.io/buttons.js"></script> <link rel="shortcut icon" href="/images/favicon.ico" > <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css"> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous"> <link rel="stylesheet" href="/css/pygments.css" type="text/css" /> <link rel="stylesheet" href="/css/site.css"> </head> <body> <div id="wrap"> <div id="header"> <div class="navbar" role="navigation"> <div class="container"> <div class="navbar-header"> <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".mobile-nav"> Toggle navigation </button> <a class="navbar-brand" href="/"> <img src="/images/lg5-21x100.png" height="35"> </a> </div> <div class="collapse navbar-collapse"> <ul class="nav navbar-nav pull-right nav-btn-rhs"> <li ><a href="/"> Home</a></li> <li class="active"><a href="/docs">Docs</a></li> <li ><a href="/docs/getting-started">Get Started</a></li> <li ><a href="/support">Help</a></li> <li ><a href="/videos">Videos</a></li> <li ><a target="_blank" href="/apidoc/13">ApiDocs</a></li> <li ><a href="/releases">Releases</a></li> <li><a target="_blank" href="https://github.com/ebean-orm/ebean"> </a></li> </ul> </div> <div class="mobile-nav"> <ul class="nav navbar-nav pull-right nav-btn-rhs"> <li ><a href="/"> Home</a></li> <li class="active"><a href="/docs">Docs</a></li> <li ><a href="/docs/getting-started">Get Started</a></li> <li ><a href="/support">Help</a></li> <li ><a href="/videos">Videos</a></li> <li ><a target="_blank" href="/apidoc/13">ApiDocs</a></li> <li ><a href="/releases">Releases</a></li> <li><a target="_blank" href="https://github.com/ebean-orm/ebean"> </a></li> </ul> </div> </div> </div> </div> <div id="main"> <div class="jumbotron mini"> <div class="container"> <h1><a href="/docs/">Documentation</a> / Persist</h1> </div> </div> <div class="container doc-index bs-docs-container"> <div class="row"> <div class="col-md-9" role="main"> <form action="https://www.google.com/search" method="get"> <div class="page-inline-search" style="margin-bottom:8px;"> <div class="input-group"> <input name="q" id="searchinput" type="text" class="form-control" placeholder="Search... (press 's' to focus)" data-placeholder-focus="Search... (use '↑', '↓' and '⏎' to select results)" data-placeholder-blur="Search... (press 's' to focus)" autocomplete="off"> <input type="hidden" name="as_sitesearch" value="ebean.io"> <div class="input-group-btn"> <button class="btn btn-default form-control" type="submit"></button> </div> </div> <div class="search-results-inline-container" style="display: none;"> <ul id="search-results-container" class="search-results"><li class=" active"><a href="/docs" title="Docs">Docs Documentation </a></li><li class="">And 101 more...</li></ul> </div> </div> </form> <h2 id="saves">Save</h2> Save will either insert or update the bean depending on its state. <div class="syntax java"><div class="highlight"><pre>Order order = new Order(); order.setOrderDate(new Date()); ... // insert the order order.save(); </pre></div> </div> If the bean was fetched it will be updated... <div class="syntax java"><div class="highlight"><pre>Order order = DB.find(Order.class, 42); order.setStatus(SHIPPED); ... // update the order order.save(); </pre></div> </div> Save and Delete will CASCADE based on the CascadeType specificed on the associated @OneToMany, @OneToOne etc annotation. By default save and delete will not cascade so you need to specify a cascade type (such as the one on details below) for save() or delete() to cascade. <div class="syntax java"><div class="highlight"><pre>... @Entity @Table(name="orders") public class Order { ... @ManyToOne // no cascading Customer customer; @OneToMany(cascade=CascadeType.ALL) // save and delete cascaded List<OrderDetail> details; ... </pre></div> </div> Note the @OneToMany(cascade=CascadeType.ALL) on the details property. This means save() and delete() will both casade from order to its order details. <div class="syntax java"><div class="highlight"><pre>... // save the order ... will cascade also saving the order details DB.save(order); </pre></div> </div> <h2 id="deletes">Delete</h2> Delete is very similar to save. Just call DB.delete(); <div class="syntax java"><div class="highlight"><pre>... Order order = DB.find(Order.class, 12); // delete the order // ... this will cascade also deleting the order details // ... with either CascadeType.ALL or CascadeType.REMOVE DB.delete(order); </pre></div> </div> <h2 id="cascading">Cascading</h2> The mapping annotations @ManyToOne, @OneToMany, @OneToOne and @ManyToMany provide a cascade attribute which is used to control whether saves and deletes are cascaded. The default is to not cascade a save or delete (as per JPA spec). The example below shows the Order entity bean with its mapping annotations. If you save an Order the details will be saved as well but the associated customer will not be saved as there is no cascade atttribute and the default is to not cascade. <div class="syntax java"><div class="highlight"><pre>... @Entity @Table(name="orders") public class Order { ... @ManyToOne // no cascading Customer customer; @OneToMany(cascade=CascadeType.ALL) // save and delete cascaded List<OrderDetail> details; </pre></div> </div> <h2 id="bulkupdate">Bulk updates</h2> Update provides a way on issuing a insert, update or delete statement. This is useful for updating or deleting multiple rows (or a single row) with a single statement (often described as a "bulk" update). This is also useful if you want to perform an update or delete without having to execute a query first. This is a typical approach for performing an update in a stateless web application. The statement can be provided in as raw DML with the table names and column names or in a 'logical' form where entity name is used in place of the table name and property names are used in place of column names. <div class="syntax java"><div class="highlight"><pre>// orm bulk delete use bean name and bean properties DB.createUpdate(OrderDetail.class, "delete from orderDetail").execute(); // sql bulk update uses table and column names DB.sqlUpdate("delete from country").execute(); </pre></div> </div>` <h2 id="bulksqlupdate">Bulk SQL updates</h2> In similar fashion to <a href="#sqlquery">SqlQuery</a> you can specify a SQL INSERT, UPDATE or DELETE statement with named or positioned parameters. <div class="syntax java"><div class="highlight"><pre>String dml = "update b_bug set title=:title where id = :id"; int rows = DB.sqlUpdate(dml) .setParameter("title", "Updated Again") .setParameter("id", 1) .execute(); </pre></div> </div> <h2 id="callablesql">CallableSql</h2> CallableSql provides a way to call a database stored procedure. <div class="syntax java"><div class="highlight"><pre>String sql = "{call sp_order_mod(?,?)}"; CallableSql cs = DB.createCallableSql(sql); cs.setParameter(1, "turbo"); cs.registerOut(2, Types.INTEGER); DB.execute(cs); // read the out parameter Integer returnValue = (Integer) cs.getObject(2); </pre></div> </div> You can extend CallableSql and you can also get the java.sql.Connection from a Transaction and use raw JDBC API to call a stored procedure. <h2 id="rawjdbc">Raw JDBC</h2> You can't always predict when your application requirements can't be met with the features in Ebean. It is nice to know you can easily use raw JDBC if and when you need to. The java.sql.Connection object can be returned from a transaction, and with that you can perform any raw JDBC calls you like. This may be useful for Savepoints, advanced Clob/Blob use or advanced stored procedure calls (if CallableSql doesn't do the business for you). <div class="syntax java"><div class="highlight"><pre>try (Transaction transaction = DB.beginTransaction()) { Connection connection = transaction.getConnection(); // use raw JDBC ... transaction.commit(); } </pre></div> </div> <h2 id="batch_processing">JDBC Batch</h2> Ebean provides support for JDBC batch processing. Batch processing groups related SQL statements into a batch and submits them with one call to the database. Batch settings can be configured through application.properties or through DatabaseConfig, and can be overridden per transaction. You can set the batch mode for the entity being saved through setBatch() and for its child collections through setCascadeBatch(). ...(under construction)... need to provide better guidance on how to determine batch mode, child batch mode, and batch size <div class="syntax java"><div class="highlight"><pre>Transaction transaction = database.beginTransaction(); try { // turn of cascade persist transaction.setCascadePersist(false); // control the jdbc batch mode and size // transaction.setBatchMode(true); // equivalent to transaction.setBatch(PersistBatch.ALL); // transaction.setBatchMode(false); // equivalent to transaction.setBatch(PersistBatch.NONE); transaction.setBatch(PersistBatch.ALL); // PersistBatch: NONE, INSERT, ALL transaction.setCascadeBatch(PersistBatch.INSERT); // PersistBatch: NONE, INSERT, ALL transaction.setBatchSize(30); // for a large batch insert if you want to skip // getting the generated keys transaction.setGetGeneratedKeys(false); // for batch processing via raw SQL you can inform // Ebean what tables were modified so that it can // clear the appropriate L2 caches String tableName = "customer"; boolean inserts = true; boolean upates = true; boolean deletes = false; transaction.addModification(tableName, inserts, updates, deletes); ... } finally { transaction.end(); } </pre></div> </div> example using @Transactional <div class="syntax java"><div class="highlight"><pre>@Transactional(batchSize = 50) public void goodStuff() { order.save() customer.save() } </pre></div> </div> <div class="next pull-right"> <a href="/docs/transactions" class="btn btn-info">Next: Transactions</a> </div> </div> <div class="col-md-3" role="complementary"> <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm"> <ul class="nav bs-docs-sidenav"> <li class="active"> <a href="/docs/persist">Persist</a> <ul class="nav"> <li><a href="#saves">Save</a></li> <li><a href="#deletes">Delete</a></li> <li><a href="#cascading">Cascade</a></li> <li><a href="#bulkupdate">Bulk updates</a></li> <li><a href="#bulksqlupdate">Bulk SQL updates</a></li> <li><a href="#callablesql">CallableSql</a></li> <li><a href="#rawjdbc">Raw JDBC</a></li> <li><a href="#batch_processing">JDBC Batch</a></li> </ul> </li> </ul> </nav> </div> </div> </div> </div> </div> <footer id="footer"> <div class="doc-footer"> <ul class="doc-footer-links"> <li><a href="/">Ebean ORM</a></li> <li> | </li> <li><a href="http://avaje-metric.github.io">Metrics</a></li> </ul> </div> </footer> <script type="text/javascript"> var categoryNames = {}; </script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <script src="/js/bootstrap.min.js"></script> <script src="/js/jquery.easing.min.js"></script> <script src="/js/jquery.storageapi.min.js"></script> <script src="/js/ebean-site.js"></script> <script src="/js/extra.js"></script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-75181644-1', 'auto'); ga('send', 'pageview'); </script> </body> </html>