[hibernate-commits] Hibernate SVN: r11544 - in trunk/HibernateExt/shards/doc/reference/fr: images and 2 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Mon May 21 10:56:13 EDT 2007
Author: anthonyHib
Date: 2007-05-21 10:56:13 -0400 (Mon, 21 May 2007)
New Revision: 11544
Added:
trunk/HibernateExt/shards/doc/reference/fr/images/
trunk/HibernateExt/shards/doc/reference/fr/images/hibernate_logo_a.png
trunk/HibernateExt/shards/doc/reference/fr/modules/
trunk/HibernateExt/shards/doc/reference/fr/modules/architecture.xml
trunk/HibernateExt/shards/doc/reference/fr/modules/configuration.xml
trunk/HibernateExt/shards/doc/reference/fr/modules/limitations.xml
trunk/HibernateExt/shards/doc/reference/fr/modules/querying.xml
trunk/HibernateExt/shards/doc/reference/fr/modules/resharding.xml
trunk/HibernateExt/shards/doc/reference/fr/modules/shardstrategy.xml
trunk/HibernateExt/shards/doc/reference/fr/styles/
trunk/HibernateExt/shards/doc/reference/fr/styles/fopdf.xsl
trunk/HibernateExt/shards/doc/reference/fr/styles/html.css
trunk/HibernateExt/shards/doc/reference/fr/styles/html.xsl
trunk/HibernateExt/shards/doc/reference/fr/styles/html_chunk.xsl
Log:
Added: trunk/HibernateExt/shards/doc/reference/fr/images/hibernate_logo_a.png
===================================================================
(Binary files differ)
Property changes on: trunk/HibernateExt/shards/doc/reference/fr/images/hibernate_logo_a.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/HibernateExt/shards/doc/reference/fr/modules/architecture.xml
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/modules/architecture.xml (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/modules/architecture.xml 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter id="shards-architecture">
+ <title>Architecture</title>
+ <sect1 id="shards-architecture-overview" revision="1">
+ <title>Vue d'ensemble</title>
+ <para>
+ Hibernate Shards est une extension d'Hibernate Core, conçu pour encapsuler et minimiser
+ la complexité de travailler avec des données fragmentées (horizontalement
+ partitionnées). Hibernate Shards peut être conceptuellement divisé en
+ deux domaines que vous aurez besoin de comprendre pour réussir. Les deux
+ domaines sont :
+ <itemizedlist mark="opencircle">
+ <listitem>
+ <para>la logique de fragmentation généralisée ;</para>
+ </listitem>
+ <listitem>
+ <para>la logique de fragmentation spécifique à l'application.</para>
+ </listitem>
+ </itemizedlist>
+ Nous discuterons de chacun de ces domaines à leur tour.
+ </para>
+ </sect1>
+ <sect1 id="shards-architecture-general" revision="1">
+ <title>La logique de fragmentation généralisée</title>
+ <para>Le but premier d'Hibernate Shards est de permettre aux développeurs
+ d'application d'interroger et de négocier des ensembles de données fragmentés
+ en utilisant l'API standard d'Hibernate Core. Ceci permet aux applications
+ existantes qui utilisent Hibernate, mais pas encore la fragmentation, d'adopter
+ notre solution sans modification majeure s'ils atteignent cette étape. Ceci
+ permet aussi aux développeurs d'application qui connaissent Hibernate, qui ont
+ besoin de fragmentation et qui partent de zéro, de devenir productifs en un
+ minimum de temps parce qu'il n'y a pas besoin de découvrir un nouvel outil.
+ Avec cet objectif en tête, il n'est pas surprenant qu'Hibernate Shards
+ soit composé principalement d'implémentations prenant en compte la fragmentation
+ de beaucoup d'interfaces d'Hibernate Core que vous connaissez et aimez.
+ </para>
+ <para>
+ La plupart du code applicatif en rapport avec Hibernate interagit avec
+ quatre interfaces fournies par Hibernate Core :
+ <itemizedlist mark="opencircle">
+ <listitem>
+ <para>
+ <classname>org.hibernate.Session</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.SessionFactory</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.Criteria</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.Query</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Hibernate Shards fournit des extensions prenant en compte la fragmentation
+ à ces quatre interfaces, ainsi votre code n'a pas besoin de savoir qu'il
+ interagit avec un ensemble de données fragmenté (à moins, bien sûr, que vous
+ ayez des raisons spécifiques pour révéler ce fait). Les extensions sont :
+ <itemizedlist mark="opencircle">
+ <listitem>
+ <para>
+ <classname>org.hibernate.shards.session.ShardedSession</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.shards.ShardedSessionFactory</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.shards.criteria.ShardedCriteria</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.shards.query.ShardedQuery</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ Les implémentations que nous fournissons pour ces quatre interfaces
+ servent de moteur à fragmentation, lequel connaît la logique de fragmentation
+ spécifique à l'application à travers vos différents stockages de données.
+ Nous n'espérons pas que les développeurs d'application aient besoin
+ d'écrire trop de code qui interagit sciemment avec ces interfaces, donc si
+ vous vous retrouvez en train de déclarer ou de passer des instances "Sharded",
+ revenez un pas en arrière et regardez si vous ne pouvez pas plutôt le faire avec
+ l'interface parente.
+ </para>
+ </sect1>
+ <sect1 id="shards-architecture-application" revision="1">
+ <title>La logique de fragmentation spécifique à l'application</title>
+ <para>
+ Chaque application qui utilise Hibernate Shards aura ses propres règles pour
+ répartir ses données à travers les fragments. Plutôt que de tenter d'anticiper
+ toutes ces règles (effort pratiquement voué à l'échec), nous avons fourni
+ un ensemble d'interfaces derrière lesquelles vous pouvez coder la logique
+ de distribution des données de votre application. Ces interfaces sont :
+ <itemizedlist mark="opencircle">
+ <listitem>
+ <para>
+ <classname>org.hibernate.shards.strategy.selection.ShardSelectionStrategy</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.shards.strategy.resolution.ShardResolutionStrategy</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>org.hibernate.shards.strategy.access.ShardAccessStrategy</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ Les implémentations que vous fournissez pour ces trois interfaces, plus
+ l'implémentation de la génération des identifiants que vous choisissez
+ (plus d'informations à ce sujet dans le chapitre "Stratégie de fragmentation")
+ constituent la <emphasis>stratégie de fragmentation</emphasis> de votre
+ application.
+ </para>
+ <para>
+ Pour vous aider à mettre en place cela rapidement, Hibernate Shards arrive
+ avec deux implémentations simples de ces interfaces. Nous attendons qu'elles
+ vous aident dans votre prototypage ou dans les premières étapes du développement
+ applicatif réel, mais nous espérons aussi que, tôt ou tard, la plupart des
+ applications fourniront leurs propres implémentations.
+ </para>
+ <para>Pour plus d'informations sur les stratégies de fragmentation, veuillez consulter le chapitre du même nom.</para>
+ </sect1>
+ <sect1 id="shards-architecture-requirements" revision="1">
+ <title>Pré-requis système</title>
+ <para>
+ Hibernate Shards a les mêmes pré-requis qu'Hibernate Core, avec la restriction
+ supplémentaire qui exige Java 1.5 ou supérieur.
+ </para>
+ </sect1>
+</chapter>
Added: trunk/HibernateExt/shards/doc/reference/fr/modules/configuration.xml
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/modules/configuration.xml (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/modules/configuration.xml 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,295 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="shards-configuration">
+ <title>Configuration</title>
+ <sect1 id="shards-configuration-overview" revision="1">
+ <title>Vue d'ensemble</title>
+ <para>
+ Lors de l'utilisation d'Hibernate Shards, vous vous retrouvez la plupart du temps
+ en train de faire des appels typiques à l'API d'Hibernate Core. Cependant,
+ pour avoir votre source de données fragmentées proprement configurée,
+ vous aurez besoin de comprendre quelques concepts spécifiques à Hibernate
+ Shards. Nous présenterons ces nouveaux concepts dans le cadre d'un exemple
+ concret. Examinons le modèle objet, le schéma de base de données, et
+ le mapping que nous utiliserons dans nos exemples à travers la documentation.
+ </para>
+ <para>
+ Notre application d'exemple recevra des rapports météorologiques de villes
+ du monde entier et stockera cette information dans une base de données
+ relationnelles.
+ </para>
+ <sect2 id="shards-configuration-overview-sample-schema" revision="1">
+ <title>Schéma de base de données d'un rapport météorologique</title>
+ <programlisting><![CDATA[
+CREATE TABLE WEATHER_REPORT (
+ REPORT_ID INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+ CONTINENT ENUM('AFRICA', 'ANTARCTICA', 'ASIA', 'AUSTRALIA', 'EUROPE', 'NORTH AMERICA', 'SOUTH AMERICA'),
+ LATITUDE FLOAT,
+ LONGITUDE FLOAT,
+ TEMPERATURE INT,
+ REPORT_TIME TIMESTAMP
+);
+ ]]></programlisting>
+ </sect2>
+ <sect2 id="shards-configuration-overview-sample-model" revision="1">
+ <title>Modèle objet d'un rapport météorologique</title>
+ <programlisting><![CDATA[
+public class WeatherReport {
+ private Integer reportId;
+ private String continent;
+ private BigDecimal latitude;
+ private BigDecimal longitude;
+ private int temperature;
+ private Date reportTime;
+
+ ... // getters et setters
+}
+ ]]></programlisting>
+ </sect2>
+ <sect2 id="shards-configuration-overview-sample-mapping" revision="1">
+ <title>Contenu de weather.hbm.xml</title>
+ <programlisting><![CDATA[
+<hibernate-mapping package="org.hibernate.shards.example.model">
+ <class name="WeatherReport" table="WEATHER_REPORT">
+ <id name="reportId" column="REPORT_ID">
+ <generator class="native"/>
+ </id>
+ <property name="continent" column="CONTINENT"/>
+ <property name="latitude" column="LATITUDE"/>
+ <property name="longitude" column="LONGITUDE"/>
+ <property name="temperature" column="TEMPERATURE"/>
+ <property name="reportTime" type="timestamp" column="REPORT_TIME"/>
+ </class>
+</hibernate-mapping>
+ ]]></programlisting>
+ </sect2>
+ </sect1>
+ <sect1 id="shards-configuration-sf" revision="1">
+ <title>Obtenir une ShardedSessionFactory</title>
+ <para>
+ Avant que nous vous montrions comment obtenir une
+ <classname>ShardedSessionFactory</classname>,
+ examinons le code qui vous permet d'avoir une
+ <classname>SessionFactory</classname> standard.
+ <programlisting><![CDATA[
+1 public SessionFactory createSessionFactory() {
+2 Configuration config = new Configuration();
+3 config.configure("weather.hibernate.cfg.xml");
+4 config.addResource("weather.hbm.xml");
+5 return config.buildSessionFactory();
+6 }
+]]></programlisting>
+ C'est assez simple. Nous instancions un nouvel objet
+ <classname>Configuration</classname> object (ligne 2), indiquons Ã
+ <classname>Configuration</classname> de lire ses propriétés Ã
+ partir d'une ressource nommée "weather.hibernate.cfg.xml" (ligne 3),
+ et ensuite fournissons
+ "weather.hbm.xml" comme une source de données de mapping OR (ligne 4).
+ Nous demandons alors à <classname>Configuration</classname>
+ de construire une
+ <classname>SessionFactory</classname>, que nous retournons (ligne 5).
+ </para>
+ <para>
+ Regardons aussi le fichier de configuration que nous chargeons :
+ <programlisting><![CDATA[
+ 1 <!-- Contenu de weather.hibernate.cfg.xml -->
+ 2 <hibernate-configuration>
+ 3 <session-factory name="HibernateSessionFactory">
+ 4 <property name="dialect">org.hibernate.dialect.MySQLInnoDBDialect</property>
+ 5 <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
+ 6 <property name="connection.url">jdbc:mysql://localhost:3306/mydb</property>
+ 7 <property name="connection.username">my_user</property>
+ 8 <property name="connection.password">my_password</property>
+ 9 </session-factory>
+ 10 </hibernate-configuration>
+ ]]></programlisting>
+ </para>
+ <para>
+ Comme vous pouvez le voir, il n'y a rien de particulièrement intéressant
+ dans le fichier de configuration ou le fichier de mapping.
+ </para>
+ <para>
+ Vous serez content d'apprendre que le processus de configuration de votre
+ application pout utiliser Hibernate Shards n'est pas radicalement différent.
+ La principale différence est que nous fournissons l'information de connexité
+ pour plusieurs sources de données, et nous décrivons aussi le comportement
+ de fragmentation désiré via une
+ <classname>ShardStrategyFactory</classname>. Examinons une exemple de code
+ de configuration pour notre application de rapports météorologiques,
+ que nous allons exécuter avec 3 fragments.
+ <programlisting><![CDATA[
+1 public SessionFactory createSessionFactory() {
+2 Configuration prototypeConfig = new Configuration().configure("shard0.hibernate.cfg.xml");
+3 prototypeConfig.addResource("weather.hbm.xml");
+4 List<Configuration> shardConfigs = new ArrayList<Configuration>();
+5 shardConfigs.add(new Configuration().configure("shard0.hibernate.cfg.xml"));
+6 shardConfigs.add(new Configuration().configure("shard1.hibernate.cfg.xml"));
+7 shardConfigs.add(new Configuration().configure("shard2.hibernate.cfg.xml"));
+8 ShardStrategyFactory shardStrategyFactory = buildShardStrategyFactory();
+9 ShardedConfiguration shardedConfig = new ShardedConfiguration(
+10 prototypeConfig,
+11 shardConfigs,
+12 shardStrategyFactory);
+13 return shardedConfig.buildShardedSessionFactory();
+14 }
+15
+16 ShardStrategyFactory buildShardStrategyFactory() {
+17 ShardStrategyFactory shardStrategyFactory = new ShardStrategyFactory() {
+18 public ShardStrategy newShardStrategy(List shardIds) {
+19 RoundRobinShardLoadBalancer loadBalancer = new RoundRobinShardLoadBalancer(shardIds);
+20 ShardSelectionStrategy pss = new RoundRobinShardSelectionStrategy(loadBalancer);
+21 ShardResolutionStrategy prs = new AllShardsShardResolutionStrategy(shardIds);
+22 ShardAccessStrategy pas = new SequentialShardAccessStrategy();
+23 return new ShardStrategyImpl(pss, prs, pas);
+24 }
+25 };
+26 return shardStrategyFactory;
+27 }
+ ]]></programlisting>
+ </para>
+ <para>
+ Que se passe-t-il ici ? D'abord, vous noterez que nous allouons réellement
+ quatre <classname>Configurations</classname>. La première <classname>Configuration</classname>
+ que nous allouons (ligne 2) est la <classname>Configuration</classname> prototype.
+ La <classname>ShardedSessionFactory</classname> que nous contruisons
+ éventuellement (ligne 13) contiendra des références aux 3 objets
+ <classname>SessionFactory</classname> standards. Chacun de ces 3 objets
+ <classname>SessionFactory</classname> standards aura été contruit à partir
+ de la configuration prototype. Les seuls attributs qui différeront de ces
+ objets <classname>SessionFactory</classname> standards sont :
+ <itemizedlist mark="opencircle">
+ <listitem>
+ <para>connection.url</para>
+ </listitem>
+ <listitem>
+ <para>connection.user</para>
+ </listitem>
+ <listitem>
+ <para>connection.password</para>
+ </listitem>
+ </itemizedlist>
+ Les trois objets <classname>Configuration</classname> que nous chargeons
+ (lignes 5 à 7) seront consultés pour l'url, l'utilisateur et le mot de
+ passe spécifiques aux bases de données des fragments, et c'est tout. Ce qui
+ veut dire que si vous changez les paramètres du pool de connexions dans
+ shard1.hibernate.cfg.xml, ils seront ignorés. Si vous ajoutez un autre fichier
+ de mapping à la <classname>Configuration</classname> chargée avec les
+ propriétés définies dans shard2.hibernate.cfg.xml, il sera ignoré.
+ A l'exception des propriétés listées plus haut, la configuration de notre
+ <classname>SessionFactory</classname> vient entièrement de la
+ <classname>Configuration</classname> prototype. Ceci peut sembler un peu strict,
+ mais le code de fragmentation a besoin de supposer que tous les fragments
+ sont configurés de la même manière.
+ </para>
+ <para>
+ Si vous examinez ce code et pensez qu'il semble un peu trop stupide pour
+ fournir des documents de configuration pleinement formés qui, pour économiser
+ deux propriétés spéciales, sont ignorés, soyez rassurés, nous avons regardé
+ ce code et pensé la même chose. Nous prévoyons de faire évoluer le mécanisme
+ de configuration. Nous avons choisi ce mécanisme-ci parce qu'il autorisait
+ la plus grande réutilisation de code de configuration qui était déjà disponible
+ dans Hibernate Core.
+ </para>
+ <para>
+ Une fois que nous avons construit nos objets
+ <classname>Configuration</classname>, nous avons besoin d'assembler
+ une <classname>ShardStrategyFactory</classname> (ligne 8). Une
+ <classname>ShardStrategyFactory</classname> est un objet qui sait comment
+ créer les 3 types de stratégie que les programmeurs peuvent utiliser
+ pour contrôler le comportement de fragmentation du système. Pour plus
+ d'informations à propos de ces stratégies, veuillez regarder les
+ chapitres intitulés "Stratégies de fragmentation".
+ </para>
+ <para>
+ Maintenant que nous avons instancié notre <classname>ShardStrategyFactory</classname>,
+ nous pouvons construire une <classname>ShardedConfiguration</classname> (ligne 9),
+ et une fois que nous avons notre <classname>ShardedConfiguration</classname> nous
+ pouvons lui demander de créer une <classname>ShardedSessionFactory</classname> (ligne 13).
+ Il est important de noter que <classname>ShardedSessionFactory</classname> étend <classname>SessionFactory</classname>.
+ Ceci signifie que nous pouvons retourner une <classname>SessionFactory</classname> standard (ligne 1).
+ Le code Hibernate de notre application n'a pas besoin de savoir qu'il
+ interagit avec des données fragmentées.
+ </para>
+ <para>
+ Examinons maintenant les fichiers de configuration et de mapping que nous
+ avons chargé. Vous les reconnaîtrez, mais il y a quelques ajouts et modifications clef
+ en rapport avec la fragmentation.
+ <programlisting><![CDATA[
+ 1 <!-- Contenu de shard0.hibernate.cfg.xml -->
+ 2 <hibernate-configuration>
+ 3 <session-factory name="HibernateSessionFactory0"> <!-- notez le nom différent -->
+ 4 <property name="dialect">org.hibernate.dialect.MySQLInnoDBDialect</property>
+ 5 <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
+ 6 <property name="connection.url">jdbc:mysql://localhost:3306/mydb</property>
+ 7 <property name="connection.username">my_user</property>
+ 8 <property name="connection.password">my_password</property>
+ 9 <property name="hibernate.connection.shard_id">0</property> <!-- nouveau -->
+ 10 <property name="hibernate.shard.enable_cross_shard_relationship_checks">true</property> <!-- nouveau -->
+ 11 </session-factory>
+ 12 </hibernate-configuration>
+ ]]></programlisting>
+ <programlisting><![CDATA[
+ 1 <!-- Contenu de shard1.hibernate.cfg.xml -->
+ 2 <hibernate-configuration>
+ 3 <session-factory name="HibernateSessionFactory1"> <!-- notez le nom différent -->
+ 4 <property name="dialect">org.hibernate.dialect.MySQLInnoDBDialect</property>
+ 5 <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
+ 6 <property name="connection.url">jdbc:mysql://localhost:3306/mydb</property>
+ 7 <property name="connection.username">my_user</property>
+ 8 <property name="connection.password">my_password</property>
+ 9 <property name="hibernate.connection.shard_id">1</property> <!-- nouveau -->
+ 10 <property name="hibernate.shard.enable_cross_shard_relationship_checks">true</property> <!-- nouveau -->
+ 11 </session-factory>
+ 12 </hibernate-configuration>
+ ]]></programlisting>
+ Nous passerons outre le contenu de shard2.hibernate.cfg.xml puisqu'il
+ devrait être évident. Nous donnons à chaque session factory un nom
+ unique via l'attribut "name" de l'élément "session-factory", et nous leur
+ donnons aussi un identifiant de fragment. Ceci est obligatoire. Si vous
+ essayez de configurer une
+ <classname>ShardedSessionFactory</classname> avec un objet
+ <classname>Configuration</classname> qui n'a pas d'identifiant de fragment,
+ vous obtiendrez une erreur. Actuellement nous obligeons à ce que l'idenfiant de
+ fragment d'une des session factory soit 0. Au-delà de ça, la représentation
+ interne d'un identifiant de fragment est un, donc toutes les valeurs dans
+ cette plage sont légales. Finalement, chaque fragment qui est mappé dans une
+ <classname>ShardedSessionFactory</classname> doit avoir un identifiant unique.
+ Si vous avez un fragment dupliqué, vous aurez une erreur.
+ </para>
+ <para>
+ L'autre ajout notable est la propriété, plutôt verbeuse mais heureusement descriptive,
+ "hibernate.shard.enable_cross_shard_relationship_checks.". Vous pouvez lire
+ d'avantage à ce propos dans le chapitre sur les limitations.
+ </para>
+ <para>
+ Maintenant regardons de nouveau comment le fichier de mapping a changé.
+ <programlisting><![CDATA[
+<hibernate-mapping package="org.hibernate.shards.example.model">
+ <class name="WeatherReport" table="WEATHER_REPORT">
+ <id name="reportId" column="REPORT_ID" type="long">
+ <generator class="org.hibernate.shards.id.ShardedTableHiLoGenerator"/>
+ </id>
+ <property name="continent" column="CONTINENT"/>
+ <property name="latitude" column="LATITUDE"/>
+ <property name="longitude" column="LONGITUDE"/>
+ <property name="temperature" column="TEMPERATURE"/>
+ <property name="reportTime" type="timestamp" column="REPORT_TIME"/>
+ </class>
+</hibernate-mapping>
+ ]]></programlisting>
+ Le seul changement signficatif dans le fichier de mapping par rapport à la
+ version sans fragmentation est dans notre sélection d'un générateur
+ d'idenfitiant pour données fragmentées. Nous couvrirons cette génération
+ d'identifiants plus en détail dans le chapitre sur les stratégies de
+ fragmentation.
+ </para>
+ </sect1>
+ <sect1 id="shards-configuration-limitations" revision="1">
+ <title>Limitations de la configuration</title>
+ <para>
+ Beaucoup d'entre vous réaliserons rapidement que le mécanisme de configuration
+ que nous avons fourni ne fonctionnera pas si vous configurez votre
+ <classname>SessionFactory</classname> via JPA ou Hibernate Annotations.
+ C'est vrai. Nous espérons que ces insuffisances seront corrigées sous peu.
+ </para>
+ </sect1>
+</chapter>
Added: trunk/HibernateExt/shards/doc/reference/fr/modules/limitations.xml
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/modules/limitations.xml (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/modules/limitations.xml 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="shards-limitations">
+ <title>Limitations</title>
+ <sect1 id="shards-limitations-api" revision="1">
+ <title>Implémentation incomplète de l'API Hibernate</title>
+ <para>
+ Pour accélérer la sortie initiale d'Hibernate Shards, certaines parties
+ de l'API Hibernate que nous utilisons rarement n'ont pas été implémentées.
+ Bien sûr, des choses que nous utilisons rarement sont probablement critiques
+ pour d'autres applications, donc si nous vous avons délaissé, nous nous en excusons.
+ Nous prévoyons d'implémenter le reste de l'API rapidement. Pour savoir quelles
+ méthodes ne sont pas implémentées, veuillez voir la javadoc de
+ <classname>ShardedSessionImpl</classname>, <classname>ShardedCriteriaImpl</classname>,
+ et <classname>ShardedQueryImpl</classname>.
+ </para>
+ </sect1>
+ <sect1 id="shards-limitations-cross-shard" revision="1">
+ <title>Graphes d'objets inter-fragments</title>
+ <para>
+ Hibernate Shards ne prend pas en charge actuellement les graphes d'objets
+ inter-fragments.
+ </para>
+ <para>
+ En d'autres mots, il est illégal de créer une association entre des objets A et B
+ quand A et B vivent sur des fragments différents. Pour contourner cela,
+ il faut définir une propriété sur A qui identifie de manière unique un
+ objet de type B, et l'utiliser pour charger un objet B (Vous souvenez-vous comment
+ la vie était avant Hibernate ? Oui, juste comme ça).
+ </para>
+ <para>
+ Par exemple :
+ <programlisting>
+ --besoin d'un domaine pour les exemples--
+ </programlisting>
+ </para>
+ <para>
+ Dans certaines applications, votre modèle peut être construit de telle
+ manière qu'il est difficile de faire ce genre d'erreur, mais dans d'autres
+ ça peut être plus facile. La chose effrayante ici est que si vous faîtes
+ cette erreur, Hibernate prendra en compte le "mauvais" objet dans la liste
+ pour en faire un nouvel objet et, supposant que vous avez activé les
+ opérations en cascade pour cette relation, créera une nouvelle version de
+ cet objet sur un fragment différent. C'est le problème. Pour aider Ã
+ éviter ce genre de chose, nous avons un intercepteur appelé
+ <classname>CrossShardRelationshipDetectingInterceptor</classname> qui
+ vérifie les relations inter-fragments pour tous les objets qui sont
+ créés ou sauvegargés.
+ </para>
+ <para>
+ Malheureusement il y a un coût associé à l'utilisation de <classname>CrossShardRelationshipDetectingInterceptor</classname>.
+ Pour déterminer le fragment sur lequel un objet associé réside, nous avons besoin de récupérer
+ l'objet en base de données, donc si vous avez des associations chargées Ã
+ la demande l'intercepteur résoudra ces associations comme partie de ses vérifications.
+ C'est potentiellement assez coûteux, et peut ne pas être approprié pour un
+ système de production. Avec ça en tête, nous avons simplifié l'activation ou non
+ de cette vérification via la propriété "hibernate.shard.enable_cross_shard_relationship_checks"
+ que nous avons référencé dans le chapitre sur la configuration. Si cette
+ propriété est positionnée à "true", un <classname>CrossShardRelationshipDetectingInterceptor</classname>
+ sera inscrit à chaque <classname>ShardedSession</classname> créée.
+ Ne vous inquiétez pas, vous pouvez toujours inscrire votre propre intercepteur.
+ Notre attente est que la plupart des applications auront activé cette
+ vérification dans leurs environnements de développement et d'assurance qualité,
+ et désactivé dans leurs environnements de tests et de production.
+ </para>
+ </sect1>
+ <sect1 id="shards-limitations-txns" revision="1">
+ <title>Transactions réparties</title>
+ <para>
+ Hibernate Shards ne fournit pas de prise en charge pour les transactions
+ réparties dans un environnement non géré. Si votre application requiert
+ des transactions réparties, vous avez besoin de brancher une implémentation
+ de gestion de transactions qui prend en charge les transactions réparties.
+ </para>
+ </sect1>
+ <sect1 id="shards-limitations-interceptors" revision="1">
+ <title>Intercepteurs à état</title>
+ <para>
+ Nous avons fait de notre mieux pour que, dans l'ensemble, le code
+ d'Hibernate Core s'exécute bien lors de l'utilisation d'Hibernate Shards.
+ Il y a, malheureusement, des exceptions, et une d'entre elles est quand
+ votre application a besoin d'utliser un
+ <classname>org.hibernate.Interceptor</classname>
+ qui maintient son état.
+ </para>
+ <para>
+ Les intercepteurs à état (NdT : stateful) ont besoin d'un traitement particulier parce que,
+ sous le capot, nous instancions une
+ <classname>org.hibernate.SessionImpl</classname> par fragment. Si nous voulons un
+ <classname>Interceptor</classname> associé à la
+ <classname>Session</classname>, nous avons besoin de passer par
+ l'<classname>Interceptor</classname>, quelqu'il soit, qui était fourni quand la
+ <classname>ShardedSession</classname> a été créée. Si cet
+ <classname>Interceptor</classname> est à état, l'état de
+ l'<classname>Interceptor</classname> pour une
+ <classname>Session</classname> sera visible dans toutes les
+ <classname>Session</classname>s. Si vous réfléchissez aux choses qui sont typiquement faites dans des
+ <classname>Interceptor</classname>s à état (audit par exemple), vous pouvez voir comment
+ cela peut poser problème.
+ </para>
+ <para>
+ Notre solution est d'obliger les utilisateurs à fournir une
+ <classname>StatefulInterceptorFactory</classname> quand ils créent leurs
+ objets <classname>Session</classname> (lesquels sont réllement des
+ <classname>ShardedSession</classname>s). Si
+ l'<classname>Interceptor</classname> fourni implémente cette interface,
+ Hibernate Shards assurera qu'une nouvelle instance du type de
+ <classname>Interceptor</classname> retournée par
+ <classname>StatefulInterceptorFactory.newInstance()</classname> sera passée
+ à chaque <classname>Session</classname> qui est créée sous le capot.
+ Voici un exemple :
+ <programlisting><![CDATA[
+public class MyStatefulInterceptorFactory extends BaseStatefulInterceptorFactory {
+ public Interceptor newInstance() {
+ return new MyInterceptor();
+ }
+}
+]]></programlisting>
+
+ </para>
+ <para>
+ Beaucoup d'implémentations d'<classname>Interceptor</classname> requièrent
+ une référence à la <classname>Session</classname> à laquelle elles sont associées.
+ Dans le cas d'un <classname>Interceptor</classname> à état, vous voulez que
+ votre <classname>Interceptor</classname> ait une référence à la
+ <classname>Session</classname> réelle (spécifique au fragment). Pour faciliter
+ cela, vous avez le choix d'avoir le type d'<classname>Interceptor</classname>
+ qui est construit par la <classname>StatefulInterceptorFactory</classname>
+ [...]
+ Si l'<classname>Interceptor</classname> contruit par la
+ <classname>StatefulInterceptorFactory</classname> implémente cette interface,
+ Hibernate Shards fournira
+
+ to have a reference to the real (shard-specific) <classname>Session</classname>, not the shard-aware
+ <classname>Session</classname>. In order to facilitate this, you have the choice of having the type of
+ <classname>Interceptor</classname> that is constructed by the
+ <classname>StatefulInterceptorFactory</classname> implement the
+ <classname>RequiresSession</classname> interface.[...] If the
+ <classname>Interceptor</classname> constructed by the
+ <classname>StatefulInterceptorFactory</classname> implements this interface, Hibernate Shards will provide the
+ <classname>Interceptor</classname> with a reference to the real (shard-specific)
+ <classname>Session</classname> once the factory constructs it. This way your
+ <classname>Interceptor</classname> can safely and accurately interact with a specific shard. Here's an example:
+ <programlisting><![CDATA[
+public class MyStatefulInterceptor implements Interceptor, RequiresSession {
+ private Session session;
+
+ public void setSession(Session session) {
+ this.session = session;
+ }
+
+ ... // Implémentation de l'interface Interceptor
+}
+]]></programlisting>
+ </para>
+ <para>
+ Vu la nature fondamentale du problème, nous ne nous attendons pas à changer cela de suite.
+ </para>
+ </sect1>
+ <sect1 id="shards-limitations-base-ids" revision="1">
+ <title>Des objets avec des identifiants qui sont des types de base</title>
+ <para>
+ Avec Hibernate, peu importe ce que vos objets du modèle utilisent commen identifiant
+ tant qu'il peut être représenté par un <classname>Serializable</classname>
+ (ou encapsulé automatiquement dans un <classname>Serializable</classname>).
+ Avec Hibernate Shards vous êtres légèrement plus contraints parce que nous
+ ne prenons pas en charge les types de base.
+ </para>
+ <para>
+ Ainsi, ceci n'est pas bon :
+ <programlisting><![CDATA[
+public class WeatherReport {
+ private int weatherReportId; // problème
+
+ public int getWeatherReportId() {
+ return weatherReportId;
+ }
+
+ public void setWeatherReportId(int id) {
+ weatherReportId = id;
+ }
+}
+]]></programlisting>
+ </para>
+ <para>
+ Mais ceci est adorable :
+ <programlisting><![CDATA[
+public class WeatherReport {
+ private Integer weatherReportId; // correct
+
+ public Integer getWeatherReportId() {
+ return weatherReportId;
+ }
+
+ public void setWeatherReportId(Integer id) {
+ weatherReportId = id;
+ }
+}
+]]></programlisting>
+ </para>
+ <para>
+ Avons-nous une bonne raison à cette limitation ? Pas réellement. C'est
+ le résultat d'un choix d'implémentation qui a filtré et qui a un peu
+ aggravé la vie de chacun. Si vous devez simplement utiliser
+ Hibernate Shards et modéliser vos identifiants avec des types de base,
+ n'appelez pas <classname>Session.saveOrUpdate</classname>. Nous avons pour
+ objectif de trouver une solution à ce problème bientôt et de vous laisser modéliser
+ comme bon vous semble (malgré cela, nous préférerions des identifiants objet parce
+ qu'ils permettent de déterminer plus facilement si un objet s'est vu assigner
+ un identifiant ou pas).
+ </para>
+ </sect1>
+ <sect1 id="shards-limitations-replicated-data" revision="1">
+ <title>Données répliquées</title>
+ <para>
+ Même si c'est un framework pour le partionnement horizontal, il y a pratiquement
+ toujours des données en lecture seules (ou du moins changeant rarement) qui vivent
+ dans chaque fragment. Si vous lisez juste ces entités nous n'avons pas de problème,
+ mais si vous voulez associer ces entités avec des entités fragmentées nous allons
+ avoir des problèmes. Supposez que vous ayez une table Country sur chaque fragment avec
+ exactement les mêmes données, et supposez que WeatherReport a un membre Country.
+ Comment garantissons-nous que le Country que vous associez à ce WeatherReport
+ est associé au même fragment que celui du WeatherReport ? Si nous nous trompons,
+ nous finirons avec une relation entre plusieurs fragments, et ce n'est pas bien.
+ </para>
+ <para>
+ Nous avons des idées pour rendre cela facile à traiter, mais nous ne les avons
+ pas encore implémentées. Pour faire court, nous pensons qu'il est plus sûr
+ pour vous de ne pas créer relations objet entre des entités fragmentées et
+ des entités répliquées. En d'autres mots, modélisez seulement la relation
+ comme vous feriez si vous n'utilisiez pas d'ORM. Nous savons que c'est
+ maladroit et annuyant. Nous nous en occuperons bientôt.
+ </para>
+ </sect1>
+</chapter>
Added: trunk/HibernateExt/shards/doc/reference/fr/modules/querying.xml
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/modules/querying.xml (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/modules/querying.xml 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter id="shards-querying">
+ <title>Requêtes</title>
+ <sect1 id="shards-querying-overview" revision="1">
+ <title>Vue d'ensemble</title>
+ <para>
+ Exécuter des requêtes à travers des fragments peut être difficile. Dans
+ ce chapitre nous parlerons de ce qui fonctionne, ce qui ne fonctionne pas, et
+ ce que vous pouvez faire pour éviter les ennuis.
+ </para>
+ </sect1>
+ <sect1 id="shards-querying-criteria" revision="1">
+ <title>Criteria</title>
+ <para>
+ Comme nous en avons parlé dans le chapitre sur les limitations, nous
+ n'avons pas encore d'implémentation complète de l'API Hibernate Core.
+ Cette limitation s'applique à <classname>ShardedCriteriaImpl</classname>,
+ qui est une implémentation de l'interface <classname>Criteria</classname>
+ prenant en compte les fragments. Dans ce chapitre nous n'entrerons pas dans
+ les détails des choses spécifiques qui n'ont pas été implémentées. Nous
+ allons plutôt discuter des types de requêtes <classname>Criteria</classname>
+ qui sont problématiques dans un environnement fragmenté.
+ </para>
+ <para>
+ Dis simplement, les requêtes qui effectuent des tris posent problème. Pourquoi ?
+ Parce que nous ne pouvons pas retourner une liste proprement triée sans la
+ capacité de comparer une valeur de la liste à toute autre valeur de la liste,
+ et la liste entière n'est pas disponible jusqu'à ce que tous les résultats
+ des requêtes individuelles aient été collectés dans la partie applicative.
+ Le tri a besoin de s'effectuer à l'intérieur d'Hibernate Shards, et pour
+ que cela arrive, nous demandons à tous les objets retournés par une requête
+ <classname>Criteria</classname> avec une clause "order-by" d'implémenter
+ l'interface <classname>Comparable</classname>. Si le type des objets que
+ vous retournez n'implémente pas cette interface, vous aurez une exception.
+ </para>
+ <para>
+ Les clauses "distinct" posent aussi problème. Tellement de problèmes, en fait,
+ que pour le moment nous les prenons même pas en charge. Désolé pour ça.
+ </para>
+ <para>
+ D'un autre côté, alors que "distinct" et "order-by" posent problèmes, les
+ agrégats fonctionnent bien. Considérez l'exemple suivante :
+ <programlisting><![CDATA[
+ // récupère la moyenne de toutes les températures enregistrées depuis jeudi dernier
+ Criteria crit = session.createCriteria(WeatherReport.class);
+ crit.add(Restrictions.gt("timestamp", lastThursday));
+ crit.setProjection(Projections.avg("temperature"));
+ return crit.list();
+ ]]></programlisting>
+ Dans un environnement avec un seul fragment, cette requête peut obtenir
+ une réponse facilement, mais dans un environnement avec plusieurs fragments
+ c'est un peu plus embêtant. Pourquoi ? Parce qu'obtenir la moyenne de chaque
+ fragment n'est pas suffisant pour calculer la moyenne à travers tous les
+ fragments. Pour calculer ce morceau d'informations, nous n'avons pas seulement
+ besoin de la moyenne mais du nombre d'enregistrements de chaque fragment.
+ C'est exactement ce que nous faisons, et l'impact sur les performances
+ (faire un "count" supplémentaire dans chaque requête) est probablement
+ négligeable. Maintenant, si nous voulions la médiane, nous aurions des problèmes
+ (ajouter le "count" à la requête ne fournirait pas assez d'informations pour
+ réaliser le calcul), mais pour le moment <classname>Criteria</classname>
+ n'expose pas de fonction médiane, donc nous traiterons ça lorsque cela
+ arrivera et sera un problème.
+ </para>
+ </sect1>
+ <sect1 id="shards-querying-hql" revision="1">
+ <title>HQL</title>
+ <para>
+ Notre prise en charge de HQL n'est pas, pour le moment, aussi bon que
+ la prise en charge des requêtes <classname>Criteria</classname>. Nous n'avons
+ pas encore implémenté d'extensions à l'analyseur lexico-syntaxique de
+ requêtes, donc nous prenons pas en charge "distinct", "order-by", ou les agrégats.
+ Cela signifie que vous pouvez seulement utiliser HQL pour des requêtes très
+ simples. Vous feriez probablement mieux d'éviter le HQL de cette version
+ si vous le pouvez.
+ </para>
+ </sect1>
+ <sect1 id="shards-querying-strategy" revision="1">
+ <title>Use of Shard Strategy When Querying</title>
+ <para>
+ Le seul composant de votre stratégie de fragmentation qui est consulté lors
+ de l'exécution d'une requête (<classname>Criteria</classname> ou HQL) est
+ la <classname>ShardAccessStrategy</classname>. <classname>ShardSelectionStrategy</classname>
+ est ignorée parce qu'exécuter une requête ne crée pas de nouvel enregistrement
+ dans la base de données. <classname>ShardResolutionStrategy</classname>
+ est ignorée parce qu'actuellement nous partons du principe que vous voulez
+ toujours que votre requête soit exécutée sur tous les fragments. Si ce n'est
+ pas le cas, la meilleure chose à faire de transtyper votre <classname>Session</classname>
+ en une <classname>ShardedSession</classname> et d'en extraire la <classname>Session</classname>
+ spécifique au fragment dont vous avez besoin. Maladroit, mais ça fonctionne.
+ Nous proposerons une meilleure solution dans une prochaine version.
+ </para>
+ </sect1>
+</chapter>
Added: trunk/HibernateExt/shards/doc/reference/fr/modules/resharding.xml
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/modules/resharding.xml (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/modules/resharding.xml 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="shards-resharding">
+ <title>Refragmentation</title>
+ <para>
+ Quand un ensemble de données d'une application grossit au-delà de la capacité
+ des bases de données allouée à l'application, il devient nécessaire d'ajouter
+ plus de bases de données, et il est souvent désirable de redistribuer les
+ données à travers les fragments (soit pour réussir une répartition des charges
+ propre, soit pour satisfaire les invariants de l'application) : ceci s'appelle
+ la refragmentation. La refragmentation est problème compliqué, et elle peut être
+ la source de complication majeures dans la gestion de votre application de production
+ si elle n'est pas prise en compte durant la conception. Pour atténuer le
+ supplice associé à la refragmentation, Hibernate Shards fournit la prise en charge
+ de fragments virtuels.
+ </para>
+ <sect1 id="shards-resharding-virtual" revision="1">
+ <title>Fragments virtuels</title>
+ <para>
+ Dans le cas général, chaque objet vit sur un fragment. Refragmenter consiste
+ en deux tâches : déplacer l'objet vers un autre fragment, et changer les
+ mappings objet-fragment. Le mapping objet-fragment est capturé soit par
+ l'identifiant du fragment codé dans l'identifiant de l'objet, soit par
+ la logique interne de la stratégie de résolution du fragment que l'objet utilise.
+ Dans le premier cas, refragmenter demanderait de changer tous les identifiants
+ des objets et les clefs étrangères. Dans le second cas, refragmenter pourrait
+ demander n'importe quoi allant du changement de configuration d'exécution
+ d'une <classname>ShardResolutionStrategy</classname> donnée au changement
+ d'algorithme de la <classname>ShardResolutionStrategy</classname>. Malheureusement,
+ le problème de changer des mappings objet-fragment devient même pire une fois
+ que l'on prend en compte le fait que Hibernate Shards ne prend pas en
+ charge les relations à travers plusieurs fragments. Cette limitation nous
+ empêche de déplacer un sous-ensemble d'un graphe d'objets d'un fragment vers
+ un autre.
+ </para>
+ <para>
+ La tâche de changer de mapping objet-fragment peut être simplifiée en ajoutant
+ un niveau d'indirection - chaque objet vit sur un fragment virtuel, et chaque
+ fragment virtuel est mappé vers un fragment physique. Durant la conception,
+ les développeurs doivent décider du nombre maximum de fragments physiques
+ dont l'application aura besoin. Ce maximum est alors utilisé comme le nombre
+ de fragments virtuels, et ces fragments virtuels sont alors mappés vers des
+ fragments physiques actuellement requis par l'application. Puisque tous les
+ <classname>ShardSelectionStrategy</classname>,
+ <classname>ShardResolutionStrategy</classname>, et
+ <classname>ShardEncodingIdentifierGenerator</classname> d'Hibernate Shards
+ opèrent sur des fragments virtuels, les objets seront répartis correctement
+ Ã travers les fragments virtuels. Durant la refragmentation, les mappings
+ objet-fragment peuvent maintenant être simplement modifié en changeant les
+ mappings de fragments virtuels vers des fragments physiques.
+ </para>
+ <para>
+ Si vous vous inquiétez à propos de l'estimation correcte du nombre maximum
+ de fragments physiques dont votre application a besoin, visez haut. Les
+ fragments virtuels ne coûtent pas grand chose. En fin de compte, vous serez bien mieux
+ avec des fragments virtuels en trop plutôt que de devoir en rajouter.
+ </para>
+ <para>
+ Pour activer la fragmentation virtuelle, vous avez besoin de créer votre
+ <classname>ShardedConfiguration</classname> avec une Map des identifiants
+ des fragments virtuels vers les identifiants des fragments physiques. Voici
+ un exemple où nous avons 4 fragments virtuels mappés vers 2 fragments physiques.
+<programlisting><![CDATA[
+Map<Integer, Integer> virtualShardMap = new HashMap<Integer, Integer>();
+virtualShardMap.put(0, 0);
+virtualShardMap.put(1, 0);
+virtualShardMap.put(2, 1);
+virtualShardMap.put(3, 1);
+ShardedConfiguration shardedConfig =
+ new ShardedConfiguration(
+ prototypeConfiguration,
+ configurations,
+ strategyFactory,
+ virtualShardMap);
+return shardedConfig.buildShardedSessionFactory();
+]]></programlisting>
+ Pour ensuite transformer le fragment virtuel en mapping de fragments physiques,
+ il faut seulement changer la <classname>virtualShardToShardMap</classname>
+ passée au constructeur.
+ </para>
+ <para>
+ Nous avons mentionné que la deuxième tâche durant la repartition est de
+ déplacer les données d'un fragment physique vers un autre. Hibernate Shards
+ n'essaie pas de fournir de prise en charge automatique pour cela puisque
+ c'est en général très spécifique à l'application, et la complexité varie
+ selon le besoin potentiel de refragmentation à chaud, de l'architecture
+ de déploiement de l'application, etc.
+ </para>
+ </sect1>
+</chapter>
Added: trunk/HibernateExt/shards/doc/reference/fr/modules/shardstrategy.xml
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/modules/shardstrategy.xml (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/modules/shardstrategy.xml 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,268 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="shards-shardstrategy">
+ <title>Shard Strategy</title>
+ <sect1 id="shards-strategy-overview" revision="1">
+ <title>Vue d'ensemble</title>
+ <para>
+ Hibernate Shards vous donne une énorme flexibilité pour configurer la
+ manière dont vos données sont réparties à travers vos fragments et la
+ façon d'interroger vos données à travers vos fragments. Le point d'entrée
+ pour cette configuration est l'interface
+ <classname>org.hibernate.shards.strategy.ShardStrategy</classname> :
+ <programlisting><![CDATA[
+public interface ShardStrategy {
+ ShardSelectionStrategy getShardSelectionStrategy();
+ ShardResolutionStrategy getShardResolutionStrategy();
+ ShardAccessStrategy getShardAccessStrategy();
+}
+]]></programlisting>
+ Comme vous pouvez le voir, une
+ <classname>ShardStrategy</classname> est composée de trois sous-stratégies.
+ Nous parlerons d'elles chacune leur tour.
+ </para>
+ </sect1>
+ <sect1 id="shards-strategy-shardaccess" revision="1">
+ <title>ShardAccessStrategy</title>
+ <para>
+ Nous commencerons avec la plus simple des stratégies :
+ <classname>ShardAccessStrategy</classname>. Hibernate Shards utilise la
+ <classname>ShardAccessStrategy</classname> pour déterminer comment appliquer
+ les opérations de base de données à travers plusieurs fragments. La
+ <classname>ShardAccessStrategy</classname> est consultée lorsque vous
+ exécutez une requête sur vos fragments. Nous avons déjà fourni deux implémentations
+ de cette interface que nous pensons suffisantes pour la majorité des applications.
+ </para>
+ <sect2 id="shards-strategy-shardaccess-seq" revision="1">
+ <title>SequentialShardAccessStrategy</title>
+ <para>
+ <classname>SequentialShardAccessStrategy</classname> se comporte
+ exactement comme l'indique son nom : les requêtes sont exécutées
+ en séquence sur vos fragments. Selon le type de requêtes que vous
+ exécutez, vous pouvez vouloir éviter cette implémentation parce
+ qu'elle exécutera les requêtes à travers les fragments dans le même
+ ordre à chaque fois. Si vous exécutez beaucoup de requêtes limitées
+ en nombre de lignes retournées et non triées, ceci <emphasis>pourrait</emphasis>
+ donner lieu à une pauvre utilisation de vos fragments (les fragments
+ apparaissant en tête de liste seront harcelés, et ceux en fin de liste
+ resteront là à ne rien faire, à se croiser les doigts). Si ceci vous
+ concerne, vous devriez plutôt envisager d'utiliser la
+ <classname>LoadBalancedSequentialShardAccessStrategy</classname>.
+ Cette implémentation reçoit une vue alternée de vos fragments à chaque
+ invocation, et ainsi distribue également la charge de requêtes.
+ </para>
+ </sect2>
+ <sect2 id="shards-strategy-shardaccess-par" revision="1">
+ <title>ParallelShardAccessStrategy</title>
+ <para>
+ <classname>ParallelShardAccessStrategy</classname> se comporte
+ exactement comme l'indique son nom : les requêtes sont exécutées
+ sur les fragments en parallèle. Lorsque vous utilisez cette
+ implémentation, vous avez besoin de fournir un
+ <classname>java.util.concurrent.ThreadPoolExecutor</classname> qui
+ soit approprié aux performances et aux besoins de votre application.
+ Voici un simple exemple :
+ <programlisting><![CDATA[
+ ThreadFactory factory = new ThreadFactory() {
+ public Thread newThread(Runnable r) {
+ Thread t = Executors.defaultThreadFactory().newThread(r);
+ t.setDaemon(true);
+ return t;
+ }
+ };
+
+ ThreadPoolExecutor exec =
+ new ThreadPoolExecutor(
+ 10,
+ 50,
+ 60,
+ TimeUnit.SECONDS,
+ new SynchronousQueue<Runnable>(),
+ factory);
+
+ return new ParallelShardAccessStrategy(exec);
+ ]]></programlisting>
+Veuillez noter que ce sont juste des valeurs d'exemple - une configuration propre
+d'un pool de threads va au-delà de la portée de ce document.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="shards-strategy-shardselection" revision="1">
+ <title>ShardSelectionStrategy</title>
+ <para>
+ Hibernate Shards utilise la
+ <classname>ShardSelectionStrategy</classname> pour déterminer le fragment
+ sur lequel un nouvel objet devrait être créé. Il vous revient entièrement
+ de décider à quoi doit ressembler l'implémentation de cette interface,
+ mais nous avons fourni une implémentation round-robin pour commencer
+ (<classname>RoundRobinShardSelectionStrategy</classname>). Nous espérons
+ que de nombreuses applications voudrons implémenter une fragmentation
+ basée sur les attributs, ainsi pour notre application d'exemple qui
+ stocke les rapports météo fragmentons les rapports par continent dont
+ les rapports sont originaires :
+
+ <programlisting><![CDATA[
+public class WeatherReportShardSelectionStrategy implements ShardSelectionStrategy {
+ public ShardId selectShardIdForNewObject(Object obj) {
+ if(obj instanceof WeatherReport) {
+ return ((WeatherReport)obj).getContinent().getShardId();
+ }
+ throw new IllegalArgumentException();
+ }
+}
+]]></programlisting>
+
+ </para>
+ <para>
+ Il est important de noter que si un graphe d'objets multi-niveau est sauvegardé
+ via la fonctionnalité de cascade d'Hibernate, la
+ <classname>ShardSelectionStrategy</classname> sera seulement consultée
+ lors de la sauvegarde de l'objet de plus haut niveau. Tous les objets
+ enfants seront automatiquement sauvegardés sur le même fragment que le
+ parent. Vous pouvez trouver votre <classname>ShardSelectionStrategy</classname>
+ plus facile à implémenter si vous empêcher les développeur de créer de
+ nouveaux objets à plus d'un niveau dans votre hiérarchie d'objets. Vous
+ vous pouvez accomplir cela en informant votre <classname>ShardSelectionStrategy</classname>
+ des objets de plus haut niveau de votre modèle, et ainsi lever une exception
+ si elle rencontre un objet qui ne fait pas partie de cet ensemble. Si vous
+ ne souhaitez pas imposer cette restriction, souvenez-vous juste que si
+ vous effectuez une sélection des fragments basée sur les attributs, les
+ attributs que vous utilisez pour prendre votre décision ont besoin d'être
+ disponibles sur chaque objet qui est passé à session.save().
+ </para>
+ </sect1>
+ <sect1 id="shards-strategy-shardresolution" revision="1">
+ <title>ShardResolutionStrategy</title>
+ <para>
+ Hibernate Shards utilise la
+ <classname>ShardResolutionStrategy</classname> pour déterminer l'ensemble
+ des fragments sur lesquels un objet avec un identifiant donné peut résider.
+ Revenons à notre application de rapports météorologiques et supposons,
+ par exemple, que chaque continent a un éventail d'identifiants qui lui
+ sont associés. N'importe quand nous assignons un identifiant à un WeatherReport,
+ nous en prenons un qui tombe dans l'intervalle légal pour le continent
+ auquel le WeatherReport appartient. Notre <classname>ShardResolutionStrategy</classname>
+ peut utiliser cette information pour identifier sur quel fragment un
+ WeatherReport réside simplement en regardant l'identifiant :
+ <programlisting><![CDATA[
+public class WeatherReportShardResolutionStrategy extends AllShardsShardResolutionStrategy {
+ public WeatherReportShardResolutionStrategy(List<ShardId> shardIds) {
+ super(shardIds);
+ }
+
+ public List<ShardId> selectShardIdsFromShardResolutionStrategyData(
+ ShardResolutionStrategyData srsd) {
+ if(srsd.getEntityName().equals(WeatherReport.class.getName())) {
+ return Continent.getContinentByReportId(srsd.getId()).getShardId();
+ }
+ return super.selectShardIdsFromShardResolutionStrategyData(srsd);
+ }
+}
+]]></programlisting>
+ Il est intéressant de montrer que nous n'avons pas (encore) implémenté
+ de cache qui mette en correspondance le nom de l'entité et l'identifiant
+ du fragment, la <classname>ShardResolutionStrategy</classname> serait
+ un excellent endroit pour brancher un tel cache.
+ </para>
+ <para>
+ Shard Resolution est étroitement lié à la génération d'identifiants. Si
+ vous sélectionnez un générateur d'identifiants pour votre classe qui code
+ l'identifiant du fragment dans l'identifiant de l'objet, votre
+ <classname>ShardResolutionStrategy</classname> ne sera plus jamais
+ appelée. Si vous avez l'intention d'utiliser seulement des générateurs
+ d'identifiant qui codent l'identifiant du fragment dans les identifiants
+ de vos objets, vous devriez utiliser
+ <classname>AllShardsShardResolutionStrategy</classname> en tant que
+ <classname>ShardResolutionStrategy</classname>.
+ </para>
+ </sect1>
+ <sect1 id="shards-strategy-idgen" revision="1">
+ <title>Génération d'identifiants</title>
+ <para>
+ Hibernate Sharding prend en charge n'importe quelle stratégie de génération
+ d'identifiant ; le seul pré-requis est que les identifiants d'objet soient
+ uniques à travers tous les fragments. Il y a quelques simples stratégies
+ de génération d'identifiant qui prennent en charge ce pré-requis :
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Génération native d'identifiants</emphasis>
+ - utilisez la stratégie de génération d'identfiants
+ <code>native</code> d'Hibernate, et configurez vos bases
+ de données de manière à ce que les identifiants n'entrent
+ jamais en collision. Par exemple, si vous utilisez la génération
+ d'identifiants <code>identity</code>, vous avez 5 bases de
+ données à travers lesquelles vous répartirez les données
+ de manière égale, et vous ne vous attendez pas à n'avoir
+ jamais plus d'1 million d'enregistrements, vous pourriez
+ configurer la base de données 0 pour retourner des identifiants
+ commençant à 0, la base de données 1 pour retourner des
+ identifiants commençant à 200000, la base de données 2 pour
+ retourner des identifiants commençant à 400000, etc. Tant
+ que vos suppositions concernant les données sont correctes,
+ les identifiants de vos objets n'entreront jamais en collision.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Génération d'UUID au niveau applicatif</emphasis>
+ - par définition vous ne devez pas vous préoccuper des collisions
+ d'identifiants, mais vous avez besoin d'être disposé à traiter les
+ clefs primaires peu maniables de nos objets.
+ </para>
+ <para>
+ Hibernate Shards fournit une implémentation d'un générateur d'UUID
+ simple et prenant en compte les fragments -
+ <classname>ShardedUUIDGenerator</classname>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Génération hilo répartie</emphasis>
+ - l'idée est d'avoir une table hilo sur un seul fragment, lequel assure
+ que les identifiants générés par l'algorithme hi/lo sont uniques à travers
+ tous les fragments. Les deux principaux inconvénients de cette approche
+ sont que les accès à la table hilo peuvent devenir le goulot d'étranglement
+ dans la génération d'identifiants, et que stocker la table hilo sur
+ une seule base de données crée un seul point de panne du système.
+ </para>
+ <para>
+ Hibernate Shards fournit une implémentation de l'algorithme de génération hilo répartie -
+ <classname>ShardedTableHiLoGenerator</classname>. Cette implémentation est basée sur
+ <classname>org.hibernate.id.TableHiLoGenerator</classname>, donc pour des informations
+ sur la structure attendue de la table de la base de données table de laquelle l'implémentation
+ dépend, veuillez lire la documentation de cette classe.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ La génération d'identifiants est aussi étroitement liée à la résolution de fragment.
+ L'objectif de la résolution de fragment est de trouve le fragment sur lequel vit un objet,
+ pour un identifiant d'objet donné. Il y a deux manières d'accomplir cela :
+ <itemizedlist>
+ <listitem>
+ <para>Utiliser la
+ <classname>ShardResolutionStrategy</classname>, décrite au-dessus
+ </para>
+ </listitem>
+ <listitem>
+ <para>Coder l'identifiant du fragment dans l'identifiant de l'objet durant
+ la génération de l'identifiant, et récupérer l'identifiant du fragment
+ pendant la réslution du fragment
+ </para>
+ </listitem>
+ </itemizedlist>
+ Le principal avantage de coder l'identifiant du fragment dans l'identifiant
+ de l'objet est que cela permet à Hibernate Shards de résoudre le fragment
+ Ã partir de l'identifiant de l'objet beaucoup plus rapidement, sans
+ recherche en base de données, sans recherche dans un cache, etc. Hibernate
+ Shards ne requiert aucun algorithme spécifique pour coder/décoder l'identifiant
+ d'un fragment - tout ce que vous avezà faire est d'utiliser un générateur
+ d'identifiants qui implémente l'interface
+ <classname>ShardEncodingIdentifierGenerator</classname>. Des deux générateurs
+ d'identifiants inclus dans Hibernate Shards, le
+ <classname>ShardedUUIDGenerator</classname>
+ implémente cette interface.
+ </para>
+ </sect1>
+</chapter>
Added: trunk/HibernateExt/shards/doc/reference/fr/styles/fopdf.xsl
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/styles/fopdf.xsl (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/styles/fopdf.xsl 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,519 @@
+<?xml version="1.0"?>
+
+<!--
+
+ This is the XSL FO configuration file for the Hibernate
+ Reference Documentation. It defines a custom titlepage and
+ the parameters for the A4 sized PDF printable output.
+
+ It took me days to figure out this stuff and fix most of
+ the obvious bugs in the DocBook XSL distribution. Some of
+ the workarounds might not be appropriate with a newer version
+ of DocBook XSL. This file is released as part of Hibernate,
+ hence LGPL licensed.
+
+ christian at hibernate.org
+
+-->
+
+<!DOCTYPE xsl:stylesheet [
+ <!ENTITY db_xsl_path "../../../../../../Hibernate3/doc/reference/support/docbook-xsl/">
+]>
+
+<xsl:stylesheet
+ version="1.0"
+ xmlns="http://www.w3.org/TR/xhtml1/transitional"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ exclude-result-prefixes="#default">
+
+ <xsl:import href="&db_xsl_path;/fo/docbook.xsl"/>
+
+ <!--###################################################
+ Custom Title Page
+ ################################################### -->
+
+ <xsl:template name="book.titlepage.recto">
+ <fo:block>
+ <fo:table table-layout="fixed" width="175mm">
+ <fo:table-column column-width="175mm"/>
+ <fo:table-body>
+ <fo:table-row>
+ <fo:table-cell text-align="center">
+ <fo:block>
+ <fo:external-graphic src="file:images/hibernate_logo_a.png"/>
+ </fo:block>
+ <fo:block font-family="Helvetica" font-size="22pt" padding-before="10mm">
+ <xsl:value-of select="bookinfo/title"/>
+ </fo:block>
+ <fo:block font-family="Helvetica" font-size="18pt" padding-before="10mm">
+ <xsl:value-of select="bookinfo/subtitle"/>
+ </fo:block>
+ <fo:block font-family="Helvetica" font-size="12pt" padding="10mm">
+ Version:
+ <xsl:value-of select="bookinfo/releaseinfo"/>
+ </fo:block>
+ </fo:table-cell>
+ </fo:table-row>
+ </fo:table-body>
+ </fo:table>
+ </fo:block>
+ </xsl:template>
+
+ <!-- Prevent blank pages in output -->
+ <xsl:template name="book.titlepage.before.verso">
+ </xsl:template>
+ <xsl:template name="book.titlepage.verso">
+ </xsl:template>
+ <xsl:template name="book.titlepage.separator">
+ </xsl:template>
+
+ <!--###################################################
+ Header
+ ################################################### -->
+
+ <!-- More space in the center header for long text -->
+ <xsl:attribute-set name="header.content.properties">
+ <xsl:attribute name="font-family">
+ <xsl:value-of select="$body.font.family"/>
+ </xsl:attribute>
+ <xsl:attribute name="margin-left">-5em</xsl:attribute>
+ <xsl:attribute name="margin-right">-5em</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!--###################################################
+ Custom Footer
+ ################################################### -->
+
+ <!-- This footer prints the Hibernate version number on the left side -->
+ <xsl:template name="footer.content">
+ <xsl:param name="pageclass" select="''"/>
+ <xsl:param name="sequence" select="''"/>
+ <xsl:param name="position" select="''"/>
+ <xsl:param name="gentext-key" select="''"/>
+
+ <xsl:variable name="Version">
+ <xsl:choose>
+ <xsl:when test="//releaseinfo">
+ <xsl:text>Hibernate </xsl:text>
+ <xsl:value-of select="//releaseinfo"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <!-- nop -->
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <xsl:choose>
+ <xsl:when test="$sequence='blank'">
+ <xsl:choose>
+ <xsl:when test="$double.sided != 0 and $position = 'left'">
+ <xsl:value-of select="$Version"/>
+ </xsl:when>
+
+ <xsl:when test="$double.sided = 0 and $position = 'center'">
+ <!-- nop -->
+ </xsl:when>
+
+ <xsl:otherwise>
+ <fo:page-number/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:when>
+
+ <xsl:when test="$pageclass='titlepage'">
+ <!-- nop: other titlepage sequences have no footer -->
+ </xsl:when>
+
+ <xsl:when test="$double.sided != 0 and $sequence = 'even' and $position='left'">
+ <fo:page-number/>
+ </xsl:when>
+
+ <xsl:when test="$double.sided != 0 and $sequence = 'odd' and $position='right'">
+ <fo:page-number/>
+ </xsl:when>
+
+ <xsl:when test="$double.sided = 0 and $position='right'">
+ <fo:page-number/>
+ </xsl:when>
+
+ <xsl:when test="$double.sided != 0 and $sequence = 'odd' and $position='left'">
+ <xsl:value-of select="$Version"/>
+ </xsl:when>
+
+ <xsl:when test="$double.sided != 0 and $sequence = 'even' and $position='right'">
+ <xsl:value-of select="$Version"/>
+ </xsl:when>
+
+ <xsl:when test="$double.sided = 0 and $position='left'">
+ <xsl:value-of select="$Version"/>
+ </xsl:when>
+
+ <xsl:otherwise>
+ <!-- nop -->
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!--###################################################
+ Custom Toc Line
+ ################################################### -->
+
+ <!-- Improve the TOC. -->
+ <xsl:template name="toc.line">
+ <xsl:variable name="id">
+ <xsl:call-template name="object.id"/>
+ </xsl:variable>
+
+ <xsl:variable name="label">
+ <xsl:apply-templates select="." mode="label.markup"/>
+ </xsl:variable>
+
+ <fo:block text-align-last="justify"
+ end-indent="{$toc.indent.width}pt"
+ last-line-end-indent="-{$toc.indent.width}pt">
+ <fo:inline keep-with-next.within-line="always">
+ <fo:basic-link internal-destination="{$id}">
+
+ <!-- Chapter titles should be bold. -->
+ <xsl:choose>
+ <xsl:when test="local-name(.) = 'chapter'">
+ <xsl:attribute name="font-weight">bold</xsl:attribute>
+ </xsl:when>
+ </xsl:choose>
+
+ <xsl:if test="$label != ''">
+ <xsl:copy-of select="$label"/>
+ <xsl:value-of select="$autotoc.label.separator"/>
+ </xsl:if>
+ <xsl:apply-templates select="." mode="titleabbrev.markup"/>
+ </fo:basic-link>
+ </fo:inline>
+ <fo:inline keep-together.within-line="always">
+ <xsl:text> </xsl:text>
+ <fo:leader leader-pattern="dots"
+ leader-pattern-width="3pt"
+ leader-alignment="reference-area"
+ keep-with-next.within-line="always"/>
+ <xsl:text> </xsl:text>
+ <fo:basic-link internal-destination="{$id}">
+ <fo:page-number-citation ref-id="{$id}"/>
+ </fo:basic-link>
+ </fo:inline>
+ </fo:block>
+ </xsl:template>
+
+ <!--###################################################
+ Extensions
+ ################################################### -->
+
+ <!-- These extensions are required for table printing and other stuff -->
+ <xsl:param name="use.extensions">1</xsl:param>
+ <xsl:param name="tablecolumns.extension">0</xsl:param>
+ <!-- FOP provide only PDF Bookmarks at the moment -->
+ <xsl:param name="fop.extensions">1</xsl:param>
+
+ <!--###################################################
+ Table Of Contents
+ ################################################### -->
+
+ <!-- Generate the TOCs for named components only -->
+ <xsl:param name="generate.toc">
+ book toc
+ </xsl:param>
+
+ <!-- Show only Sections up to level 3 in the TOCs -->
+ <xsl:param name="toc.section.depth">3</xsl:param>
+
+ <!-- Dot and Whitespace as separator in TOC between Label and Title-->
+ <xsl:param name="autotoc.label.separator" select="'. '"/>
+
+
+ <!--###################################################
+ Paper & Page Size
+ ################################################### -->
+
+ <!-- Paper type, no headers on blank pages, no double sided printing -->
+ <xsl:param name="paper.type" select="'A4'"/>
+ <xsl:param name="double.sided">0</xsl:param>
+ <xsl:param name="headers.on.blank.pages">0</xsl:param>
+ <xsl:param name="footers.on.blank.pages">0</xsl:param>
+
+ <!-- Space between paper border and content (chaotic stuff, don't touch) -->
+ <xsl:param name="page.margin.top">5mm</xsl:param>
+ <xsl:param name="region.before.extent">10mm</xsl:param>
+ <xsl:param name="body.margin.top">10mm</xsl:param>
+
+ <xsl:param name="body.margin.bottom">15mm</xsl:param>
+ <xsl:param name="region.after.extent">10mm</xsl:param>
+ <xsl:param name="page.margin.bottom">0mm</xsl:param>
+
+ <xsl:param name="page.margin.outer">18mm</xsl:param>
+ <xsl:param name="page.margin.inner">18mm</xsl:param>
+
+ <!-- No intendation of Titles -->
+ <xsl:param name="title.margin.left">0pc</xsl:param>
+
+ <!--###################################################
+ Fonts & Styles
+ ################################################### -->
+
+ <!-- Default Font size -->
+ <xsl:param name="body.font.master">11</xsl:param>
+
+ <!-- Line height in body text -->
+ <xsl:param name="line-height">1.4</xsl:param>
+
+ <!-- Monospaced fonts are smaller than regular text -->
+ <xsl:attribute-set name="monospace.properties">
+ <xsl:attribute name="font-family">
+ <xsl:value-of select="$monospace.font.family"/>
+ </xsl:attribute>
+ <xsl:attribute name="font-size">0.8em</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!--###################################################
+ Tables
+ ################################################### -->
+
+ <!-- The table width should be adapted to the paper size -->
+ <xsl:param name="default.table.width">17.4cm</xsl:param>
+
+ <!-- Some padding inside tables -->
+ <xsl:attribute-set name="table.cell.padding">
+ <xsl:attribute name="padding-left">4pt</xsl:attribute>
+ <xsl:attribute name="padding-right">4pt</xsl:attribute>
+ <xsl:attribute name="padding-top">4pt</xsl:attribute>
+ <xsl:attribute name="padding-bottom">4pt</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- Only hairlines as frame and cell borders in tables -->
+ <xsl:param name="table.frame.border.thickness">0.1pt</xsl:param>
+ <xsl:param name="table.cell.border.thickness">0.1pt</xsl:param>
+
+ <!--###################################################
+ Labels
+ ################################################### -->
+
+ <!-- Label Chapters and Sections (numbering) -->
+ <xsl:param name="chapter.autolabel">1</xsl:param>
+ <xsl:param name="section.autolabel" select="1"/>
+ <xsl:param name="section.label.includes.component.label" select="1"/>
+
+ <!-- Label only Sections up to level 2 -->
+ <xsl:param name="local.l10n.xml" select="document('')"/>
+ <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
+ <l:l10n language="en">
+ <l:context name="title-numbered">
+ <l:template name="sect3" text="%t"/>
+ <l:template name="sect4" text="%t"/>
+ <l:template name="sect5" text="%t"/>
+ </l:context>
+ <l:context name="section-xref-numbered">
+ <l:template name="sect3" text="the section called %t"/>
+ <l:template name="sect4" text="the section called %t"/>
+ <l:template name="sect5" text="the section called %t"/>
+ </l:context>
+ </l:l10n>
+ </l:i18n>
+
+ <!--###################################################
+ Titles
+ ################################################### -->
+
+ <!-- Chapter title size -->
+ <xsl:attribute-set name="chapter.titlepage.recto.style">
+ <xsl:attribute name="text-align">left</xsl:attribute>
+ <xsl:attribute name="font-weight">bold</xsl:attribute>
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master * 1.8"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- Why is the font-size for chapters hardcoded in the XSL FO templates?
+ Let's remove it, so this sucker can use our attribute-set only... -->
+ <xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
+ <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ xsl:use-attribute-sets="chapter.titlepage.recto.style">
+ <xsl:call-template name="component.title">
+ <xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
+ </xsl:call-template>
+ </fo:block>
+ </xsl:template>
+
+ <!-- Sections 1, 2 and 3 titles have a small bump factor and padding -->
+ <xsl:attribute-set name="section.title.level1.properties">
+ <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
+ <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
+ <xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master * 1.5"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+ <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
+ </xsl:attribute-set>
+ <xsl:attribute-set name="section.title.level2.properties">
+ <xsl:attribute name="space-before.optimum">0.6em</xsl:attribute>
+ <xsl:attribute name="space-before.minimum">0.6em</xsl:attribute>
+ <xsl:attribute name="space-before.maximum">0.6em</xsl:attribute>
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master * 1.25"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+ <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
+ </xsl:attribute-set>
+ <xsl:attribute-set name="section.title.level3.properties">
+ <xsl:attribute name="space-before.optimum">0.4em</xsl:attribute>
+ <xsl:attribute name="space-before.minimum">0.4em</xsl:attribute>
+ <xsl:attribute name="space-before.maximum">0.4em</xsl:attribute>
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master * 1.0"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+ <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- Titles of formal objects (tables, examples, ...) -->
+ <xsl:attribute-set name="formal.title.properties" use-attribute-sets="normal.para.spacing">
+ <xsl:attribute name="font-weight">bold</xsl:attribute>
+ <xsl:attribute name="font-size">
+ <xsl:value-of select="$body.font.master"/>
+ <xsl:text>pt</xsl:text>
+ </xsl:attribute>
+ <xsl:attribute name="hyphenate">false</xsl:attribute>
+ <xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
+ <xsl:attribute name="space-after.optimum">0.6em</xsl:attribute>
+ <xsl:attribute name="space-after.maximum">0.8em</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!--###################################################
+ Programlistings
+ ################################################### -->
+
+ <!-- Verbatim text formatting (programlistings) -->
+ <xsl:attribute-set name="verbatim.properties">
+ <xsl:attribute name="space-before.minimum">1em</xsl:attribute>
+ <xsl:attribute name="space-before.optimum">1em</xsl:attribute>
+ <xsl:attribute name="space-before.maximum">1em</xsl:attribute>
+ <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
+ <xsl:attribute name="border-color">#444444</xsl:attribute>
+ <xsl:attribute name="border-style">solid</xsl:attribute>
+ <xsl:attribute name="border-width">0.1pt</xsl:attribute>
+ <xsl:attribute name="padding-top">0.5em</xsl:attribute>
+ <xsl:attribute name="padding-left">0.5em</xsl:attribute>
+ <xsl:attribute name="padding-right">0.5em</xsl:attribute>
+ <xsl:attribute name="padding-bottom">0.5em</xsl:attribute>
+ <xsl:attribute name="margin-left">0.5em</xsl:attribute>
+ <xsl:attribute name="margin-right">0.5em</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- Shade (background) programlistings -->
+ <xsl:param name="shade.verbatim">1</xsl:param>
+ <xsl:attribute-set name="shade.verbatim.style">
+ <xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!--###################################################
+ Callouts
+ ################################################### -->
+
+ <!-- We want to use callouts... -->
+ <xsl:param name="callout.extensions">1</xsl:param>
+
+ <!-- Place callout bullets at this column in programmlisting.-->
+ <xsl:param name="callout.defaultcolumn">90</xsl:param>
+
+ <!--
+ No, don't use crappy graphics for the callout bullets. This setting
+ enables some weird Unicode rendering for some fancy bullet points
+ in callouts. By default, this can only count to 10 and produces
+ strange results if you ever have more than 10 callouts for one
+ programlisting. We will fix that next.
+ -->
+ <xsl:param name="callout.graphics">0</xsl:param>
+
+ <!--
+ Again, fun with DocBook XSL: The callout bullets are rendered in
+ two places: In the programlisting itself and in the list below
+ the listing, with the actual callout text. The rendering in the
+ programlisting is some XSL transformer extension (e.g. a Saxon
+ extension), so we can't change that without messing with the
+ extensions. We only can turn it off by setting this limit to
+ zero, then, a simple bracket style like "(3)" and "(4)" will
+ be used in the programlisting.
+ -->
+ <xsl:param name="callout.unicode.number.limit" select="'0'"></xsl:param>
+
+ <!--
+ The callout bullets in the actual callout list will be rendered
+ with an XSL FO template. The default template is broken: limited to 10
+ nice looking Unicode bullet points and then it doesn't print anything,
+ the fallback doesn't work. We implement our own template, which is not
+ as complicated, more ugly, but works. As always, function is more
+ important than form.
+ -->
+ <xsl:template name="callout-bug">
+ <xsl:param name="conum" select='1'/>
+ <fo:inline
+ color="black"
+ padding-top="0.1em"
+ padding-bottom="0.1em"
+ padding-start="0.2em"
+ padding-end="0.2em"
+ baseline-shift="0.1em"
+ font-family="{$monospace.font.family}"
+ font-weight="bold"
+ font-size="75%">
+ <xsl:text>(</xsl:text>
+ <xsl:value-of select="$conum"/>
+ <xsl:text>)</xsl:text>
+ </fo:inline>
+
+ </xsl:template>
+
+ <!--###################################################
+ Misc
+ ################################################### -->
+
+ <!-- Correct placement of titles for figures and examples. -->
+ <xsl:param name="formal.title.placement">
+ figure after
+ example before
+ equation before
+ table before
+ procedure before
+ </xsl:param>
+
+ <!-- Format Variable Lists as Blocks (prevents horizontal overflow). -->
+ <xsl:param name="variablelist.as.blocks">1</xsl:param>
+
+ <!-- The horrible list spacing problems, this is much better. -->
+ <xsl:attribute-set name="list.block.spacing">
+ <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
+ <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
+ <xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
+ <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
+ <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
+ </xsl:attribute-set>
+
+ <!-- Newer DocBook XSL apparently thinks that some sections are by
+ default "draft" status, and this idiotic thing is by default
+ also set to "maybe", so it spits out a lot of errors with the
+ latest FOP as the XSL/FO styles have references to some draft
+ watermarks, which you actually don't want in the first place.
+ Turn this crap off. If you have to work with the "status"
+ attribute, don't.
+ -->
+ <xsl:param name="draft.mode" select="'no'"/>
+
+</xsl:stylesheet>
Added: trunk/HibernateExt/shards/doc/reference/fr/styles/html.css
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/styles/html.css (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/styles/html.css 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,97 @@
+A {
+ color: #003399;
+}
+
+A:active {
+ color: #003399;
+}
+
+A:visited {
+ color: #888888;
+}
+
+P, OL, UL, LI, DL, DT, DD, BLOCKQUOTE {
+ color: #000000;
+}
+
+TD, TH, SPAN {
+ color: #000000;
+}
+
+BLOCKQUOTE {
+ margin-right: 0px;
+}
+
+
+H1, H2, H3, H4, H5, H6 {
+ color: #000000;
+ font-weight:500;
+ margin-top:10px;
+ padding-top:15px;
+}
+
+TABLE {
+ border-collapse: collapse;
+ border-spacing:0;
+ border: 1px thin black;
+ empty-cells: hide;
+}
+
+TD {
+ padding: 4pt;
+}
+
+H1 { font-size: 150%; }
+H2 { font-size: 140%; }
+H3 { font-size: 110%; font-weight: bold; }
+H4 { font-size: 110%; font-weight: bold;}
+H5 { font-size: 100%; font-style: italic; }
+H6 { font-size: 100%; font-style: italic; }
+
+TT {
+font-size: 90%;
+ font-family: "Courier New", Courier, monospace;
+ color: #000000;
+}
+
+PRE {
+font-size: 100%;
+ padding: 5px;
+ border-style: solid;
+ border-width: 1px;
+ border-color: #CCCCCC;
+ background-color: #F4F4F4;
+}
+
+UL, OL, LI {
+ list-style: disc;
+}
+
+HR {
+ width: 100%;
+ height: 1px;
+ background-color: #CCCCCC;
+ border-width: 0px;
+ padding: 0px;
+ color: #CCCCCC;
+}
+
+.variablelist {
+ padding-top: 10;
+ padding-bottom:10;
+ margin:0;
+}
+
+.itemizedlist, UL {
+ padding-top: 0;
+ padding-bottom:0;
+ margin:0;
+}
+
+.term {
+ font-weight:bold;
+}
+
+
+
+
Added: trunk/HibernateExt/shards/doc/reference/fr/styles/html.xsl
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/styles/html.xsl (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/styles/html.xsl 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,84 @@
+<?xml version="1.0"?>
+
+<!--
+
+ This is the XSL HTML configuration file for the Hibernate
+ Reference Documentation.
+
+ It took me days to figure out this stuff and fix most of
+ the obvious bugs in the DocBook XSL distribution. Some of
+ the workarounds might not be appropriate with a newer version
+ of DocBook XSL. This file is released as part of Hibernate,
+ hence LGPL licensed.
+
+ christian at hibernate.org
+-->
+
+<!DOCTYPE xsl:stylesheet [
+ <!ENTITY db_xsl_path "../../../../../../Hibernate3/doc/reference/support/docbook-xsl/">
+]>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0"
+ xmlns="http://www.w3.org/TR/xhtml1/transitional"
+ exclude-result-prefixes="#default">
+
+<xsl:import href="&db_xsl_path;/html/docbook.xsl"/>
+
+<!--###################################################
+ HTML Settings
+ ################################################### -->
+
+ <xsl:param name="html.stylesheet">../shared/css/html.css</xsl:param>
+
+ <!-- These extensions are required for table printing and other stuff -->
+ <xsl:param name="use.extensions">1</xsl:param>
+ <xsl:param name="tablecolumns.extension">0</xsl:param>
+ <xsl:param name="callout.extensions">1</xsl:param>
+ <xsl:param name="graphicsize.extension">0</xsl:param>
+
+<!--###################################################
+ Table Of Contents
+ ################################################### -->
+
+ <!-- Generate the TOCs for named components only -->
+ <xsl:param name="generate.toc">
+ book toc
+ </xsl:param>
+
+ <!-- Show only Sections up to level 3 in the TOCs -->
+ <xsl:param name="toc.section.depth">3</xsl:param>
+
+<!--###################################################
+ Labels
+ ################################################### -->
+
+ <!-- Label Chapters and Sections (numbering) -->
+ <xsl:param name="chapter.autolabel">1</xsl:param>
+ <xsl:param name="section.autolabel" select="1"/>
+ <xsl:param name="section.label.includes.component.label" select="1"/>
+
+<!--###################################################
+ Callouts
+ ################################################### -->
+
+ <!-- Don't use graphics, use a simple number style -->
+ <xsl:param name="callout.graphics">0</xsl:param>
+
+ <!-- Place callout marks at this column in annotated areas -->
+ <xsl:param name="callout.defaultcolumn">90</xsl:param>
+
+<!--###################################################
+ Misc
+ ################################################### -->
+
+ <!-- Placement of titles -->
+ <xsl:param name="formal.title.placement">
+ figure after
+ example before
+ equation before
+ table before
+ procedure before
+ </xsl:param>
+
+</xsl:stylesheet>
Added: trunk/HibernateExt/shards/doc/reference/fr/styles/html_chunk.xsl
===================================================================
--- trunk/HibernateExt/shards/doc/reference/fr/styles/html_chunk.xsl (rev 0)
+++ trunk/HibernateExt/shards/doc/reference/fr/styles/html_chunk.xsl 2007-05-21 14:56:13 UTC (rev 11544)
@@ -0,0 +1,86 @@
+<?xml version="1.0"?>
+
+<!--
+
+ This is the XSL HTML configuration file for the Hibernate
+ Reference Documentation.
+
+ It took me days to figure out this stuff and fix most of
+ the obvious bugs in the DocBook XSL distribution. Some of
+ the workarounds might not be appropriate with a newer version
+ of DocBook XSL. This file is released as part of Hibernate,
+ hence LGPL licensed.
+
+ christian at hibernate.org
+-->
+
+<!DOCTYPE xsl:stylesheet [
+ <!ENTITY db_xsl_path "../../../../../../Hibernate3/doc/reference/support/docbook-xsl/">
+]>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0"
+ xmlns="http://www.w3.org/TR/xhtml1/transitional"
+ exclude-result-prefixes="#default">
+
+<xsl:import href="&db_xsl_path;/html/chunk.xsl"/>
+
+<!--###################################################
+ HTML Settings
+ ################################################### -->
+
+ <xsl:param name="chunk.section.depth">'5'</xsl:param>
+ <xsl:param name="use.id.as.filename">'1'</xsl:param>
+ <xsl:param name="html.stylesheet">../shared/css/html.css</xsl:param>
+
+ <!-- These extensions are required for table printing and other stuff -->
+ <xsl:param name="use.extensions">1</xsl:param>
+ <xsl:param name="tablecolumns.extension">0</xsl:param>
+ <xsl:param name="callout.extensions">1</xsl:param>
+ <xsl:param name="graphicsize.extension">0</xsl:param>
+
+<!--###################################################
+ Table Of Contents
+ ################################################### -->
+
+ <!-- Generate the TOCs for named components only -->
+ <xsl:param name="generate.toc">
+ book toc
+ </xsl:param>
+
+ <!-- Show only Sections up to level 3 in the TOCs -->
+ <xsl:param name="toc.section.depth">3</xsl:param>
+
+<!--###################################################
+ Labels
+ ################################################### -->
+
+ <!-- Label Chapters and Sections (numbering) -->
+ <xsl:param name="chapter.autolabel">1</xsl:param>
+ <xsl:param name="section.autolabel" select="1"/>
+ <xsl:param name="section.label.includes.component.label" select="1"/>
+
+<!--###################################################
+ Callouts
+ ################################################### -->
+
+ <!-- Don't use graphics, use a simple number style -->
+ <xsl:param name="callout.graphics">0</xsl:param>
+
+ <!-- Place callout marks at this column in annotated areas -->
+ <xsl:param name="callout.defaultcolumn">90</xsl:param>
+
+<!--###################################################
+ Misc
+ ################################################### -->
+
+ <!-- Placement of titles -->
+ <xsl:param name="formal.title.placement">
+ figure after
+ example before
+ equation before
+ table before
+ procedure before
+ </xsl:param>
+
+</xsl:stylesheet>
More information about the hibernate-commits
mailing list