[jboss-cvs] JBossRemoting/docs/guide/en ...
Ron Sigal
ron_sigal at yahoo.com
Wed Aug 2 02:44:14 EDT 2006
User: rsigal
Date: 06/08/02 02:44:14
Modified: docs/guide/en chap5.xml
Log:
JBREM-559: Corrected typos.
Revision Changes Path
1.6 +83 -77 JBossRemoting/docs/guide/en/chap5.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap5.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap5.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- chap5.xml 1 Aug 2006 22:31:39 -0000 1.5
+++ chap5.xml 2 Aug 2006 06:44:14 -0000 1.6
@@ -323,7 +323,7 @@
<bridgehead>HTTP Client</bridgehead>
<para>The HttpClientInvoker will now put the return from
- HTTPURLConnection's getHeaderFields() method into the metadata map
+ HttpURLConnection getHeaderFields() method into the metadata map
passed to the Client's invoke() method (if not null). This means that if
the caller passes a non-null Map, it can then get the response headers.
It is important to note that each response header field key in the
@@ -682,8 +682,8 @@
<para><emphasis role="bold">socket.check_connection</emphasis> -
indicates if the invoker should try to check the connection before
re-using it by sending a single byte ping from the client to the
- server and then back from the server. This config is needed for both
- client and server to work. This if false by default.</para>
+ server and then back from the server. This config needs to be set on
+ both client and server to work. This if false by default.</para>
<bridgehead>Configurations affecting the Socket invoker
client</bridgehead>
@@ -742,6 +742,12 @@
Making this change will not affect the marshaller/unmarshaller that is
used, which may also be a requirement.</para>
+ <para><emphasis role="bold">socket.check_connection</emphasis> -
+ indicates if the invoker should try to check the connection before
+ re-using it by sending a single byte ping from the client to the
+ server and then back from the server. This config needs to be set on
+ both client and server to work. This if false by default.</para>
+
<para>An example of locator uri for a socket invoker that has
TCP_NODELAY set to false and the client's max pool size of 30 would
be:</para>
@@ -825,7 +831,7 @@
initial client connections and the connection is released before the
timeout for the other 202 that are waiting (200 for backlog and 2
for accept thread), then they will be processed (of course this is a
- request by request determiniation).</para>
+ request by request determination).</para>
<bridgehead>client</bridgehead>
@@ -836,7 +842,7 @@
Then when finished making invocation, will return the still active
socket connection to the pool. As more client invocations are made,
is possible for the number of socket connections to reach the
- maximum allowd (which is controlled by 'clientMaxPoolSize'
+ maximum allowed (which is controlled by 'clientMaxPoolSize'
property). At this point, when the next client invocation is made,
it will keep trying to get an available connection from the pool,
waiting 1 second in between tries for up to maximum number of
@@ -846,13 +852,13 @@
<para>Once the socket client invoker goes get an available socket
connection from the pool, are not out of the woods yet. There is
- still a posibility that the socket connection returned, while still
- appearing to be valid, has timedout while sitting in the pool. So if
+ still a possibility that the socket connection returned, while still
+ appearing to be valid, has timed out while sitting in the pool. So if
discover this while trying to make invocation, will throw it away
and retry the whole process again. Will do this up to the number set
by the numberOfCallRetries before throwing an exception. The trick
here is that when get to numberOfCallRetries -2, will assume that
- any socket connection gotten from the pool will have timedout and
+ any socket connection gotten from the pool will have timed out and
will flush the pool all together so that the next retry will cause a
new socket connection to be recreated. A typical scenario when this
might occur is when have had a burst of client invocations and then
@@ -895,16 +901,17 @@
creates SSL socket and server socket factories by default.</para>
<para><emphasis role="bold">Note.</emphasis> The SSL RMI
- server invoker create a socket factory and passes it to a client
+ server invoker creates a socket factory and passes it to a client
invoker along with the RMI stub, so the socket factory must be
serializable. If the SSL RMI server invoker is allowed to create an
- <classname>SSLSocketFactory</classname> from SSL parameters, it will
+ <classname>SSLSocketFactory</classname> from SSL parameters, as
+ discussed in section <xref linkend="section-socket-factories"/>, it will
take care to create a serializable socket factory. However, if a
- socket factory is passed in to the server invoker by one of the
- methods discussed in section <xref linkend="section-socket-factories"/>,
- then the user is responsible for supplying
- a serializable socket factory.
- See <xref linkend="subsection-sslrmi"/> for more information.</para>
+ socket factory is passed in to the server invoker (also discussed in
+ section <xref linkend="section-socket-factories"/>),
+ then the user is responsible for supplying a serializable socket
+ factory. See <xref linkend="subsection-sslrmi"/> below for more
+ information. </para>
</section>
<section id="section-http-invoker" xreflabel="HTTP Invoker">
@@ -938,19 +945,18 @@
<code>org.apache.coyote.http11.Http11AprProtocol</code> protocol,
which is based on the Apache Portable Runtime (see <ulink
url="http://tomcat.apache.org/tomcat-5.5-doc/apr.html">http://tomcat.apache.org/tomcat-5.5-doc/apr.html</ulink>
- <!--<link linkend="???">http://tomcat.apache.org/tomcat-5.5-doc/apr.html</link>-->
and <ulink url="http://apr.apache.org/">http://apr.apache.org/</ulink>
- <!--<link linkend="???">http://apr.apache.org/</link>--> for more
+ for more
details). If want to use the APR implementation, simply put the
tcnative-1.dll (or tcnative-1.so) on the system path so can be loaded.
The APR native binaries can be found at <ulink
- url="http://tomcat.heanet.ie">http://tomcat.heanet.ie</ulink>.<!--<link linkend="???">http://tomcat.heanet.ie</link>--></para>
+ url="http://tomcat.heanet.ie">http://tomcat.heanet.ie</ulink>.</para>
<para>Note: There is a bug with release 1.1.1 of APR where get an
error upon shutting down (see JBREM-277 for more information). This
does not impact anything while running, but is still an issue when
shutting down (as upon starting up again, can get major problems).
- This should be fixed in a later release of APR and since can just
+ This should be fixed in a later release of APR so can just
replace the 1.1.1 version of tcnative-1.dll with the new one.</para>
<bridgehead>Client request headers</bridgehead>
@@ -963,7 +969,7 @@
session id to identify the client caller. If this is not passed, the
HTTP server invoker will try to create a session id based on
information that is passed. Note, this means if the sessionId is not
- passed as part of the header, there is no gurantee that the sessionId
+ passed as part of the header, there is no guarantee that the sessionId
supplied to the invocation handler will always indicate the request
from the same client.</para>
@@ -1006,7 +1012,7 @@
<para>There are a few ways in which to enable http proxy using the
HTTP client invoker. The first is simply to add the following
properties to the metadata Map passed on the Client's invoke() method:
- <code>http.proxyHost</code> and <code>http.proxyPort</code></para>
+ <code>http.proxyHost</code> and <code>http.proxyPort</code>.</para>
<para>An example would be:</para>
@@ -1030,7 +1036,7 @@
HTTP client invoker is to set the following system properties (either
via <code>System.setProperty()</code> method call or via JVM
arguments): <code>http.proxyHost</code>, <code>http.proxyPort</code>,
- and <code>proxySet</code></para>
+ and <code>proxySet</code>.</para>
<para>An example would be setting the following JVM arguments:</para>
@@ -1067,16 +1073,15 @@
authentication in this great world of web, not all possible
configurations have been tested (or even supported). If you find a
particular problem or see that a particular implementation is not
- supported, please enter an issue in Jira ( <!--<link linkend="???">http://jira.jboss.com</link>-->
- <ulink url="http://jira.jboss.com">http://jira.jboss.com</ulink> )
+ supported, please enter an issue in Jira
+ (<ulink url="http://jira.jboss.com">http://jira.jboss.com</ulink>)
under the JBossRemoting project, as this is where bugs and feature
requests belong. If after reading the documentation have unanswered
questions about how to use these features, please post them to the
- remoting forum ( <!--<link linkend="???">http://www.jboss.org/index.html?module=bb&op=viewforum&f=176</link> -->
- <ulink
+ remoting forum (<ulink
url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=176">
http://www.jboss.org/index.html?module=bb&op=viewforum&f=176
- </ulink> ).</para>
+ </ulink>).</para>
<bridgehead>Host name verification</bridgehead>
@@ -1183,7 +1188,7 @@
to the servlet server invoker it needs to pass its request onto. The
first is by using the param 'invokerName', as is shown above. The
value for this should be the JMX ObjectName for the servlet server
- invoker that was deployed as an service mbean (see service xml above).
+ invoker that was deployed as a service mbean (see service xml above).
The other way is to provide a param 'locatorUrl' with a value that
matches the locator url of the servlet server invoker to use. In this
case, will use the InvokerRegistry to find the server invoker instead
@@ -1215,7 +1220,7 @@
'sslservlet'. On the server side it is deployed exactly the same as a
servlet invoker would be but requires setting up ssl within the web
container (i.e. enabling the ssl connector within Tomcat's
- server.xml). This will usually specifing a different port as
+ server.xml). This will usually require specifing a different port as
well.</para>
<para>An example of the mbean service xml for deploying the ssl
@@ -1301,7 +1306,7 @@
stream. In the case that the data returned from this error stream is
of type java.lang.String (i.e. is error html), it will be wrapped in a
WebServerError and returned as this type. The raw data from the web
- server can the be retreived by getting the WebServerError's message.
+ server can the be retrieved by getting the WebServerError's message.
</para>
</section>
@@ -2232,7 +2237,7 @@
<programlisting>socket://myhost:5400/?datatype=serializable</programlisting>
<para>This can be done for types that are statically bound within the
- <code>MarshalFactory</code> , serializable and http, without requiring
+ <code>MarshalFactory</code>, serializable and http, without requiring
any extra coding, since they will be available to any user of remoting.
However, is more likely this will be used for custom marshallers (since
could just use the default data type from the invokers if using the
@@ -2380,7 +2385,7 @@
configuring this below).</para>
<para>By default, the persistent store used by the invokers is the
- <code>org.jboss.remoting.NullCallbackStore</code> . The
+ <code>org.jboss.remoting.NullCallbackStore</code>. The
NullCallbackStore will simply throw away the callback to help avoid
running out of memory. When the persistence policy is triggered and
the NullCallbackStore is called upon to store the callback, the
@@ -2392,8 +2397,8 @@
<para>and there will be an error in the log stating which object was
lost. In this same scenario, the client will get an instance of the
- <code>org.jboss.remoting.NullCallbackStore</code> .
- <code>FailedCallback</code> class when they call to get their
+ <code>org.jboss.remoting.NullCallbackStore.FailedCallback</code>
+ class when they call to get their
callbacks. This class will throw a RuntimeException with the following
message when <code>getCallbackObject()</code> is called:</para>
@@ -2671,8 +2676,8 @@
socket. Moreover, some server invokers, e.g., the RMI server invoker,
have their own idiosyncratic uses for socket factories. Remoting offers a
number of ways of configuring socket factories and server socket
- factories, and these apply to all transports.
- </para>
+ factories, and these apply to all transports (except for the servlet
+ invokers).</para>
<section id="section-ssf-serverside" xreflabel="Server socket factories">
<title>
@@ -3396,14 +3401,14 @@
dependent on the server invoker MBean, e.g.</para>
<programlisting>
- <mbean code="org.jboss.Blah" name="jboss.remoting:whatever,name=blah">
+ <mbean code="org.jboss.BlueMonkey" name="jboss.remoting:bluemonkey,name=diamond">
<depends optional-attribute-name="serverInvoker">
jboss.remoting:service=invoker,transport=socket,host=www.jboss.com,port=8765
</depends>
</mbean>
</programlisting>
- <para>then <methodname>org.jboss.Blah.create()</methodname> will have
+ <para>then <methodname>org.jboss.BlueMonkey.create()</methodname> will have
access to the designated server invoker after the invoker has been
created but before it has been started, which means that
<methodname>ServerInvoker.setServerSocketFactory()</methodname> will be
@@ -3416,7 +3421,8 @@
<title>SSL transports</title>
<para>There are now four transports that support SSL: https,
- sslmultiplex, sslrmi, and sslsocket. All of preceding discussion
+ sslmultiplex, sslrmi, and sslsocket (plus sslservlet, which is not
+ relevant here). All of the preceding discussion
applies to each of these, and, moreover, they are all extensions of their
non-ssl counterparts, so only some ssl specific information will be
added here.</para>
@@ -3475,7 +3481,7 @@
<para>See section <xref linkend="section-SSLServerSocketFactoryService"/>
below for a discussion of the
- "jboss.remoting:service=ServerSocketFactory,type=SSL'
+ "jboss.remoting:service=ServerSocketFactory,type=SSL"
MBean that appears in this configuration element.</para>
<para>Note that the configuration for SSL support only works when using the java
@@ -3499,20 +3505,18 @@
<bridgehead id="subsection-sslrmi" xreflabel="sslrmi">sslrmi</bridgehead>
- <para>The rules discussed in <xref linkend="section-socket-factories"/>
- for configuring socket and server
- socket factories apply to the SSL RMI transport, but there is a twist,
- since the server invoker creates the (client) socket factory and
- packages it with its own stub. It follows that the socket factory must be
- serializable. If the SSL RMI server invoker is allowed to create an
+ <para>The extra twist in the sslrmi invoker is that
+ the server invoker creates the (client) socket factory and packages it
+ with its own stub, from which it follows that the socket factory must
+ be serializable. If the sslrmi server invoker is allowed to create an
<classname>SSLSocketFactory</classname> from SSL parameters, it will
take care to create a serializable socket factory. In particular,
the server invoker creates a copy of
<classname>org.jboss.remoting.transport.rmi.ssl.SerializableSSLClientSocketFactory</classname>,
which is essentially just a holder for the configuration map passed to
the server invoker, with any parameters removed which concern trust
- store and key store configuration. On the client side, when a client
- SSL RMI invoker is created, it stores its own configuration map in a
+ store and key store configuration. On the client side, when an sslrmi
+ client invoker is created, it stores its own configuration map in a
static variable which the transferred
<classname>SerializableSSLClientSocketFactory</classname> can retrieve
and merge with the configuration information it brought with it from
@@ -3526,8 +3530,7 @@
<para><emphasis role="bold">Note.</emphasis> If instead of using
<classname>SerializableSSLClientSocketFactory</classname>, a
socket factory is passed in to the server invoker by one of the
- methods discussed in section <xref linkend="section-socket-factories"/>,
- then the user is responsible for supplying
+ methods discussed above, then the user is responsible for supplying
a serializable socket factory.</para>
<bridgehead>sslsocket</bridgehead>
@@ -4105,8 +4108,8 @@
'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
+ has a default datatype of 'serializable', which is automatically
+ registered with the MarshalFactory and associated by default with
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
@@ -4117,7 +4120,7 @@
<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
+ 'test'. Of course, this requires that the marshaller and unmarshaller
implementations to be used have already been registered with the
MarshalFactory (otherwise will get an exception).</para>
@@ -4152,13 +4155,13 @@
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
+ the classpath, have 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
+ particular classes locally and would want to load them from the server
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
@@ -4175,7 +4178,7 @@
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
+ 6501) to load the classes locally. Once they are retrieved from the
server, will be registered locally, so is a one time only event (as next
time will be found in the registry).</para>
@@ -4220,11 +4223,11 @@
<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
+ 'rawPayload') - key to use for the metadata Map passed when making an
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>
+ making an 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
@@ -4270,7 +4273,9 @@
<para></para>
<para><emphasis role="bold">Bean properties (meaning have
- getter/setter):</emphasis> <emphasis role="bold">SessionId</emphasis> -
+ getter/setter):</emphasis></para>
+
+ <para><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>
@@ -4289,7 +4294,7 @@
<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,
+ one has not been specifically set via configuration or call to set it,
will always return instance of
org.jboss.util.threadpool.BasicThreadPool.</para>
@@ -4321,12 +4326,11 @@
<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
+ to a Client to indicate the socket factory to be used. 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
+ is 'socketFactory') - 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
@@ -4338,7 +4342,7 @@
<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
+ threads 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>
@@ -4359,7 +4363,7 @@
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
+ (actual value is 'clientConnectAddress') - key for setting the address
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
@@ -4387,7 +4391,7 @@
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>
+ initially queries server for leasing information.</para>
<para><emphasis role="bold">TIMEOUT</emphasis> (actual value is
'timeout') - key for setting the timeout value (in milliseconds) for
@@ -4399,9 +4403,9 @@
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
+ MBeanServerInvocationHandler.newProxyInstance()), or, 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
+ implementation to be used and will load the class and 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>
@@ -4423,12 +4427,12 @@
(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
+ it initially queries 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
+ maximum number of threads 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>
@@ -4460,8 +4464,8 @@
<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
+ 'StoreFilePath') - key for setting the directory in which 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
@@ -4477,7 +4481,7 @@
<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
+ callback exceptions that 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>
@@ -4489,7 +4493,7 @@
<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.
+ 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>
@@ -4504,7 +4508,7 @@
org.jboss.remoting.callback.DefaultCallbackErrorHandler.</para>
<para><emphasis role="bold">CALLBACK_MEM_CEILING</emphasis> (actual
- value is 'callbackMemCeiling') - key for specifing the percentage of
+ value is 'callbackMemCeiling') - key for specifying 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
@@ -4515,7 +4519,9 @@
<bridgehead>org.jboss.remoting.detection.jndi.JNDIDetector</bridgehead>
<para><emphasis role="bold">Bean properties (meaning have
- getter/setter):</emphasis> <emphasis
+ getter/setter):</emphasis></para>
+
+ <para><emphasis
role="bold">SubContextName</emphasis> - sub context name under which
detection messages will be bound and looked up.</para>
@@ -4534,7 +4540,7 @@
Map headers = invocation.getRequestPayload();
</programlisting>
- <para>Where variable 'headers' will contain entries for the following
+ <para>where variable 'headers' will contain entries for the following
keys.</para>
<para><emphasis role="bold">METHODTYPE</emphasis> (actual value is
More information about the jboss-cvs-commits
mailing list