[hibernate-commits] Hibernate SVN: r11544 - in trunk/HibernateExt/shards/doc/reference/fr: images and 2 other directories.

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(a)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(a)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(a)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>