[jboss-cvs] JBossRemoting/docs/guide/en ...
Ron Sigal
ron_sigal at yahoo.com
Wed Mar 7 04:10:00 EST 2007
User: rsigal
Date: 07/03/07 04:10:00
Modified: docs/guide/en chap5.xml
Log:
JBREM-634: Reorganized callback store sections.
Revision Changes Path
1.16 +124 -104 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.15
retrieving revision 1.16
diff -u -b -r1.15 -r1.16
--- chap5.xml 7 Mar 2007 08:09:50 -0000 1.15
+++ chap5.xml 7 Mar 2007 09:10:00 -0000 1.16
@@ -2819,6 +2819,106 @@
</section>
<section>
+ <title>Callback stores.</title>
+
+ <para>
+ For pull callbacks (and also simulated push callbacks - see Section
+ <xref linkend="section-callback-handlers"/>), the
+ server has to manage callback messages
+ until the client calls to collect them. Since the server has no control
+ of when the client will call to get the callbacks, it has to be aware of
+ memory constraints as it manages a growing number of callbacks. The way
+ the callback server does this is through use of a
+ <emphasis role="bold">persistence policy</emphasis>.
+ </para>
+
+ <para>
+ The persistence policy indicates at what point the server has too little
+ free memory available and therefore the callback message should be put
+ into a persistent store. This policy can be configured via the
+ <code>memPercentCeiling</code> attribute (see more on configuring this
+ below).</para>
+
+ <para>By default, the persistent store used by the invokers is 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 invocation handler making the
+ call will be thrown an IOException with the message:</para>
+
+ <para><blockquote>Callback has been lost because not enough free memory to
+ hold object.</blockquote></para>
+
+ <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.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>
+
+ <para><blockquote>This is an invalid callback. The server ran out of
+ memory, so callbacks were lost.</blockquote></para>
+
+ <para>Also, the payload of the callback will be the same string. The
+ client will also get any valid callbacks that were kept in memory before
+ the persistence policy was triggered.</para>
+
+ <para>An example case when using the NullCallbackStore might be when
+ callback objects A, B, and C are stored in memory because there is
+ enough free memory. Then when callback D comes, the persistence policy
+ is triggered and the NullCallbackStore is asked to persist callback D.
+ The NullCallbackStore will throw away callback D and create a
+ FailedCallback object to take its place. Then callback E comes, and
+ there is still too little free memory, so that is thrown away by the
+ NullCallbackStore.</para>
+
+ <para>Then the client calls to get its callbacks. It will receive a List
+ containing callbacks A, B, C and the FailedCallback. When the client
+ asks the FailedCallback for its callback payload, it will throw the
+ aforementioned exception.</para>
+
+ <para>Besides the default NullCallbackStore, there is a truly persistent
+ CallbackStore, which will persist callback messages to disk so they will
+ not be lost. The description of the CallbackStore is as follows:</para>
+
+ <para><blockquote>Acts as a persistent list which writes Serializable
+ objects to disk and will retrieve them in same order in which they were
+ added (FIFO). Each file will be named according to the current time
+ (using System.currentTimeMillis() with the file suffix specified (see
+ Section <xref linkend="section-callback-store-configuartion"/>).
+ When the object is read and returned by calling the getNext()
+ method, the file on disk for that object will be deleted. If for some
+ reason the store VM crashes, the objects will still be available upon
+ next startup</blockquote></para>
+
+ <para>CallbackStore is also a service mbean, so can be run as a service
+ within JBoss AS or stand alone.</para>
+
+ <para>Remoting also offers the
+ <classname>BlockingCallbackStore</classname>,
+ which is described as follows.</para>
+
+ <para><blockquote>
+ This callback store does not persist callback messages when memory is
+ running low, but instead will block the thread making the handle
+ callback call from the server invoker. The intention is that this will
+ throttle the server invoker from generating/sending any more callbacks
+ until client as called to get the in-memory callbacks that have already
+ been collected and memory has been released.
+ </blockquote></para>
+
+ <para>Custom callback stores can also be implemented and defined within
+ configuration. The only requirement is that it implements the
+ org.jboss.remoting.SerializableStore interface and has a void
+ constructor (only in the case of using a fully qualified classname in
+ configuration).</para>
+
+ <para>Once a callback client has been removed as a listener, all
+ persisted callbacks will be removed from disk.</para>
+
+ </section>
+
+ <section>
<title>Callback acknowledgements</title>
<para>
@@ -3224,104 +3324,22 @@
</section>
- <section id="section-pull-callback-configuration" xreflabel="Server side configuration for pull callbacks">
- <title>Server side configuration of pull callbacks</title>
-
- <para>
- For pull callbacks (and also simulated push callbacks), the
- server has to manage callback messages
- until the client calls to collect them. Since the server has no control
- of when the client will call to get the callbacks, it has to be aware of
- memory constraints as it manages a growing number of callbacks. The way
- the callback server does this is through use of a
- <emphasis role="bold">persistence policy</emphasis>.
- </para>
-
- <para>
- The persistence policy indicates at what point the server has too little
- free memory available and therefore the callback message should be put
- into a persistent store. This policy can be configured via the
- <code>memPercentCeiling</code> attribute (see more on configuring this
- below).</para>
-
- <para>By default, the persistent store used by the invokers is 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 invocation handler making the
- call will be thrown an IOException with the message:</para>
-
- <para><literal>Callback has been lost because not enough free memory to
- hold object.</literal></para>
-
- <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.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>
-
- <para><literal>This is an invalid callback. The server ran out of
- memory, so callbacks were lost.</literal></para>
-
- <para>Also, the payload of the callback will be the same string. The
- client will also get any valid callbacks that were kept in memory before
- the persistence policy was triggered.</para>
-
- <para>An example case when using the NullCallbackStore might be when
- callback objects A, B, and C are stored in memory because there is
- enough free memory. Then when callback D comes, the persistence policy
- is triggered and the NullCallbackStore is asked to persist callback D.
- The NullCallbackStore will throw away callback D and create a
- FailedCallback object to take its place. Then callback E comes, and
- there is still too little free memory, so that is thrown away by the
- NullCallbackStore.</para>
-
- <para>Then the client calls to get its callbacks. It will receive a List
- containing callbacks A, B, C and the FailedCallback. When the client
- asks the FailedCallback for its callback payload, it will throw the
- aforementioned exception.</para>
-
- <para>Besides the default NullCallbackStore, there is a truly persistent
- CallbackStore, which will persist callback messages to disk so they will
- not be lost. The description of the CallbackStore is as follows:</para>
-
- <para><literal>Acts as a persistent list which writes Serializable
- objects to disk and will retrieve them in same order in which they were
- added (FIFO). Each file will be named according to the current time
- (using System.currentTimeMillis() with the file suffix specified (see
- below). When the object is read and returned by calling the getNext()
- method, the file on disk for that object will be deleted. If for some
- reason the store VM crashes, the objects will still be available upon
- next startup. The attributes to make sure to configure
- are:</literal></para>
-
- <para><literal>file path - this determines which directory to write the
- objects. The default value is the property value of
- 'jboss.server.data.dir' and if this is not set, then will be 'data'. For
- example, might be /jboss/server/default/data.</literal></para>
-
- <para><literal>file suffix - the file suffix to use for the file written
- for each object stored.</literal></para>
-
- <para><literal>This is also a service mbean, so can be run as a service
- within JBoss AS or stand alone.</literal></para>
+ <section id="section-callback-store-configuartion"
+ xreflabel="Callback store configuration">
+ <title>Callback store configuration.</title>
+
+ <para>All callback store configuration will need to be defined within the
+ server invoker configuration, since the server invoker is the parent that
+ creates the callback stores as needed (when client registers for pull
+ callbacks). Example service xml files are included below.</para>
+
+ <para>The following general callback store parameters may be configured.
+ They are defined as constants in the
+ <classname>org.jboss.callback.ServerInvokerCallbackHandler</classname>
+ class.</para>
- <para>Custom callback stores can also be implemented and defined within
- configuration. The only requirement is that it implements the
- org.jboss.remoting.SerializableStore interface and has a void
- constructor (only in the case of using a fully qualified classname in
- configuration).</para>
-
- <para>Once a callback client has been removed as a listener, all
- persisted callbacks will be removed from disk.</para>
-
- <para>All callback configuration will need to be defined within the
- invoker configuration, since the invoker is the parent that creates the
- callback servers as needed (when client registers for pull callbacks).
- Example service xml are included below.</para>
-
- <para><emphasis role="bold">callbackMemCeiling</emphasis> - the
+ <para><emphasis role="bold">CALLBACK_MEM_CEILING</emphasis> (actual value
+ is "callbackMemCeiling"): 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,
@@ -3337,27 +3355,29 @@
percentage ceiling is high, it might not trigger until after free memory
percentage is well below the ceiling.</para>
- <para><emphasis role="bold">callbackStore</emphasis> - specifies the
+ <para><emphasis role="bold">CALLBACK_STORE_KEY</emphasis> (actual value
+ is "callbackStore"): specifies the
callback store to be used. The value can be either an MBean ObjectName
or a fully qualified class name. If using class name, the callback store
implementation must have a void constructor. The default is to use the
NullCallbackStore.</para>
- <bridgehead>CallbackStore configuration</bridgehead>
-
- <para>The CallbackStore can be configured via the invoker configuration
- as well.</para>
+ <para>The following parameters specific to <classname>CallbackStore</classname>
+ can be configured via the invoker configuration as well. They are
+ defined as constants in the <classname>CallbackStore</classname>
+ class.</para>
- <para><emphasis role="bold">StoreFilePath</emphasis> - indicates to
+ <para><emphasis role="bold">FILE_PATH_KEY</emphasis> (actual value is
+ "StoreFilePath"): indicates to
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">StoreFileSuffix</emphasis> - indicates the
- file suffix to use for the callback objects written to disk. The default
- value is 'ser'.</para>
+ <para><emphasis role="bold">FILE_SUFFIX_KEY</emphasis> (actual value is
+ "StoreFileSuffix"): indicates the file suffix to use for the callback
+ objects written to disk. The default value is 'ser'.</para>
<bridgehead>Sample service configuration</bridgehead>
More information about the jboss-cvs-commits
mailing list