[hibernate-commits] Hibernate SVN: r15528 - in search/trunk: src/java/org/hibernate/search/bridge and 1 other directory.

[hibernate-commits at lists.jboss.org]

Author: sannegrinovero
Date: 2008-11-06 18:11:06 -0500 (Thu, 06 Nov 2008)
New Revision: 15528

Modified:
   search/trunk/doc/reference/en/modules/mapping.xml
   search/trunk/src/java/org/hibernate/search/bridge/FieldBridge.java
   search/trunk/src/java/org/hibernate/search/bridge/ParameterizedBridge.java
   search/trunk/src/java/org/hibernate/search/bridge/StringBridge.java
   search/trunk/src/java/org/hibernate/search/bridge/TwoWayStringBridge.java
Log:
HSEARCH-291 improve documentation about thread safety requirements of Bridges

Modified: search/trunk/doc/reference/en/modules/mapping.xml
===================================================================
--- search/trunk/doc/reference/en/modules/mapping.xml	2008-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/doc/reference/en/modules/mapping.xml	2008-11-06 23:11:06 UTC (rev 15528)
@@ -988,11 +988,13 @@
       <section>
         <title>StringBridge</title>
 
-        <para>The simpliest custom solution is to give Hibernate Search an
+        <para>The simplest custom solution is to give Hibernate Search an
         implementation of your expected <emphasis>object to String</emphasis>
         bridge. To do so you need to implements the
         <literal>org.hibernate.search.bridge.StringBridge</literal>
-        interface</para>
+        interface.</para>
+        <para>All implementations have to be thread-safe as they
+        are used concurrently.</para>
 
         <programlisting>/**
  * Padding Integer bridge.
@@ -1063,6 +1065,9 @@
         <classname>TwoWayStringBridge</classname> ,
         <classname>FieldBridge</classname> implementations (see
         bellow).</para>
+        <para>All implementations have to be thread-safe, but the parameters
+        are set during initialization and no special care is required at
+        this stage.</para>
 
         <para>If you expect to use your bridge implementation on for an id
         property (ie annotated with <literal>@DocumentId</literal> ), you need
@@ -1178,7 +1183,7 @@
         <para>It is sometimes useful to combine more than one property of a
         given entity and index this combination in a specific way into the
         Lucene index. The <classname>@ClassBridge</classname> and
-        <classname>@ClassBridges</classname> annotations can be defined at the
+        <classname>@ClassBridge</classname> annotations can be defined at the
         class level (as opposed to the property level). In this case the
         custom field bridge implementation receives the entity instance as the
         value parameter instead of a particular property. Though not shown in

Modified: search/trunk/src/java/org/hibernate/search/bridge/FieldBridge.java
===================================================================
--- search/trunk/src/java/org/hibernate/search/bridge/FieldBridge.java	2008-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/src/java/org/hibernate/search/bridge/FieldBridge.java	2008-11-06 23:11:06 UTC (rev 15528)
@@ -5,7 +5,9 @@
 
 /**
  * Link between a java property and a Lucene Document
- * Usually a Java property will be linked to a Document Field
+ * Usually a Java property will be linked to a Document Field.
+ * 
+ * All implementations need to be threadsafe.
  *
  * @author Emmanuel Bernard
  */

Modified: search/trunk/src/java/org/hibernate/search/bridge/ParameterizedBridge.java
===================================================================
--- search/trunk/src/java/org/hibernate/search/bridge/ParameterizedBridge.java	2008-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/src/java/org/hibernate/search/bridge/ParameterizedBridge.java	2008-11-06 23:11:06 UTC (rev 15528)
@@ -4,7 +4,11 @@
 import java.util.Map;
 
 /**
- * Allow parameter injection to a given bridge
+ * Allow parameter injection to a given bridge.
+ * 
+ * Implementors need to be threadsafe, but the
+ * setParameterValues method doesn't need any
+ * guard as initialization is always safe.
  *
  * @author Emmanuel Bernard
  */

Modified: search/trunk/src/java/org/hibernate/search/bridge/StringBridge.java
===================================================================
--- search/trunk/src/java/org/hibernate/search/bridge/StringBridge.java	2008-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/src/java/org/hibernate/search/bridge/StringBridge.java	2008-11-06 23:11:06 UTC (rev 15528)
@@ -2,7 +2,12 @@
 package org.hibernate.search.bridge;
 
 /**
- * Transform an object into a string representation
+ * Transform an object into a string representation.
+ * 
+ * All implementations are required to be threadsafe;
+ * usually this is easily achieved avoiding the usage
+ * of class fields, unless they are either immutable
+ * or needed to store parameters.
  *
  * @author Emmanuel Bernard
  */

Modified: search/trunk/src/java/org/hibernate/search/bridge/TwoWayStringBridge.java
===================================================================
--- search/trunk/src/java/org/hibernate/search/bridge/TwoWayStringBridge.java	2008-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/src/java/org/hibernate/search/bridge/TwoWayStringBridge.java	2008-11-06 23:11:06 UTC (rev 15528)
@@ -8,6 +8,9 @@
  *
  * objectToString( stringToObject( string ) ).equals(string) for string not null
  * stringToObject( objectToString( object ) ).equals(object) for object not null 
+ * 
+ * As for all Bridges implementors must be threasafe.
+ * 
  * @author Emmanuel Bernard
  */
 public interface TwoWayStringBridge extends StringBridge {