Author: ron.sigal(a)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