/**
   This class holds information about any data...
   @author Your name
   @version 2.0
   @hibernate.class table="`Anys`" lazy="false" batch-size="10"
   @base.modified $Date: 2007-08-17 09:18:29 +0200 (Fri, 17 Aug 2007) $
*/
public class AnyData
   extends CommonData
{
   // Rest of class code...
}

The class declaration must contain a @hibernate.class Javadoc entry where Hibernate can find the name of the table where items of this type are stored. The table name should generally be the same as the class name, without the ending Data and in a plural form. For example UserData --> Users. The back-ticks (`) around the table name tells Hibernate to enclose the name in whatever the actual database manager uses for such things (back-ticks in MySQL, quotes for an ANSI-compatible database).

See also:

Properties such as strings, integers, dates, etc. are mapped with the @hibernate.property Javadoc tag. The main purpose is to define the database column name. The column names should generally be the same as the get/set method name without the get/set prefix, and with upper-case letters converted to lower-case and an underscore inserted. Examples:

The back-ticks (`) around the column name tells Hibernate to enclose the name in whatever the actual database manager uses for such things (back-ticks in MySQL, quotes for an ANSI-compatible database).

String properties

public static int long MAX_STRINGPROPERTY_LENGTH = 255;
private String stringProperty;
/**
   Get the string property.
   @hibernate.property column="`string_property`" type="string" 
      length="255" not-null="true"
*/
public String getStringProperty()
{
   return stringProperty;
}
public void setStringProperty(String stringProperty)
{
   this.stringProperty = stringProperty;
}

Do not use a greater value than 255 for the length attribute. Some databases has that as the maximum length for character columns (ie. MySQL). If you need to store longer texts use type="text" instead. You can then skip the length attribute. Most databases will allow up to 65535 characters or more in a text field. Do not forget to specify the not-null attribute.

You should also define a public constant MAX_STRINGPROPERTY_LENGTH containing the maximum allowed length of the string.

Numerical properties

private int intProperty;
/**
   Get the int property.
   @hibernate.property column="`int_property`" type="int" not-null="true"
*/
public int getIntProperty()
{
   return intProperty;
}
public void setIntProperty(int intProperty)
{
   this.intProperty = intProperty;
}

It is also possible to use Integer, Long or Float objects instead of int, long and float. We have only used it if null values have some meaning.

Boolean properties

private boolean booleanProperty;
/**
   Get the boolean property.
   @hibernate.property column="`boolean_property`" 
      type="boolean" not-null="true"
*/
public boolean isBooleanProperty()
{
   return booleanProperty;
}
public void setBooleanProperty(boolean booleanProperty)
{
   this.booleanProperty = booleanProperty;
}

It is also possible to use a Boolean object instead of boolean. It is only required if you absolutely need null values to handle special cases.

Date values

private Date dateProperty;
/**
   Get the date property. Null is allowed.
   @hibernate.property column="`date_property`" type="date" not-null="false"
*/
public Date getDateProperty()
{
   return dateProperty;
}
public void setDateProperty(Date dateProperty)
{
   this.dateProperty = dateProperty;
}

Hibernate defines several other date and time types. We have decided to use the type="date" type when we are only interested in the date and the type="timestamp" when we are interested in both the date and time.

See also:

private OtherData other;
/**
   Get the other object.
   @hibernate.many-to-one column="`other_id`" not-null="true" outer-join="false"
*/
public OtherData getOther()
{
   return other;
}
public void setOther(OtherData other)
{
   this.other = other;
}

We create a many-to-one mapping with the @hibernate.many-to-one tag. The most important attribute is the column attribute which specifies the name of the database column to use for the id of the other item. The back-ticks (`) around the column name tells Hibernate to enclose the name in whatever the actual database manager uses for such things (back-ticks in MySQL, quotes for an ANSI-compatible database).

We also recommend that the not-null attribute is specified. Hibernate will not check for null values, but it will generate table columns that allow or disallow null values. See it as en extra safety feature while debugging. It is also used to determine if Hibernate uses LEFT JOIN or INNER JOIN in SQL statements.

The outer-join attribute is important and affects how the cache and proxies are used. It can take three values: auto, true or false. If the value is true Hibernate will always use a join to load the linked object in a single select statement, overriding the cache and proxy settings. This value should only be used if the class being linked has disabled both proxies and the second-level cache, or if it is a link between a child and parent in a parent-child relationship. A false value is best when we expect the associated object to be in the second-level cache or proxying is enabled. This is probably the most common case. The auto setting uses a join if proxying is disabled otherwise it uses a proxy. Since we always know if proxying is enabled or not, this setting is not very useful. See Table 31.1, “Choosing cache and proxy settings” for the recommended settings.

See also:

There are many variants of mapping many-to-many or one-to-many, and it is not possible to give examples of all of them. In the code these mappings are represented by Set:s, Map:s, List:s, or some other collection object. The most important thing to remember is that (in our application) the collections are only used to maintain the links between objects. They are not used for returning objects to client applications, as is the case with the many-to-one mapping.

For example, if we want to find all members of a group we do not use the GroupData.getUsers() method, instead we will execute a database query to retrieve them. The reason for this design is that the logged in user may not have access to all users and we must add a permission checking filter before returning the user objects to the client application. Using a query will also allow client applications to specify sorting and filtering options for the users that are returned.

// RoleData.java
private Set<UserData> users;
/**
   Many-to-many from roles to users
   @hibernate.set table="`UserRoles`" lazy="true"
   @hibernate.collection-key column="`role_id`"
   @hibernate.collection-many-to-many column="`user_id`" 
      class="net.sf.basedb.core.data.UserData"
*/
public Set<UserData> getUsers()
{
   if (users == null) users = new HashSet<UserData>();
   return users;
}
void setUsers(Set<UserData> users)
{
   this.users = users;
}

As you can see this mapping is a lot more complicated than what we have seen before. The most important thing is the lazy attribute. It tells Hibernate to delay the loading of the related objects until the set is accessed. If the value is false or missing, Hibernate will load all objects immediately. There is almost never a good reason to specify something other than lazy="true".

Another important thing to remember is that the get method must always return the same object that Hibernate passed to the set method. Otherwise, Hibernate will not be able to detect changes made to the collection and as a result will have to delete and then recreate all links. To ensure that the collection object is not changed we have made the setUsers() method package private, and the getUsers() will create a new HashSet for us only if Hibernate didn't pass one in the first place.

Let's also have a look at the reverse mapping:

// UserData.java
private Set<RoleData> roles;
/**
   Many-to-many from users to roles
   @hibernate.set table="`UserRoles`" lazy="true"
   @hibernate.collection-key column="`user_id`"
   @hibernate.collection-many-to-many column="`role_id`" 
      class="net.sf.basedb.core.data.RoleData"
*/
Set<RoleData> getRoles()
{
   return roles;
}
void setRoles(Set<RoleData> roles)
{
   this.roles = roles;
}

The only real difference here is that both the setter and the getter methods are package private. This is required because Hibernate will get confused if we modify both ends. Thus, we are forced to always add/remove users to/from the set in the GroupData object. The methods in the RoleData class are never used by us. Note that we do not have to check for null and create a new set since Hibernate will handle null values as an empty set.

So, why do we need the second collection at all? It is never accessed except by Hibernate, and since it is lazy it will always be "empty". The answer is that we want to use the relation in HQL statements. For example:

SELECT ... FROM GroupData grp WHERE grp.users ...
SELECT ... FROM UserData usr WHERE usr.groups ...

Without the inverse mapping, it would not have been possible to execute the second HQL statement. The inverse mapping is also important in parent-child relationships, where it is used to cascade delete the children if a parent is deleted.

Parent-child relationships

When one or more objects are tightly linked to some other object we talk about a parent-child relationship. This kind of relationship becomes important when we are about to delete a parent object. The children cannot exist without the parent so they must also be deleted. Luckily, Hibernate can do this for us if we specify a cascade="delete" option for the link. This example is a one-to-many link between client and help texts.

// ClientData.java
private Set<HelpData> helpTexts;
/**
   This is the inverse end.
   @see HelpData#getClient()
   @hibernate.set lazy="true" inverse="true" cascade="delete"
   @hibernate.collection-key column="`client_id`"
   @hibernate.collection-one-to-many class="net.sf.basedb.core.data.HelpData"
*/
Set<HelpData> getHelpTexts()
{
   return helpTexts;
}

void setHelpTexts(Set<HelpData> helpTexts)
{
   this.helpTexts = helpTexts;
}

// HelpData.java
private ClientData client;
/**
   Get the client for this help text.
   @hibernate.many-to-one column="`client_id`" not-null="true" 
      update="false" outer-join="false" unique-key="uniquehelp"
*/
public ClientData getClient()
{
   return client;
}
public void setClient(ClientData client)
{
   this.client = client;
}

This show both sides of the one-to-many mapping between parent and children. As you can see the @hibernate.set doesn't specify a table, since it is given by the class attribute of the @hibernate.collection-one-to-many tag.

In a one-to-many mapping, it is always the "one" side that handles the link so the "many" side should always be mapped with inverse="true".

Maps

Another type of many-to-many mapping uses a Map for the collection. This kind of mapping is needed when the association between two objects needs additional data to be kept as part of the association. For example, the permission (stored as an integer value) given to users that are members of a project. Note that you should use a Set for mapping the inverse end.

// ProjectData.java
private Map<UserData, Integer> users;
/**
   Many-to-many mapping between projects and users including permission values.
   @hibernate.map table="`UserProjects`" lazy="true"
   @hibernate.collection-key column="`project_id`"
   @hibernate.index-many-to-many column="`user_id`" 
      class="net.sf.basedb.core.data.UserData"
   @hibernate.collection-element column="`permission`" type="int" not-null="true"
*/
public Map<UserData, Integer> getUsers()
{
   if (users == null) users = new HashMap<UserData, Integer>();
   return users;
}
void setUsers(Map<UserData, Integer> users)
{
   this.users = users;
}

// UserData.java
private Set<ProjectData> projects;
/**
   This is the inverse end.
   @see ProjectData#getUsers()
   @hibernate.set table="`UserProjects`" lazy="true"
   @hibernate.collection-key column="`user_id`"
   @hibernate.collection-many-to-many column="`project_id`"
      class="net.sf.basedb.core.data.ProjectData"
*/
Set<ProjectData> getProjects()
{
   return projects;
}
void setProjects(Set<ProjectData> projects)
{
   this.projects = projects;
}

See also:

A one-to-one mapping can come in two different forms, depending on if both objects should have the same id or not. We start with the case were the objects can have different id:s and the link is done with an extra column in one of the tables. The example is from the mapping between hybridizations and arrayslides.

// HybridizationData.java
private ArraySlideData arrayslide;
/**
   Get the array slide
   @hibernate.many-to-one column="`arrayslide_id`" not-null="false" unique="true"
*/
public ArraySlideData getArraySlide()
{
   return arrayslide;
}
public void setArraySlide(ArraySlideData arrayslide)
{
   arrayslide.setHybridization(this);
   this.arrayslide = arrayslide;
}

// ArraySlideData.java
private HybridizationData hybridization;
/**
   Get the hybridization
   @hibernate.one-to-one property-ref="arraySlide"
*/
public HybridizationData getHybridization()
{
   return hybridization;
}
void setHybridization(HybridizationData hybridization)
{
   this.hybridization = hybridization;
}					

As you can see, we use the many-to-one mapping on with a unique="true" option for the hybridization. This will force the database to only allow the same array slide to be linked once. Also note that since, not-null="false", null values are allowed and it doesn't matter which end of the relation that is inserted first into the database.

For the array slide end we use a @hibernate.one-to-one mapping and specify the name of the property on the other end that we are linking to. Also, note that the we can only change the link with the HybridizationData.setArraySlide() method, and that this method also updates the other end.

The second form of a one-to-one mapping is used when both objects must have the same id (primary key). The example is from the mapping between users and passwords.

// UserData.java
/**
   @hibernate.id column="`id`" generator-class="foreign"
   @hibernate.generator-param name="property" value="password"
*/
public int getId()
{
   return super.getId();
}
private PasswordData password;
/**
   Get the password.
   @hibernate.one-to-one class="net.sf.basedb.core.data.PasswordData"
      cascade="all" outer-join="false" constrained="true"
*/
public PasswordData getPassword()
{
   if (password == null)
   {
      password = new PasswordData();
      password.setUser(this);
   }
   return password;
}
void setPassword(PasswordData user)
{
   this.password = password;
}

// PasswordData.java
private UserData user;
/**
   Get the user.
   @hibernate.one-to-one class="net.sf.basedb.core.data.UserData"
*/
public UserData getUser()
{
   return user;
}
void setUser(UserData user)
{
   this.user = user;
}

In this case, we use the @hibernate.one-to-one mapping in both classes. The constrained="true" tag in UserData tells Hibernate to always insert the password first, and then the user. The makes it possible to use the (auto-generated) id for the password as the id for the user. This is controlled by the mapping for the UserData.getId() method, which uses the foreign id generator. This generator will look at the password property, ie. call getPassword().getId() to find the id for the user. Also note the initialisation code and cascade="all" tag in the UserData.getPassword() method. This is need to avoid NullPointerException:s and to make sure everything is created and deleted properly.

See also:

The documentation for the class doesn't have to be very lengthy. A single sentence is usually enough. Provide tags for the author, version, last modification date and a reference to the corresponding class in the net.sf.basedb.core package.

/**
   This class holds information about any items.

   @author Your name
   @version 2.0
   @see net.sf.basedb.core.AnyItem
   @base.modified $Date: 2007-08-17 09:18:29 +0200 (Fri, 17 Aug 2007) $
   @hibernate.class table="`Anys`" lazy="false"
*/
public class AnyData
   extends CommonData
{
...
}

Write a short one-sentence description for all public getter methods. You do not have document the parameters or the setter methods, since it would just be a repetition. Methods defined by interfaces are documented in the interface class. You should not have to write any documentation for those methods.

For the inverse end of an association, which has only package private methods, write a notice about this and provide a link to to non-inverse end.

// UserData.java
private String address;
/**
   Get the address for the user.
   @hibernate.property column="`address`" type="string" length="255"
*/
public String getAddress()
{
   return address;
}
public void setAddress(String address)
{
   this.address = address;
}

private Set<GroupData> groups;
/**
   This is the inverse end.
   @see GroupData#getUsers()
   @hibernate.set table="`UserGroups`" lazy="true" inverse="true"
   @hibernate.collection-key column="`user_id`"
   @hibernate.collection-many-to-many column="`group_id`"
      class="net.sf.basedb.core.data.GroupData"
*/
Set<GroupData> getGroups()
{
   return groups;
}
void setGroups(Set<GroupData> groups)
{
   this.groups = groups;
}

Write a short one-sentence description for public static final fields. Private fields does not have to be documented.

/**
   The maximum length of the name of an item that can be
   stored in the database.
   @see #setName(String)
*/
public static int MAX_NAME_LENGTH = 255;

Groups of related classes should be included in an UML-like diagram to show how they are connected and work together. For example we group together users, groups, roles, etc. into an authentication UML diagram. It is also possible that a single class may appear in more than one diagram. For more information about how to create UML diagrams see Section 30.2, “Create UML diagrams with MagicDraw”.