12:11 a.m.
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 {