From 4b13e3544f7353a3dea1f6672e904247bd5b9021 Mon Sep 17 00:00:00 2001 From: Christian Bauer Date: Mon, 28 Feb 2005 12:43:52 +0000 Subject: [PATCH] HHH-154 and versions git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@5964 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- reference/en/master.xml | 2 +- reference/en/modules/basic_mapping.xml | 22 ++++++------ reference/en/modules/collection_mapping.xml | 8 ++--- reference/en/modules/configuration.xml | 2 +- reference/en/modules/events.xml | 8 ++--- reference/en/modules/example_mappings.xml | 4 +-- reference/en/modules/example_parentchild.xml | 2 +- reference/en/modules/inheritance_mapping.xml | 2 +- reference/en/modules/performance.xml | 36 +++++++++++--------- reference/en/modules/persistent_classes.xml | 3 +- reference/en/modules/query_hql.xml | 2 +- reference/en/modules/query_sql.xml | 6 ++-- reference/en/modules/session_api.xml | 14 ++++---- reference/en/modules/toolset_guide.xml | 8 ++--- reference/en/modules/transactions.xml | 18 +++++----- 15 files changed, 70 insertions(+), 67 deletions(-) diff --git a/reference/en/master.xml b/reference/en/master.xml index 8fa11075cf..c684582c0c 100644 --- a/reference/en/master.xml +++ b/reference/en/master.xml @@ -33,7 +33,7 @@ HIBERNATE - Relational Persistence for Idiomatic Java Hibernate Reference Documentation - 3.0 beta4 + 3.0 diff --git a/reference/en/modules/basic_mapping.xml b/reference/en/modules/basic_mapping.xml index f728d79441..a59c6cb5e5 100644 --- a/reference/en/modules/basic_mapping.xml +++ b/reference/en/modules/basic_mapping.xml @@ -436,7 +436,7 @@ by a query that names any superclass or implemented interface or the class and that instances of any subclass of the class will be returned by a query that names the class itself. Explicit polymorphism means that class instances will be returned only - be queries that explicitly name that class and that queries that name the class will return + by queries that explicitly name that class and that queries that name the class will return only instances of subclasses mapped inside this <class> declaration as a <subclass> or <joined-subclass>. For most purposes the default, polymorphism="implicit", is appropriate. @@ -898,7 +898,7 @@ You must instantiate an instance of the persistent class itself and populate its identifier properties before you can load() the persistent state associated with a composite key. We will describe a much more - convenient approach where the composite identifier is implemented as a seperate class + convenient approach where the composite identifier is implemented as a separate class in . The attributes described below apply only to this alternative approach: @@ -1404,7 +1404,7 @@ - join (optional - defaults to select): + fetch (optional - defaults to select): Chooses between outer-join fetching or sequential select fetching. @@ -1641,7 +1641,7 @@ ]]> - A newly saved instance of Person is then assigned the same primar + A newly saved instance of Person is then assigned the same primary key value as the Employee instance refered with the employee property of that Person. @@ -1767,7 +1767,7 @@ The <dynamic-component> element allows a Map to be mapped as a component, where the property names refer to keys of the map, see - . + . @@ -2533,7 +2533,7 @@ An entity's persistent state consists of references to other entities and instances of value types. Values are primitives, - collections (not whats inside a collection), components and certain immutable + collections (not what's 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 @@ -2560,10 +2560,10 @@ - The challenge is to map the Java type system (and the developers definition of + 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. + <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 @@ -2750,7 +2750,7 @@ The CompositeUserType, EnhancedUserType, - and UserCollectionType and UserVersionType + UserCollectionType, and UserVersionType interfaces provide support for more specialized uses. @@ -2795,11 +2795,11 @@ Even though Hibernate's rich range of built-in types and support for components means you will very rarely need to use a custom type, it is nevertheless considered good form to use custom types for (non-entity) classes that occur frequently - in your application. For example, a MonetoryAmount class is a good + in your application. For example, a MonetaryAmount class is a good candidate for a CompositeUserType, even though it could easily be mapped as a component. One motivation for this is abstraction. With a custom type, your mapping documents would be future-proofed against possible changes in your way of representing - monetory values. + monetary values. diff --git a/reference/en/modules/collection_mapping.xml b/reference/en/modules/collection_mapping.xml index 9c99757676..1e1a570f2f 100644 --- a/reference/en/modules/collection_mapping.xml +++ b/reference/en/modules/collection_mapping.xml @@ -239,10 +239,10 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set not-null="true". - ]]> + ]]> - The foreign key constraint may use ON CASCADE DELETE. + The foreign key constraint may use ON DELETE CASCADE. ]]> @@ -261,7 +261,7 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set Collections may contain almost any other Hibernate type, including all basic types, custom types, components, and of course, references to other entities. This is an important distinction: an object in a collection might be handled with "value" - semantics (it's lifecycle fully depends on the collection owner) or it might be a + semantics (its lifecycle fully depends on the collection owner) or it might be a reference to another entity, with its own lifecycle. In the latter case, only the "link" between the two objects is considered to be state held by the collection. @@ -492,7 +492,7 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set fetch (optional - defaults to join): enables outer-join or sequential select fetching for this association. This - is a special case, for full eager fetching (in a single SELECT) + is a special case; for full eager fetching (in a single SELECT) of an entity and its many-to-many relationships to other entities, you would enable join fetching not only of the collection itself, but also with this attribute on the <many-to-many> diff --git a/reference/en/modules/configuration.xml b/reference/en/modules/configuration.xml index 631ff42451..3ed51faa23 100644 --- a/reference/en/modules/configuration.xml +++ b/reference/en/modules/configuration.xml @@ -92,7 +92,7 @@ - hibernate.properties is the easiest approach is you + hibernate.properties is the easiest approach if you want to get started quickly. diff --git a/reference/en/modules/events.xml b/reference/en/modules/events.xml index 8c963de38e..30e54cf106 100755 --- a/reference/en/modules/events.xml +++ b/reference/en/modules/events.xml @@ -153,7 +153,7 @@ public class AuditInterceptor implements Interceptor, Serializable { A custom listener should implement the appropriate interface for the event it wants to process and/or extend one of the convenience base classes (or even the default event listeners used by Hibernate out-of-the-box as these are declared non-final for this - purpose). Custom listeners can either be registered programatically through the + purpose). Custom listeners can either be registered programmatically through the Configuration object, or specified in the Hibernate configuration XML (declarative configuration through the properties file is not supported). Here's an example of a custom load event listener: @@ -183,7 +183,7 @@ public class AuditInterceptor implements Interceptor, Serializable { ]]> - Instead, you may register it programatically: + Instead, you may register it programmatically: Listeners registered declaratively cannot share instances. If the same class name is used in multiple <listener/> elements, each reference will - result in a seperate instance of that class. If you need the capability to share - listener instances between listener types you must use the programatic registration + result in a separate instance of that class. If you need the capability to share + listener instances between listener types you must use the programmatic registration approach. diff --git a/reference/en/modules/example_mappings.xml b/reference/en/modules/example_mappings.xml index 8072e5e75c..acd2065c86 100644 --- a/reference/en/modules/example_mappings.xml +++ b/reference/en/modules/example_mappings.xml @@ -12,7 +12,7 @@ The following model of the relationship between Employer and Employee uses an actual entity class (Employment) to represent the association. This is done because there might be more than one - period of employment for the same two parties. Components are used to model monetory + period of employment for the same two parties. Components are used to model monetary values and employee names. @@ -50,7 +50,7 @@ - + diff --git a/reference/en/modules/example_parentchild.xml b/reference/en/modules/example_parentchild.xml index afd39b5935..9c187bd2c0 100644 --- a/reference/en/modules/example_parentchild.xml +++ b/reference/en/modules/example_parentchild.xml @@ -271,7 +271,7 @@ session.update(parent); session.flush();]]> - Well, thats all very well for the case of a generated identifier, but what about assigned identifiers + Well, that's all very well for the case of a generated identifier, but what about assigned identifiers and composite identifiers? This is more difficult, since Hibernate can't use the identifier property to distinguish between a newly instantiated object (with an identifier assigned by the user) and an object loaded in a previous session. In this case, Hibernate will either use the timestamp or version diff --git a/reference/en/modules/inheritance_mapping.xml b/reference/en/modules/inheritance_mapping.xml index 764c95c823..db020fd239 100644 --- a/reference/en/modules/inheritance_mapping.xml +++ b/reference/en/modules/inheritance_mapping.xml @@ -91,7 +91,7 @@ - Table per class subclass + Table per subclass A table per subclass mapping would look like: diff --git a/reference/en/modules/performance.xml b/reference/en/modules/performance.xml index d8d1e36963..56a5490e5c 100644 --- a/reference/en/modules/performance.xml +++ b/reference/en/modules/performance.xml @@ -8,7 +8,7 @@ A fetching strategy is the strategy Hibernate will use for retrieving associated objects if the application needs to navigate the association. Fetch strategies may be declared in the O/R - mapping metadata, or over-ridden by particular HQL or + mapping metadata, or over-ridden by a particular HQL or Criteria query. @@ -130,7 +130,7 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]> The fetch strategy specified in the mapping document does not affect - HQL queries + HQL queries. @@ -162,7 +162,7 @@ Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]>SELECTing two collections per outer join would create one. This would almost always be slower than two (lazy or - non-defered) SELECTs. The restriction to a single outer-joined + non-deferred) SELECTs. The restriction to a single outer-joined collection applies to both the mapping fetching strategies and to HQL/Criteria queries. @@ -250,7 +250,7 @@ System.out.println( dc.getWeight() ); // 11.0]]> - These problems are all due to fundamental limitations in Java's single inheritence model. + These problems are all due to fundamental limitations in Java's single inheritance model. If you wish to avoid these problems your persistent classes must each implement an interface that declares its business methods. You should specify these interfaces in the mapping file. eg. @@ -263,8 +263,8 @@ System.out.println( dc.getWeight() ); // 11.0]]> ]]> - where Cat implements the interface ICat and - DomesticCat implements the interface IDomesticCat. Then + where CatImpl implements the interface Cat and + DomesticCatImpl implements the interface DomesticCat. Then proxies for instances of Cat and DomesticCat may be returned by load() or iterate(). (Note that list() does not usually return proxies.) @@ -314,7 +314,7 @@ Cat fritz = (Cat) iter.next();]]> Initializing collections and proxies - A LazyInitializationException will be thrown by Hibernate if an unitialized + A LazyInitializationException will be thrown by Hibernate if an uninitialized collection or proxy is accessed outside of the scope of the Session, ie. when the entity owning the collection or having the reference to the proxy is in the detached state. @@ -328,7 +328,7 @@ Cat fritz = (Cat) iter.next();]]> The static methods Hibernate.initialize() and Hibernate.isInitialized() - provide the application with a convenient way of working with lazyily initialized collections or + provide the application with a convenient way of working with lazily initialized collections or proxies. Hibernate.initialize(cat) will force the initialization of a proxy, cat, as long as its Session is still open. Hibernate.initialize( cat.getKittens() ) has a similar effect for the collection @@ -380,7 +380,7 @@ Cat fritz = (Cat) iter.next();]]> You may also attach a previously loaded object to a new Session with merge() or lock() before - accessing unitialized collections (or other proxies). No, Hibernate does not, + accessing uninitialized collections (or other proxies). No, Hibernate does not, and certainly should not do this automatically, since it would introduce ad hoc transaction semantics! @@ -513,7 +513,7 @@ Cat fritz = (Cat) iter.next();]]> A different (better?) way to avoid unnecessary column reads, at least for - read-only transactons is to use the projection features of HQL. This avoids + read-only transactions is to use the projection features of HQL. This avoids the need for buildtime bytecode processing. @@ -650,7 +650,7 @@ Cat fritz = (Cat) iter.next();]]> If your application needs to read but never modify instances of a persistent class, a read-only cache may be used. This is the simplest and best performing - strategy. Its even perfectly safe for use in a cluster. + strategy. It's even perfectly safe for use in a cluster. @@ -914,7 +914,7 @@ hibernate.cache.use_structured_entries true]]> If the query should force a refresh of its query cache region, you should call Query.setCacheMode(CacheMode.REFRESH). This is particularly useful - in cases where underlying data may have been updated via a seperate process (i.e., + in cases where underlying data may have been updated via a separate process (i.e., not modified through Hibernate) and allows the application to selectively refresh particular query result sets. This is a more efficient alternative to eviction of a query cache region via SessionFactory.evictQueries(). @@ -1176,7 +1176,7 @@ server.registerMBean(stats, on); //we register the MBean]]> Statistics can be reset programatically using the clear() method. A summary - can be sent logger (info level) using the logSummary() method. + can be sent to a logger (info level) using the logSummary() method. Metrics @@ -1216,10 +1216,12 @@ server.registerMBean(stats, on); //we register the MBean]]> SecondLevelCacheStatistics and QueryStatistics API for more informations. In order to work on all detailed entities, collections, queries and region caches statistics, you can retrieve @@ -1232,9 +1234,9 @@ log.info(Cat.class.getName() + " changes:" + changes);]]> Understanding metrics You can find interesting informations while looking at metrics. An entity/collection/query with a high cache - miss ratio (cache miss superior to cache hit) should not be cached: the benefit of caching is not significant + miss ratio (cache miss greater than cache hit) should not be cached: the benefit of caching is not significant for your application and use case. - An entity/collection/query with a cache put way superior to its cache hit should not be cached either: you spend + An entity/collection/query with a cache put much greater than its cache hit should not be cached either: you spend a lot of resources in caching without efficiently use it. A session factory having more open sessions than closed ones shows a session leak which must be addressed. A use case using lots of connections might show a good candidate for a conversion to the session per user diff --git a/reference/en/modules/persistent_classes.xml b/reference/en/modules/persistent_classes.xml index e8fe1bebc8..5df3b6e9ed 100644 --- a/reference/en/modules/persistent_classes.xml +++ b/reference/en/modules/persistent_classes.xml @@ -302,7 +302,8 @@ public class DomesticCat extends Cat { 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 + primary key candidate (see ). + Immutable or unique properties are usually good candidates for a business key. diff --git a/reference/en/modules/query_hql.xml b/reference/en/modules/query_hql.xml index ddb6be1edc..cbf2a1e845 100644 --- a/reference/en/modules/query_hql.xml +++ b/reference/en/modules/query_hql.xml @@ -688,7 +688,7 @@ having cat.color in (eg.Color.TABBY, eg.Color.BLACK)]]> SQL functions and aggregate functions are allowed in the having - and order by clauses, if supported by the underlying database (ie. + and order by clauses, if supported by the underlying database (eg. not in MySQL). diff --git a/reference/en/modules/query_sql.xml b/reference/en/modules/query_sql.xml index 1c9ba7870c..5dcca9e22e 100644 --- a/reference/en/modules/query_sql.xml +++ b/reference/en/modules/query_sql.xml @@ -71,7 +71,7 @@ The {cat.*} notation used above is a shorthand for "all properties". Alternatively, you may list the columns explicity, but even then you must let Hibernate - inject the SQL column aliases for each property. The placeholders for a column alias is + inject the SQL column aliases for each property. The placeholder for a column alias is just the property name qualified by the table alias. In the following example, we retrieve Cats from a different table (cat_log) to the one declared in the mapping metadata. Notice that we may even use the property aliases in the @@ -159,12 +159,12 @@ List loggedCats = sess.createSQLQuery(sql) ]]> - The SQL is directly execute in your database, so you are free to use any dialect + The SQL is directly executed in your database, so you are free to use any dialect you like. - Stored procedures are support if the callable attribute is set: + Stored procedures are supported if the callable attribute is set: diff --git a/reference/en/modules/session_api.xml b/reference/en/modules/session_api.xml index bd9b5659ef..1c7a84c304 100644 --- a/reference/en/modules/session_api.xml +++ b/reference/en/modules/session_api.xml @@ -31,7 +31,7 @@ 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 of + 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). @@ -64,7 +64,7 @@ - We'll know discuss the states and state transitions (and the Hibernate methods that + We'll now discuss the states and state transitions (and the Hibernate methods that trigger a transition) in more detail. @@ -111,7 +111,7 @@ sess.save( pk, new Long(1234) );]]> If the object you make persistent has associated objects (e.g. the - kittens collection role) in the previous example), + 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 @@ -256,7 +256,7 @@ Cat mother = (Cat) session.createQuery( A query is usually executed by invoking list(), the result of the query will be loaded completely into a collection in memory. - Entity instance retrieved by a query are in persistent state. The + 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. @@ -498,7 +498,7 @@ List cats = q.list();]]> );]]> - The returned collection is considered a bag, and its a copy of the given + 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). @@ -900,7 +900,7 @@ session2.close();]]> ReplicationMode.EXCEPTION - throw an exception if there is - and existing database row with the same identifier + an existing database row with the same identifier @@ -933,7 +933,7 @@ session2.close();]]> - before from some query executions + before some query executions diff --git a/reference/en/modules/toolset_guide.xml b/reference/en/modules/toolset_guide.xml index 756a80b081..0f43b63944 100644 --- a/reference/en/modules/toolset_guide.xml +++ b/reference/en/modules/toolset_guide.xml @@ -38,7 +38,7 @@ - There's actually another utitily living in Hibernate Extensions: ddl2hbm. + There's actually another utility living in Hibernate Extensions: ddl2hbm. It is considered deprecated and will no longer be maintained, Middlegen does a better job for the same task. @@ -456,7 +456,7 @@ new SchemaUpdate(cfg).execute(false);]]> The Hibernate code generator may be used to generate skeletal Java implementation classes from a Hibernate mapping file. This tool is included in the Hibernate Extensions package - (a seperate download). + (a separate download). @@ -515,7 +515,7 @@ new SchemaUpdate(cfg).execute(false);]]> This config file declares a global meta attribute "implements" and specify two renderers, the - default one (BasicRenderer) and a renderer that generates Finder's (See more in "Basic Finder + default one (BasicRenderer) and a renderer that generates Finders (See more in "Basic Finder generation" below). @@ -771,7 +771,7 @@ public class Person implements Serializable, IAuditable { Note: This applies to all <meta>-tags. - Thus it can also e.g. be used to specify that all fields should be declare protected, + Thus it can also e.g. be used to specify that all fields should be declared protected, instead of the default private. This is done by adding <meta attribute="scope-field">protected</meta> at e.g. just under the <class> tag and all fields of that class will be protected. diff --git a/reference/en/modules/transactions.xml b/reference/en/modules/transactions.xml index 82c8ab0858..e6865fd149 100644 --- a/reference/en/modules/transactions.xml +++ b/reference/en/modules/transactions.xml @@ -226,7 +226,7 @@ JVM identity for database identity is guaranteed by Hibernate. However, while the application might concurrently access the "same" (persistent identity) business object in two different sessions, the two instances will actually be "different" (JVM identity). Conflicts are - resolved using (automatic versioning) at flush/commit time, using an optmistic approach. + resolved using (automatic versioning) at flush/commit time, using an optimistic approach. @@ -272,7 +272,7 @@ A Session is not thread-safe. Things which are supposed to work - concurrently, like HTTP requests, session beans, or swing workers, will cause race + concurrently, like HTTP requests, session beans, or Swing workers, will cause race conditions if a Session instance would be shared. If you keep your Hibernate Session in your HttpSession (discussed later), you should consider synchronizing access to your Http session. Otherwise, @@ -332,7 +332,7 @@ - However, it is often desireable to keep your persistence layer portable. Hibernate offers a wrapper + However, it is often desirable to keep your persistence layer portable. Hibernate offers a wrapper API called Transaction that translates into the native transaction system of your deployment environment. This API is optional (using database transactions is not!) and you don't have to use it if database portability provided by Hibernate is all you need. @@ -399,7 +399,7 @@ finally { Note that you will very likely never see this piece of code in a normal application; - fatal (system) exceptions should always be catched at the "top". In other words, the + fatal (system) exceptions should always be caught at the "top". In other words, the code that executes Hibernate calls (in the persistence layer) and the code that handles RuntimeException (and usually can only clean up and exit) are in different layers. This can be a challenge to design yourself and you should use J2EE/EJB @@ -490,7 +490,7 @@ finally { transaction, call Session.close() and discard the Session instance. Certain methods of Session will not leave the session in a consistent state. No - exception thrown by Hibernate can be treaded as recoverable. Ensure that the + exception thrown by Hibernate can be treated as recoverable. Ensure that the Session will be closed by calling close() in a finally block. @@ -618,7 +618,7 @@ session.disconnect(); // Return JDBC connection ]]> This pattern is problematic if the Session is too big to be stored during user think time, e.g. an HttpSession should be kept as small as possible. As the Session is also the - (mandatory) first-level cache and contains all loaded objects, we can propably + (mandatory) first-level cache and contains all loaded objects, we can probably use this strategy only for a few request/response cycles. This is indeed recommended, as the Session will soon also have stale data. @@ -669,7 +669,7 @@ session.close();]]> You may disable Hibernate's automatic version increment for particular properties and - collections by setting the optmistic-lock mapping attribute to + collections by setting the optimistic-lock mapping attribute to false. Hibernate will then no longer increment versions if the property is dirty. @@ -679,8 +679,8 @@ session.close();]]> might also access the same database and don't know how to handle version numbers or even timestamps. In both cases, versioning can't rely on a particular column in a table. To force a version check without a version or timestamp property mapping, with a - comparison of the state of all fields in a row, turn on optmistic-lock="all" - in the <class> mapping. Note that this concpetually only works + comparison of the state of all fields in a row, turn on optimistic-lock="all" + in the <class> mapping. Note that this concepetually only works if Hibernate can compare the old and new state, i.e. if you use a single long Session and not session-per-request-with-detached-objects.