diff --git a/documentation/manual/fr-FR/src/main/docbook/content/architecture.xml b/documentation/manual/fr-FR/src/main/docbook/content/architecture.xml index 762b91b5bd..4ac898c709 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/architecture.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/architecture.xml @@ -323,6 +323,14 @@ courantes sont associées au thread d'exécution. Voir les javadocs pour les détails. + + + org.hibernate.context.ManagedSessionContext - current + sessions are tracked by thread of execution. However, you are responsible to + bind and unbind a Session instance with static methods + on this class, it does never open, flush, or close a Session. + + diff --git a/documentation/manual/fr-FR/src/main/docbook/content/association_mapping.xml b/documentation/manual/fr-FR/src/main/docbook/content/association_mapping.xml index 6f94a3aca3..656935c437 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/association_mapping.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/association_mapping.xml @@ -365,7 +365,14 @@ create table Address ( addressId bigint not null primary key ) ]]> - + + It is important that you define not-null="true" on the + <key> element of the collection mapping if the + underlying foreign key column is NOT NULL. Don't only + declare not-null="true" on a possible nested + <column> element, but on the <key> + element. + diff --git a/documentation/manual/fr-FR/src/main/docbook/content/basic_mapping.xml b/documentation/manual/fr-FR/src/main/docbook/content/basic_mapping.xml index 3e50d96bfb..3818c4b983 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/basic_mapping.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/basic_mapping.xml @@ -98,8 +98,61 @@ des recherches de la DTD sur Internet, vérifiez votre déclaration de DTD par rapport au contenu de votre classpath. - - + + EntityResolver + + As mentioned previously, Hibernate will first attempt to resolve DTDs in its classpath. The + manner in which it does this is by registering a custom org.xml.sax.EntityResolver + implementation with the SAXReader it uses to read in the xml files. This custom + EntityResolver recognizes two different systemId namespaces. + + + + + a hibernate namespace is recognized whenever the + resolver encounteres a systemId starting with + http://hibernate.sourceforge.net/; the resolver + attempts to resolve these entities via the classlaoder which loaded + the Hibernate classes. + + + + + a user namespace is recognized whenever the + resolver encounteres a systemId using a classpath:// + URL protocol; the resolver will attempt to resolve these entities + via (1) the current thread context classloader and (2) the + classloader which loaded the Hibernate classes. + + + + + An example of utilizing user namespacing: + + + + ]> + + + + + ... + + + &types; + ]]> + + Where types.xml is a resource in the your.domain + package and contains a custom typedef. + + + + + + hibernate-mapping Cet élément a plusieurs attributs optionnels. Les attributs schema et catalog @@ -357,19 +410,14 @@ pour plus d'informations. + - - catalog (optionnel) : The name of a database catalog used for this - class and its table. - - - check (optionnel) : expression SQL utilisée pour générer une contrainte de vérification multi-lignes pour la génération automatique de schéma. - + rowid (optionnel) : Hibernate peut utiliser des ROWID sur les bases de données qui utilisent ce mécanisme. Par exemple avec Oracle, Hibernate peut utiliser la colonne additionnelle @@ -377,14 +425,14 @@ la localisation physique d'un tuple enregistré. - + subselect (optionnel) : Permet de mapper une entité immuable en lecture-seule sur un sous-select de base de données. Utile pour avoir une vue au lieu d'une table en base, mais à éviter. Voir plus bas pour plus d'information. - + abstract (optionnel) : Utilisé pour marquer des superclasses abstraites dans des hiérarchies de <union-subclass>. @@ -733,6 +781,19 @@ avec une association <one-to-one> sur la clef primaire. + + sequence-identity + + + a specialized sequence generation strategy which utilizes a + database sequence for the actual value generation, but combines + this with JDBC3 getGeneratedKeys to actually return the generated + identifier value as part of the insert statement execution. This + strategy is only known to be supported on Oracle 10g drivers + targetted for JDK 1.4. Note comments on these insert statements + are disabled due to a bug in the Oracle drivers. + + @@ -829,7 +890,177 @@ - + + + + Enhanced identifier generators + + + Starting with release 3.2.3, there are 2 new generators which represent a re-thinking of 2 different + aspects of identifier generation. The first aspect is database portability; the second is optimization + (not having to query the database for every request for a new identifier value). These two new + generators are intended to take the place of some of the named generators described above (starting + in 3.3.x); however, they are included in the current releases and can be referenced by FQN. + + + + The first of these new generators is org.hibernate.id.enhanced.SequenceStyleGenerator + which is intended firstly as a replacement for the sequence generator and secondly as + a better portability generator than native (because native + (generally) chooses between identity and sequence which have + largely different semantics which can cause subtle isssues in applications eyeing portability). + org.hibernate.id.enhanced.SequenceStyleGenerator however achieves portability in + a different manner. It chooses between using a table or a sequence in the database to store its + incrementing values depending on the capabilities of the dialect being used. The difference between this + and native is that table-based and sequence-based storage have the same exact + semantic (in fact sequences are exactly what Hibernate tries to emmulate with its table-based + generators). This generator has a number of configuration parameters: + + + + sequence_name (optional, defaults to hibernate_sequence): + The name of the sequence (or table) to be used. + + + + + initial_value (optional, defaults to 1): The initial + value to be retrieved from the sequence/table. In sequence creation terms, this is analogous + to the clause typical named "STARTS WITH". + + + + + increment_size (optional, defaults to 1): The value by + which subsequent calls to the sequence/table should differ. In sequence creation terms, this + is analogous to the clause typical named "INCREMENT BY". + + + + + force_table_use (optional, defaults to false): Should + we force the use of a table as the backing structure even though the dialect might support + sequence? + + + + + value_column (optional, defaults to next_val): Only + relevant for table structures! The name of the column on the table which is used to + hold the value. + + + + + optimizer (optional, defaults to none): + See + + + + + + The second of these new generators is org.hibernate.id.enhanced.TableGenerator which + is intended firstly as a replacement for the table generator (although it actually + functions much more like org.hibernate.id.MultipleHiLoPerTableGenerator) and secondly + as a re-implementation of org.hibernate.id.MultipleHiLoPerTableGenerator utilizing the + notion of pluggable optimiziers. Essentially this generator defines a table capable of holding + a number of different increment values simultaneously by using multiple distinctly keyed rows. This + generator has a number of configuration parameters: + + + + table_name (optional, defaults to hibernate_sequences): + The name of the table to be used. + + + + + value_column_name (optional, defaults to next_val): + The name of the column on the table which is used to hold the value. + + + + + segment_column_name (optional, defaults to sequence_name): + The name of the column on the table which is used to hold the "segement key". This is the + value which distinctly identifies which increment value to use. + + + + + segment_value (optional, defaults to default): + The "segment key" value for the segment from which we want to pull increment values for + this generator. + + + + + segment_value_length (optional, defaults to 255): + Used for schema generation; the column size to create this segment key column. + + + + + initial_value (optional, defaults to 1): + The initial value to be retrieved from the table. + + + + + increment_size (optional, defaults to 1): + The value by which subsequent calls to the table should differ. + + + + + optimizer (optional, defaults to ): + See + + + + + + + + Identifier generator optimization + + For identifier generators which store values in the database, it is inefficient for them to hit the + database on each and every call to generate a new identifier value. Instead, you'd ideally want to + group a bunch of them in memory and only hit the database when you have exhausted your in-memory + value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators + ( support this notion. + + + + none (generally this is the default if no optimizer was specified): This + says to not perform any optimizations, and hit the database each and every request. + + + + + hilo: applies a hi/lo algorithm around the database retrieved values. The + values from the database for this optimizer are expected to be sequential. The values + retrieved from the database structure for this optimizer indicates the "group number"; the + increment_size is multiplied by that value in memory to define a group + "hi value". + + + + + pooled: like was discussed for hilo, this optimizers + attempts to minimize the number of hits to the database. Here, however, we simply store + the starting value for the "next group" into the database structure rather than a sequential + value in combination with an in-memory grouping algorithm. increment_size + here refers to the values coming from the database. + + + + + + + + + composite-id ex. on_close (default) | after_transaction | after_statement | auto + + Note that this setting only affects Sessions returned from + SessionFactory.openSession. For Sessions + obtained through SessionFactory.getCurrentSession, the + CurrentSessionContext implementation configured for use + controls the connection release mode for those Sessions. + See - hibernate.connection.<propertyName> + hibernate.connection.<propertyName> - Passe la propriété JDBCpropertyName + Passe la propriété JDBC <propertyName> à DriverManager.getConnection(). - hibernate.jndi.<propertyName> + hibernate.jndi.<propertyName> Passe la propriété propertyName à l'InitialContextFactory @@ -1415,7 +1422,13 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]> - + + You can pick a different XML configuration file using + + + diff --git a/documentation/manual/fr-FR/src/main/docbook/content/events.xml b/documentation/manual/fr-FR/src/main/docbook/content/events.xml index b627183eb6..0638607e83 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/events.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/events.xml @@ -116,15 +116,26 @@ public class AuditInterceptor extends EmptyInterceptor { }]]> - - L'intercepteur doit être spécifié quand une session est créée. + + Interceptors come in two flavors: Session-scoped and + SessionFactory-scoped. + + + + A Session-scoped interceptor is specified + when a session is opened using one of the overloaded SessionFactory.openSession() + methods accepting an Interceptor. - - Vous pouvez aussi mettre un intercepteur au niveau global, en utilisant l'objet Configuration. - Dans ce cas, l'intercepteur doit être "threadsafe". + + A SessionFactory-scoped interceptor is registered with the Configuration + object prior to building the SessionFactory. In this case, the supplied interceptor + will be applied to all sessions opened from that SessionFactory; this is true unless + a session is opened explicitly specifying the interceptor to use. SessionFactory-scoped + interceptors must be thread safe, taking care to not store session-specific state since multiple + sessions will use this interceptor (potentially) concurrently. diff --git a/documentation/manual/fr-FR/src/main/docbook/content/performance.xml b/documentation/manual/fr-FR/src/main/docbook/content/performance.xml index 231ba35116..395a659686 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/performance.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/performance.xml @@ -719,7 +719,7 @@ Cat fritz = (Cat) iter.next();]]> OSCache org.hibernate.cache.OSCacheProvider mémoire, disque - oui (invalidation de cluster) + oui diff --git a/documentation/manual/fr-FR/src/main/docbook/content/query_hql.xml b/documentation/manual/fr-FR/src/main/docbook/content/query_hql.xml index db4ad7084c..967ba92c02 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/query_hql.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/query_hql.xml @@ -214,6 +214,43 @@ + + Refering to identifier property + + + There are, generally speaking, 2 ways to refer to an entity's identifier property: + + + + + The special property (lowercase) id may be used to reference the identifier + property of an entity provided that entity does not define a non-identifier property + named id. + + + + + If the entity defines a named identifier property, you may use that property name. + + + + + + References to composite identifier properties follow the same naming rules. If the + entity has a non-identifier property named id, the composite identifier property can only + be referenced by its defined named; otherwise, the special id property + can be used to rerference the identifier property. + + + + Note: this has changed significantly starting in version 3.2.2. In previous versions, + id always referred to the identifier property no + matter what its actual name. A ramification of that decision was that non-identifier + properties named id could never be referenced in Hibernate queries. + + + + La clause select @@ -904,34 +941,10 @@ from Cat as cat]]> Notez que les sous-requêtes HQL peuvent arriver seulememnt dans les clauses select ou where. - - Pour des sous-requêtes avec plus d'une expression dans le select, vous pouvez utiliser un constructeur de tuples : + + Note that subqueries can also utilize row value constructor syntax. See + for more details. - - - - - Notez que sur certaines bases de données (mais par Oracle ou HSQL), vous pouvez utiliser des constructeurs de tuples - dans d'autres contextes, par exemple lors du requêtage de composants ou de types utilisateur composites : - - - - - - Ce qui est équivalent à la forme plus verbeuse suivante : - - - - - - Il y a deux bonnes raisons que vous ne puissiez ne pas vouloir faire cette sorte de choses : d'abord, ce n'est - pas complètement portable entre les plateformes de base de données ; deuxièmement, la requête est maintenant - dépendante de l'ordre des propriétés dans le document de mapping. - - diff --git a/documentation/manual/fr-FR/src/main/docbook/content/query_sql.xml b/documentation/manual/fr-FR/src/main/docbook/content/query_sql.xml index dbd2d2b229..b3b88e16a4 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/query_sql.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/query_sql.xml @@ -23,225 +23,378 @@ Dans des cas extrêmement simples, nous pouvons utiliser la forme suivante : - List cats = sess.createSQLQuery("select * from cats") - .addEntity(Cat.class) - .list(); - - Cette requête a spécifié : - - - - la requête SQL - - - - l'entité retournée par la requête - - - - - Ici, les noms de colonne des résultats sont supposés être les mêmes que les noms de colonne spécifiés dans le - document de mapping. Cela peut être problématique pour des requêtes SQL qui joignent de multiple tables, puisque - les mêmes noms de colonne peuvent apparaître dans plus d'une table. La forme suivante n'est pas vulnérable à la - duplication des noms de colonne : - - - List cats = sess.createSQLQuery("select {cat.*} from cats cat") - .addEntity("cat", Cat.class) - .list(); - - Cette requête a spécifié : - - - - la requête SQL, avec un paramètre fictif pour Hibernate pour injecter les alias de colonne - - - - l'entité retournée par la requête, et son alias de table SQL - - - - - La méthode addEntity() associe l'alias de la table SQL - avec la classe de l'entité retournée, et détermine la forme de l'ensemble des résultats de la requête. - - - - La méthode addJoin() peut être utilisée pour charger des associations vers d'autres - entités et collections. - - - List cats = sess.createSQLQuery( - "select {cat.*}, {kitten.*} from cats cat, cats kitten where kitten.mother = cat.id" - ) - .addEntity("cat", Cat.class) - .addJoin("kitten", "cat.kittens") - .list(); - - - Une requête SQL native pourrait retourner une simple valeur scalaire ou une combinaison de scalaires et d'entités. - - - Double max = (Double) sess.createSQLQuery("select max(cat.weight) as maxWeight from cats cat") - .addScalar("maxWeight", Hibernate.DOUBLE); - .uniqueResult(); - - Vous pouvez alternativement décrire les informations de mapping des résultats dans vos fichiers hbm - et les utiliser pour vos requêtes. - - List cats = sess.createSQLQuery( - "select {cat.*}, {kitten.*} from cats cat, cats kitten where kitten.mother = cat.id" - ) - .setResultSetMapping("catAndKitten") - .list(); - - - - Alias et références de propriété - - - La notation {cat.*} utilisée au-dessus est un raccourci pour "toutes les propriétés". - Alternativement, vous pouvez lister explicitement les colonnes, mais même ce cas que nous laissons à Hibernate - injecte des alias de colonne SQL pour chaque propriété. Le remplaçant pour un alias de colonne - est juste le nom de la propriété qualifié par l'alias de la table. - Dans l'exemple suivant, nous récupérons des Cats à partir d'une table différente - (cat_log) de celle déclarée dans les méta-données de mapping. - Notez que nous pouvons même utiliser les alias de propriété dans la clause "where" si nous le souhaitons. - - - - La syntaxe {} n'est pas requise pour le requêtes nommées. Voir - . - - - String sql = "select cat.originalId as {cat.id}, " + - "cat.mateid as {cat.mate}, cat.sex as {cat.sex}, " + - "cat.weight*10 as {cat.weight}, cat.name as {cat.name} " + - "from cat_log cat where {cat.mate} = :catId" - -List loggedCats = sess.createSQLQuery(sql) - .addEntity("cat", Cat.class) - .setLong("catId", catId) - .list(); - - - À noter : si vous listez chaque propriété explicitement, vous devez inclure - toutes les propriétés de la classe et ses sous-classes ! - - - - La table suivante montre les différentes possibilités d'utilisation de l'injection d'alias. À noter : les noms - des alias dans le résultat sont des exemples, chaque alias aura un nom unique et probablement différent lors de l'utilisation. - - - - Noms d'injection d'alias - - - - - - - - - - - Description - - Syntaxe - - Exemple - - - - - - Une simple propriété - - {[aliasname].[propertyname]} - - A_NAME as {item.name} - - - - Une propriété composée - - {[aliasname].[componentname].[propertyname]} - - CURRENCY as {item.amount.currency}, VALUE as - {item.amount.value} - - - - Discriminant d'une entité - - {[aliasname].class} - - DISC as {item.class} - - - - Toutes les propriétés d'une entité - - {[aliasname].*} - - {item.*} - - - - Une clef de collection - - {[aliasname].key} - - ORGID as {coll.key} - - - - L'identifiant d'une collection - - {[aliasname].id} - - EMPID as {coll.id} - - - - L'élément d'une collection - - {[aliasname].element} - - XID as {coll.element} - - - - - - Propriété de l'élément dans la collection - - {[aliasname].element.[propertyname]} - - NAME as {coll.element.name} - - - - Toutes les propriétés de l'élément dans la collection - - {[aliasname].element.*} - - {coll.element.*} - - - - Toutes les propriétés de la collection - - {[aliasname].*} - - {coll.*} - - - -
- + + + Scalar queries + + The most basic SQL query is to get a list of scalars + (values). + + + + These will both return a List of Object arrays (Object[]) with + scalar values for each column in the CATS table. Hibernate will use + ResultSetMetadata to deduce the actual order and types of the returned + scalar values. + + To avoid the overhead of using + ResultSetMetadata or simply to be more explicit in + what is returned one can use addScalar(). + + + + This query specified: + + + + the SQL query string + + + + the columns and types to return + + + + This will still return Object arrays, but now it will not use + ResultSetMetdata but will instead explicitly get the + ID, NAME and BIRTHDATE column as respectively a Long, String and a Short + from the underlying resultset. This also means that only these three + columns will be returned, even though the query is using + * and could return more than the three listed + columns. + + It is possible to leave out the type information for all or some + of the scalars. + + + + This is essentially the same query as before, but now + ResultSetMetaData is used to decide the type of NAME + and BIRTHDATE where as the type of ID is explicitly specified. + + How the java.sql.Types returned from ResultSetMetaData is mapped + to Hibernate types is controlled by the Dialect. If a specific type is + not mapped or does not result in the expected type it is possible to + customize it via calls to registerHibernateType in + the Dialect. + + + + Entity queries + + The above queries were all about returning scalar values, + basically returning the "raw" values from the resultset. The following + shows how to get entity objects from a native sql query via + addEntity(). + + + + This query specified: + + + + the SQL query string + + + + the entity returned by the query + + + + Assuming that Cat is mapped as a class with the columns ID, NAME + and BIRTHDATE the above queries will both return a List where each + element is a Cat entity. + + If the entity is mapped with a many-to-one to + another entity it is required to also return this when performing the + native query, otherwise a database specific "column not found" error + will occur. The additional columns will automatically be returned when + using the * notation, but we prefer to be explicit as in the following + example for a many-to-one to a + Dog: + + + + This will allow cat.getDog() to function properly. + + + + Handling associations and collections + + It is possible to eagerly join in the Dog to + avoid the possible extra roundtrip for initializing the proxy. This is + done via the addJoin() method, which allows you to + join in an association or collection. + + + + In this example the returned Cat's will have + their dog property fully initialized without any + extra roundtrip to the database. Notice that we added a alias name + ("cat") to be able to specify the target property path of the join. It + is possible to do the same eager joining for collections, e.g. if the + Cat had a one-to-many to Dog + instead. + + + + + At this stage we are reaching the limits of what is possible with native queries without starting to + enhance the sql queries to make them usable in Hibernate; the problems starts to arise when returning + multiple entities of the same type or when the default alias/column names are not enough. + + + + + Returning multiple entities + + Until now the result set column names are assumed to be the same + as the column names specified in the mapping document. This can be + problematic for SQL queries which join multiple tables, since the same + column names may appear in more than one table. + + Column alias injection is needed in the following query (which + most likely will fail): + + + + The intention for this query is to return two Cat instances per + row, a cat and its mother. This will fail since there is a conflict of + names since they are mapped to the same column names and on some + databases the returned column aliases will most likely be on the form + "c.ID", "c.NAME", etc. which are not equal to the columns specificed in + the mappings ("ID" and "NAME"). + + The following form is not vulnerable to column name + duplication: + + + + This query specified: + + + + the SQL query string, with placeholders for Hibernate to + inject column aliases + + + + the entities returned by the query + + + + The {cat.*} and {mother.*} notation used above is a shorthand for + "all properties". Alternatively, you may list the columns explicity, but + even in this case we let Hibernate 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 and their mothers 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 where clause if we like. + + + + + Alias and property references + + For most cases the above alias injection is needed, but for + queries relating to more complex mappings like composite properties, + inheritance discriminators, collections etc. there are some specific + aliases to use to allow Hibernate to inject the proper aliases. + + The following table shows the different possibilities of using + the alias injection. Note: the alias names in the result are examples, + each alias will have a unique and probably different name when + used. + + + Alias injection names + + + + + + + + + + + Description + + Syntax + + Example + + + + + + A simple property + + {[aliasname].[propertyname] + + A_NAME as {item.name} + + + + A composite property + + {[aliasname].[componentname].[propertyname]} + + CURRENCY as {item.amount.currency}, VALUE as + {item.amount.value} + + + + Discriminator of an entity + + {[aliasname].class} + + DISC as {item.class} + + + + All properties of an entity + + {[aliasname].*} + + {item.*} + + + + A collection key + + {[aliasname].key} + + ORGID as {coll.key} + + + + The id of an collection + + {[aliasname].id} + + EMPID as {coll.id} + + + + The element of an collection + + {[aliasname].element} + + XID as {coll.element} + + + + roperty of the element in the collection + + {[aliasname].element.[propertyname]} + + NAME as {coll.element.name} + + + + All properties of the element in the collection + + {[aliasname].element.*} + + {coll.element.*} + + + + All properties of the the collection + + {[aliasname].*} + + {coll.*} + + + +
+ + + + + Returning non-managed entities + + It is possible to apply a ResultTransformer to native sql queries. Allowing it to e.g. return non-managed entities. + + + + This query specified: + + + + the SQL query string + + + + a result transformer + + + + + The above query will return a list of CatDTO which has been instantiated and injected the values of NAME and BIRTHNAME into its corresponding + properties or fields. + + + + + Handling inheritance + + Native sql queries which query for entities that is mapped as part + of an inheritance must include all properties for the baseclass and all + it subclasses. + + + + Parameters + + Native sql queries support positional as well as named + parameters: + + + + + + Requêtes SQL nommées @@ -252,19 +405,19 @@ List loggedCats = sess.createSQLQuery(sql) cas, nous n'avons pas besoin d'appeler addEntity(). - <sql-query name="persons"> - <return alias="person" class="eg.Person"/> - SELECT person.NAME AS {person.name}, - person.AGE AS {person.age}, - person.SEX AS {person.sex} - FROM PERSON person - WHERE person.NAME LIKE :namePattern -</sql-query> - - List people = sess.getNamedQuery("persons") - .setString("namePattern", namePattern) - .setMaxResults(50) - .list(); + + + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex} + FROM PERSON person + WHERE person.NAME LIKE :namePattern + ]]> + + Les éléments <return-join> et @@ -272,34 +425,34 @@ List loggedCats = sess.createSQLQuery(sql) des associations et définir des requêtes qui initialisent des collections. - <sql-query name="personsWith"> - <return alias="person" class="eg.Person"/> - <return-join alias="address" property="person.mailingAddress"/> - SELECT person.NAME AS {person.name}, - person.AGE AS {person.age}, - person.SEX AS {person.sex}, - address.STREET AS {address.street}, - address.CITY AS {address.city}, - address.STATE AS {address.state}, - address.ZIP AS {address.zip} - FROM PERSON person - JOIN ADDRESS address - ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' - WHERE person.NAME LIKE :namePattern -</sql-query> + + + + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex}, + address.STREET AS {address.street}, + address.CITY AS {address.city}, + address.STATE AS {address.state}, + address.ZIP AS {address.zip} + FROM PERSON person + JOIN ADDRESS address + ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' + WHERE person.NAME LIKE :namePattern +]]> Une requête SQL nommée peut retourner une valeur scalaire. Vous devez spécifier l'alias de colonne et le type Hibernate utilisant l'élément <return-scalar> : - <sql-query name="mySqlQuery"> - <return-scalar column="name" type="string"/> - <return-scalar column="age" type="long"/> - SELECT p.NAME AS name, - p.AGE AS age, - FROM PERSON p WHERE p.NAME LIKE 'Hiber%' -</sql-query> + + + + SELECT p.NAME AS name, + p.AGE AS age, + FROM PERSON p WHERE p.NAME LIKE 'Hiber%' +]]> Vous pouvez externaliser les informations de mapping des résultats dans un @@ -308,24 +461,32 @@ List loggedCats = sess.createSQLQuery(sql) setResultSetMapping(). - <resultset name="personAddress"> - <return alias="person" class="eg.Person"/> - <return-join alias="address" property="person.mailingAddress"/> -</resultset> + + + + + + + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex}, + address.STREET AS {address.street}, + address.CITY AS {address.city}, + address.STATE AS {address.state}, + address.ZIP AS {address.zip} + FROM PERSON person + JOIN ADDRESS address + ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' + WHERE person.NAME LIKE :namePattern +]]> +You can alternatively use the resultset mapping information in your + hbm files directly in java code. -<sql-query name="personsWith" resultset-ref="personAddress"> - SELECT person.NAME AS {person.name}, - person.AGE AS {person.age}, - person.SEX AS {person.sex}, - address.STREET AS {address.street}, - address.CITY AS {address.city}, - address.STATE AS {address.state}, - address.ZIP AS {address.zip} - FROM PERSON person - JOIN ADDRESS address - ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' - WHERE person.NAME LIKE :namePattern -</sql-query> + Utilisation de return-property pour spécifier explicitement les noms des colonnes/alias @@ -336,18 +497,18 @@ List loggedCats = sess.createSQLQuery(sql) {} pour laisser Hibernate injecter ses propres alias. - <sql-query name="mySqlQuery"> - <return alias="person" class="eg.Person"> - <return-property name="name" column="myName"/> - <return-property name="age" column="myAge"/> - <return-property name="sex" column="mySex"/> - </return> - SELECT person.NAME AS myName, - person.AGE AS myAge, - person.SEX AS mySex, - FROM PERSON person WHERE person.NAME LIKE :name -</sql-query> - + + + + + + + SELECT person.NAME AS myName, + person.AGE AS myAge, + person.SEX AS mySex, + FROM PERSON person WHERE person.NAME LIKE :name + +]]> <return-property> fonctionne aussi avec de @@ -355,21 +516,22 @@ List loggedCats = sess.createSQLQuery(sql) qui ne peut pas permettre une bonne granularité des propriétés multi-colonnes. - <sql-query name="organizationCurrentEmployments"> - <return alias="emp" class="Employment"> - <return-property name="salary"> - <return-column name="VALUE"/> - <return-column name="CURRENCY"/> - </return-property> - <return-property name="endDate" column="myEndDate"/> - </return> - SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, - STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, - REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY - FROM EMPLOYMENT - WHERE EMPLOYER = :id AND ENDDATE IS NULL - ORDER BY STARTDATE ASC -</sql-query> + + + + + + + + + + SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, + STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, + REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY + FROM EMPLOYMENT + WHERE EMPLOYER = :id AND ENDDATE IS NULL + ORDER BY STARTDATE ASC +]]> Notez que dans cet exemple nous avons utilisé <return-property> @@ -396,36 +558,37 @@ List loggedCats = sess.createSQLQuery(sql) version supérieure : - CREATE OR REPLACE FUNCTION selectAllEmployments - RETURN SYS_REFCURSOR -AS - st_cursor SYS_REFCURSOR; -BEGIN - OPEN st_cursor FOR - SELECT EMPLOYEE, EMPLOYER, - STARTDATE, ENDDATE, - REGIONCODE, EID, VALUE, CURRENCY - FROM EMPLOYMENT; - RETURN st_cursor; - END; + + Pour utiliser cette requête dans Hibernate vous avez besoin de la mapper via une requête nommée. - <sql-query name="selectAllEmployees_SP" callable="true"> - <return alias="emp" class="Employment"> - <return-property name="employee" column="EMPLOYEE"/> - <return-property name="employer" column="EMPLOYER"/> - <return-property name="startDate" column="STARTDATE"/> - <return-property name="endDate" column="ENDDATE"/> - <return-property name="regionCode" column="REGIONCODE"/> - <return-property name="id" column="EID"/> - <return-property name="salary"> - <return-column name="VALUE"/> - <return-column name="CURRENCY"/> - </return-property> - </return> - { ? = call selectAllEmployments() } -</sql-query> + + + + + + + + + + + + + + { ? = call selectAllEmployments() } +]]> Notez que les procédures stockées retournent, pour le moment, seulement des @@ -447,7 +610,10 @@ BEGIN Les requêtes de procédures stockées ne peuvent pas être paginées avec setFirstResult()/setMaxResults(). - + Recommended call form is standard SQL92: { ? = call + functionName(<parameters>) } or { ? = call + procedureName(<parameters>}. Native call syntax is not + supported. Pour Oracle les règles suivantes s'appliquent : @@ -493,15 +659,15 @@ BEGIN <sql-delete>, et <sql-update> surchargent ces chaînes de caractères : - <class name="Person"> - <id name="id"> - <generator class="increment"/> - </id> - <property name="name" not-null="true"/> - <sql-insert>INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), ? )</sql-insert> - <sql-update>UPDATE PERSON SET NAME=UPPER(?) WHERE ID=?</sql-update> - <sql-delete>DELETE FROM PERSON WHERE ID=?</sql-delete> -</class> + + + + + + INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), ? ) + UPDATE PERSON SET NAME=UPPER(?) WHERE ID=? + DELETE FROM PERSON WHERE ID=? +]]> Le SQL est directement exécuté dans votre base de données, donc vous êtes libre d'utiliser le dialecte que vous souhaitez. Cela réduira bien sûr la portabilité de votre mapping si vous @@ -509,15 +675,16 @@ BEGIN Les procédures stockées sont supportées si l'attribut callable est paramétré : - <class name="Person"> - <id name="id"> - <generator class="increment"/> - </id> - <property name="name" not-null="true"/> - <sql-insert callable="true">{call createPerson (?, ?)}</sql-insert> - <sql-delete callable="true">{? = call deletePerson (?)}</sql-delete> - <sql-update callable="true">{? = call updatePerson (?, ?)}</sql-update> -</class> + + + + + + + {call createPerson (?, ?)} + {? = call deletePerson (?)} + {? = call updatePerson (?, ?)} +]]> L'ordre des paramètres positionnels est actuellement vital, car ils doivent être dans la même séquence qu'Hibernate les attend. @@ -536,19 +703,20 @@ BEGIN Hibernate inscrit toujours la première expression comme un paramètre de sortie numérique pour les opérations CUD : - CREATE OR REPLACE FUNCTION updatePerson (uid IN NUMBER, uname IN VARCHAR2) - RETURN NUMBER IS -BEGIN - update PERSON - set - NAME = uname, - where - ID = uid; - - return SQL%ROWCOUNT; - -END updatePerson; + @@ -556,53 +724,52 @@ END updatePerson; Vous pouvez aussi déclarer vos propres requêtes SQL (ou HQL) pour le chargement d'entité : - <sql-query name="person"> - <return alias="pers" class="Person" lock-mode="upgrade"/> - SELECT NAME AS {pers.name}, ID AS {pers.id} - FROM PERSON - WHERE ID=? - FOR UPDATE -</sql-query> + + + + SELECT NAME AS {pers.name}, ID AS {pers.id} + FROM PERSON + WHERE ID=? + FOR UPDATE +]]> Ceci est juste une déclaration de requête nommée, comme vu plus tôt. Vous pouvez référencer cette requête nommée dans un mapping de classe : - - <class name="Person"> - <id name="id"> - <generator class="increment"/> - </id> - <property name="name" not-null="true"/> - <loader query-ref="person"/> -</class> + + + + + + +]]> Ceci fonctionne même avec des procédures stockées. Vous pouvez même définir une requête pour le chargement d'une collection : - - <set name="employments" inverse="true"> - <key/> - <one-to-many class="Employment"/> - <loader query-ref="employments"/> -</set> - - <sql-query name="employments"> - <load-collection alias="emp" role="Person.employments"/> - SELECT {emp.*} - FROM EMPLOYMENT emp - WHERE EMPLOYER = :id - ORDER BY STARTDATE ASC, EMPLOYEE ASC -</sql-query> + + + + + ]]> + + + + SELECT {emp.*} + FROM EMPLOYMENT emp + WHERE EMPLOYER = :id + ORDER BY STARTDATE ASC, EMPLOYEE ASC +]]> Vous pourriez même définir un chargeur d'entité qui charge une collection par jointure : - <sql-query name="person"> - <return alias="pers" class="Person"/> - <return-join alias="emp" property="pers.employments"/> - SELECT NAME AS {pers.*}, {emp.*} - FROM PERSON pers - LEFT OUTER JOIN EMPLOYMENT emp - ON pers.ID = emp.PERSON_ID - WHERE ID=? -</sql-query> + + + + SELECT NAME AS {pers.*}, {emp.*} + FROM PERSON pers + LEFT OUTER JOIN EMPLOYMENT emp + ON pers.ID = emp.PERSON_ID + WHERE ID=? +]]> diff --git a/documentation/manual/fr-FR/src/main/docbook/content/session_api.xml b/documentation/manual/fr-FR/src/main/docbook/content/session_api.xml index ae85237693..68abc923aa 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/session_api.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/session_api.xml @@ -94,6 +94,30 @@ Long generatedId = (Long) sess.save(fritz);]]> Vous pouvez aussi utiliser persist() à la place desave(), avec la sémantique définie plus tôt dans le brouillon d'EJB3. + + + + + persist() makes a transient instance persistent. + However, it doesn't guarantee that the identifier value will be assigned to + the persistent instance immediately, the assignment might happen at flush time. + persist() also guarantees that it will not execute an + INSERT statement if it is called outside of transaction + boundaries. This is useful in long-running conversations with an extended + Session/persistence context. + + + + + save() does guarantee to return an identifier. If an INSERT + has to be executed to get the identifier ( e.g. "identity" generator, not + "sequence"), this INSERT happens immediately, no matter if you are inside or + outside of a transaction. This is problematic in a long-running conversation + with an extended Session/persistence context. + + + + Alternativement, vous pouvez assigner l'identifiant en utilisant une version @@ -307,8 +331,8 @@ while ( iter.hasNext() ) { while ( kittensAndMothers.hasNext() ) { Object[] tuple = (Object[]) kittensAndMothers.next(); - Cat kitten = (Cat) tuple[0]; - Cat mother = (Cat) tuple[1]; + Cat kitten = (Cat) tuple[0]; + Cat mother = (Cat) tuple[1]; .... }]]> @@ -478,6 +502,13 @@ List cats = q.list();]]> utilisé, vous pouvez aussi définir des requêtes SQL nativez dans les méta-données, ou migrer des requêtes existantes vers Hibernate en les plaçant dans les fichiers de mapping. + UNTRANSLATED! + Also note that a query declaration inside a <hibernate-mapping> + element requires a global unique name for the query, while a query declaration inside a + <class> element is made unique automatically by prepending the + fully qualified name of the class, for example + eg.Cat.ByNameAndMaximumWeight. + @@ -560,16 +591,16 @@ List cats = crit.list();]]> l'API Hibernate, vous devez mettre les alias SQL entre accolades : - - - + + + Les requêtes SQL peuvent contenir des paramètres nommés et positionnels, comme des diff --git a/documentation/manual/fr-FR/src/main/docbook/content/toolset_guide.xml b/documentation/manual/fr-FR/src/main/docbook/content/toolset_guide.xml index c815d18d79..22455c934a 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/toolset_guide.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/toolset_guide.xml @@ -219,7 +219,9 @@ spécifie le nom d'une contrainte de clé étrangère générée pour une association, utilisez-la avec les éléments de mapping - <one-to-one>, <many-to-one>, <key>, et <many-to-many> + <one-to-one>, + <many-to-one>, <key>, + or <many-to-many> Notez que les extrêmités inverse="true" se seront pas prises en compte par SchemaExport. @@ -451,8 +453,8 @@ new SchemaExport(cfg).create(false, true);]]> - java -cp classpath_hibernate - net.sf.hibernate.tool.hbm2ddl.SchemaUpdate options fichiers_de_mapping + java -cp hibernate_classpaths + org.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files @@ -482,6 +484,9 @@ new SchemaExport(cfg).create(false, true);]]> --properties=hibernate.properties lire les propriétés de la base de données à partir d'un fichier + + --config=hibernate.cfg.xml + specify a .cfg.xml file diff --git a/documentation/manual/fr-FR/src/main/docbook/content/transactions.xml b/documentation/manual/fr-FR/src/main/docbook/content/transactions.xml index dbeb6839af..6a20af9234 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/transactions.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/transactions.xml @@ -800,7 +800,12 @@ catch (RuntimeException e) { pour conserver la Session et évitez de la sérialiser et de la transférer à la couche de présentation (i.e. Il est préférable de ne pas la conserver dans la session HttpSession .) - + + The extended session pattern, or session-per-conversation, is + more difficult to implement with automatic current session context management. + You need to supply your own implementation of the CurrentSessionContext + for this, see the Hibernate Wiki for examples. + diff --git a/documentation/manual/fr-FR/src/main/docbook/content/tutorial.xml b/documentation/manual/fr-FR/src/main/docbook/content/tutorial.xml index d315bc29cd..cc28f7cf18 100644 --- a/documentation/manual/fr-FR/src/main/docbook/content/tutorial.xml +++ b/documentation/manual/fr-FR/src/main/docbook/content/tutorial.xml @@ -681,7 +681,9 @@ public class EventManager { La méthode getCurrentSession() renvoie toujours l'unité de travail courante. Souvenez vous que nous avons basculé notre option de configuration au mécanisme basé sur le "thread" dans hibernate.cfg.xml. Par conséquent, le scope de l'unité de travail - courante est le thread java courant d'exécution. Ceci n'est pas totalement vrai. Une + courante est le thread java courant d'exécution. Ceci n'est pas totalement vrai. + + Une Session commence lorsqu'elle est vraiment utilisée la première fois, Lorsque nous appelons pour la première fois getCurrentSession(). Ensuite, elle est liée, par Hibernate, au thread courant. Lorsque la transaction s'achève @@ -691,7 +693,17 @@ public class EventManager { Ce modèle de programmation "thread-bound" est le moyen le plus populaire d'utiliser Hibernate. - + UNTRANSLATED + ! + Related to the unit of work scope, should the Hibernate Session be used to + execute one or several database operations? The above example uses one Session + for one operation. This is pure coincidence, the example is just not complex enough to show any + other approach. The scope of a Hibernate Session is flexible but you should + never design your application to use a new Hibernate Session for + every database operation. So even if you see it a few more times in + the following (very trivial) examples, consider session-per-operation + an anti-pattern. A real (web) application is shown later in this tutorial. + Lisez pour plus d'informations sur la gestion des transactions et leur démarcations. Nous n'avons pas géré les erreurs et rollback sur l'exemple précédent. @@ -801,7 +813,13 @@ else if (args[0].equals("list")) { les événements que vous avez stockés jusque là. Vous pouvez bien sûr aussi appeler l'action store plusieurs fois. - + UNTRANSLATED! + Note: Most new Hibernate users fail at this point and we see questions about + Table not found error messages regularly. However, if you follow the + steps outlined above you will not have this problem, as hbm2ddl creates the database + schema on the first run, and subsequent application restarts will use this schema. If + you change the mapping and/or database schema, you have to re-enable hbm2ddl once again. + @@ -1285,7 +1303,12 @@ public void removeFromEvent(Event event) { doesn't scale anymore with our growing application. --> + + + Let's turn this into a small web application. + + @@ -1305,27 +1328,18 @@ public void removeFromEvent(Event event) { Créons une nouvelle classe dans notre répertoire source, dans le package events: - - - - Le dateFormatter est un outil que nous utiliserons plus tard pour convertir les objets - Date depuis et vers des chaines de caractères. Il est propice de n'avoir qu'un - formatter comme membre de la servlet. - - - - La servlet n'accepte que les requêtes HTTP GET, la méthode à implémenter est donc - doGet(): + + + + The servlet handles HTTP GET requests only, hence, the method + we implement is doGet(): - + UNTRANSLATED + Do not use a new Hibernate Session for + every database operation. Use one Hibernate Session that is + scoped to the whole request. Use getCurrentSession(), so that + it is automatically bound to the current Java thread. + Ensuite, les actions possibles de la requêtes sont exécutées et la réponse HTML est rendue. Nous en parlerons plus tard.