diff --git a/reference/en/modules/architecture.xml b/reference/en/modules/architecture.xml index 8d93c48981..04de408f1c 100644 --- a/reference/en/modules/architecture.xml +++ b/reference/en/modules/architecture.xml @@ -250,6 +250,11 @@ Consult the JBoss AS user guide for more information about these options. + + + Another feature available as a JMX service are runtime Hibernate statistics. See + . + diff --git a/reference/en/modules/basic_mapping.xml b/reference/en/modules/basic_mapping.xml index dc1811c2d3..304b32a65b 100644 --- a/reference/en/modules/basic_mapping.xml +++ b/reference/en/modules/basic_mapping.xml @@ -1,14 +1,14 @@ Basic O/R Mapping - + Mapping declaration - Object/relational mappings are defined in an XML document. The mapping document - is designed to be readable and hand-editable. The mapping language is Java-centric, - meaning that mappings are constructed around persistent class declarations, not - table declarations. + Object/relational mappings are usually defined in an XML document. The mapping + document is designed to be readable and hand-editable. The mapping language is + Java-centric, meaning that mappings are constructed around persistent class + declarations, not table declarations. @@ -96,18 +96,20 @@ - + Doctype All XML mappings should declare the doctype shown. The actual DTD may be found at the URL above, in the directory hibernate-x.x.x/src/org/hibernate or in hibernate3.jar. Hibernate will always look for - the DTD in its classpath first. + the DTD in its classpath first. If you experience lookups of the DTD using an + Internet connection, check your DTD declaration against the contents of your + claspath. - + hibernate-mapping @@ -192,6 +194,16 @@ auto-import="false". Hibernate will throw an exception if you attempt to assign two classes to the same "imported" name. + + + Note that the hibernate-mapping element allows you to nest + several persistent <class> mappings, as shown above. + It is however good practice (and expected by some tools) to map only a single + persistent class (or a single class hierarchy) in one mapping file and name + it after the persistent superclass, e.g. Cat.hbm.xml, + Dog.hbm.xml, or if using inheritance, + Animal.hbm.xml. + @@ -510,9 +522,9 @@ ...]]> - Declare the tables to synchronize this entity, to ensure that auto-flush happens + Declare the tables to synchronize this entity with, ensuring that auto-flush happens correctly, and that queries against the derived entity do not return stale data. - The <subselect> is available as both an attribute and + The <subselect> is available as both as an attribute and a nested mapping element. @@ -915,7 +927,7 @@ - + discriminator @@ -997,11 +1009,13 @@ that will be used to evaluate the type of a row: - ]]> + ]]> - + version (optional) @@ -1062,7 +1076,7 @@ - Version numbers may be of type long, integer, + Version numbers may be of Hibernate type long, integer, short, timestamp or calendar. @@ -1072,7 +1086,7 @@ no matter what other unsaved-value strategies are specified. Declaring a nullable version or timestamp property is an easy way to avoid any problems with transitive reattachment in Hibernate, especially useful for people - using assigned identiifers or composite keys! + using assigned identifiers or composite keys! @@ -1318,13 +1332,14 @@ - + many-to-one An ordinary association to another persistent class is declared using a many-to-one element. The relational model is a - many-to-one association. (Its really just an object reference.) + many-to-one association: a foreign key in one table is referencing + the primary key column(s) of the target table. @@ -1369,8 +1384,7 @@ column (optional): The name of the foreign key column. This may also be specified by nested <column> element(s). - - + @@ -1437,11 +1451,10 @@ - The cascade attribute permits the following values: - all, save-update, delete, - none. Setting a value other than none - will propagate certain operations to the associated (child) object. - See "Lifecycle Objects" below. + Setting a value of the cascade attribute to not + none will propagate certain operations to the + associated object (usually in a parent/child fashion). See + "Lifecycle Objects" discussed later. @@ -1621,7 +1634,7 @@ - + component, dynamic-component @@ -1692,15 +1705,15 @@ accessed (requires build-time bytecode instrumentation). + + + optimistic-lock (optional - defaults to true): + Specifies that updates to this component do or do not require acquisition of the + optimistic lock. In other words, define if a version check should be made if this + property is dirty. + + - - - optimistic-lock (optional - defaults to true): - Specifies that updates to this component do or do not require acquisition of the - optimistic lock. In other words, define if a version check should be made if this - property is dirty. - - @@ -1716,17 +1729,18 @@ The <dynamic-component> element allows a Map - to be mapped as a component, where the property names refer to keys of the map. + to be mapped as a component, where the property names refer to keys of the map, see + . - + subclass Finally, polymorphic persistence requires the declaration of each subclass of - the root persistent class. For the (recommended) table-per-class-hierarchy + the root persistent class. For the table-per-class-hierarchy mapping strategy, the <subclass> declaration is used. @@ -1783,6 +1797,10 @@ fully qualified Java class name is used. + + For information about inheritance mappings, see . + + @@ -1884,9 +1902,13 @@ ]]> + + For information about inheritance mappings, see . + + - + union-subclass @@ -1896,7 +1918,7 @@ not absolutely necessary to explicitly map such inheritance hierarchies. You can simply map each class with a separate <class> declaration. However, if you wish use polymorphic associations (e.g. an association - directed at the superclass of your hierarchy), you need to + to the superclass of your hierarchy), you need to use the <union-subclass> mapping. @@ -1954,6 +1976,10 @@ No discriminator column or key column is required for this mapping strategy. + + For information about inheritance mappings, see . + + @@ -2164,7 +2190,7 @@ Hibernate Types - + Entities and values @@ -2186,16 +2212,12 @@ An entity's persistent state consists of references to other entities and instances of value types. Values are primitives, - collections, components and certain immutable objects. Unlike entities, values - (in particular collections and components) are - persisted and deleted by reachability. Since value objects (and primitives) are - persisted and deleted along with their containing entity they may not be - independently versioned. Values have no independent identity, so they cannot be - shared by two entities or collections. - - - - All Hibernate types except collections support null semantics. + collections (not whats inside a collection), components and certain immutable + objects. Unlike entities, values (in particular collections and components) + are persisted and deleted by reachability. Since value + objects (and primitives) are persisted and deleted along with their containing + entity they may not be independently versioned. Values have no independent + identity, so they cannot be shared by two entities or collections. @@ -2203,14 +2225,43 @@ entities. We will continue to do that. Strictly speaking, however, not all user-defined classes with persistent state are entities. A component is a user defined class with value semantics. + A Java property of type java.lang.String also has value + semantics. Given this definition, we can say that all types (classes) provided + by the JDK have value type semantics in Java, while user-defined types may + be mapped with entity or value type semantics. This decision is up to the + application developer. A good hint for an entity class in a domain model are + shared references to a single instance of that class, while composition or + aggregation usually translates to a value type. + + + We'll revisit both concepts throughout the documentation. + + + + The challenge is to map the Java type system (and the developers definition of + entities and value types) to the SQL/database type system. The bridge between + both systems is provided by Hibernate: for entities we use + <class>, <subclass< and so on. + For value types we use <property>, + <component>, etc, usually with a type + attribute. The value of this attribute is the name of a Hibernate + mapping type. Hibernate provides many mappings (for standard + JDK value types) out of the box. You can write your own mapping types and implement your + custom conversion strategies as well, as you'll see later. + + + + All built-in Hibernate types except collections support null semantics. + + - + Basic value types - The basic types may be roughly categorized into + The built-in basic mapping types may be roughly categorized into @@ -2422,6 +2473,10 @@ + + + TODO: document parameterizable usertypes + Any type mappings @@ -2544,7 +2599,7 @@ hibernate-mapping. This allows you to extend a class hierachy just by adding a new mapping file. You must specify an extends attribute in the subclass mapping, naming a previously mapped superclass. Note: Previously this feature made the ordering of the mapping - documents important. Since Hibernate 3, the ordering of mapping files does not matter when using the + documents important. Since Hibernate3, the ordering of mapping files does not matter when using the extends keyword. The ordering inside a single mapping file still needs to be defined as superclasses before subclasses. @@ -2585,7 +2640,7 @@ public class Cat { private char sex; private float weight; - /** + /* * @hibernate.id * generator-class="native" * column="CAT_ID" @@ -2693,6 +2748,34 @@ public class Cat { package, as a separate download. Both EJB3 (JSR-220) and Hibernate3 metadata is supported. + + This is an example of a POJO class annotated as an EJB entity bean: + + + + Note that support for JDK 5.0 Annotations (and JSR-220) is still work in progress and not completed. diff --git a/reference/en/modules/configuration.xml b/reference/en/modules/configuration.xml index d35feb998f..b1710029e4 100644 --- a/reference/en/modules/configuration.xml +++ b/reference/en/modules/configuration.xml @@ -797,16 +797,13 @@ hibernate.dialect = \ - + SQL Dialects You should always set the hibernate.dialect property to the correct - org.hibernate.dialect.Dialect subclass for your database. This is not - strictly essential unless you wish to use native or - sequence primary key generation or pessimistic locking (with, eg. - Session.lock() or Query.setLockMode()). - However, if you specify a dialect, Hibernate will use sensible defaults for some of the + org.hibernate.dialect.Dialect subclass for your database. If you + specify a dialect, Hibernate will use sensible defaults for some of the other properties listed above, saving you the effort of specifying them manually. @@ -931,23 +928,24 @@ hibernate.dialect = \ - + Second-level and query cache The properties prefixed by hibernate.cache allow you to use a process or cluster scoped second-level cache system - with Hibernate. See the "Performance" chapter for more details. + with Hibernate. See the for + more details. - + Transaction strategy configuration If you wish to use the Hibernate Transaction API instead - of directly calling a particular transaction API, you must + of directly calling a particular system transaction API, you must specify a factory class for Transaction instances by setting the property hibernate.transaction.factory_class. The Transaction API hides the underlying transaction @@ -980,9 +978,10 @@ hibernate.dialect = \ - If you wish to use a second-level cache for mutable data in a JTA environment, you must specify - a strategy for obtaining the JTA TransactionManager, since J2EE does not - standardize a single mechanism: + Some features in Hibernate (i.e. the second level cache) require access to the + JTA TransactionManager in a management environment. You have to + specify how Hibernate should obtain a reference to the TransactionManager, + since J2EE does not standardize a single mechanism: @@ -1039,7 +1038,7 @@ hibernate.dialect = \ - + JNDI-bound <literal>SessionFactory</literal> @@ -1066,7 +1065,8 @@ hibernate.dialect = \ Hibernate will automatically place the SessionFactory in JNDI after you call cfg.buildSessionFactory(). This means you will at least have - this call in some startup code (or utility class) in your application. + this call in some startup code (or utility class) in your application, unless you use + JMX deployment with the HibernateService. @@ -1101,14 +1101,15 @@ hibernate.dialect = \ - + Hibernate statistics If you enable hibernate.generate_statistics, Hibernate will expose a number of metrics that are useful when tuning a running system via SessionFactory.getStatistics(). Hibernate can even be configured - to expose these statistics via JMX (see the website for details). + to expose these statistics via JMX. Read the Javadoc of the interfaces in + org.hibernate.stats for more information. @@ -1177,8 +1178,8 @@ hibernate.dialect = \ - - XML Configuration File + + XML configuration file An alternative approach to configuration is to specify a full configuration in @@ -1216,6 +1217,11 @@ hibernate.dialect = \ + + + + + ]]> @@ -1223,11 +1229,14 @@ hibernate.dialect = \ As you can see, the advantage of this approach is the externalization of the mapping file names to configuration. The hibernate.cfg.xml - is also more convenient once you have to tune the Hibernate cache. + is also more convenient once you have to tune the Hibernate cache. Note that is + your choice to use either hibernate.properties or + hibernate.cfg.xml, both are equivalent, except for the above + mentioned benefits of using the XML syntax. - Configuring Hibernate is then as simple as + With the XML configuration, starting Hibernate is then as simple as diff --git a/reference/en/modules/persistent_classes.xml b/reference/en/modules/persistent_classes.xml index 6af1b9d018..2b1451f369 100644 --- a/reference/en/modules/persistent_classes.xml +++ b/reference/en/modules/persistent_classes.xml @@ -12,7 +12,7 @@ Hibernate works best if these classes follow some simple rules, also known as the Plain Old Java Object (POJO) programming model. However, Hibernate3 allows you to express a domain model in other ways: using trees of - Map instances, for example. + Map instances, for example. @@ -134,16 +134,16 @@ public class Cat { persistent classes must have a default constructor (which may be non-public) so Hibernate can instantiate them using Constructor.newInstance(). We recommend having a constructor with at least package - visibility for runtime proxy generation in Hibernate. + visibility for runtime proxy generation in Hibernate. - + Provide an identifier property (optional) Cat has a property called id. This property - holds the primary key column of a database table. The property might have been called + maps to the primary key column of a database table. The property might have been called anything, and its type might have been any primitive type, any primitive "wrapper" type, java.lang.String or java.util.Date. (If your legacy database table has composite keys, you can even use a user-defined class @@ -165,7 +165,7 @@ public class Cat { Transitive reattachment for detached objects (cascade update) - - see "Lifecycle Objects" + see "Lifecycle Objects" @@ -190,8 +190,8 @@ public class Cat { You can persist final classes that do not implement an interface - with Hibernate, but you won't be able to use proxies for lazy associationfetching - - which will limit your options for performance tuning. + with Hibernate, but you won't be able to use proxies for lazy association fetching - + which will limit your options for performance tuning. @@ -219,20 +219,20 @@ public class DomesticCat extends Cat { }]]> - + Implementing <literal>equals()</literal> and <literal>hashCode()</literal> You have to override the equals() and hashCode() methods if you - + intend to put instances of persistent classes in a Set (the recommended way to represent many-valued associations) - and - + and + @@ -240,13 +240,13 @@ public class DomesticCat extends Cat { - + Hibernate guarantees equivalence of persistent identity (database row) and Java identity - only inside a particular session scope. So as soon as we mix instances retrieved in - different sessions, we must implement equals() and - hashCode() if we wish to have meaningful semantics for - Sets. + only inside a particular session scope. So as soon as we mix instances retrieved in + different sessions, we must implement equals() and + hashCode() if we wish to have meaningful semantics for + Sets. @@ -255,15 +255,20 @@ public class DomesticCat extends Cat { be the same database row, they are therefore equal (if both are added to a Set, we will only have one element in the Set). Unfortunately, we can't use that approach with generated identifiers! Hibernate will only assign identifier values to objects - that are persistent, a newly created instance will not have any identifier value! We recommend - implementing equals() and hashCode() using - Business key equality. + that are persistent, a newly created instance will not have any identifier value! Furthermore, + if an instance is unsaved and currently in a Set, saving it will assign + an identifier value to the object. If equals() and hashCode() + are based on the identifier value, the hash code would change, breaking the contract of the + Set. See the Hibernate website for a full discussion of this problem. Note + that this is not a Hibernate issue, but normal Java semantics of object identity and equality. - Business key equality means that the equals() - method compares only the properties that form the business key, a key that would - identify our instance in the real world (a natural candidate key): + We recommend implementing equals() and hashCode() + using Business key equality. Business key equality means that the + equals() method compares only the properties that form the business + key, a key that would identify our instance in the real world (a + natural candidate key): + + Note that a business key does not have to be as solid as a database + primary key candidate. Immutable or unique properties are usually good + candidates for a business key. + + - + Dynamic models @@ -302,42 +313,42 @@ public class DomesticCat extends Cat { - + - + + type="long" + column="ID"> - - - - - - - - + + + + + + + + - + ]]> At runtime, you just instantiate HashMaps and use - the Hibernate entity name to refer to a particular type. + the Hibernate entity name to refer to a particular type: