[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
msurtani at jboss.com
Mon Jan 22 20:12:37 EST 2007
User: msurtani
Date: 07/01/22 20:12:37
Modified: docs/JBossCache-UserGuide/en/modules preface.xml
introduction.xml
Log:
Checked in master and intro docs, plus UML diags
Revision Changes Path
1.3 +23 -31 JBossCache/docs/JBossCache-UserGuide/en/modules/preface.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: preface.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/preface.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- preface.xml 22 Jan 2007 22:50:09 -0000 1.2
+++ preface.xml 23 Jan 2007 01:12:37 -0000 1.3
@@ -2,8 +2,8 @@
<title>Preface</title>
<para>
- This is the official JBoss Cache user guide, and along with it's accompanying documents (an FAQ, a tutorial and a
- whole set of documents on PojoCache) are all freely available on the JBoss Cache documentation site,
+ This is the official JBoss Cache user guide. Along with it's accompanying documents (an FAQ, a tutorial and a
+ whole set of documents on PojoCache), this is freely available on the JBoss Cache documentation site,
<ulink url="http://labs.jboss.com/jbosscache">http://labs.jboss.com/jbosscache</ulink>
.
</para>
@@ -15,49 +15,41 @@
</para>
<para>
- JBoss Cache is flexible, versatile and very configurable. Aspects of the cache such as replication mechanisms,
- transaction isolation levels, eviction policies, and transaction managers are all configurable. JBoss Cache can be
- used
- in a standalone fashion - independent of JBoss Application Server or any
- other application server. PojoCache on the other hand requires both
- TreeCache and the JBossAOP standalone subsystem. PojoCache, documented
- separately, is the first in the market to provide a POJO cache
- functionality.
+ This book is targeted at both developers wishing to use the JBoss Cache as a clustering and caching library in
+ their codebase, as well as people who wish to "OEM" JBoss Cache by building on and extending it's features. As
+ such,
+ this book is split into two major sections - one detailing the "User" API and the other going much deeper into
+ specialist topics and the JBoss Cache architecture.
</para>
<para>
- This document is meant to be a user guide to explain the
- architecture, api, configuration, and examples for JBoss Cache's
- TreeCache. Good knowledge of the Java programming language along with a
- string appreciation and understanding of transactions and concurrent
- threads is presumed. No prior knowledge of JBoss Application Server is
- expected or required.
+ In general, a good knowledge of the Java programming language along with a strong appreciation and understanding
+ of transactions and concurrent threads is necessary. No prior knowledge of JBoss Application Server is expected
+ or required.
</para>
<para>
- If you have questions, use the
+ For further discussion, use the
<ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=157">user forum</ulink>
linked on the
<ulink url="http://labs.jboss.com/jbosscache">JBoss Cache website</ulink>
. We also provide a mechanism for
tracking bug reports and feature requests on the
- <ulink url="http://jira.jboss.com">JBoss JIRA issue tracker</ulink>
- . If you are
- interested in the development of JBoss Cache or in translating this documentation into other languages, we'd love
- to
- hear from you. Please post a message on the user forum or contact us on the
- <ulink url="http://lists.jboss.org">developer mailing list</ulink>
+ <ulink url="http://jira.jboss.com/jira/browse/JBCACHE">JBoss JIRA issue tracker</ulink>
+ .
+ If you are interested in the development of JBoss Cache or in translating this documentation into other languages,
+ we'd love
+ to hear from you. Please post a message on the
+ <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=157">user forum</ulink>
+ or contact us by using the
+ <ulink url="https://lists.jboss.org/mailman/listinfo/jbosscache-dev">JBoss Cache developer mailing list</ulink>
.
</para>
<para>
- JBoss Cache is an open-source product based on LGPL. Commercial
- development support, production support and training for JBoss Cache is
- available through
- <ulink url="http://www.jboss.com">JBoss Inc</ulink>
- .
- JBoss Cache is a product in JBoss Professional Open Source
- <ulink url="http://www.jboss.com/products/index">JEMS</ulink>
- (JBoss Enterprise Middleware Suite).
+ This book is specifically targeted at the JBoss Cache release of the same version number. It may not apply to
+ older or newer releases of JBoss Cache. It is important that you use the documentation appropriate to the version
+ of JBoss Cache you intend to use.
</para>
+
</preface>
\ No newline at end of file
1.2 +84 -97 JBossCache/docs/JBossCache-UserGuide/en/modules/introduction.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: introduction.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/introduction.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- introduction.xml 19 Jan 2007 17:01:00 -0000 1.1
+++ introduction.xml 23 Jan 2007 01:12:37 -0000 1.2
@@ -1,102 +1,83 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="introduction">
- <title>Introduction</title>
+ <title>Overview</title>
<section>
- <title>What is a
- <literal>TreeCache</literal>
- ?
- </title>
+ <title>What is JBoss Cache?</title>
<para>
- A
- <literal>TreeCache</literal>
- is a tree-structured, replicated, transactional cache from JBoss Cache.
- <literal>TreeCache</literal>
+ JBoss Cache is a tree-structured, clustered, transactional cache from JBoss Cache. It is
is the backbone for many fundamental JBoss Application Server clustering services, including - in certain
- versions - clustering JNDI, HTTP and EJB sessions, and clustering JMS.
+ versions - clustering JNDI, HTTP and EJB sessions.
</para>
<para>
- In addition to this,
- <literal>TreeCache</literal>
- can be used as a standalone transactional and replicated cache or even an object oriented data store, may be
- embedded in other J2EE compliant application servers such as BEA WebLogic or IBM WebSphere, servlet containers
- such as Tomcat, or even in Java applications that do not run from within an application server.
+ JBoss Cache can also be used as a standalone transactional and clustered caching library or even an object
+ oriented data store. It can even be embedded in other enterprise Java frameworks and application servers
+ such as BEA WebLogic or IBM WebSphere, Tomcat, Spring, Hibernate, and many others. It is also very commonly
+ used directly by standalone Java applications that do not run from within an application server, to maintain
+ clustered state.
+ </para>
+ <section>
+ <title>And what is Pojo Cache?</title>
+ <para>
+ Pojo Cache is an extension of the core JBoss Cache API. Pojo Cache offers additional functionality such as:
+ <itemizedlist>
+ <listitem>maintaining object references even affter replication or persistence.</listitem>
+ <listitem>fine grained replication, where only modified object fields are replicated.</listitem>
+ <listitem>"API-less" clustering model where pojos are simply annotated as being clustered.</listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Pojo Cache has a complete and separate set of documentation, including a user guide, FAQ and tutorial and
+ as such, Pojo Cache is not discussed further in this book.
</para>
</section>
+ </section>
+
<section>
- <title>
- <literal>TreeCache</literal>
- Basics
- </title>
-
- <para>The structure of a
- <literal>TreeCache</literal>
- is a tree with nodes. Each node has a
- name and zero or more children. A node can only have 1 parent; there is
- currently no support for graphs. A node can be reached by navigating from
- the root recursively through children, until the requested node is found. It can
- also be accessed by giving a fully qualified name (FQN), which consists of
- the concatenation of all node names from the root to the node in question.
+ <title>Summary of Features</title>
+
+ <para>
+ JBoss Cache offers a simple and straightforward API, where data (simple Java objects) can be placed in the
+ cache and, based on configuration options selected, this data may be one or all of:
+ <itemizedlist>
+ <listitem>replicated to some or all cache instances in a cluster</listitem>
+ <listitem>persisted to disk and/or a remote cluster ("far-cache")</listitem>
+ <listitem>garbage collected from memory when memory runs low, and passivated to disk so state isn't lost
+ </listitem>
+ </itemizedlist>
+ In addition, JBoss Cache offers a rich set of enterprise-class features:
+ <itemizedlist>
+ <listitem>being able to participate in JTA transactions (works with Java EE compliant TransactionManagers)
+ </listitem>
+ <listitem>attach to JMX servers and provide runtime statistics on the state of the cache</listitem>
+ <listitem>allow client code to attach listeners and receive notifications on cache events</listitem>
+ </itemizedlist>
</para>
<para>A
- <literal>TreeCache</literal>
- can have multiple roots, allowing for a number of
- different trees to be present in a single cache instance. Note that a one level tree is
- essentially a
- <literal>HashMap</literal>
- . Each node in the tree has a map of keys and
- values. For a replicated cache, all keys and values have to be
- <literal>Serializable</literal>
- . Serializability is not a requirement for
- <literal>PojoCache</literal>
- , where
- reflection and aspect-oriented programming is used to replicate any type.
+ The cache is organised as a tree, with a single root. Each node in the tree essentially contains a Map,
+ which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that
+ they implement
+ <literal>java.io.Serializable</literal>
+ . Note that this requirement does not exist for Pojo Cache.
</para>
- <para>A
- <literal>TreeCache</literal>
+ <para>JBoss Cache
can be either local or replicated. Local trees exist
- only inside the Java VM in which they are created, whereas replicated trees
+ only inside the JVM in which they are created, whereas replicated trees
propagate any changes to all other replicated trees in the same cluster. A
cluster may span different hosts on a network or just different JVMs
on a single host.
</para>
- <para>The first version of
- <literal>TreeCache</literal>
- was essentially a single
- <literal>HashMap</literal>
- that replicated. However, the decision
- was taken to go with a tree structured cache because (a) it is more
- flexible and efficient and (b) a tree can always be reduced to a map,
- thereby offering both possibilities. The efficiency argument was driven by
- concerns over replication overhead, and was that a value itself can be a
- rather sophisticated object, with aggregation pointing to other objects,
- or an object containing many fields. A small change in the object would
- therefore trigger the entire object (possibly the transitive closure over
- the object graph) to be serialized and propagated to the other nodes in
- the cluster. With a tree, only the modified nodes in the tree need to be
- serialized and propagated. This is not necessarily a concern for
- <literal>TreeCache</literal>
- , but is a
- vital requirement for
- <literal>PojoCache</literal>
- (as we will see in the separate
- <literal>PojoCache</literal>
- documentation).
- </para>
-
- <para>When a change is made to the
- <literal>TreeCache</literal>
- , and that change is done in
+ <para>When a change is made to an object in the cache and that change is done in
the context of a transaction, then we defer the replication of changes until the transaction
commits successfully. All modifications are kept in a list associated with
the transaction for the caller. When the transaction commits, we replicate the
- changes. Otherwise, (on a rollback) we simply undo the changes locally and release
- any locks, resulting in zero replication traffic and overhead. For example, if a caller
+ changes. Otherwise, (on a rollback) we simply undo the changes locally
+ resulting in zero network traffic and overhead. For example, if a caller
makes 100 modifications and then rolls back the transaction, we will not replicate
anything, resulting in no network traffic.
</para>
@@ -108,29 +89,35 @@
auto-commit switched on in JDBC terminology, where each operation is committed automatically.
</para>
- <para>There is an API for plugging in different transaction managers: all
- it requires is to get the transaction associated with the caller's thread. Several
- <literal>TransactionManagerLookup</literal>
- implementations are provided for popular transaction managers, including a
- <literal>DummyTransactionManager</literal>
- for testing.
- </para>
-
- <para>Finally, we use pessimistic locking of the cache by default, with optimistic locking as a configurable
- option. With pessimistic locking, we can
- configure the local locking policy corresponding to database-style
- transaction isolation levels, i.e., SERIALIZABLE, REPEATABLE,
- READ_COMMITTED, READ_UNCOMMITTED and NONE. More on transaction
- isolation levels will be discussed later. Note that the cluster-wide
- isolation level is READ-UNCOMMITTED by default as we don’t acquire a
- cluster-wide lock on touching an object for which we don’t yet have a lock
- (this would result in too high an overhead for messaging).
- </para>
- <para>With optimistic locking, isolation levels are ignored as each transaction effectively maintains a copy of
- the data with which it works on and then attempts to merge back into the tree structure upon transaction
- completion. This results in a near-serializable degree of data integrity, applied cluster-wide, for the minor
- performance penalty incurred when validating workspace data at commit time, and the occasional transaction
- commit failure due to validation failures at commit time.
+ <para>
+ JBoss Cache works out of the box with most popular transaction managers, and even provides an API where
+ custom transaction manager lookups can be written.
+ </para>
+
+ <para>
+ The cache is also completely thread-safe. It uses a pessimistic locking scheme for nodes in the tree by
+ default, with an optimistic locking scheme as a configurable option. With pessimistic locking, the degree
+ of concurrency can be tuned using a number of isolation levels, corresponding to database-style
+ transaction isolation levels, i.e., SERIALIZABLE, REPEATABLE_READ, READ_COMMITTED, READ_UNCOMMITTED and NONE.
+ More on concurrency, locking and isolation levels will be discussed later.
+ </para>
+ </section>
+
+ <section>
+ <title>License</title>
+ <para>
+ JBoss Cache is an open source product, using the business and OEM-friendly
+ <ulink url="http://www.opensource.org/">OSI-approved</ulink>
+ <ulink url="http://www.gnu.org/copyleft/lesser.html">LGPL license</ulink>
+ . Commercial development support,
+ production support and training for JBoss Cache is available through
+ <ulink url="http://www.jboss.com">JBoss, a division of Red Hat Inc</ulink>
+ .
+ </para>
+ <para>
+ JBoss Cache is a part of the JBoss Professional Open Source
+ <ulink url="http://www.jboss.com/products/index">JEMS</ulink>
+ (JBoss Enterprise Middleware Suite).
</para>
</section>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list