CINXE.COM

<!doctype html> <html lang="en"> <head> <title>Best practice | Docs | Ebean</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="shortcut icon" href="/images/favicon.ico"> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto|Source+Sans+Pro|Ubuntu&display=swap"> <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/reset3.css"> <link rel="stylesheet" href="/css/site3.css"> <link rel="stylesheet" href="/css/pygments3.css"> </head> <body> <div id="main"> <div id="banner"> <header> <nav id="top"> <h1 id="breadcrumb"> <a class="nav-logo" href="/"><img src="/images/logo-200.png" height="35"></a>  <a href="/docs">Documentation</a> / Best Practice </h1> <ul> <li><a onclick="toggleTheme();" title="switch dark light theme"></a></li> </ul> </nav> </header> </div> <div class="grid grid-docs"> <aside> <nav class="side"> <ul> <li class="nav0 "> <a href="/docs/getting-started">Getting started</a> </li> <li class="nav0 "> <a href="/docs/intro">Introduction</a> </li> <li class="nav0 active"> <a class="active" href="/docs">Documentation</a> <ul> <li class="nav1 active"> <a class="active" href="/docs/best-practice">Best practice</a> <ul class="nav nav-scroll"> <li > <a href="#identity">Identity</a> </li> <li > <a href="#kotlin-data-class">Kotlin data classes</a> </li> <li > <a href="#list">List vs Set</a> </li> <li > <a href="#join-column">@JoinColumn</a> </li> <li > <a href="#column-name">@Column(name=...)</a> </li> <li > <a href="#mapped-superclass">@MappedSuperclass</a> </li> <li > <a href="#ddl-generation">DDL generation</a> </li> <li > <a href="#not-null">NOT NULL</a> </li> <li > <a href="#use-constructors">Use Constructors</a> </li> <li > <a href="#getters-setters">Getters Setters</a> </li> <li > <a href="#builder-pattern">Builder pattern</a> </li> <li > <a href="#bulk-update">Bulk update queries</a> </li> <li > <a href="#reference-beans">Reference beans</a> </li> <li > <a href="#naming-entities">Naming entity beans</a> </li> <li > <a href="#database-design-mindset">Database design mindset</a> </li> </ul> </li> <li class="nav1 "> <a href="/docs/query">Query</a> </li> <li class="nav1 "> <a href="/docs/persist">Persist</a> </li> <li class="nav1 "> <a href="/docs/transactions">Transactions</a> </li> <li class="nav1 "> <a href="/docs/mapping">Mapping</a> </li> <li class="nav1 "> <a href="/docs/ddl-generation">DDL & Migrations</a> </li> <li class="nav1 "> <a href="/docs/logging">Logging</a> </li> <li class="nav1 "> <a href="/docs/testing">Testing</a> </li> <li class="nav1 "> <a href="/docs/read-replicas">Read Replicas</a> </li> <li class="nav1 "> <a href="/docs/database">Database platforms</a> </li> <li class="nav1 "> <a href="/docs/multi-database">Multiple databases</a> </li> <li class="nav1 "> <a href="/docs/kotlin">Kotlin</a> </li> <li><a href="/docs/tuning">Tuning</a></li> <li class="nav1 "> <a href="/docs/features">Features</a> </li> </ul> </li> <li class="nav0 "> <a href="/support">Getting help</a> </li> <li class="nav0 "> <a target="_blank" href="/apidoc/13">API Javadoc</a> </li> <li class="nav0 "> <a href="/videos">Videos</a> </li> <li class="nav0 "> <a href="/docs/upgrading">Upgrading</a> </li> <li class="nav0 "> <a href="/releases">Releases</a> </li> </ul> </nav> </aside> <article> <form action="https://www.google.com/search" method="get" class="inline-form"> <input type="hidden" name="as_sitesearch" value="ebean.io"> <div id="page-search"> <div class="input-group"> <input class="frm" name="q" id="searchinput" type="text" 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"> <div class="input-group-btn"> <button class="frm" type="submit"></button> </div> </div> <div id="page-search-results" 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="identity">Identity - equals/hashCode</h2> Do not implement <code>equals()</code> and <code>hashCode()</code> on <code>@Entity</code> beans (but instead leave that to Ebean enhancement). Ebean will enhance entity beans with an optimal implementation of <code>equals()</code> and <code>hashCode()</code> and we should not try and do better and instead just leave it to Ebean. <h2 id="toString">toString() - avoid getters</h2> Avoid using getter methods in <code>toString()</code>. We want to avoid invoking any accidental lazy loading when using the debugger. That is, using the debugger and inspecting entity beans in the debugger will implicitly call toString() methods on entity beans. We don't want to have different behaviour when stepping through with a debugger. Ebean does not enhance toString() methods but if the toString() implementation uses getter methods then those methods could invoke lazy loading and we generally want to avoid that. <h2 id="kotlin-data-class">Kotlin data classes</h2> Do not use Kotlin data classes for <code>@Entity</code> beans as the equals/hashCode implementation is not desirable. Instead use normal Kotlin classes for entity beans. Do use Kotlin data classes for <code>@EmbeddedId</code> beans. <h2 id="list">Prefer List over Set</h2> For <code>@OneToMany</code> and <code>@ManyToMany</code> collections prefer the use of List over Set. The use of Set will implicitly calls <code>equals()</code> and <code>hashCode()</code> and generally it's preferable to not call those methods until entity beans have Id values. <h2 id="join-column">@JoinColumn</h2> Don't use <code>@JoinColumn</code> or <code>@JoinTable</code> unless we have to. The naming convention will provide good names of foreign key columns and join tables so only use these annotations when there are existing foreign keys etc and these do not match the naming convention. <h2 id="column-name">@Column(name=...)</h2> Do not use <code>@Column(name=...)</code> to map database column names but instead use the naming convention. Only specify explicit <code>@Column(name=...)</code> when it for some reason does not match the naming convention used. <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre>@Column(name="when_activated") // This is redundant, just adds "annotation noise" OffsetDateTime whenActivated; </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre>@Column(name="when_activated") // This is redundant, just adds "annotation noise" val whenActivated: OffsetDateTime? = null </pre></div> </div> </div> <h2 id="mapped-superclass">Use @MappedSuperclass</h2> Make use of <code>@MappedSuperclass</code> to hold common properties. A common mapped superclass might have: <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre>... @MappedSuperclass public abstract class BaseDomain extends Model { @Id long id; @Version long version; @WhenCreated Instant whenCreated; @WhenModified Instant whenModified; // getters and setters ... } </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre>... @MappedSuperclass open class BaseDomain : Model() { @Id var id: Long = 0 @Version var version: Long = 0 @WhenModified lateinit var whenModified: Instant @WhenCreated lateinit var whenCreated: Instant } </pre></div> </div> </div> <h2 id="ddl-generation">DDL Generation</h2> Use Ebean to generate all DDL including DB migrations - aka prefer forward generation of DDL. This keeps all the DDL "in sync" for testing and db migrations and makes it easier to support multiple database platforms or migrate between database platforms (e.g. MySql to Postgres). If we hand craft DDL we increase the chance of variation between the model and actual database schema and can make testing harder. <h2 id="not-null">Promote use of NOT NULL constraint</h2> Make as much of the model NOT NULL as we can - prefer DB columns to have the NOT NULL constraint if possible. Reduce the amount of 3 valued logic required - have a "tighter" model. <h2 id="use-constructors">Use Constructors</h2> Use constructors to help enforce non nullable properties (Kotlin) or promote non nullable properties (Java). For example, if a Customer should always have a name define a constructor that takes the name property. <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre>@Entity public class Customer extends BaseModel { @NotNull @Length(100) private String name; ... public Customer(String name) { this.name = name; } // getters and setters } </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre>... @Entity class Customer(name : String) : BaseModel() { @Length(100) var name: String = name // Ebean knows this is Kotlin non-nullable type } </pre></div> </div> </div> Now when we create a new Customer we must create it with a name. For Kotlin we should make name a <code>non-nullable type</code>. Ebean will treat Kotlin non-nullable types as NOT NULL from a database perspective as well giving us a tighter model. <h2 id="getters-setters">Getters Setters</h2> Ebean does NOT need getters and setters as it adds it's own accessor methods via enhancement. We can omit getter and setter methods as desired. We can have setter methods follow a fluid style returning this if desired. <h2 id="builder-pattern">Builder pattern</h2> If we want to use the Builder pattern rather than generate an additional builder class for a given entity (that then duplicates all the properties of the entity making things harder to maintain) a simpler approach is to have the "setter" methods on the entity bean use the fluid style and return this. <div class="syntax java"><div class="highlight"><pre>@Entity public class Customer extends BaseModel { @NotNull @Length(100) private String name; private String notes; private int level; ... public Customer(String name) { this.name = name; } // accessors public Customer setNotes(String notes) { // fluid style this.notes = notes; return this; } public Customer setLevel(int level) { // fluid style this.level = level; return this; } ... } // using fluid style Customer customer = new Customer("Roberto") .setNotes("An example") .setLevel(42); </pre></div> </div> <h2 id="bulk-update">Bulk update queries</h2> Prefer the use of <a href="/docs/query/update">bulk update</a> and <a href="/docs/query/delete">delete</a> statements where appropriate. Avoid fetching beans just to iterate and delete them or iterate and update them all in the same way. <h2 id="reference-beans">Reference beans</h2> When we have the id value, use a reference bean rather than execute a query to find by id - unless we really want to query the database of course. That is, for inserts and updates when we have the <code>@Id</code> value we can use reference bean for the foreign key value> rather than execute an extra query against the database. <h4>Do NOT do this - as it executes an extra database query</h4> <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre>Order order = new Order() order.setCustomer(database.find(Customer.class, 42)); // extra db query for customer ... database.save(order); </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre>val order = Order() order.setCustomer(database.find(Customer.class, 42)); ... database.save(order) </pre></div> </div> </div> <h4>Do THIS - use reference bean instead</h4> <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre>Order order = new Order() order.setCustomer(database.getReference(Customer.class, 42)); // no extra db query ... database.save(order); </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre>val order = Order() order.setCustomer(database.getReference(Customer.class, 42)); ... database.save(order) </pre></div> </div> </div> <h2 id="naming-entities">Naming entity beans</h2> As a "Rob Preference" rather than strictly a "best practice" I have found that I often prefer to give entity beans a <code>D</code> prefix (Hungarian notation) like: <ul> <li>DCustomer instead of Customer</li> <li>DProduct instead of Product</li> <li>DOrder instead of Order </li> </ul> Entity beans are generally considered internal and not publicly exposed. Entity bean names often match/clash with types/names that we want to use in the public API and we frequently want to map to/from the publicly exposed API types and our internal entity beans. Giving the entity beans a D prefix (D for Domain) generally: <ul> <li>Avoids name clashes with public API types</li> <li>Avoids needing full package qualified types in mappers</li> <li>Can be more obvious when code is using internal entity beans (persistence domain objects)</li> </ul> Generally entity beans are in a <code>domain</code> package. The beans being generally related to each other via @OneToMany, @ManyToOne etc means that I prefer to keep them together as a holistic model. <h2 id="database-design-mindset">Database design mindset</h2> When we are building / modelling entity beans I strongly subscribe to being in a "database design mindset". What this means is that we are primarily focused on normalisation and good database design principals with a resulting database design that we are happy will last for the long term and be good regardless of any ORM or persistence layer we are using to interact with the database. Design for the long term. <nav class="next"> <a href="https://github.com/ebean-orm/website-source/blob/master/docs/best-practice/index.html"> Edit Page</a> <a href="/docs/query" class="btn btn-info">Next: Queries</a> </nav> </article> </div> </div> <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script> <script src="/js/site3.js"></script> <script src="/js/search3.js"></script> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-75181644-1"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-75181644-1'); </script> </body> </html>