Make sure that the web service client Java class IbisClientConnection

is thread safe.

--
Imported using git-svn from
https://dev.csi.cam.ac.uk/svn/lookup/trunk@11

src/java/uk/ac/cam/ucs/ibis/client/IbisClientConnection.java

@@ -70,8 +70,8 @@ public class IbisClientConnection implements ClientConnection
     /** Whether to ask for flattened XML (recommended for efficiency). */
     protected boolean flatXML = true;
 
-    /** JAXB Unmarshaller to unmarshall results from the server. */
-    protected Unmarshaller unmarshaller;
+    /** JAXB context for unmarshalling results from the server. */
+    protected JAXBContext jaxbCtx;
 
     /**
      * Create a ClientConnection to the Lookup/Ibis web service API at
@@ -153,9 +153,12 @@ public class IbisClientConnection implements ClientConnection
         else
             sf = IbisSocketFactory.createUntrusted();
 
-        // Create the JAXB Unmarshaller to unmarshall results from the server
-        JAXBContext ctx = JAXBContext.newInstance(IbisResult.class);
-        unmarshaller = ctx.createUnmarshaller();
+        // Create a JAXB context for unmarshalling results from the server.
+        // This is relatively slow, so we do it only once here, rather than
+        // in each request. Note, however, that the Unmarshaller itself is
+        // not thread safe, so we do need to create separate unmarshallers
+        // for each request, but they are cheap to create.
+        jaxbCtx = JAXBContext.newInstance(IbisResult.class);
 
         // Initially use anonymous authentication
         setUsername("anonymous");
@@ -354,6 +357,8 @@ public class IbisClientConnection implements ClientConnection
         {
             // The result is XML, which we should be able to unmarshal
             // into an IbisResult object
+            Unmarshaller unmarshaller = jaxbCtx.createUnmarshaller();
+
             if (conn.getResponseCode() == HttpsURLConnection.HTTP_OK)
                 return (IbisResult )unmarshaller.unmarshal(conn.getInputStream());
             else

src/java/ws-overview.html

@@ -62,5 +62,26 @@
             of the <code>ClientConnection</code> and <code>XxxMethods</code>
             objects, and then re-use them throughout your Java application.
         </p>
+
+        <h4>Thread safety</h4>
+
+        <p>
+            Once created and initialised, the <code>ClientConnection</code> and
+            <code>XxxMethods</code> classes are safe to use from multiple
+            simultaneous threads (for example in a web server).
+        </p>
+
+        <p>
+            Note, however, that
+            <a href="uk/ac/cam/ucs/ibis/client/IbisClientConnection.html#setUsername(java.lang.String)">
+            IbisClientConnection.setUsername()</a> and
+            <a href="uk/ac/cam/ucs/ibis/client/IbisClientConnection.html#setPassword(java.lang.String)">
+            IbisClientConnection.setPassword()</a> are not thread safe. These
+            methods are regarded as part of the initialisation of the connection,
+            and should typically only be use once on startup. If you need to
+            regularly switch between users, then use a separate
+            <code>ClientConnection</code> per user or per thread (and separate
+            corresponding <code>XxxMethods</code> objects).
+        </p>
     </body>
 </html>