Writing persistence-capable classes

Working with fine-grained and rich domain models is a major Hibernate objective. This is a reason we work with POJOs. In general, using fine-grained objects means more classes than tables.

A persistence-capable plain-old Java class declares attributes, which represent state, and business methods, which define behavior. Some attributes represent associations to other persistence-capable classes.

A POJO implementation of the User entity of the domain model is shown in the following listing. Let’s walk through the code.

public class User implements Serializable { protected String username;

public User() { }

public String getUsername() { return username;

}

public void setUsername(String username) { this.username = username;

}

public BigDecimal calcShippingCosts(Address fromLocation) {

// Empty implementation of business method

return null; }

// ...

}

Listing 3.1 POJO implementation of the User class

PATH: /model/src/main/java/org/jpwh/model/simple/User.java POJO

POJO is the acronym for Plain Old Java Objects. Martin Fowler, Rebecca Parsons, and Josh Mackenzie coined this term in 2000.

JPA doesn’t require that persistent classes implement java.io.Serializable. But when instances are stored in an HttpSession or passed by value using RMI, serializa- tion is necessary. Although this might not occur in your application, the class will be serializable without any additional work, and there are no downsides to declaring that. (We aren’t going to declare it on every example, assuming that you know when it will be necessary.)

The class can be abstract and, if needed, extend a non-persistent class or imple- ment an interface. It must be a top-level class, not nested within another class. The persistence-capable class and any of its methods can’t be final (a requirement of the JPA specification).

Unlike the JavaBeans specification, which requires no specific constructor, Hiber- nate (and JPA) require a constructor with no arguments for every persistent class. Alternatively, you might not write a constructor at all; Hibernate will then use the Java default constructor. Hibernate calls classes using the Java reflection API on such a no- argument constructor to create instances. The constructor may not be public, but it has to be at least package-visible if Hibernate will use runtime-generated proxies for performance optimization. Also, consider the requirements of other specifications: the EJB standard requires public visibility on session bean constructors, just like the JavaServer Faces (JSF) specification requires for its managed beans. There are other situations when you’d want a public constructor to create an “empty” state: for exam- ple, query-by-example building.

The properties of the POJO implement the attributes of the business entities—for example, the username of User. You usually implement properties as private or pro- tected member fields, together with public or protected property accessor methods: for each field a method for retrieving its value and a method for setting the value. These methods are known as the getter and setter, respectively. The example POJO in listing 3.1 declares getter and setter methods for the username property.

The JavaBean specification defines the guidelines for naming accessor methods; this allows generic tools like Hibernate to easily discover and manipulate property val- ues. A getter method name begins with get, followed by the name of the property (the first letter in uppercase); a setter method name begins with set and similarly is followed by the name of the property. You may begin getter methods for Boolean properties with is instead of get.

Hibernate doesn’t require accessor methods. You can choose how the state of an instance of your persistent classes should be persisted. Hibernate will either directly access fields or call accessor methods. Your class design isn’t disturbed much by these considerations. You can make some accessor methods non-public or completely remove them—then configure Hibernate to rely on field access for these properties.

Although trivial accessor methods are common, one of the reasons we like to use Java- Beans-style accessor methods is that they provide encapsulation: you can change the hidden internal implementation of an attribute without any changes to the public interface. If you configure Hibernate to access attributes through methods, you abstract the internal data structure of the class—the instance variables—from the design of the database.

For example, if your database stores the name of a user as a single NAME column, but your User class has firstname and lastname fields, you can add the following per- sistent name property to the class.

public class User {

protected String firstname; protected String lastname; public String getName() {

return firstname + ' ' + lastname; }

public void setName(String name) {

StringTokenizer t = new StringTokenizer(name); firstname = t.nextToken();

lastname = t.nextToken(); }

}

Listing 3.2 POJO implementation of the User class with logic in accessor methods

Should property fields and accessor methods be private, protected, or package visible?

Typically, you want to discourage direct access to the internal state of your class, so you don’t make attribute fields public. If you make fields or methods private, you’re effectively declaring that nobody should ever access them; only you’re allowed to do that (or a service like Hibernate). This is a definitive statement. There are often good reasons for someone to access your “private” internals—usually to fix one of your bugs—and you only make people angry if they have to fall back to reflection access in an emergency. Instead, you might assume or know that the engineer who comes after you has access to your code and knows what they’re doing.

The protected visibility then is a more reasonable default. You’re forbidding direct public access, indicating that this particular member detail is internal, but allowing access by subclasses if need be. You trust the engineer who creates the subclass. Package visibility is rude: you’re forcing someone to create code in the same package to access member fields and methods; this is extra work for no good reason. Most important, these recommendations for visibility are relevant for environments without security policies and a runtime SecurityManager. If you have to keep your internal code private, make it private.

Later, you’ll see that a custom type converter in the persistence service is a better way to handle many of these kinds of situations. It helps to have several options.

Another issue to consider is dirty checking. Hibernate automatically detects state changes in order to synchronize the updated state with the database. It’s usually safe to return a different instance from the getter method than the instance passed by Hibernate to the setter. Hibernate compares them by value—not by object identity— to determine whether the attribute’s persistent state needs to be updated. For exam- ple, the following getter method doesn’t result in unnecessary SQL UPDATEs:

public String getFirstname() { return new String(firstname); }

There is one important exception to this: collections are compared by identity! For a property mapped as a persistent collection, you should return exactly the same collec- tion instance from the getter method that Hibernate passed to the setter method. If you don’t, Hibernate will update the database, even if no update is necessary, every time the state held in memory is synchronized with the database. You should usually avoid this kind of code in accessor methods:

protected String[] names = new String[0];

public void setNames(List<String> names) {

this.names = names.toArray(new String[names.size()]); }

public List<String> getNames() { return Arrays.asList(names); }

Of course, this won’t be a problem if Hibernate is accessing the names field directly, ignoring your getter and setter methods.

How does Hibernate handle exceptions when your accessor methods throw them? If Hibernate uses accessor methods when loading and storing instances and a Run- timeException (unchecked) is thrown, the current transaction is rolled back, and the exception is yours to handle in the code that called the Java Persistence (or Hibernate native) API. If you throw a checked application exception, Hibernate wraps the excep- tion into a RuntimeException.

The example in listing 3.2 also defines a business method that calculates the cost of shipping an item to a particular user (we left out the implementation of this method).

Next, we’ll focus on the relationships between entities and associations between persistent classes.