[hibernate-commits] Hibernate SVN: r12757 - shards/trunk/doc/reference/en/modules.

[hibernate-commits at lists.jboss.org]

Author: max.ross
Date: 2007-07-12 00:26:31 -0400 (Thu, 12 Jul 2007)
New Revision: 12757

Modified:
   shards/trunk/doc/reference/en/modules/configuration.xml
Log:
HSHARDS-36
Docs describe how to use Shards with Annotations

Modified: shards/trunk/doc/reference/en/modules/configuration.xml
===================================================================
--- shards/trunk/doc/reference/en/modules/configuration.xml	2007-07-12 04:17:22 UTC (rev 12756)
+++ shards/trunk/doc/reference/en/modules/configuration.xml	2007-07-12 04:26:31 UTC (rev 12757)
@@ -169,13 +169,16 @@
                 <listitem>
                     <para>connection.password</para>
                 </listitem>
+                <listitem>
+                    <para>connection.datasource</para>
+                </listitem>
               <listitem>
-                  <para>connection.datasource</para>
+                    <para>cache.region_prefix</para>
               </listitem>
             </itemizedlist>
             The three <classname>ShardConfiguration</classname> objects we're loading (lines 5 - 7) will be consulted for the
-            shard-specific database url, database user, database password, datasource identifier, and that's all.  (For a discussion
-            of what these properties are and how they are used, please consult the Hibernate Core documentation.)
+            shard-specific database url, database user, database password, datasource identifier, cache region prefix, and that's all.
+            (For a discussion of what these properties are and how they are used, please consult the Hibernate Core documentation.)
             This means that if you change the
             connection pool parameters in shard1.hibernate.cfg.xml, those parameters will be ignored. If you add another
             mapping file to the <classname>Configuration</classname>
@@ -276,12 +279,85 @@
             shard-aware id generator. We'll cover id generation in more detail in the chapter on Shard Strategies.
         </para>
     </sect1>
+    <sect1 id="shards-configuration-anno" revision="1">
+        <title>Using Hibernate Annotations With Shards</title>
+        <para>
+            In the above example we're using Hibernate mapping files (hbm.xml)
+            to specify our mappings, but it's just as easy to use Hibernate
+            Annotations.  We can annotate our <classname>WeatherReport</classname>
+            class as follows:
+            <programlisting><![CDATA[
+ at Entity
+ at Table(name="WEATHER_REPORT")
+public class WeatherReport {
+
+    @Id @GeneratedValue(generator="WeatherReportIdGenerator")
+    @GenericGenerator(name="WeatherReportIdGenerator", strategy="org.hibernate.shards.id.ShardedUUIDGenerator")
+    @Column(name="REPORT_ID")
+    private Integer reportId;
+
+    @Column(name="CONTINENT")
+    private String continent;
+
+    @Column(name="LATITUDE")
+    private BigDecimal latitude;
+
+    @Column(name="LONGITUDE")
+    private BigDecimal longitude;
+
+    @Column(name="TEMPERATURE")
+    private int temperature;
+
+    @Column(name="REPORT_TIME")
+    private Date reportTime;
+
+    ... // getters and setters
+}
+]]></programlisting>
+            This is a pretty standard use of Hibernate Annotations.  The only
+            thing here that's particularly noteworthy is the use of the
+            <classname>GenericGenerator</classname> annotation, which is part
+            of Hibernate Annotations but not JPA.  We need this to specify our
+            shard-aware id generator.
+         </para>
+         <para>
+            The changes we now need to make to the <code>createSessionFactory()</code>
+            method we implemented above are actually quite small:
+           <programlisting><![CDATA[
+ 1     public SessionFactory createSessionFactory() {
+ 2         AnnotationConfiguration prototypeConfig = new AnnotationConfiguration().configure("shard0.hibernate.cfg.xml");
+ 3         prototypeConfig.addAnnotatedClass(WeatherReport.class);
+ 4         List<ShardConfiguration> shardConfigs = new ArrayList<ShardConfiguration>();
+ 5         shardConfigs.add(buildShardConfig("shard0.hibernate.cfg.xml"));
+ 6         shardConfigs.add(buildShardConfig("shard1.hibernate.cfg.xml"));
+ 7         shardConfigs.add(buildShardConfig("shard2.hibernate.cfg.xml"));
+ 8         ShardStrategyFactory shardStrategyFactory = buildShardStrategyFactory();
+ 9         ShardedConfiguration shardedConfig = new ShardedConfiguration(
+ 10            prototypeConfig,
+ 11            shardConfigs,
+ 12            shardStrategyFactory);
+ 13        return shardedConfig.buildShardedSessionFactory();
+ 14    }
+ ]]></programlisting>
+           The only changes between this method and the non-annotated versions
+           are on lines 2 and 3.  On line 2 we're declaring and instantiating an
+           <classname>AnnotationConfiguration</classname> instead of a
+           <classname>Configuration</classname>, and on line 3 we're adding
+           an annotated class to the configuration instead of an xml mapping file.
+           That's it!
+         </para>
+         <para>
+           Please note that while Hibernate Shards works with Hibernate Annotations,
+           Hibernate Shards does not ship with Hibernate Annotations.  You'll need
+           to download Hibernate Annotations and its dependencies separately.
+         </para>
+    </sect1>
     <sect1 id="shards-configuration-limitations" revision="1">
         <title>Configuration Limitations</title>
         <para>
             Many of you will quickly realize that the configuration mechanism we've provided won't work if you're
             configuring your <classname>SessionFactory</classname>
-            via JPA or Hibernate Annotations. It's true. We expect these deficiencies to be addressed shortly.
+            via JPA. It's true. We expect this deficiency to be addressed shortly.
         </para>
     </sect1>
 </chapter>