[jboss-remoting-commits] JBoss Remoting SVN: r5213 - remoting2/branches/2.2/docs/guide/en.

[jboss-remoting-commits at lists.jboss.org]

Author: ron.sigal at jboss.com
Date: 2009-05-13 04:01:07 -0400 (Wed, 13 May 2009)
New Revision: 5213

Modified:
   remoting2/branches/2.2/docs/guide/en/chap5.xml
Log:
JBREM-1079: Various additions.

Modified: remoting2/branches/2.2/docs/guide/en/chap5.xml
===================================================================
--- remoting2/branches/2.2/docs/guide/en/chap5.xml	2009-05-13 06:27:53 UTC (rev 5212)
+++ remoting2/branches/2.2/docs/guide/en/chap5.xml	2009-05-13 08:01:07 UTC (rev 5213)
@@ -1371,6 +1371,40 @@
       <para>These request headers are set automatically when using a remoting
       client, but if using another client to send request to the HTTP server
       invoker, may want to add these headers.</para>
+      
+      <bridgehead>Response headers</bridgehead>
+    
+      <para>If a request on the HTTP transport is made with the
+      <classname>org.jboss.remoting.Client</classname> method</para>
+      
+      <programlisting>public Object invoke(Object param, Map metadata) throws Throwable</programlisting>
+      
+      <para>then
+      <classname>org.jboss.remoting.transport.http.HTTPClientInvoker</classname>
+      returns the HTTP response headers in a map in metadata, associated with
+      the key
+      <code>org.jboss.remoting.transport.http.HTTPMetadataConstants.RESPONSE_HEADERS</code>
+      (actual value "ResponseHeaders"). For example, the response header "Date"
+      can be retrieved as follows:</para>
+      
+      <programlisting>Object payload = ... ;
+HashMap metadata = new HashMap();
+client.invoke(payload, metadata);
+Map responseHeaders = (Map) metadata.get(HTTPMetadataConstants.RESPONSE_HEADERS);
+String date = (String) responseHeaders.get("Date");</programlisting>
+      
+      <bridgehead>CR/LF in HTTP transport</bridgehead>
+    
+      <para>By default, the HTTP transport uses
+      <classname>org.jboss.remoting.marshal.http.HTTPMarshaller</classname> and
+      <classname>org.jboss.remoting.marshal.http.HTTPUnMarshaller</classname> to
+      marshal and unmarshal invocations and responses. Prior to Remoting version
+      2.2.3, <classname>HTTPUnMarshaller</classname> stripped CR/LF characters. As
+      of version 2.2.3, the default behavior remains the same, but it is possible
+      to change the behavior, on the client and the server, by setting the
+      parameter <code>HTTPUnMarshaller.PRESERVE_LINES</code> (actual value
+      "preserveLines") to "true". </para>
+      
     </section>
 
     <section>
@@ -1617,6 +1651,29 @@
       to is changed, will need to change the value for the InvokerLocator in
       the Connector configuration mentioned above.</para>
 
+      <para><emphasis role="bold">Note.</emphasis> Prior to Remoting version 2.2.3,
+      <classname>org.jboss.remoting.transport.servlet.ServletServerInvoker</classname>
+      generated a single MBean ObjectName for representing
+      <classname>ServletServerInvoker</classname>s as MBeans, which meant that
+      an MBeanServer could be aware of only a single
+      <classname>ServletServerInvoker</classname> MBean. As of version 2.2.3, that
+      restriction can be eliminated by setting the parameter 
+      <code>org.jboss.remoting.transport.servlet.ServletServerInvoker.CREATE_UNIQUE_OBJECT_NAME</code>
+      (actual value "createUniqueObjectName") to "true".</para>
+      
+      <section>
+         <title>Configuration</title>
+         
+        <para><emphasis role="bold">unwrapSingletonArrays</emphasis> - If the map
+        returned by <methodname>javax.servlet.http.HttpServletRequest.getParameterMap()</methodname>
+        maps a String key to an array of length one, the value in the array will be extracted
+        and associated with the key.</para>
+        
+        <para><emphasis role="bold">createUniqueObjectName</emphasis> - If set to "true",
+        each <classname>InvokerLocator</classname> will be transformed into a unique
+        ObjectName.</para>
+      </section>
+      
       <bridgehead>Issues</bridgehead>
 
       <para>One of the issues of using Servlet invoker is that the invocation
@@ -6509,6 +6566,17 @@
       responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, "Custom response code and message from remoting server");
 </programlisting>
 
+    <para><emphasis role="bold">RESPONSE_HEADERS</emphasis> (actual value is
+    'ResponseHeaders') - key for returning the value of
+    <methodname>java.net.URLConnection.getHeaderFields()</methodname>. In other
+    words, a map containing all of the response headers is stored in the
+    metadata map. For example,</para>
+    
+    <programlisting>Object payload = ... ;
+HashMap metadata = new HashMap();
+client.invoke(payload, metadata);
+Map responseHeaders = (Map) metadata.get(HTTPMetadataConstants.RESPONSE_HEADERS);</programlisting>
+
     <para><emphasis role="bold">NO_THROW_ON_ERROR</emphasis> (actual value is
     'NoThrowOnError') - key indicating if http client invoker (for transports
     http, https, servlet, and sslservlet) should throw an exception if the