[jboss-cvs] JBossRemoting/docs/guide/en ...
Tom Elrod
tom.elrod at jboss.com
Thu Jul 27 15:54:58 EDT 2006
User: telrod
Date: 06/07/27 15:54:58
Modified: docs/guide/en master.xml
Log:
JBREM-507 - changed some config property values to be consistent and added config properties to doc.
Revision Changes Path
1.29 +653 -12 JBossRemoting/docs/guide/en/master.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: master.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/master.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -b -r1.28 -r1.29
--- master.xml 25 Jul 2006 21:57:50 -0000 1.28
+++ master.xml 27 Jul 2006 19:54:58 -0000 1.29
@@ -3807,6 +3807,631 @@
configuration for the server socket factory) and the key store password
has not been set.</para>
</section>
+
+ <section>
+ <title>Configuration by properties</title>
+
+ <para>This section covers configuration properties by constant values
+ and bean properties for individual classes. This will duplicate some of
+ the configuration properties already covered and is just another view to
+ some of the same information.</para>
+
+ <bridgehead>org.jboss.remoting.InvokerLocator</bridgehead>
+
+ <para><emphasis role="bold">SERVER_BIND_ADDRESS</emphasis> (actual value
+ is 'jboss.bind.address') - indicates the system property key for bind
+ address that should be used.</para>
+
+ <para><emphasis role="bold">BIND_BY_HOST</emphasis> (actual value is
+ 'remoting.bind_by_host') - indicates the system property key for if the
+ local bind address should be by host name (e.g.
+ InetAddress.getLocalHost().getHostName()) or if should be by IP (e.g.
+ InetAddress.getLocalHost().getHostAddress()). The default is 'True',
+ meaning will will use local host name. This configuration only applies
+ when the initial bind address is 0.0.0.0 (or InvokerLocator.ANY).</para>
+
+ <para><emphasis role="bold">DATATYPE</emphasis> (actual value is
+ 'datatype') - indicates the marshalling datatype that should be used for
+ a particular invoker. Each invoker has its own default marshaller and
+ unmarshaller based on default datatype. For examle, the socket transport
+ has a default datatype of 'serializable', which is has a default
+ registry within the MarshalFactory to use
+ org.jboss.remoting.marshal.serializable.SerializableMarshaller and
+ org.jboss.remoting.marshal.serializable.SerializableUnMarshaller. The
+ marshaller and unmarshaller used by an invoker can be overriden by
+ setting the 'datatype' parameter within the LocatorInvoker. For example,
+ could use a locator url of:</para>
+
+ <programlisting>socket://myhost:6500/?datatype=test</programlisting>
+
+ <para>which would cause the socket invoker to use the marshaller and
+ unmarshaller registered with the MarshalFactory under the datatype
+ 'test'. Of course, this require that the marshaller and unmarshaller
+ implementations to be used have already been registered with the
+ MarshalFactory (otherwise will get an exception).</para>
+
+ <para><emphasis role="bold">SERIALIZATIONTYPE</emphasis> (actual value
+ is 'serializationtype') - indicates the serialization implementation to
+ use. Currently, the only possible values are 'java' and 'jboss'. Java
+ serialization is the default. Setting to 'jboss' will cause JBoss
+ Serialization to be used. In implementation, this equates to the
+ parameter that will be passed to the
+ SerializationStreamFactory.getManagerInstance() method. This
+ configuration can be set as an invoker locator url parameter (e.g.
+ socket://myhost:5400/?serializationtype=jboss) or as an entry to the
+ configuration Map passed when constructing a remoting client or
+ server.</para>
+
+ <para><emphasis role="bold">MARSHALLER</emphasis> (actual value is
+ 'marshaller') - used to indicate which marshaller implementation should
+ be used by the invoker. This is an override for whatever the invoker's
+ default implementation is. This can be set as a parameter of the invoker
+ locator url (e.g.
+ socket://myhost:6500/?marshaller=org.jboss.test.remoting.marshall.dynamic.remote.http.TestMarshaller).
+ Using this configuration requires that the value be the fully qualified
+ classname of the marshaller implementation to use (which must be on the
+ classpath, have a void constructor, and implement the
+ org.jboss.remoting.marshal.Marshaller interface).</para>
+
+ <para><emphasis role="bold">UNMARSHALLER</emphasis> (actual value is
+ 'unmarshaller') - used to indicate which unmarshaller implementation
+ should be used by the invoker. This is an override for whatever the
+ invoker's default implementation is. This can be set as a parameter of
+ the invoker locator url (e.g.
+ socket://myhost:6500/?unmarshaller=org.jboss.test.remoting.marshall.dynamic.remote.http.TestUnMarshaller).
+ Using this configuration requires that the value be the fully qualified
+ classname of the unmarshaller implementation to use (which must be on
+ the classpath, ahve a void constructor, and implement the
+ org.jboss.remotng.marshal.UnMarshaller interface).</para>
+
+ <para><emphasis role="bold">LOADER_PORT</emphasis> (actual value is
+ 'loaderport') - indicates the port number where the class loader server
+ resides. This can be used when is possible that a client may not have
+ particular classes locally and would want to load them from ther
+ dynamically. This property can be set as a parameter to the invoker
+ locator url. A clasic example of when this might be used would be in
+ conjunction with using custom marshalling. For example, if have
+ configured a server to use custom marshaller and unmarshaller that the
+ client will not have access to, could create a invoker locator such
+ as:</para>
+
+ <programlisting>socket://myhost:6500/?datatype=test&loaderport=6501&
+marshaller=org.jboss.test.remoting.marshall.dynamic.remote.http.TestMarshaller&
+unmarshaller=org.jboss.test.remoting.marshall.dynamic.remote.http.TestUnMarshaller</programlisting>
+
+ <para>When the client invoker begins to make an invocation, will try to
+ look up marshaller and unmarshaller based on type ('test' in this case)
+ and when can not find a registry entry for it, will try to load the
+ TestMarshaller and TestUnMarshaller from the classpath. When the classes
+ can not be found locally, will make a call to the loader server (on port
+ 6501) to load the classes locally. Once they are retreived from the
+ server, will be registered locally, so is a one time only event (as next
+ time will be found in the registry).</para>
+
+ <para>This can work for loading any remote server classes, but requires
+ the loaderport be included in the invoker locator url.</para>
+
+ <para><emphasis role="bold">BYVALUE</emphasis> (actual value is
+ 'byvalue') - indicates if when making local invocations (meaning client
+ and server invoker exists within same jvm), the marshalling will be done
+ by value, instead of the default, by reference. Using this
+ configuration, the marshalling will actually perform a clone of the
+ object instance (see
+ org.jboss.remoting.serialization.SerializationManager.createMarshalledValueForClone()).
+ Value for this property should be of type String and be either 'true' or
+ 'false'.</para>
+
+ <para><emphasis role="bold">FORCE_REMOTE</emphasis> (actual value is
+ 'force_remote') - indicates if when making local invocations (meaning
+ client and server invoker exists within same jvm), the remote invokers
+ should be used instead of local invoker. Is equivalent to making
+ invocations as though client and server were in different jvms). Value
+ for this property should be of type String and be either 'true' or
+ 'false'.</para>
+
+ <para><emphasis role="bold">CLIENT_LEASE</emphasis> (actual value is
+ 'leasing') - indicates if client should try to automatically establish a
+ lease with the server. Is false by default. Value for this property
+ should be of type String and be either 'true' or 'false'.</para>
+
+ <para><emphasis role="bold">CLIENT_LEASE_PERIOD</emphasis> (actual value
+ is 'lease_period') - defines what the client lease period should be in
+ the case that server side leasing is turned on. Value for this parameter
+ key should be the number of milliseconds to wait before each client
+ lease renewal and must be greater than zero in order to be recognized.
+ If this property is not set (and CLIENT_LEASE is), will use the lease
+ period as specified by the server.</para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.Client</bridgehead>
+
+ <para><emphasis role="bold">RAW</emphasis> (actual value is
+ 'rawPayload') - key to use for the metadata Map passed when making a
+ invoke() call and wish for the invocation payload to be sent as is and
+ not wrapped within a remoting invocation request object. This should be
+ used when want to make direct calls on systems outside of remoting (e.g.
+ making a http POST request to a web service).</para>
+
+ <para><emphasis role="bold">ENABLE_LEASE</emphasis> (actual value is
+ 'enableLease') - key for the configuration map passed to the Client
+ constructor to indicate that client should make initial request to
+ establish lease with server. The value for this should be either a
+ String that java.lang.Boolean can evaluate or a java.lang.Boolean. By
+ default, leasing is turned off, so this property would be used to turn
+ on leasing for the client.</para>
+
+ <para><emphasis role="bold">HANDSHAKE_COMPLETED_LISTENER</emphasis>
+ (actual value is 'handshakeCompletedListener') - key for the
+ configuration map passed to the Client constructor providing a ssl
+ javax.net.ssl.HandshakeCompletedListener implementation, which will be
+ called on when ssl handshake completed with server.</para>
+
+ <para></para>
+
+ <para>The following three configuration properties are only useful when
+ using one of the following Client methods:</para>
+
+ <programlisting>public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject) throws Throwable
+public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject, boolean serverToClient) throws Throwable</programlisting>
+
+ <para> <emphasis role="bold">CALLBACK_SERVER_PROTOCOL</emphasis> (actual
+ value is 'callbackServerProtocol') - key for the configuration when
+ adding a callback handler and internal callback server connector is
+ created. The value should be the transport protocol to be used. By
+ default will use the same protocol as being used by this client (e.g.
+ http, socket, rmi, multiplex, etc.).</para>
+
+ <para><emphasis role="bold">CALLBACK_SERVER_HOST</emphasis> (actual
+ value is 'callbackServerHost') - key for the configuration when adding a
+ callback handler and internal callback server connector is created. The
+ value should be the host name to be used. By default will use the result
+ of calling InetAddress.getLocalHost().getHostAddress().</para>
+
+ <para><emphasis role="bold">CALLBACK_SERVER_PORT</emphasis> (actual
+ value is 'callbackServerPort') - key for the configuration when adding a
+ callback handler and internal callback server connector is created. The
+ value should be the port to be used. By default will find a random
+ unused port. </para>
+
+ <para></para>
+
+ <para><emphasis role="bold">Bean properties (meaning have
+ getter/setter):</emphasis> <emphasis role="bold">SessionId</emphasis> -
+ session id used when making invocations on server invokers. There is a
+ default unique id automatically generated for each Client instance, so
+ unless you have a good reason to set this, do not set this.</para>
+
+ <para><emphasis role="bold">Subsystem</emphasis> - the subsystem being
+ used when routing invocation requests on the server side. Specifing a
+ subsystem is only needed when server has multiple handlers registered
+ (which will each have their own associated subsystem). Best if specified
+ using Client constructor.</para>
+
+ <para><emphasis role="bold">MaxNumberOfThreads</emphasis> - the maximum
+ number of threads to use within client pool for one way invocations on
+ the client side (meaning oneway invocation is handled by thread in this
+ pool and user's call returns immediately) Default value is
+ MAX_NUM_ONEWAY_THREADS (whose value is 10).</para>
+
+ <para><emphasis role="bold">OnewayThreadPool</emphasis> - the thread
+ pool being used for making one way invocations on the client side. If
+ one has not be specifically set via configuration or call to set it,
+ will always return instance of
+ org.jboss.util.threadpool.BasicThreadPool.</para>
+
+ <para><emphasis role="bold">SocketFactory</emphasis> - instance of
+ javax.net.SocketFactory, which can only be set on the Client before the
+ connect() method has been called. Otherwise, a runtime exception will be
+ thrown.</para>
+
+ <para><emphasis role="bold">Marshaller</emphasis> - the marshaller
+ implementation that should be used by the client invoker (transport).
+ This overrides the client's default marshaller (or any set within
+ configuration).</para>
+
+ <para><emphasis role="bold">UnMarshaller</emphasis> - the unmarshaller
+ implementation that should be used by the client invoker (transport).
+ This overrides the client's default unmarshaller (or any set within
+ configuration). </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.Remoting</bridgehead>
+
+ <para><emphasis role="bold">CUSTOM_SERVER_SOCKET_FACTORY</emphasis>
+ (actual value is 'customServerSocketFactory') - key for the
+ configuration map passed to a Connector to indicate the server socket
+ factory to be used. This will override the creation of any other socket
+ factory. Value must be an instance of
+ javax.net.ServerSocketFactory.</para>
+
+ <para><emphasis role="bold">CUSTOM_SOCKET_FACTORY</emphasis> (actual
+ value is 'customSocketFactory') - key for the configuration map passed
+ to a Client to indicate the socket factory to be used. This will
+ override the creation of any other socket factory. Value must be
+ instance of javax.net.SocketFactory.</para>
+
+ <para><emphasis role="bold">SOCKET_FACTORY_NAME</emphasis> (actual value
+ is 'customSocketFactoryName') - key for the configuration map passed to
+ a Client to indicate the classname of the socket factory to be used.
+ Value should be fully qualified classname of class that is an instance
+ of javax.net.SocketFactory and has a void constructor. This property
+ will not be used if CUSTOM_SOCKET_FACTORY is also set. </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.ServerInvoker</bridgehead>
+
+ <para><emphasis role="bold">MAX_NUM_ONEWAY_THREADS_KEY</emphasis>
+ (actual value is 'maxNumThreadsOneway') - key for the maximum number of
+ thread to be used in the thread pool for one way invocations (server
+ side). This property is only used when the default oneway thread pool is
+ used.</para>
+
+ <para><emphasis role="bold">ONEWAY_THREAD_POOL_CLASS_KEY</emphasis>
+ (actual value is 'onewayThreadPool') - key for setting the setting the
+ oneway thread pool to use. The value used with this key will first be
+ checked to see if is a JMX ObjectName and if so, try to look up
+ associated mbean for the ObjectName given and cast to type
+ org.jboss.util.threadpool.ThreadPoolMBean (via
+ MBeanServerInvocationHandler.newProxyInstance()). If the value is not a
+ JMX ObjectName, will assume is a fully qualified classname and load the
+ coresponding class and create a new instance of it (which will require
+ it to have a void constructor). The newly created instance will then be
+ cast to type of org.jboss.util.threadpool.ThreadPool.</para>
+
+ <para><emphasis role="bold">SERVER_BIND_ADDRESS_KEY</emphasis> (actual
+ value is 'serverBindAddress') - key for setting the address the server
+ invoker should bind to. The value can be either host name or IP.</para>
+
+ <para><emphasis role="bold">CLIENT_CONNECT_ADDRESS_KEY</emphasis>
+ (actual value is 'clientConnectAddress') - key for setting the addres
+ the client invoker should connecto to. This should be used when client
+ will be connecting to server from outside the server's network and the
+ external address is different from that of the internal address the
+ server invoker will bind to (e.g. using NAT to expose different external
+ address). This will mostly be useful when client uses remoting detection
+ to discover remoting servers. The value can be either host name or
+ IP.</para>
+
+ <para><emphasis role="bold">SERVER_BIND_PORT_KEY</emphasis> (actual
+ value is 'serverBindPort') - key for setting the port the server invoker
+ should bind to. If the value supplied is less than or equal to zero, the
+ server invoker will randomly choose a free port to use.</para>
+
+ <para><emphasis role="bold">CLIENT_CONNECT_PORT_KEY</emphasis> (actual
+ value is 'clientConnectPort') - key for setting the port the client
+ invoker should connect to. This should be used when client will be
+ connecting to server from outside the server's network and the external
+ port is different from that of the internal port the server invoker will
+ bind to (e.g. using NAT to expose different port routing). This will be
+ mostly useful when client uses remoting detection to discover remoting
+ servers.</para>
+
+ <para><emphasis role="bold">CLIENT_LEASE_PERIOD</emphasis> (actual value
+ is 'clientLeasePeriod') - key used for setting the amount of time (in
+ milliseconds) that a client should renew its lease. If this value is not
+ set, the default of five seconds (see DEFAULT_CLIENT_LEASE_PERIOD), will
+ be used. This value will also be what is given to the client when it
+ initially querys server for leasing information.</para>
+
+ <para><emphasis role="bold">TIMEOUT</emphasis> (actual value is
+ 'timeout') - key for setting the timeout value (in milliseconds) for
+ socket connections.</para>
+
+ <para><emphasis role="bold">SERVER_SOCKET_FACTORY</emphasis> (actual
+ value is 'serverSocketFactory') - key for setting the value for the
+ server socket factory to be used by the server invoker. The value can be
+ either a JMX Object name, in which case will lookup the mbean and create
+ a proxy to it with type of
+ org.jboss.remoting.security.ServerSocketFactoryMBean (via
+ MBeanServerInvocationHandler.newProxyInstance()). If not a JMX
+ ObjectName, will assume is the fully qualified classname to the
+ implementation to be used and will load the class, create a new instance
+ of it (which requires it to have a void constructor). The instance will
+ then be cast to type javax.net.ServerSocketFactory.</para>
+
+ <para></para>
+
+ <para><emphasis role="bold">Bean properties (meaning have
+ getter/setter):</emphasis></para>
+
+ <para><emphasis role="bold">ServerSocketFactory</emphasis> -
+ implementation of javax.net.ServerSocketFactory to be used by the server
+ invoker. This takes precedence over any other configuration for the
+ server socket factory.</para>
+
+ <para><emphasis role="bold">Timeout</emphasis> - timeout (in
+ milliseconds) for socket connection. If set after create() method
+ called, this value will override value set by TIMEOUT key.</para>
+
+ <para><emphasis role="bold">LeasePeriod</emphasis> - the amount of time
+ (in milliseconds) that a client should renew its lease. If this value is
+ not set, the default of five seconds (see DEFAULT_CLIENT_LEASE_PERIOD),
+ will be used. This value will also be what is given to the client when
+ it initially querys server for leasing information. If set after
+ create() method called, this value will override value set by
+ CLIENT_LEASE_PERIOD key.</para>
+
+ <para><emphasis role="bold">MaxNumberOfOnewayThreads</emphasis> - the
+ maximum number of thread to be used in the thread pool for one way
+ invocations (server side). This property is only used when the default
+ oneway thread pool is used. If set after create() method called, this
+ value will override value set by MAX_NUM_ONEWAY_THREADS_KEY key.</para>
+
+ <para><emphasis role="bold">OnewayThreadPool</emphasis> - the oneway
+ thread pool to use.</para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.callback.CallbackPoller</bridgehead>
+
+ <para><emphasis role="bold">CALLBACK_POLL_PERIOD</emphasis> (actual
+ value is 'callbackPollPeriod') - key for setting the frequency (in
+ milliseconds) in which Client's internal callback poller should poll
+ server for waiting callbacks. This configuration is only necessary when
+ using one of the following Client methods:</para>
+
+ <programlisting>public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject) throws Throwable
+public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject, boolean serverToClient) throws Throwable</programlisting>
+
+ <para>and should be one of the entries in the metadata Map passed. This
+ will also only apply when the underlying transport is uni-directional
+ (e.g. socket, http, rmi). Bi-directional transports will not need to
+ poll. If this property is not set, the default (see
+ CallbackPoller.DEFAULT_POLL_PERIOD) value is five seconds. </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.callback.CallbackStore </bridgehead>
+
+ <para><emphasis role="bold">FILE_PATH_KEY</emphasis> (actual value is
+ 'StoreFilePath') - key for setting which directory to write the callback
+ objects. The default value is the property value of
+ 'jboss.server.data.dir' and if this is not set, then will be 'data'.
+ Will then append 'remoting' and the callback client's session id. An
+ example would be
+ 'data\remoting\5c4o05l-9jijyx-e5b6xyph-1-e5b6xyph-2'.</para>
+
+ <para><emphasis role="bold">FILE_SUFFIX_KEY</emphasis> (actual value is
+ 'StoreFileSuffix') - key for setting the file suffix to use for the
+ callback objects written to disk. The default value is ‘ser’. </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.callback.DefaultCallbackErrorHandler
+ </bridgehead>
+
+ <para><emphasis role="bold">CALLBACK_ERRORS_ALLOWED</emphasis> (actual
+ value is 'callbackErrorsAllowed') - key for setting the number of
+ callback exceptions will be allowed when calling on
+ org.jboss.remoting.callback.InvokerCallbackHandler.handleCallback(Callback
+ callback) before cleaning up the callback listener. This only applies to
+ push callback. The default if this property is not set is five. </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.callback.ServerInvokerCallbackHandler</bridgehead>
+
+ <para><emphasis role="bold">CALLBACK_STORE_KEY</emphasis> (actual value
+ is 'callbackStore') - key for specifing the callback store to be used.
+ The value can be either a JMX ObjectName or a fully qualified class
+ name, either way, must implement org.jboss.remoting.SerializableStore.
+ If using class name, the callback store implementation must have a void
+ constructor. The default is to use the
+ org.jboss.remoting.callback.NullCallbackStore.</para>
+
+ <para><emphasis role="bold">CALLBACK_ERROR_HANDLER_KEY</emphasis>
+ (actual value is 'callbackErrorHandler') - key for specifing the
+ callback exception handler to be used. The value can be either a JMX
+ ObjectName or a fully qualified class name, either way, must implement
+ org.jboss.remoting.callback.CallbackErrorHandler. If using class name,
+ the callback exception handler implementation must have a void
+ constructor. The default is to use
+ org.jboss.remoting.callback.DefaultCallbackErrorHandler.</para>
+
+ <para><emphasis role="bold">CALLBACK_MEM_CEILING</emphasis> (actual
+ value is 'callbackMemCeiling') - key for specifing the percentage of
+ free memory available before callbacks will be persisted. If the memory
+ heap allocated has reached its maximum value and the percent of free
+ memory available is less than the callbackMemCeiling, this will trigger
+ persisting of the callback message. The default value is 20. </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.detection.jndi.JNDIDetector</bridgehead>
+
+ <para><emphasis role="bold">Bean properties (meaning have
+ getter/setter):</emphasis> <emphasis
+ role="bold">SubContextName</emphasis> - sub context name under which
+ detection messages will be bound and looked up. </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.transport.http.HTTPMetadataConstants</bridgehead>
+
+ <para>The following are keys to use to get corresponding values from the
+ Map returned from call to
+ org.jboss.remoting.InvocationRequest.getRequestPayload() within a
+ org.jboss.remoting.ServerInvocationHandler implementation. For
+ example:</para>
+
+ <programlisting> public Object invoke(InvocationRequest invocation) throws Throwable
+ {
+ Map headers = invocation.getRequestPayload();
+</programlisting>
+
+ <para>Where variable ‘headers’ will contain entries for the following
+ keys.</para>
+
+ <para><emphasis role="bold">METHODTYPE</emphasis> (actual value is
+ ‘MethodType’) – key for getting the method type used by client in http
+ request. This will be populated within the Map returned from call to
+ org.jboss.remoting.InvocationRequest.getRequestPayload() within a
+ org.jboss.remoting.ServerInvocationHandler implementation. For example:
+ </para>
+
+ <programlisting> public Object invoke(InvocationRequest invocation) throws Throwable
+ {
+ Map headers = invocation.getRequestPayload();
+ String methodType = (String) headers.get(HTTPMetadataConstants.METHODTYPE);
+ if(methodType != null)
+ {
+ if(methodType.equals("GET"))
+ …
+</programlisting>
+
+ <para> <emphasis role="bold">PATH</emphasis> (actual value is ‘Pathâ€) –
+ key for getting the path from the url request from the calling client.
+ This will be populated within the Map returned from call to
+ org.jboss.remoting.InvocationRequest.getRequestPayload() within a
+ org.jboss.remoting.ServerInvocationHandler implementation. For example:
+ </para>
+
+ <programlisting> public Object invoke(InvocationRequest invocation) throws Throwable
+ {
+ Map headers = invocation.getRequestPayload();
+ String path = (String) headers.get(HTTPMetadataConstants.PATH);
+ …
+</programlisting>
+
+ <para> <emphasis role="bold">HTTPVERSION</emphasis> (actual value is
+ ‘HttpVersion’) – key for getting the HTTP version from the calling
+ client request (e.g. HTTP/1.1). </para>
+
+ <para></para>
+
+ <para></para>
+
+ <para><emphasis role="bold">RESPONSE_CODE</emphasis> (actual value is
+ ‘ResponseCode’) – key for getting and setting the HTTP response code.
+ Will be used as key to get the response code from metadata Map passed to
+ the Client’s invoke() method after the invocation has been made. For
+ example:</para>
+
+ <programlisting>Map metadata = new HashMap();
+Object response = remotingClient.invoke(myPayloadObject, metadata);
+Integer responseCode = (Integer) metadata.get(HTTPMetadataConstants.RESPONSE_CODE);
+</programlisting>
+
+ <para>Will be used as key to put the response code in the return payload
+ map from invocation handler. For example:</para>
+
+ <programlisting> public Object invoke(InvocationRequest invocation) throws Throwable
+ {
+ Map responseHeaders = invocation.getReturnPayload();
+ responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE, new Integer(202));
+</programlisting>
+
+ <para> <emphasis role="bold">RESPONSE_CODE_MESSAGE</emphasis> (actual
+ value is 'ResponseCodeMessage') - key for getting and setting the HTTP
+ response code message. Will be used as the key to get the response code
+ message from metadata Map passed to the Client's invoke() method after
+ the invocation has been made. For example:</para>
+
+ <programlisting>Map metadata = new HashMap();
+Object response = remotingClient.invoke(myPayloadObject, metadata);
+String responseCodeMessage = (String) metadata.get(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE);
+</programlisting>
+
+ <para>Will be used as key to put the response code message in the return
+ payload map from invocation handler. For example:</para>
+
+ <programlisting> public Object invoke(InvocationRequest invocation) throws Throwable
+ {
+ Map responseHeaders = invocation.getReturnPayload();
+ responseHeaders.put(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE, "Custom response code and message from remoting server");
+</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 server response code is equal to or greater than 400.
+ Unless set to true, the client invoker will by default throw either the
+ exception that originated on the server (if using remoting server) or
+ throw a org.jboss.remoting.transport.http.WebServerError, whose message
+ will be the error html returned from the web server.</para>
+
+ <para></para>
+
+ <para>For every http client request made from remoting client, a
+ remoting version and remoting specific user agent will be set as a
+ request property. The request property key for the remoting version will
+ be 'JBoss-Remoting-Version' and the value will be set based on return
+ from call to Version.getDefaultVersion(). The 'User-Agent' request
+ property value will be set to the evaluation of '"JBossRemoting - " +
+ Version.VERSION'.</para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.transport.http.ssl.HTTPSClientInvoker</bridgehead>
+
+ <para><emphasis role="bold">IGNORE_HTTPS_HOST</emphasis> (actual value
+ is 'org.jboss.security.ignoreHttpsHost') - key indicating if the http
+ client invoker (for transports https and sslservlet) should ignore host
+ name verification (meaning will not check for URL's hostname and
+ server's identification hostname mismatch during handshaking). By
+ default, if this not set to true, standard hostname verification will be
+ performed.</para>
+
+ <para><emphasis role="bold">HOSTNAME_VERIFIER</emphasis> (actual value
+ is 'hostnameVerifier') - key indicating the hostname verifier that
+ should be used by the http client invoker. The value should be the fully
+ qualified classname of class that implements
+ javax.net.ssl.HostnameVerifier and has a void constructor.</para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.transport.rmi.RMIServerInvoker</bridgehead>
+
+ <para><emphasis role="bold">REGISTRY_PORT_KEY</emphasis> (actual value
+ is 'registryPort') - the port on which to create the RMI registry. The
+ default is 3455. This also needs to have the isParam attribute set to
+ true. </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.transport.socket.MicroSocketClientInvoker
+ </bridgehead>
+
+ <para><emphasis role="bold">TCP_NODELAY_FLAG</emphasis> (actual value is
+ 'enableTcpNoDelay') - can be either true or false and will indicate if
+ client socket should have TCP_NODELAY turned on or off. TCP_NODELAY is
+ for a specific purpose; to disable the Nagle buffering algorithm. It
+ should only be set for applications that send frequent small bursts of
+ information without getting an immediate response; where timely delivery
+ of data is required (the canonical example is mouse movements). The
+ default is false.</para>
+
+ <para><emphasis role="bold">MAX_POOL_SIZE_FLAG</emphasis> (actual value
+ is 'clientMaxPoolSize') - the client side maximum number of threads. The
+ default is 50.</para>
+
+ <para><emphasis role="bold">CLIENT_SOCKET_CLASS_FLAG</emphasis> (actual
+ value is 'clientSocketClass') - specifies the fully qualified class name
+ for the custom SocketWrapper implementation to use on the client. Note,
+ will need to make sure this is marked as a client parameter (using the
+ 'isParam' attribute). Making this change will not affect the
+ marshaller/unmarshaller that is used, which may also be a requirement.
+ </para>
+
+ <para></para>
+
+ <bridgehead>org.jboss.remoting.transport.socket.SocketServerInvoker
+ </bridgehead>
+
+ <para><emphasis role="bold">CHECK_CONNECTION_KEY</emphasis> (actual
+ value is 'socket.check_connection') - key for indicating if socket
+ invoker should continue to keep socket connection between client and
+ server open after invocations by sending a ping on the connection before
+ being re-used. The default for this is false.</para>
+
+ <para><emphasis role="bold">SERVER_SOCKET_CLASS_FLAG</emphasis> (actual
+ value is 'serverSocketClass') - specifies the fully qualified class name
+ for the custom SocketWrapper implementation to use on the server.
+ </para>
+ </section>
</chapter>
<chapter>
@@ -3910,18 +4535,27 @@
<chapter>
<title>Serialization</title>
- <para>JBoss Remoting allows for the plugging in of custom serialization
- implementations. This is available via the
+ <para> Serialization – how it works within remoting In general, remoting
+ will rely on a factory to provide the serialization implementation, or
+ <code>org.jboss.remoting.serialization.SerializationManager</code>, to be
+ used when doing object serialization. This factory is
<code>org.jboss.remoting.serialization.SerializationStreamFactory</code>
- class, which will provide the implementation as a
- <code>org.jboss.remoting.serialization.SerializationManager</code> . The
- SerializationManager can then be called on to get implementations for
- <code>java.io.ObjectInputStream</code> and
- <code>java.io.ObjectOutputStream</code> . This SerializationManager is
- used by most of the standard remoting marshallers and unmarshallers. There
- are currently two implementations of the SerializationManager; one for the
- standard java serialization, which is the default, and one for JBoss
- Serialization.</para>
+ and is a (as defined by its javadoc):</para>
+
+ <literallayout>“factory is for defining the Object stream implemenations to be used along with creating those implemenations for use.
+The main function will be to return instance of ObjectOutput and ObjectInput. By default, the implementations will be
+java.io.ObjectOutputStream and java.io.ObjectInputStream.â€
+</literallayout>
+
+ <para>Currently there are only two different types of serialization
+ implementations; ‘java’ and ‘jboss’. The ‘java’ type uses
+ <code>org.jboss.remoting.serialization.impl.java.JavaSerializationManager</code>
+ as the SerializationManager implementation and is backed by standard Java
+ serialization provide by the JVM, which is the default. The ‘jboss’ type
+ uses
+ <code>org.jboss.remoting.serialization.impl.jboss.JBossSerializationManager</code>
+ as the SerializationManger implementation and is backed by JBoss
+ Serialization. </para>
<para>JBoss Serialization is a new project under development to provide a
more performant implementation of object serialization. It complies with
@@ -3933,7 +4567,14 @@
<para>- different protocol</para>
- <para>JBoss Serialization requires JDK 1.5.</para>
+ <para>JBoss Serialization requires JDK 1.5</para>
+
+ <para></para>
+
+ <para>It is possible to override the default SerializationManger
+ implementation to be used by setting the system property ‘SERIALIZATION’
+ to the fully qualified name of the class to use (which will need to
+ provide a void contructor). </para>
</chapter>
<chapter>
More information about the jboss-cvs-commits
mailing list