From hibernate-commits at lists.jboss.org Thu Nov  6 18:11:06 2008
Content-Type: multipart/mixed; boundary="===============1900751271548301927=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r15528 - in search/trunk:
 src/java/org/hibernate/search/bridge and 1 other directory.
Date: Thu, 06 Nov 2008 18:11:06 -0500
Message-ID: <E1KyE0I-0007XD-JF@committer01.frg.pub.inap.atl.jboss.com>

--===============1900751271548301927==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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.ja=
va
   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 Bridg=
es

Modified: search/trunk/doc/reference/en/modules/mapping.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- search/trunk/doc/reference/en/modules/mapping.xml	2008-11-06 16:44:55 U=
TC (rev 15527)
+++ search/trunk/doc/reference/en/modules/mapping.xml	2008-11-06 23:11:06 U=
TC (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</emphas=
is>
         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 paramete=
rs
+        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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- 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/ParameterizedBr=
idge.java
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- search/trunk/src/java/org/hibernate/search/bridge/ParameterizedBridge.j=
ava	2008-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/src/java/org/hibernate/search/bridge/ParameterizedBridge.j=
ava	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.ja=
va
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- search/trunk/src/java/org/hibernate/search/bridge/StringBridge.java	200=
8-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/src/java/org/hibernate/search/bridge/StringBridge.java	200=
8-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/TwoWayStringBri=
dge.java
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- search/trunk/src/java/org/hibernate/search/bridge/TwoWayStringBridge.ja=
va	2008-11-06 16:44:55 UTC (rev 15527)
+++ search/trunk/src/java/org/hibernate/search/bridge/TwoWayStringBridge.ja=
va	2008-11-06 23:11:06 UTC (rev 15528)
@@ -8,6 +8,9 @@
  *
  * objectToString( stringToObject( string ) ).equals(string) for string no=
t null
  * stringToObject( objectToString( object ) ).equals(object) for object no=
t null =

+ * =

+ * As for all Bridges implementors must be threasafe.
+ * =

  * @author Emmanuel Bernard
  */
 public interface TwoWayStringBridge extends StringBridge {


--===============1900751271548301927==--