Chapter 10. Working with objects
Prev |  | Next

## Chapter 10. Working with objects

Hibernate is a full object/relational mapping solution that not only shields the developer from the details of the underlying database management system, but also offers state management of objects. This is, contrary to the management of SQL `statements` in common JDBC/SQL persistence layers, a very natural object-oriented view of persistence in Java applications.

In other words, Hibernate application developers should always think about the state of their objects, and not necessarily about the execution of SQL statements. This part is taken care of by Hibernate and is only relevant for the application developer when tuning the performance of the system.

## 10.1. Hibernate object states

Hibernate defines and supports the following object states:

- Transient - an object is transient if it has just been instantiated using the `new` operator, and it is not associated with a Hibernate `Session`. It has no persistent representation in the database and no identifier value has been assigned. Transient instances will be destroyed by the garbage collector if the application doesn't hold a reference anymore. Use the Hibernate `Session` to make an object persistent (and let Hibernate take care of the SQL statements that need to be executed for this transition).

- Persistent - a persistent instance has a representation in the database and an identifier value. It might just have been saved or loaded, however, it is by definition in the scope of a `Session`. Hibernate will detect any changes made to an object in persistent state and synchronize the state with the database when the unit of work completes. Developers don't execute manual `UPDATE` statements, or `DELETE` statements when an object should be made transient.

- Detached - a detached instance is an object that has been persistent, but its `Session` has been closed. The reference to the object is still valid, of course, and the detached instance might even be modified in this state. A detached instance can be reattached to a new `Session` at a later point in time, making it (and all the modifications) persistent again. This feature enables a programming model for long running units of work that require user think-time. We call them application transactions, i.e. a unit of work from the point of view of the user.

We'll now discuss the states and state transitions (and the Hibernate methods that trigger a transition) in more detail.

## 10.2. Making objects persistent

Newly instantiated instances of a a persistent class are considered transient by Hibernate. We can make a transient instance persistent by associating it with a session:

    DomesticCat fritz = new DomesticCat();
    fritz.setColor(Color.GINGER);
    fritz.setSex('M');
    fritz.setName("Fritz");
    Long generatedId = (Long) sess.save(fritz);

If `Cat` has a generated identifier, the identifier is generated and assigned to the `cat` when `save()` is called. If `Cat` has an `assigned` identifier, or a composite key, the identifier should be assigned to the `cat` instance before calling `save()`. You may also use `persist()` instead of `save()`, with the semantics defined in the EJB3 early draft.

Alternatively, you may assign the identifier using an overloaded version of `save()`.

    DomesticCat pk = new DomesticCat();
    pk.setColor(Color.TABBY);
    pk.setSex('F');
    pk.setName("PK");
    pk.setKittens( new HashSet() );
    pk.addKitten(fritz);
    sess.save( pk, new Long(1234) );

If the object you make persistent has associated objects (e.g. the `kittens` collection in the previous example), these objects may be made persistent in any order you like unless you have a `NOT NULL` constraint upon a foreign key column. There is never a risk of violating foreign key constraints. However, you might violate a `NOT NULL` constraint if you `save()` the objects in the wrong order.

Usually you don't bother with this detail, as you'll very likely use Hibernate's transitive persistence feature to save the associated objects automatically. Then, even `NOT NULL` constraint violations don't occur - Hibernate will take care of everything. Transitive persistence is discussed later in this chapter.

## 10.3. Loading an object

The `load()` methods of `Session` gives you a way to retrieve a persistent instance if you already know its identifier. `load()` takes a class object and will load the state into a newly instantiated instance of that class, in persistent state.

    Cat fritz = (Cat) sess.load(Cat.class, generatedId);

    // you need to wrap primitive identifiers
    long id = 1234;
    DomesticCat pk = (DomesticCat) sess.load( DomesticCat.class, new Long(id) );

Alternatively, you can load state into a given instance:

    Cat cat = new DomesticCat();
    // load pk's state into cat
    sess.load( cat, new Long(pkId) );
    Set kittens = cat.getKittens();

Note that `load()` will throw an unrecoverable exception if there is no matching database row. If the class is mapped with a proxy, `load()` just returns an uninitialized proxy and does not actually hit the database until you invoke a method of the proxy. This behaviour is very useful if you wish to create an association to an object without actually loading it from the database. It also allows multiple instances to be loaded as a batch if `batch-size` is defined for the class mapping.

If you are not certain that a matching row exists, you should use the `get()` method, which hits the database immediately and returns null if there is no matching row.

    Cat cat = (Cat) sess.get(Cat.class, id);
    if (cat==null) {
        cat = new Cat();
        sess.save(cat, id);
    }
    return cat;

You may even load an object using an SQL `SELECT ... FOR UPDATE`, using a `LockMode`. See the API documentation for more information.

    Cat cat = (Cat) sess.get(Cat.class, id, LockMode.UPGRADE);

Note that any associated instances or contained collections are not selected `FOR UPDATE`, unless you decide to specify `lock` or `all` as a cascade style for the association.

It is possible to re-load an object and all its collections at any time, using the `refresh()` method. This is useful when database triggers are used to initialize some of the properties of the object.

    sess.save(cat);
    sess.flush(); //force the SQL INSERT
    sess.refresh(cat); //re-read the state (after the trigger executes)

An important question usually appears at this point: How much does Hibernate load from the database and how many SQL `SELECT`s will it use? This depends on the fetching strategy and is explained in Section 19.1, “Fetching strategies”.

## 10.4. Querying

If you don't know the identifiers of the objects you are looking for, you need a query. Hibernate supports an easy-to-use but powerful object oriented query language (HQL). For programmatic query creation, Hibernate supports a sophisticated Criteria and Example query feature (QBC and QBE). You may also express your query in the native SQL of your database, with optional support from Hibernate for result set conversion into objects.

### 10.4.1. Executing queries

HQL and native SQL queries are represented with an instance of `org.hibernate.Query`. This interface offers methods for parameter binding, result set handling, and for the execution of the actual query. You always obtain a `Query` using the current `Session`:

    List cats = session.createQuery(
        "from Cat as cat where cat.birthdate < ?")
        .setDate(0, date)
        .list();

    List mothers = session.createQuery(
        "select mother from Cat as cat join cat.mother as mother where cat.name = ?")
        .setString(0, name)
        .list();

    List kittens = session.createQuery(
        "from Cat as cat where cat.mother = ?")
        .setEntity(0, pk)
        .list();

    Cat mother = (Cat) session.createQuery(
        "select cat.mother from Cat as cat where cat = ?")
        .setEntity(0, izi)
        .uniqueResult();]]

    Query mothersWithKittens = (Cat) session.createQuery(
        "select mother from Cat as mother left join fetch mother.kittens");
    Set uniqueMothers = new HashSet(mothersWithKittens.list());

A query is usually executed by invoking `list()`, the result of the query will be loaded completely into a collection in memory. Entity instances retrieved by a query are in persistent state. The `uniqueResult()` method offers a shortcut if you know your query will only return a single object. Note that queries that make use of eager fetching of collections usually return duplicates of the root objects (but with their collections initialized). You can filter these duplicates simply through a `Set`.

#### 10.4.1.1. Iterating results

Occasionally, you might be able to achieve better performance by executing the query using the `iterate()` method. This will only usually be the case if you expect that the actual entity instances returned by the query will already be in the session or second-level cache. If they are not already cached, `iterate()` will be slower than `list()` and might require many database hits for a simple query, usually 1 for the initial select which only returns identifiers, and n additional selects to initialize the actual instances.

    // fetch ids
    Iterator iter = sess.createQuery("from eg.Qux q order by q.likeliness").iterate();
    while ( iter.hasNext() ) {
        Qux qux = (Qux) iter.next();  // fetch the object
        // something we couldnt express in the query
        if ( qux.calculateComplicatedAlgorithm() ) {
            // delete the current instance
            iter.remove();
            // dont need to process the rest
            break;
        }
    }

#### 10.4.1.2. Queries that return tuples

Hibernate queries sometimes return tuples of objects, in which case each tuple is returned as an array:

    Iterator kittensAndMothers = sess.createQuery(
                "select kitten, mother from Cat kitten join kitten.mother mother")
                .list()
                .iterator();

    while ( kittensAndMothers.hasNext() ) {
        Object[] tuple = (Object[]) kittensAndMothers.next();
        Cat kitten  = tuple[0];
        Cat mother  = tuple[1];
        ....
    }

#### 10.4.1.3. Scalar results

Queries may specify a property of a class in the `select` clause. They may even call SQL aggregate functions. Properties or aggregates are considered "scalar" results (and not entities in persistent state).

    Iterator results = sess.createQuery(
            "select cat.color, min(cat.birthdate), count(cat) from Cat cat " +
            "group by cat.color")
            .list()
            .iterator();

    while ( results.hasNext() ) {
        Object[] row = (Object[]) results.next();
        Color type = (Color) row[0];
        Date oldest = (Date) row[1];
        Integer count = (Integer) row[2];
        .....
    }

#### 10.4.1.4. Bind parameters

Methods on `Query` are provided for binding values to named parameters or JDBC-style `?` parameters. Contrary to JDBC, Hibernate numbers parameters from zero. Named parameters are identifiers of the form `:name` in the query string. The advantages of named parameters are:

- named parameters are insensitive to the order they occur in the query string

- they may occur multiple times in the same query

- they are self-documenting

    //named parameter (preferred)
    Query q = sess.createQuery("from DomesticCat cat where cat.name = :name");
    q.setString("name", "Fritz");
    Iterator cats = q.iterate();

    //positional parameter
    Query q = sess.createQuery("from DomesticCat cat where cat.name = ?");
    q.setString(0, "Izi");
    Iterator cats = q.iterate();

    //named parameter list
    List names = new ArrayList();
    names.add("Izi");
    names.add("Fritz");
    Query q = sess.createQuery("from DomesticCat cat where cat.name in (:namesList)");
    q.setParameterList("namesList", names);
    List cats = q.list();

#### 10.4.1.5. Pagination

If you need to specify bounds upon your result set (the maximum number of rows you want to retrieve and / or the first row you want to retrieve) you should use methods of the `Query` interface:

    Query q = sess.createQuery("from DomesticCat cat");
    q.setFirstResult(20);
    q.setMaxResults(10);
    List cats = q.list();

Hibernate knows how to translate this limit query into the native SQL of your DBMS.

#### 10.4.1.6. Scrollable iteration

If your JDBC driver supports scrollable `ResultSet`s, the `Query` interface may be used to obtain a `ScrollableResults` object, which allows flexible navigation of the query results.

    Query q = sess.createQuery("select cat.name, cat from DomesticCat cat " +
                                "order by cat.name");
    ScrollableResults cats = q.scroll();
    if ( cats.first() ) {

        // find the first name on each page of an alphabetical list of cats by name
        firstNamesOfPages = new ArrayList();
        do {
            String name = cats.getString(0);
            firstNamesOfPages.add(name);
        }
        while ( cats.scroll(PAGE_SIZE) );

        // Now get the first page of cats
        pageOfCats = new ArrayList();
        cats.beforeFirst();
        int i=0;
        while( ( PAGE_SIZE > i++ ) && cats.next() ) pageOfCats.add( cats.get(1) );

    }
    cats.close()

Note that an open database connection (and cursor) is required for this functionality, use `setMaxResult()`/`setFirstResult()` if you need offline pagination functionality.

#### 10.4.1.7. Externalizing named queries

You may also define named queries in the mapping document. (Remember to use a `CDATA` section if your query contains characters that could be interpreted as markup.)

    <query name="eg.DomesticCat.by.name.and.minimum.weight"><![CDATA[
        from eg.DomesticCat as cat
            where cat.name = ?
            and cat.weight > ?
    ] ]></query>

Parameter binding and executing is done programatically:

    Query q = sess.getNamedQuery("eg.DomesticCat.by.name.and.minimum.weight");
    q.setString(0, name);
    q.setInt(1, minWeight);
    List cats = q.list();

Note that the actual program code is independent of the query language that is used, you may also define native SQL queries in metadata, or migrate existing queries to Hibernate by placing them in mapping files.

### 10.4.2. Filtering collections

A collection filter is a special type of query that may be applied to a persistent collection or array. The query string may refer to `this`, meaning the current collection element.

    Collection blackKittens = session.createFilter(
        pk.getKittens(),
        "where this.color = ?")
        .setParameter( Color.BLACK, Hibernate.custom(ColorUserType.class) )
        .list()
    );

The returned collection is considered a bag, and it's a copy of the given collection. The original collection is not modified (this is contrary to the implication of the name "filter", but consistent with expected behavior).

Observe that filters do not require a `from` clause (though they may have one if required). Filters are not limited to returning the collection elements themselves.

    Collection blackKittenMates = session.createFilter(
        pk.getKittens(),
        "select this.mate where this.color = eg.Color.BLACK.intValue")
        .list();

Even an empty filter query is useful, e.g. to load a subset of elements in a huge collection:

    Collection tenKittens = session.createFilter(
        mother.getKittens(), "")
        .setFirstResult(0).setMaxResults(10)
        .list();

### 10.4.3. Criteria queries

HQL is extremely powerful but some developers prefer to build queries dynamically, using an object-oriented API, rather than building query strings. Hibernate provides an intuitive `Criteria` query API for these cases:

    Criteria crit = session.createCriteria(Cat.class);
    crit.add( Expression.eq( "color", eg.Color.BLACK ) );
    crit.setMaxResults(10);
    List cats = crit.list();

The `Criteria` and the associated `Example` API are discussed in more detail in Chapter 15, Criteria Queries.

### 10.4.4. Queries in native SQL

You may express a query in SQL, using `createSQLQuery()` and let Hibernate take care of the mapping from result sets to objects. Note that you may at any time call `session.connection()` and use the JDBC `Connection` directly. If you chose to use the Hibernate API, you must enclose SQL aliases in braces:

    List cats = session.createSQLQuery(
        "SELECT {cat.*} FROM CAT {cat} WHERE ROWNUM<10",
        "cat",
        Cat.class
    ).list();

    List cats = session.createSQLQuery(
        "SELECT {cat}.ID AS {cat.id}, {cat}.SEX AS {cat.sex}, " +
               "{cat}.MATE AS {cat.mate}, {cat}.SUBCLASS AS {cat.class}, ... " +
        "FROM CAT {cat} WHERE ROWNUM<10",
        "cat",
        Cat.class
    ).list()

SQL queries may contain named and positional parameters, just like Hibernate queries. More information about native SQL queries in Hibernate can be found in Chapter 16, Native SQL.

## 10.5. Modifying persistent objects

Transactional persistent instances (ie. objects loaded, saved, created or queried by the `Session`) may be manipulated by the application and any changes to persistent state will be persisted when the `Session` is flushed (discussed later in this chapter). There is no need to call a particular method (like `update()`, which has a different purpose) to make your modifications persistent. So the most straightforward way to update the state of an object is to `load()` it, and then manipulate it directly, while the `Session` is open:

    DomesticCat cat = (DomesticCat) sess.load( Cat.class, new Long(69) );
    cat.setName("PK");
    sess.flush();  // changes to cat are automatically detected and persisted

Sometimes this programming model is inefficient since it would require both an SQL `SELECT` (to load an object) and an SQL `UPDATE` (to persist its updated state) in the same session. Therefore Hibernate offers an alternate approach, using detached instances.

Note that Hibernate does not offer its own API for direct execution of `UPDATE` or `DELETE` statements. Hibernate is a state management service, you don't have to think in statements to use it. JDBC is a perfect API for executing SQL statements, you can get a JDBC `Connection` at any time by calling `session.connection()`. Furthermore, the notion of mass operations conflicts with object/relational mapping for online transaction processing-oriented applications. Future versions of Hibernate may however provide special mass operation functions. See Chapter 13, Batch processing for some possible batch operation tricks.

## 10.6. Modifying detached objects

Many applications need to retrieve an object in one transaction, send it to the UI layer for manipulation, then save the changes in a new transaction. Applications that use this kind of approach in a high-concurrency environment usually use versioned data to ensure isolation for the "long" unit of work.

Hibernate supports this model by providing for reattachment of detached instances using the `Session.update()` or `Session.merge()` methods:

    // in the first session
    Cat cat = (Cat) firstSession.load(Cat.class, catId);
    Cat potentialMate = new Cat();
    firstSession.save(potentialMate);

    // in a higher layer of the application
    cat.setMate(potentialMate);

    // later, in a new session
    secondSession.update(cat);  // update cat
    secondSession.update(mate); // update mate

If the `Cat` with identifier `catId` had already been loaded by `secondSession` when the application tried to reattach it, an exception would have been thrown.

Use `update()` if you are sure that the session does not contain an already persistent instance with the same identifier, and `merge()` if you want to merge your modifications at any time without consideration of the state of the session. In other words, `update()` is usually the first method you would call in a fresh session, ensuring that reattachment of your detached instances is the first operation that is executed.

The application should individually `update()` detached instances reachable from the given detached instance if and only if it wants their state also updated. This can be automated of course, using transitive persistence, see Section 10.11, “Transitive persistence”.

The `lock()` method also allows an application to reassociate an object with a new session. However, the detached instance has to be unmodified!

    //just reassociate:
    sess.lock(fritz, LockMode.NONE);
    //do a version check, then reassociate:
    sess.lock(izi, LockMode.READ);
    //do a version check, using SELECT ... FOR UPDATE, then reassociate:
    sess.lock(pk, LockMode.UPGRADE);

Note that `lock()` can be used with various `LockMode`s, see the API documentation and the chapter on transaction handling for more information. Reattachment is not the only usecase for `lock()`.

Other models for long units of work are discussed in Section 11.3, “Optimistic concurrency control”.

## 10.7. Automatic state detection

Hibernate users have requested a general purpose method that either saves a transient instance by generating a new identifier or updates/reattaches the detached instances associated with its current identifier. The `saveOrUpdate()` method implements this functionality.

    // in the first session
    Cat cat = (Cat) firstSession.load(Cat.class, catID);

    // in a higher tier of the application
    Cat mate = new Cat();
    cat.setMate(mate);

    // later, in a new session
    secondSession.saveOrUpdate(cat);   // update existing state (cat has a non-null id)
    secondSession.saveOrUpdate(mate);  // save the new instance (mate has a null id)

The usage and semantics of `saveOrUpdate()` seems to be confusing for new users. Firstly, so long as you are not trying to use instances from one session in another new session, you should not need to use `update()`, `saveOrUpdate()`, or `merge()`. Some whole applications will never use either of these methods.

Usually `update()` or `saveOrUpdate()` are used in the following scenario:

- the application loads an object in the first session

- the object is passed up to the UI tier

- some modifications are made to the object

- the object is passed back down to the business logic tier

- the application persists these modifications by calling `update()` in a second session

`saveOrUpdate()` does the following:

- if the object is already persistent in this session, do nothing

- if another object associated with the session has the same identifier, throw an exception

- if the object has no identifier property, `save()` it

- if the object's identifier has the value assigned to a newly instantiated object, `save()` it

- if the object is versioned (by a `<version>` or `<timestamp>`), and the version property value is the same value assigned to a newly instantiated object, `save()` it

- otherwise `update()` the object

and `merge()` is very different:

- if there is a persistent instance with the same identifier currently associated with the session, copy the state of the given object onto the persistent instance

- if there is no persistent instance currently associated with the session, try to load it from the database, or create a new persistent instance

- the persistent instance is returned

- the given instance does not become associated with the session, it remains detached

## 10.8. Deleting persistent objects

`Session.delete()` will remove an object's state from the database. Of course, your application might still hold a reference to a deleted object. It's best to think of `delete()` as making a persistent instance transient.

    sess.delete(cat);

You may delete objects in any order you like, without risk of foreign key constraint violations. It is still possible to violate a `NOT NULL` constraint on a foreign key column by deleting objects in the wrong order, e.g. if you delete the parent, but forget to delete the children.

## 10.9. Replicating object between two different datastores

It is occasionally useful to be able to take a graph of persistent instances and make them persistent in a different datastore, without regenerating identifier values.

    //retrieve a cat from one database
    Session session1 = factory1.openSession();
    Transaction tx1 = session1.beginTransaction();
    Cat cat = session1.get(Cat.class, catId);
    tx1.commit();
    session1.close();

    //reconcile with a second database
    Session session2 = factory2.openSession();
    Transaction tx2 = session2.beginTransaction();
    session2.replicate(cat, ReplicationMode.LATEST_VERSION);
    tx2.commit();
    session2.close();

The `ReplicationMode` determines how `replicate()` will deal with conflicts with existing rows in the database.

- `ReplicationMode.IGNORE` - ignore the object when there is an existing database row with the same identifier

- `ReplicationMode.OVERWRITE` - overwrite any existing database row with the same identifier

- `ReplicationMode.EXCEPTION` - throw an exception if there is an existing database row with the same identifier

- `ReplicationMode.LATEST_VERSION` - overwrite the row if its version number is earlier than the version number of the object, or ignore the object otherwise

Usecases for this feature include reconciling data entered into different database instances, upgrading system configuration information during product upgrades, rolling back changes made during non-ACID transactions and more.

## 10.10. Flushing the Session

From time to time the `Session` will execute the SQL statements needed to synchronize the JDBC connection's state with the state of objects held in memory. This process, flush, occurs by default at the following points

- before some query executions

- from `org.hibernate.Transaction.commit()`

- from `Session.flush()`

The SQL statements are issued in the following order

1. all entity insertions, in the same order the corresponding objects were saved using `Session.save()`

2. all entity updates

3. all collection deletions

4. all collection element deletions, updates and insertions

5. all collection insertions

6. all entity deletions, in the same order the corresponding objects were deleted using `Session.delete()`

(An exception is that objects using `native` ID generation are inserted when they are saved.)

Except when you explicity `flush()`, there are absolutely no guarantees about when the `Session` executes the JDBC calls, only the order in which they are executed. However, Hibernate does guarantee that the `Query.list(..)` will never return stale data; nor will they return the wrong data.

It is possible to change the default behavior so that flush occurs less frequently. The `FlushMode` class defines three different modes: only flush at commit time (and only when the Hibernate `Transaction` API is used), flush automatically using the explained routine, or never flush unless `flush()` is called explicitly. The last mode is useful for long running units of work, where a `Session` is kept open and disconnected for a long time (see Section 11.3.2, “Extended session and automatic versioning”).

    sess = sf.openSession();
    Transaction tx = sess.beginTransaction();
    sess.setFlushMode(FlushMode.COMMIT); // allow queries to return stale state

    Cat izi = (Cat) sess.load(Cat.class, id);
    izi.setName(iznizi);

    // might return stale data
    sess.find("from Cat as cat left outer join cat.kittens kitten");

    // change to izi is not flushed!
    ...
    tx.commit(); // flush occurs
    sess.close();

During flush, an exception might occur (e.g. if a DML operation violates a constraint). Since handling exceptions involves some understanding of Hibernate's transactional behavior, we discuss it in Chapter 11, Transactions And Concurrency.

## 10.11. Transitive persistence

It is quite cumbersome to save, delete, or reattach individual objects, especially if you deal with a graph of associated objects. A common case is a parent/child relationship. Consider the following example:

If the children in a parent/child relationship would be value typed (e.g. a collection of addresses or strings), their lifecycle would depend on the parent and no further action would be required for convenient "cascading" of state changes. When the parent is saved, the value-typed child objects are saved as well, when the parent is deleted, the children will be deleted, etc. This even works for operations such as the removal of a child from the collection; Hibernate will detect this and, since value-typed objects can't have shared references, delete the child from the database.

Now consider the same scenario with parent and child objects being entities, not value-types (e.g. categories and items, or parent and child cats). Entities have their own lifecycle, support shared references (so removing an entity from the collection does not mean it can be deleted), and there is by default no cascading of state from one entity to any other associated entities. Hibernate does not implement persistence by reachability by default.

For each basic operation of the Hibernate session - including `persist(), merge(), saveOrUpdate(), delete(), lock(), refresh(), evict(), replicate()` - there is a corresponding cascade style. Respectively, the cascade styles are named `create, merge, save-update, delete, lock, refresh, evict, replicate`. If you want an operation to be cascaded along an association, you must indicate that in the mapping document. For example:

    <one-to-one name="person" cascade="persist"/>

Cascade styles my be combined:

    <one-to-one name="person" cascade="persist,delete,lock"/>

You may even use `cascade="all"` to specify that all operations should be cascaded along the association. The default `cascade="none"` specifies that no operations are to be cascaded.

A special cascade style, `delete-orphan`, applies only to one-to-many associations, and indicates that the `delete()` operation should be applied to any child object that is removed from the association.

Recommendations:

- It doesn't usually make sense to enable cascade on a `<many-to-one>` or `<many-to-many>` association. Cascade is often useful for `<one-to-one>` and `<one-to-many>` associations.

- If the child object's lifespan is bounded by the lifespan of the of the parent object make it a lifecycle object by specifying `cascade="all,delete-orphan"`.

- Otherwise, you might not need cascade at all. But if you think that you will often be working with the parent and children together in the same transaction, and you want to save yourself some typing, consider using `cascade="persist,merge,save-update"`.

Mapping an association (either a single valued association, or a collection) with `cascade="all"` marks the association as a parent/child style relationship where save/update/delete of the parent results in save/update/delete of the child or children.

Futhermore, a mere reference to a child from a persistent parent will result in save/update of the child. This metaphor is incomplete, however. A child which becomes unreferenced by its parent is not automatically deleted, except in the case of a `<one-to-many>` association mapped with `cascade="delete-orphan"`. The precise semantics of cascading operations for a parent/child relationship are as follows:

- If a parent is passed to `persist()`, all children are passed to `persist()`

- If a parent is passed to `merge()`, all children are passed to `merge()`

- If a parent is passed to `save()`, `update()` or `saveOrUpdate()`, all children are passed to `saveOrUpdate()`

- If a transient or detached child becomes referenced by a persistent parent, it is passed to `saveOrUpdate()`

- If a parent is deleted, all children are passed to `delete()`

- If a child is dereferenced by a persistent parent, nothing special happens - the application should explicitly delete the child if necessary - unless `cascade="delete-orphan"`, in which case the "orphaned" child is deleted.

Finally, note that cascading of operations can be applied to an object graph at call time or at flush time. All operations, if enabled, are cascaded to associated entities reachable when the operation is executed. However, `save-upate` and `delete-orphan` are transitive for all associated entities reachable during flush of the `Session`.

## 10.12. Using metadata

Hibernate requires a very rich meta-level model of all entity and value types. From time to time, this model is very useful to the application itself. For example, the application might use Hibernate's metadata to implement a "smart" deep-copy algorithm that understands which objects should be copied (eg. mutable value types) and which should not (eg. immutable value types and, possibly, associated entities).

Hibernate exposes metadata via the `ClassMetadata` and `CollectionMetadata` interfaces and the `Type` hierarchy. Instances of the metadata interfaces may be obtained from the `SessionFactory`.

    Cat fritz = ......;
    ClassMetadata catMeta = sessionfactory.getClassMetadata(Cat.class);

    Object[] propertyValues = catMeta.getPropertyValues(fritz);
    String[] propertyNames = catMeta.getPropertyNames();
    Type[] propertyTypes = catMeta.getPropertyTypes();

    // get a Map of all properties which are not collections or associations
    Map namedValues = new HashMap();
    for ( int i=0; i<propertyNames.length; i++ ) {
        if ( !propertyTypes[i].isEntityType() && !propertyTypes[i].isCollectionType() ) {
            namedValues.put( propertyNames[i], propertyValues[i] );
        }
    }

Prev | Up | Next
Chapter 9. Inheritance Mapping | Home | Chapter 11. Transactions And Concurrency