[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
msurtani at jboss.com
Tue Jan 23 10:23:23 EST 2007
User: msurtani
Date: 07/01/23 10:23:23
Modified: docs/JBossCache-UserGuide/en/modules deployment.xml
compatibility.xml basic_api.xml
Log:
Chapters 4 and 5
Revision Changes Path
1.2 +123 -146 JBossCache/docs/JBossCache-UserGuide/en/modules/deployment.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: deployment.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/deployment.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- deployment.xml 22 Jan 2007 22:50:09 -0000 1.1
+++ deployment.xml 23 Jan 2007 15:23:23 -0000 1.2
@@ -2,56 +2,56 @@
<title>Deploying JBoss Cache</title>
<section>
<title>Standalone Use</title>
- <para>TODO</para>
- </section>
-
- <section>
- <title>Via JNDI</title>
- <para>TODO</para>
+ <para>
+ When used in a standalone Java program, all that needs to be done is to instantiate the cache using the
+ <literal>CacheFactory</literal> and a <literal>Configuration</literal> instance or an XML file, as discussed
+ in the <link linkend="api">User API chapter</link>.
+ </para>
</section>
<section>
<title>Via JMX (JBoss AS 4.x)</title>
- <para>If JBoss Cache is run in JBoss AS then JBoss Cache can be deployed as an
+ <para>If JBoss Cache is run in JBoss AS 4.x then JBoss Cache can be deployed as an
MBean. The steps below illustrate how to do this. We do not deploy JBoss Cache as a
Service Archive (SAR), but as a JAR (
- <literal>jboss-cache.jar</literal>
- in the lib directory) and
+ <literal>jboss-cache.jar</literal> and all it's dependent jars in the lib directory) and
an XML file defining the MBean. Of course, JBoss Cache can also be
deployed as a SAR, or even as part of a WAR, EJB or EAR.
</para>
<para>First, the
- <literal>jboss-cache.jar</literal>
- file has to be copied to the /lib
+ <literal>jboss-cache.jar</literal> and all it's dependent jars
+ have to be copied to the /lib
directory and JBoss AS has to be restarted. Then a regular JBoss Cache
configuration file in XML format has to be copied to the /deploy
directory. The XML file format is the same as discussed in
- the Configuration chapter.
+ the <link linkend="configuration">configuration chapter</link>.
</para>
<para>In order to be used from a client such as a servlet in the Tomcat web
- container inside the same JBoss container, JMX can be used:
+ container inside the same JBoss container, a JMX lookup can be used:
</para>
<programlisting>
<![CDATA[
MBeanServer server=MBeanServerLocator.locateJBoss();
- TreeCacheMBean cache;
- cache=(TreeCacheMBean)MBeanProxyExt.create(TreeCacheMBean.class, "jboss.cache:service=TreeCache", server);
- cache.put("/a/b/c", null);
+ CacheJmxWrapperMBean cacheWrapper;
+ cacheWrapper = (CacheJmxWrapperMBean) MBeanProxyExt.create(CacheJmxWrapperMBean.class, "jboss.cache:service=Cache", server);
+ Cache cache = cacheWrapper.getCache();
+ cache.getRoot(); // etc etc
]]>
</programlisting>
<para>The MBeanServerLocator class is a helper to find the (only) JBoss
- MBean server inside the current VM. The static create() method creates a
+ MBean server inside the current JVM. The static create() method creates a
dynamic proxy to the given interface and uses JMX to dynamically dispatch
methods invoked against the generated interface. The name used to look up
the MBean is the same as defined in the configuration file.
</para>
+ </section>
<section>
- <title>Running as an MBean</title>
+ <title>Binding to JNDI</title>
<para>If JBoss Cache is run inside of JBoss AS (as an MBean), we can bind it
into JNDI using JrmpProxyFactory, just like any other MBean. Below is an
example of how to do this:
@@ -94,11 +94,10 @@
the MBean.
</para>
</section>
- </section>
<section>
<title>Via JBoss Microcontainer (JBoss AS 5.x)</title>
- <para>TODO</para>
+ <para><emphasis>TODO</emphasis></para>
</section>
<section>
@@ -111,95 +110,72 @@
<section>
<title>JBoss Cache MBeans</title>
- <para>JBoss Cache provides an MBean that allows JMX access to a cache instance. This MBean is accessible from
- an
- MBean
- server through the service name specified in the cache instance's configuration. For example, the Tomcat
- clustering cache instance
- is accessible through the service named "jboss.cache:service=TomcatClusteringCache." This MBean can be used
- to
- perform
- most cache operations via JMX.
- </para>
- <para>JBoss Cache also provides MBeans for each interceptor configured in the cache's interceptor stack. These
- MBeans
- are used to capture and expose statistics related to cache operations. They are hierarchically associated
- with
- the
- cache's primary MBean and have service names that reflect this relationship. For example, a replication
- interceptor MBean
- for the TomcatClusteringCache instance will be accessible through the service named
- "jboss.cache:service=TomcatClusteringCache,treecache-interceptor=ReplicationInterceptor."
+ <para>
+ JBoss Cache provides an MBean that allows JMX access to a cache instance. This MBean is accessible from
+ an MBean server through the service name specified in the cache instance's configuration. For example,
+ the Tomcat clustering cache instance is accessible through the service named
+ <literal>jboss.cache:service=TomcatClusteringCache</literal>. This MBean can be used to perform most cache
+ operations via JMX, as shown earlier.
+ </para>
+ <para>
+ JBoss Cache also provides MBeans for each interceptor configured in the cache's interceptor stack. These
+ MBeans are used to capture and expose statistics related to cache operations. They are hierarchically
+ associated with the cache's primary MBean and have service names that reflect this relationship. For
+ example, a replication interceptor MBean for the <literal>TomcatClusteringCache</literal> instance will be
+ accessible through the service named <literal>jboss.cache:service=TomcatClusteringCache,treecache-interceptor=ReplicationInterceptor</literal>.
</para>
</section>
<section>
<title>JBoss Cache Statistics</title>
- <para>JBoss Cache captures statistics in its interceptors and exposes the statistics through interceptor
- MBeans.
- Cache interceptor
- MBeans are enabled by default; these MBeans can be disabled for a specific cache instance through the
- <emphasis>UseInterceptorMbeans</emphasis>
- attribute. See the Configuration chapter for further details on configuration of this
- attribute.
- </para>
- <para>Each interceptor's MBean provides an attribute that can be used to disable maintenance of statistics for
- that interceptor.
- Note that the majority of the statistics are provided by the CacheMgmtInterceptor MBean so this interceptor
- is
- the most significant
- in this regard. If you want to disable all statistics for performance reasons, you should utilize the
- <emphasis>UseInterceptorMbeans</emphasis>
- configuration setting as this will prevent the CacheMgmtInterceptor from being included in the cache's
- interceptor stack when the
- cache is started.
+ <para>
+ JBoss Cache captures statistics in its interceptors and exposes the statistics through interceptor
+ MBeans. Cache interceptor MBeans are enabled by default; these MBeans can be disabled for a specific cache
+ instance through the <literal>UseInterceptorMbeans</literal> configuration attribute. See the
+ <link linkend="configuration_reference">Configuration Reference chapter</link> for further details on
+ this attribute.
+ </para>
+ <para>
+ Each interceptor's MBean provides an attribute that can be used to disable maintenance of statistics for
+ that interceptor. Note that the majority of the statistics are provided by the <literal>CacheMgmtInterceptorMBean</literal>
+ so this MBean is the most significant in this regard. If you want to disable all statistics for performance
+ reasons, you should utilize the <literal>UseInterceptorMbeans</literal> configuration setting as this will
+ prevent the <literal>CacheMgmtInterceptor</literal> from being included in the cache's interceptor stack
+ when the cache is started.
</para>
- <para>Each interceptor provides the following common operations and attributes.</para>
-
+ <para>Each interceptor provides the following common operations and attributes.
<itemizedlist>
- <listitem>dumpStatistics - returns a Map containing the interceptor's attributes and values.</listitem>
- <listitem>resetStatistics - resets all statistics maintained by the interceptor.</listitem>
- <listitem>setStatisticsEnabled(boolean) - allows statistics to be disabled for a specific interceptor.
- </listitem>
+ <listitem><literal>dumpStatistics</literal> - returns a <literal>Map</literal> containing the interceptor's attributes and values.</listitem>
+ <listitem><literal>resetStatistics</literal> - resets all statistics maintained by the interceptor.</listitem>
+ <listitem><literal>setStatisticsEnabled(boolean)</literal> - allows statistics to be disabled for a specific interceptor.</listitem>
</itemizedlist>
-
- <para>See the section in the
- <link
- linkend="jmx_reference.statistics">JMX Reference chapter
- </link>
- pertaining to the statistics that are made available via JMX.
+ See the section in the <link linkend="jmx_reference.statistics">JMX Reference chapter</link> pertaining to the
+ statistics that are made available via JMX.
</para>
</section>
<section>
- <title>Receiving Cache Notifications</title>
- <para>JBoss Cache users can register a listener to receive cache events as described in the Eviction Policies
- chapter.
- Users can alternatively utilize the cache's management information infrastructure to receive these events
- via
- JMX
- notifications. Cache events are accessible as notifications by registering a NotificationListener for the
- CacheMgmtInterceptor
- MBean. This functionality is only available if cache statistics are enabled as described in the previous
- section.
- </para>
-
- <para>See the section in the
- <link linkend="jmx_reference.notifications">JMX Reference chapter</link>
- pertaining to JMX notifications
- for a list of notifications that can be received through the
- <literal>CacheMgmtInterceptor</literal>
- MBean.
+ <title>Receiving JMX Notifications</title>
+ <para>
+ JBoss Cache users can register a listener to receive cache events described earlier in the <link linkend="api.listener">User API</link>
+ chapter. Users can alternatively utilize the cache's management information infrastructure to receive these events
+ via JMX notifications. Cache events are accessible as notifications by registering a <literal>NotificationListener</literal> for the
+ <literal>CacheMgmtInterceptorMBean</literal>. This functionality is only available if cache statistics are enabled
+ as described in the previously.
+ </para>
+
+ <para>
+ See the section in the <link linkend="jmx_reference.notifications">JMX Reference chapter</link> pertaining
+ to JMX notifications for a list of notifications that can be received through the <literal>CacheMgmtInterceptorMBean</literal>.
</para>
- <para>The following is an example of how to programmatically receive cache notifications when running in a
- JBoss
- application server
- environment. In this example, the client uses a filter to specify which events are of interest.
+ <para>
+ The following is an example of how to programmatically receive cache notifications when running in a
+ JBoss AS environment. In this example, the client uses a filter to specify which events are of interest.
</para>
<programlisting>
@@ -236,25 +212,34 @@
<para>The following is the simple notification listener implementation used in the previous example.</para>
<programlisting>
<![CDATA[
- private class MyListener implements NotificationListener, Serializable {
- public void handleNotification(Notification notification, Object handback) {
+ private class MyListener implements NotificationListener, Serializable
+ {
+ public void handleNotification(Notification notification, Object handback)
+ {
String message = notification.getMessage();
String type = notification.getType();
Object userData = notification.getUserData();
- System.out.println(type + ": "+message);
- if (userData == null) {
+
+ System.out.println(type + ": " + message);
+
+ if (userData == null)
+ {
System.out.println("notification data is null");
}
- else if (userData instanceof String) {
- System.out.println("notification data: "+(String)userData);
+ else if (userData instanceof String)
+ {
+ System.out.println("notification data: " + (String) userData);
}
- else if (userData instanceof Object[]) {
- Object[] ud = (Object[])userData;
- for (int i = 0; i > ud.length; i++) {
- System.out.println("notification data: "+ud[i].toString());
+ else if (userData instanceof Object[])
+ {
+ Object[] ud = (Object[]) userData;
+ for (Object data : ud)
+ {
+ System.out.println("notification data: " + data.toString());
}
}
- else {
+ else
+ {
System.out.println("notification data class: " + userData.getClass().getName());
}
}
@@ -262,58 +247,52 @@
]]>
</programlisting>
- <para>Note: the JBoss Cache management implementation only listens to cache events after a client registers to
- receive MBean notifications. As soon as no clients are registered for notifications, the MBean will remove
- itself
- as a cache listener.
+ <para>Note that the JBoss Cache management implementation only listens to cache events after a client registers
+ to receive MBean notifications. As soon as no clients are registered for notifications, the MBean will remove
+ itself as a cache listener.
</para>
</section>
<section>
<title>Accessing Cache MBeans in a Standalone Environment</title>
- <para>JBoss Cache MBeans are readily accessed when running cache instances in an application server that
- provides
- an MBean server interface such as JBoss JMX Console. Refer to server documentation for instructions on how
- to
- access
- MBeans running in a server's MBean container.
- </para>
- <para>JBoss Cache MBeans are also accessible when running in a non-server environment if the JVM is JDK 5.0 or
- later.
- When running a standalone cache in a JDK 5 environment, you can access the cache's MBeans as follows.
+ <para>
+ JBoss Cache MBeans are easily accessed when running cache instances in an application server that
+ provides an MBean server interface such as JBoss JMX Console. Refer to server documentation for instructions on how
+ to access MBeans running in a server's MBean container.
+ </para>
+ <para>
+ In additio, though, JBoss Cache MBeans are also accessible when running in a non-server environment if the
+ JVM is JDK 5.0 or later. When running a standalone cache in a JDK 5.0 environment, you can access the
+ cache's MBeans as follows.
</para>
<para>
<orderedlist>
- <listitem>Set the system property
- <emphasis>-Dcom.sun.management.jmxremote</emphasis>
- when starting the JVM
+ <listitem>
+ Set the system property <literal>-Dcom.sun.management.jmxremote</literal> when starting the JVM
where the cache will run.
</listitem>
- <listitem>Once the JVM is running, start the JDK 5
- <emphasis>jconsole</emphasis>
- utility, located in the JDK's /bin directory.
+ <listitem>
+ Once the JVM is running, start the JDK 5.0 <literal>jconsole</literal> utility, located in your JDK's <literal>/bin</literal>
+ directory.
</listitem>
- <listitem>When the utility loads, you will be able to select your JVM and connect to it. The JBoss Cache
- MBeans will be
- available on the MBeans panel.
+ <listitem>When the utility loads, you will be able to select your running JVM and connect to it. The JBoss Cache
+ MBeans will be available on the MBeans panel.
</listitem>
</orderedlist>
</para>
- <para>Note: The
- <emphasis>jconsole</emphasis>
- utility will automatically register as a listener for cache notifications when connected
- to a JVM running JBoss Cache instances.
+ <para>Note that the
+ <literal>jconsole</literal> utility will automatically register as a listener for cache notifications when
+ connected to a JVM running JBoss Cache instances.
</para>
<para>The following figure shows cache interceptor MBeans in
- <emphasis>jconsole</emphasis>
- . Cache statistics are displayed
- for the CacheMgmt interceptor:
+ <literal>jconsole</literal>. Cache statistics are displayed
+ for the <literal>CacheMgmtInterceptorMBean</literal>:
</para>
<figure>
- <title>CacheMgmtInterceptor MBean</title>
+ <title>CacheMgmtInterceptorMBean in jconsole</title>
<mediaobject>
<imageobject>
@@ -324,6 +303,4 @@
</section>
</section>
-
-
</chapter>
\ No newline at end of file
1.2 +12 -39 JBossCache/docs/JBossCache-UserGuide/en/modules/compatibility.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: compatibility.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/compatibility.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- compatibility.xml 19 Jan 2007 17:01:00 -0000 1.1
+++ compatibility.xml 23 Jan 2007 15:23:23 -0000 1.2
@@ -1,8 +1,8 @@
<chapter id="compatibility">
<title>Version Compatibility and Interoperability</title>
- <para>While this is not absolutely guaranteed, generally speaking within a
- major version, releases of JBoss Cache are meant to be compatible and
+ <para>
+ Within a major version, releases of JBoss Cache are meant to be compatible and
interoperable. Compatible in the sense that it should be possible to
upgrade an application from one version to another by simply replacing the
jars. Interoperable in the sense that if two different versions of
@@ -13,44 +13,17 @@
be upgraded.
</para>
- <para>In the 1.2.4 and 1.2.4.SP1 releases, API compatibility and
- interoperability with previous releases was broken. The primary purpose
- of the 1.2.4.SP2 release was to restore API compatibility and
- interoperability. Note, however, that restoring API compatibility with
- earlier releases meant that 1.2.4.SP2 is not completely API compatible with
- the other two 1.2.4 releases. If you have built applications on top of
- 1.2.4 or 1.2.4.SP1, please recompile before upgrading to 1.2.4.SP2 in
- order to be sure you have no issues.
+ <para>
+ As such, JBoss Cache 2.x.x is not API or binary compatible with prior 1.x.x versions.
+ However, JBoss Cache 2.1.x will be API and binary compatible with 2.0.x.
</para>
- <para>Beginning in 1.2.4.SP2, a new configuration attribute
- <literal>ReplicationVersion</literal>
- has been added. This attribute needs to be set in
- order to allow interoperability with previous releases. The value should
- be set to the release name of the version with which interoperability is
- desired, e.g. "1.2.3". If this attribute is set, the wire format of
- replication and state transfer messages will conform to that understood
- by the indicated release. This mechanism allows us to improve JBoss Cache by
- using more efficient wire formats while still providing a means to preserve
- interoperability.
- </para>
-
- <para>In a rare usage scenario, multiple different JBoss Cache instances may
- be operating on each node in a cluster, but not all need to interoperate
- with a version 1.2.3 cache, and thus some caches will not be configured
- with
- <literal>ReplicationVersion</literal>
- set to 1.2.3. This can cause problems with
- serialization of Fqn objects. If you are using this kind of configuration,
- are having problems and are unwilling to set
- <literal>ReplicationVersion</literal>
- to
- <literal>1.2.3</literal>
- on all caches, a workaround is to set system property
- <literal>jboss.cache.fqn.123compatible</literal>
- to
- <literal>true</literal>
- .
+ <para>
+ A configuration attribute, <literal>ReplicationVersion</literal>, is available and is used
+ to control the wire format of inter-cache communications. They can be wound back from more
+ efficient and newer protocols to "compatible" versions when talking to older releases.
+ This mechanism allows us to improve JBoss Cache by using more efficient wire formats while
+ still providing a means to preserve interoperability.
</para>
</chapter>
\ No newline at end of file
1.4 +1 -1 JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: basic_api.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- basic_api.xml 23 Jan 2007 03:11:44 -0000 1.3
+++ basic_api.xml 23 Jan 2007 15:23:23 -0000 1.4
@@ -117,7 +117,7 @@
</para>
</section>
- <section>
+ <section id="api.listener">
<title>
Adding a CacheListener
</title>
More information about the jboss-cvs-commits
mailing list