The Amber bean lifecycle follows the JPA model. Amber supports both transactional and non-transactional lifecycles.

Example configuration

The lifecycle description uses a single running example, Test, which has two properties: getData() which returns a string, and getParent() which is a pointer to another Test object.

<hibernate-mapping>
  <class name="qa.Test">
    <id name="id"/>

    <property name="data"/>

    <many-to-one name="parent"/>
  </class>
</hibernate-mapping>

Non-Transactional Lifecycle

Amber's non-transactional lifecycle has three important states:

• clean: the bean is loaded from the database
• dirty: the bean has unwritten changes
• hollow: the bean is unloaded (lazily-loaded)

In the diagram below, the red methods (load(), getXXX(), and flush()) query and update the database.

The aConn.load("1") method loads the bean from the database and transitions to the clean state.

Calling test.setData("foo") will change to the dirty state.

Calling aConn.flush() writes the changes to the database and changes to the clean state. Amber may also flush the changes and change to the clean state at any time. flush() merely guarantees that the changes will be flushed to the database.

The hollow state represents lazily-loaded entities. many-to-one relations and some queries will return the unloaded bean instead of a loaded bean. When the application calls a getXXX() method, the bean will load from the database and change to the clean state. When the application calls a setXXX() method, the bean will change to the dirty state.

// load() queries the database and puts test in the clean state
qa.Test test = aConn.load(qa.Test.class, "1");

// getter calls remain in the clean state
System.out.println(test.getData());

// setters change to the dirty state
test.setData("foo");

// parent is lazily-loaded in the hollow state.
qa.Test parent = test.getParent();

// the getter loads parent from the database and changes to the clean state
System.out.println(parent.getData());

// the flush updates test and changes back to the clean state
aConn.flush();

// closing the connection changes all beans to the transient state
aConn.close();

Transactional Lifecycle

In a transaction, Amber loads the bean from the database, even if it was loaded outside of the transaction. (Exceptions exist for cases like read-only beans.) By loading the bean in the transaction, Amber lets the database handle the transactional locking and state consistency.

Just like the non-transactional clean and dirty states, Amber has transactional clean and dirty states called Persistent-clean and Persistent-dirty. As in the non-transactional case, the hollow state represents lazily-loaded beans.

• persistent-clean: the bean is loaded from the database within the transaction
• persistent-dirty: the bean has been changed
• hollow: the bean is unloaded (lazily-loaded or rolled-back)
• persistent-nonXA: the bean was loaded outside of the transaction (and would need reloading if used in the transaction)

The main differences from the non-transactional lifecycle are:

• Transactions need a load from inside the transaction. Loads before the transaction cannot be reused.
• Updates occur during the commit() call and change to the nonXA-clean state
• Rollbacks change to the hollow state.