Naming Conventions for Java Persistence

Status: In Early Access
Sean BrydonSmitha Kangath

Problem Description

Reading other people's code can be difficult, especially on large projects. Developer may have their own styles and may make their own choices for naming classes, objects, resources, etc. This makes it harder for others to read their code and be enabled to use or maintain it. Moreover, it may lead to frustrations among developer on the same team by arguing needlessly over which choices are better.

Solution

Naming conventions make code more understandable by making it easier to read. They can also give information about the intended function of an identifier. This document describes the naming conventions that the Java BluePrints team uses for its sample applications. These conventions pertain to the various components and modules in the Java  EE 5 platform. By applying these conventions, your modules and components will be easier to identify and organize, thus enhancing their maintenance and promoting better coordination on large projects.

All conventions described here are compliant with the Code Conventions for the Java Programming Language.

One thing to note is that for annotations, many things have defaults. For example, when mapping an entity object to a database table, the default is that the table name is the same as the object name. So if you had an entity bean called Customer, you do not need to use the name attribute of the @Table(name=CUSTOMER) annotation to map it to the customer table in the database.  So naming conventions need to take into account the fact that annotations use many default names to make coding simpler. This means there is some implicit naming that you need to be aware of. We recommend following all the defaults for naming conventions of annotation as it allows you to write less code for annotations and instead just rely on defaults.

Another thing to be aware of is that there are many reserved words in SQL and in the Java Query language. You need to be cautious when using those reserved words.

Now lets look at some identifier types and their associated naming conventions. We will start by trying to follow the conventions used for samples in the specification for Java Persistence (JSR 220).

Identifier Type

Rules for Naming

Examples and Reference

Entities (annotation is @Entity) Just use the name of the object.
Do not append a "Bean" or "POJO" suffix.
Follows naming conventions for classes

For example, Address.java would be the name of an address entity. 
EntityManagerFactory (annotation is @PersitenceUnit) emf is the name if there is only one entity manager factory

If there is more than one entity manager factory, the naming rule is to append "Emf" to the name like <persistence unit name>Emf 

For example,
public EntityManagerFactory emf;

For more than one,
public EntityManagerFactory pestoreEmf;
public EntityManagerFactory inventoryWarehouseEmf;
EntityManager  (annotation is @PersistenceContext) em is the name if there is only one entity manager

If there is more than one entity manager, append "Em" to the name. Often an entity manager is closely related to a persistence unit, so a common convention is <persistence unit name>Em

For example,
private EntityManager em;


When more than one,
private EntityManager pestoreEm;
private EntityManager inventoryWarehouseEm;
UserTransaction utx is the name to be used

For example,
public UserTransaction utx;
Listeners (annotation is @EntityListeners) Rule is to append "Listener" to the entity name
For example,
OrderListener
Persistence Unit
Should be based on the resource name. The resource name should be suffixed with "Pu". The resource name should be written in mixed case with the first letter of each  word capitalized
<resource-name>Pu
For example, in the persistence.xml file

<persistence>
    <persistence-unit name="PetstorePu">
        <jta-data-source>jdbc/PetstoreDB</jta-data-source>
    </persistence-unit>
</persistence>

DataSource name

Should be based on the resource name. The resource name should be written in mixed case with the first letter of each word capitalized
jdbc/<resource-name>


Examples:
jdbc/PetStoreDB
O/R mapping file

This file is used when wanting to override O/R mapping annotations in the source code.
Use the default name orm.xml when only one mapping file is needed per META_INF/persistence.xml.

When more than one mapping file is needed , use <resource-name>Orm.xml

For example,
<persistence>
    <persistence-unit name="PetstorePu">
        <jta-data-source>jdbc/PetstoreDB</jta-data-source>
        <mapping-file>orm.xml<mapping-file>
          ...
    </persistence-unit>
</persistence>

<persistence>
    <persistence-unit name="InventoryWarehousePu">
        <jta-data-source>jdbc/OrdersDB</jta-data-source>
        <mapping-file>orderOrm.xml<mapping-file>
          ...
    </persistence-unit>
</persistence>

Named queries and finder methods
In mixed case with the first letter lowercase, with the first letter of each internal word capitalized.

Named queries must be scoped. We use the class name as the scope.
For example, "getItemsPerProductCategory" in this named query
@NamedQuery(
name="getItemsPerProductCategory",
query="SELECT i FROM Item i WHERE i.product.categoryId LIKE :categoryName"
)
public class MyEntity { ...

Then in a query that uses the named query, it would scope it and use it like this
Query query =
 em.createNamedQuery("MyEntity.getItemsPerProductCategory")
Named parameters In mixed case with the first letter lowercase, with the first letter of each internal word capitalized.
In the Java Query language you can specify named parameters that can be passed in to queries. These named parameters are also used by named queries.
For example, the parameter ":categoryName"
query =
 em.createQuery("
SELECT i FROM Item i WHERE i.product.categoryId LIKE :categoryName");
query = query.setParameter("
categoryName", "dogs");
Database

If your organization already has a convention for database naming, follow that. Otherwise, name  databases after the application and append DB.

<application-name>DB

For example: PetStoreDB

Database Naming Conventions and Java Naming Conventions

When naming entity objects, often the names of entities are similar to names of the associated database tables. But database naming conventions are somewhat different from Java naming conventions. For example, in databases, tables often are plural like CUSTOMERS table. Whereas in object naming conventions, the mapped objects often have singular names, like Customer. In this case, you would need to put the mapping information to CUSTOMERS in the entity annotation for the Customer entity. As this is a common practice, we will consider this an alternative convention, though it requires that each entity class use the table annotation to map the entity to the table, as for example with @Table(name=CUSTOMERS) annotation on the Customer entity.

In Java Persistence, default mappings are provided. For example, the default is that a table name has same name as the object name. So Customer entity would map to the CUSTOMER table by default, and it is not necessary to use an annotation. It is very handy to name objects and the associated table with the same name and just use the default mappings. Since it is the default naming in Java Persistence and is an ease-of-use feature, we will also use this convention.

References

Here are some references

© Sun Microsystems 2006. All of the material in The Java BluePrints Solutions Catalog is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.