March 2008 - jbosscache-commits - Jboss List Archives

JBoss Cache SVN: r5434 - in pojo/trunk: src/main/docbook/faq/en and 2 other directories.

by jbosscache-commits＠lists.jboss.org

Author: jason.greene(a)jboss.com Date: 2008-03-15 00:20:53 -0400 (Sat, 15 Mar 2008) New Revision: 5434 Added: pojo/trunk/src/main/release/etc/ pojo/trunk/src/main/release/etc/replSync-service.xml Removed: pojo/trunk/src/main/release/etc/replSync-service.xml Modified: pojo/trunk/pom.xml pojo/trunk/src/main/docbook/faq/en/master.xml Log: Merge release fixes Modified: pojo/trunk/pom.xml =================================================================== --- pojo/trunk/pom.xml 2008-03-15 04:18:42 UTC (rev 5433) +++ pojo/trunk/pom.xml 2008-03-15 04:20:53 UTC (rev 5434) @@ -51,6 +51,26 @@ </dependencies> <build> <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>javadoc</goal> + </goals> + <configuration> + <aggregate>${jbosscache.reports.aggregate}</aggregate> + <links> + <link>http://java.sun.com/j2se/1.5.0/docs/api/</link> + <link>http://java.sun.com/javaee/5/docs/api/</link> + <link>http://labs.jboss.org/file-access/default/members/jbosscache/freezone/doc...</link> + </links> + </configuration> + </execution> + </executions> + </plugin> <plugin> <artifactId>maven-assembly-plugin</artifactId> <version>2.2-beta-1</version> Modified: pojo/trunk/src/main/docbook/faq/en/master.xml =================================================================== --- pojo/trunk/src/main/docbook/faq/en/master.xml 2008-03-15 04:18:42 UTC (rev 5433) +++ pojo/trunk/src/main/docbook/faq/en/master.xml 2008-03-15 04:20:53 UTC (rev 5434) @@ -4,9 +4,9 @@ > <article class="faq" lang="en"> <articleinfo> - <title>Frequently Asked Questions about PojoCache</title> - <releaseinfo>Release 2.0.0</releaseinfo> - <pubdate>June 2007</pubdate> + <title>Frequently Asked Questions about POJO Cache</title> + <releaseinfo>Release 2.1.0.GA</releaseinfo> + <pubdate>March 2008</pubdate> <author> <firstname>Ben</firstname> @@ -18,21 +18,25 @@ <surname>Marlow</surname> <email>smarlow(a)novell.com</email> </author> - + <author> + <firstname>Jason</firstname> + <surname>Greene</surname> + <email>jason.greene(a)jboss.com</email> + </author> </articleinfo> - <para>These are frequently asked questions regarding Pojocache.</para> + <para>These are frequently asked questions regarding POJO Cache.</para> <qandaset defaultlabel="qanda"> <title>General Information</title> <qandaentry> <question id="a49"> - <para>What is PojoCache?</para> + <para>What is POJO Cache?</para> </question> <answer> - <para>PojoCache is a fine-grained field-level replicated and + <para>POJO Cache is a fine-grained field-level replicated and transactional POJO (plain old Java object) cache. By POJO, we mean that the cache: 1) automatically manages object mapping and relationship for a client under both local and replicated cache @@ -48,12 +52,12 @@ <para>From a user perspective, once your POJO is managed by the cache, all cache operations are transparent. Therefore, all the usual in-VM POJO method semantics are still preserved, providing - ease of use. For example, if a POJO has been put in PojoCache (by + ease of use. For example, if a POJO has been put in POJO Cache (by calling <literal>attach</literal> , for example), then any POJO get/set method will be - intercepted by PojoCache to provide the data from the + intercepted by POJO Cache to provide the data from the cache. </para> </answer> @@ -61,17 +65,14 @@ <qandaentry> <question id="a1"> - <para>What is the relationship between Cache and PojoCache?</para> + <para>What is the relationship between Core Cache and POJO Cache?</para> </question> <answer> - <para>The core JBoss Cache library - <literal>Cache</literal> - is a traditional generic distributed cache system. - PojoCache uses Cache as the underlying distributed state system to achieve POJO caching. It uses Cache as - a - delegate. As a result, all the replication aspects are configured with the Cache configuration XML. - Additionally, PojoCache also has API to expose the Cache interface (via + <para>Cores Cache is a traditional generic distributed cache system. + POJO Cache uses Core Cache as the underlying distributed state system to achieve object caching. + As a result, all the replication aspects are configured with the Cache configuration XML. + Additionally, POJO Cache also has API to expose the Cache interface (via <literal>getCache()</literal> API). </para> @@ -80,41 +81,39 @@ <qandaentry> <question id="a52"> - <para>What is the difference between Cache and - PojoCache? + <para>What is the difference between Core Cache and + POJO Cache? </para> </question> <answer> - <para>Think of PojoCache as a Cache on steroids. :-) + <para>Think of POJO Cache as a Cache on steroids. :-) Seriously, both are cache stores-- one is a generic cache and the other other one POJO Cache. However, while Cache only provides pure object reference storage (e.g., <literal>put(FQN fqn, Object key, Object value) </literal> - ), PojoCache goes beyond that + ), POJO Cache goes beyond that and performs fine-grained field level replication object mapping and relationship management for a user behind the scenes. As a result, if you have complex object systems that you would like to cache, you - can have PojoCache manage it for you. You simply treat your + can have POJO Cache manage it for you. You simply treat your object systems as they are residing in-memory, e.g., use your regular POJO methods without worrying about cache management. - Furthermore, this is true in replication mode as well. </para> </answer> </qandaentry> <qandaentry> <question id="a521"> - <para>How does PojoCache work then?</para> + <para>How does POJO Cache work then?</para> </question> <answer> - <para>PojoCache uses the so-called AOP technology (aspect oriented programming) to do field level - interception. Currently, it uses - <literal>JBoss Aop</literal> - library to do it. + <para>POJO Cache uses the JBoss AOP project to perform field level + interception. This allows POJO Cache to monitor changes to your object model, and react + accordingly. </para> </answer> </qandaentry> @@ -125,7 +124,7 @@ </question> <answer> - <para>Starting in 2.0 release, we have a separate library for PojoCache, + <para>Starting in 2.0 release, we have a separate library for POJO Cache, <literal>pojocache.jar</literal> that is extra to the core @@ -134,7 +133,7 @@ will need to have a regular xml to configure the core Cache functionality (e.g., replication and locking aspect). In addition, there is also the <literal>pojocache-aop.xml</literal> - that specifies the PojoCache + that specifies the POJO Cache interceptor stack (that can be left as default). </para> <para>Additionally, here are the changed features: @@ -151,14 +150,14 @@ <para>New POJO based events that a user can subscribe to.</para> </listitem> <listitem> - <para>New configuration pojocache-aop.xml specifically for PojoCache, in addition to + <para>New configuration pojocache-aop.xml specifically for POJO Cache, in addition to the regular cache-service.xml for the delegating Cache. </para> </listitem> <listitem> <para>New package namespace ( <literal>org.jboss.cache.pojo)</literal> - for PojoCache. + for POJO Cache. The previous <literal>org.jboss.cache.aop</literal> space has been deprecated. @@ -171,58 +170,43 @@ <qandaentry> <question id="a53"> - <para>What are the steps to use the PojoCache feature?</para> + <para>How do you use POJO Cache?</para> </question> <answer> - <para>In order to use PojoCache, you will need to:</para> + <para>In order to use POJO Cache, you will need to:</para> <itemizedlist> <listitem> - <para>prepare POJO. You can do either via xml declaration or JDK50 annotation. - This is the step to declare your POJO such that it will be instrumented by - <literal>JBoss Aop</literal> - . + <para>Annotate your POJOt with @Replicable. </para> </listitem> <listitem> - <para>instrumentation. You will need to instrument your POJO either at compile- or load-time. - If you do it during compile-time, you use so-called an aop pre-compiler (aopc) to do bytecode - manipulation. - If you do it via load-time, however, you need either a special system class loader or, in JDK50, - you can - use the javaagent option. Either way, - <literal>JBoss Aop</literal> - will byte code manipulate your POJO - class such that all field access can be intercepted. + <para>Instrument your POJO. This can be done at load-time using special JVM arguments (prefered), or at compile time using the + AOP precompiler tool (aopc). See the user guide for more specific details on instrumentation. </para> </listitem> </itemizedlist> - <para>So if you use JDK50, for example, with annotation and load-time instrumentation, then you won't need - any pre-processing step to use PojoCache. For a full example, please refer to the distro examples - directory. - There are numerous PojoCache examples that uses different options. - </para> </answer> </qandaentry> <qandaentry> <question id="a541"> - <para>What is the JDK version required to run PojoCache 2.x?</para> + <para>What is the JDK version required to run POJO Cache 2.x?</para> </question> <answer> - <para>PojoCache 2.x requires JDK5.0 since it uses the annotation extensively.</para> + <para>POJO Cache 2.x requires Java 5 or newer.</para> </answer> </qandaentry> <qandaentry> <question id="a542"> - <para>Can I run PojoCache as a standalone mode?</para> + <para>Can I run POJO Cache as a standalone mode?</para> </question> <answer> - <para>Yes, same as the core Cache library, you can run PojoCache either as a standalone or + <para>Yes, same as the Core Cache library, you can run POJO Cache either as a standalone or inside an application server. </para> </answer> @@ -230,11 +214,11 @@ <qandaentry> <question id="a543"> - <para>What is the JBoss AS recommended version to run PojoCache 2.x?</para> + <para>What is the JBoss AS recommended version to run POJO Cache 2.x?</para> </question> <answer> - <para>PojoCache can be run either in AS4.0.5 (and up) and 5.0. But either way, it will require + <para>POJO Cache can be run either in AS4.0.5 (and up) and 5.0. But either way, it will require JDK5.0 though. </para> </answer> @@ -242,51 +226,29 @@ <qandaentry> <question id="a56"> - <para>Can I pre-compile the aop classes such that I don't need to - use the system classloader and jboss-aop configuration xml during runtime? + <para>Can I pre-compile objects used in POJO Cache, so that I don't have to provide an AOP descriptor? </para> </question> <answer> - <para>Yes. The latest versions of JBossCache have a pre-compiler - option called - <literal>aopc</literal> - . You can use this option to - pre-compile your "aspectized" POJO. Once the classes have been byte - code generated, they can be treated as regular class files, i.e., - you will not need to include any - <literal>jboss-aop.xml</literal> - that specifies the advisable POJO and to specify the JBossAop system - class loader. + <para>Yes. The AOP library included with POJO Cache has a pre-compiler called + <literal>aopc</literal> that can be used to instrument objects in advance. However, + this is not the recommended approach, since your classes become tied to a specific AOP version. + See the instrumentation chapter in the user guide for more information. </para> - - <para>For an example of how to use - <literal>aopc</literal> - , please - see 1) - <literal>tools</literal> - directory for PojoCacheTasks14.xml - and PojoCacheTasks50.xml. Both contain Ant tasks that you can - import to your regular project for - <literal>aopc</literal> - . In addition, please also check out the - <literal>examples</literal> - directory for concrete examples. - </para> </answer> </qandaentry> <qandaentry> <question id="a561"> - <para>In PojoCache 2.x release, do I still need + <para>In POJO Cache 2.x release, do I still need <literal>annoc</literal> ? </para> </question> <answer> - <para>The annoc precompiler is needed for JDK1.4 style annotation. For 2.x release, since - we require the use of JDK5.0, there is no need to use annoc anymore. + <para>No. POJO Cache 2.x requires JDK 5, and recommends load-time instrumentation. Alternatively the offline aopc tool may be used. </para> </answer> </qandaentry> @@ -306,15 +268,11 @@ <qandaentry> <question id="a57a"> - <para>Does PojoCache provide POJO event subscription?</para> + <para>Does POJO Cache provide a listener/event model for catching changes?</para> </question> <answer> - <para>Yes, since 2.0, you can use PojoCacheListener to subscribe to events - such as POJO attach and detach and field updates. And if you need some customization, - you can also use the Obervable pattern directly. TO see an example, please check - out the test case: - <literal>org.jboss.cache.pojo.observer.LocalTest.java</literal> + <para>Yes. See the javadoc for PojoCache.addListener() and @PojoCacheListener. </para> </answer> </qandaentry> @@ -322,33 +280,18 @@ <qandaentry> <question id="a58"> <para>What's in the - <literal>jboss-aop.xml</literal> + <literal>pojocaches-aop.xml</literal> configuration? </para> </question> <answer> <para> - <literal>jboss-aop.xml</literal> - is needed for POJO - instrumentation. In - <literal>jboss-aop.xml</literal> - , you can - declare your POJO (e.g., - <literal>Person</literal> - ) to be - "prepared", a JBossAop term to denote that the object will be - "aspectized" by the system. After this declaration, JBossAop will - invoke any interceptor that associates with this POJO. PojoCache - will dynamically add an - <literal>org.jboss.cache.pojo.interceptor.dynamic.CacheFieldInterceptor</literal> - to this POJO - to perform object mapping and relationship management. + These descriptors are necessary for instrumentation. However, yyou typically do not need to touch them since they include a rule + which matches the classes with an @Replicable annotation. Therefore, all you need to do, is just + annotate your class with @Replicable. Advanced users may decide to customize them with special AOP prepare statements that match + classes which do not have @Replicable. </para> - - <para>Note that to add your POJO, you should declare all the fields - to be "prepared" as in the example. - </para> </answer> </qandaentry> @@ -367,7 +310,7 @@ is essentially a <literal>jboss-aop.xml</literal> , - except it is used specifically for PojoCache. The analogy is similar to JBoss' own + except it is used specifically for POJO Cache. The analogy is similar to JBoss' own MBean service file <literal>jboss-service.xml</literal> , for example. So in our documentation, @@ -378,26 +321,22 @@ <qandaentry> <question id="a59"> - <para>Can I use annotation instead of the xml declaration?</para> + <para>Can I use annotations instead of editing the AOP XML descriptors?</para> </question> <answer> - <para>Yes, in release 2.0, you can use JDK5.0 annotation to - instrument your POJO. Check the documentation for details. + <para>Yes, in release 2.0, we recommend you use the @Replicable annotation, and don't bother with editing the AOP files. </para> </answer> </qandaentry> <qandaentry> <question id="a60"> - <para>What are the pro and con of xml vs. annotation?</para> + <para>Is there a problem with using a custom AOP descriptor over the provided annotations?</para> </question> <answer> - <para>It really depends on your organization environment, I'd say, since this can be turned into a - hot debate. Having said that, I feel strongly that POJO annotation is well suited for PojoCache. This is - because once you specify the annotation, you'd probably change it rarely since there is no parameters to - tune, for example. + <para>The only real benefit to a custom AOP descriptor is if you can't easily add the annotation to the class source (it's not under your control). </para> </answer> </qandaentry> @@ -418,13 +357,13 @@ , when applied has the same effect as declaring a field <literal>transient</literal> - . PojoCache + . POJO Cache won't put this field under management. </para> <para>The second one, <literal>@org.jboss.cache.pojo.Serializable</literal> when applied, - will cause PojoCache to + will cause POJO Cache to treat the field as a Serializable object even when it is <literal>@org.jboss.cache.pojo.Replicable</literal> . @@ -434,14 +373,14 @@ <qandaentry> <question id="a62"> - <para>What about compile-time vs. load-time instrumentation then?</para> + <para>Why do you recommend load-time over compile-time instrumentation?</para> </question> <answer> - <para>Again it depends. But my preference is to do compile-time instrumentation via aopc. I prefer this - approach because it is easier to debug (at least at the development stage). In addition, once I generate - the - new class, there is no more steps needed. + <para> The major problem with compile-time instrumentation is that it adds a binary dependency on your class files to whatever + version of JBoss AOP that was used to run aopc. Once this has been done, the class may not work with a future version of + JBoss AOP (although the AOP team tries to ensure binary compatibility across minor revisions). Load-time doesn't have + this problem since the class is instrumented only in memory, and only when it is loaded. </para> </answer> </qandaentry> @@ -454,8 +393,8 @@ </question> <answer> - <para>Yes, you can use PojoCache to do that. It supports the - notion of object reference. PojoCache manages the unique object + <para>Yes, you can use POJO Cache to do that. It supports the + notion of multiple object references. POJO Cache manages the unique object through association of the dynamic cache interceptor. </para> </answer> @@ -463,32 +402,27 @@ <qandaentry> <question id="a64"> - <para>Do I need to declare all my objects "prepared" in - <literal>jboss-aop.xml</literal> - ? + <para>Do I have to instrument my objects? </para> </question> <answer> - <para>Not necessarily. If there is an object that you don't need the - cache to manage for you, you can leave it out of the declaration. - The cache will treat this object as a "primitive" type. However, the - object will need to implement - <literal>Serializable</literal> - interface for replication. + <para> You can also attach objects that implement + <literal>Serializable</literal>. However, you lose field-level replication and object identity preservation. + This is really only supported as a compatibility measure. It is definately worth useing instrumentation. </para> </answer> </qandaentry> <qandaentry> <question id="a65"> - <para>Can the cache aop intercept update via reflection?</para> + <para>Will POJO Cache intercept changes made from Java Reflection?</para> </question> <answer> - <para>No. The update via reflection will not be intercepted in - JBossAop and therefore PojoCache will not be able to perform the - necessary synchronization. + <para>Yes and No. Since POJO Cache intercepts field changes, any method + of an object that has been annotated with @Replicable will be handled properly when called with reflection. + However, modifying fields using reflection is not currently supported. </para> </answer> </qandaentry> @@ -501,7 +435,7 @@ </question> <answer> - <para>PojoCache currently will ignore the fields with these + <para>POJO Cache currently will ignore the fields with these modifiers. That is, it won't put these fields into the cache (and thus no replication either). </para> @@ -536,13 +470,13 @@ <para>No. Since the Collection classes such as <literal>ArrayList</literal> are java util classes, aop by default - won't instrument these classes. Instead, PojoCache will generate + won't instrument these classes. Instead, POJO Cache will generate a dynamic class proxy for the Collection classes (upon the <literal>attach</literal> call is invoked). The proxy will delegate the operations to a cache interceptor that implements the actual Collection classes APIs. That is, the system classes won't be - invoked when used in PojoCache. + invoked when used in POJO Cache. </para> <para>Internally, the cache interceptor implements the APIs by @@ -566,32 +500,29 @@ <literal>Set</literal> , and - <literal>Map</literal> - dynamic proxy? + <literal>Map</literal> with POJO Cache? </para> </question> <answer> - <para>PojoCache supports classes extending from + <para>POJO Cache supports all classes that implement <literal>List</literal> , <literal>Set</literal> , and <literal>Map</literal> - without users to declare them "aspectized". - It is done via a dynamic proxy. Here is a code snippet to use an - <literal>ArrayList</literal> - proxy class. + without instrumentation. This is done using a dynamic proxy. Here is an example using + <literal>ArrayList</literal>: </para> <programlisting role="JAVA"><![CDATA[ ArrayList list = new ArrayList(); list.add("first"); - cache.attach("list/test", list); // Put the list under the aop cache + cache.attach("/list/test", list); // Put the list under the cache list.add("second"); // Won't work since AOP intercepts the dynamic proxy not the original POJO. - ArrayList myList = (List)cache.find("list/test"); // we are getting a dynamic proxy instead + ArrayList myList = (List)cache.find("/list/test"); // we are getting a dynamic proxy instead myList.add("second"); // it works now myList.add("third"); myList.remove("third"); @@ -619,12 +550,12 @@ ArrayList list = new ArrayList(); list.add("first"); - cache.attach("list", list); // Put the list under the aop cache + cache.attach("/list", list); // Put the list under the aop cache - ArrayList myList = (List)cache.find("list"); // we are getting a dynamic proxy instead + ArrayList myList = (List)cache.find("/list"); // we are getting a dynamic proxy instead myList.add("second"); // it works now - cache.attach("list_alias", myList); // Note you will need to use the proxy here!! + cache.attach("/list_alias", myList); // Note you will need to use the proxy here!! myList.remove("second"); ]]></programlisting> </answer> @@ -634,36 +565,35 @@ <question id="a71"> <para>OK, so I know I am supposed to use proxy when manipulating the Collection classes once they are managed by the cache. But what - happens to Pojos that share the Collection objects, e.g., a + happens to POJOs that share the Collection objects, e.g., a <literal>List</literal> - instance that is shared by 2 Pojos? + instance that is shared by two objects?? </para> </question> <answer> - <para>Pojos that share Collection instance references will be + <para>POJOss that share Collection instance references will be handled by the cache automatically. That is, when you ask the Cache to manage it, the Cache will dynamically swap out the regular Collection references with the dynamic proxy ones. As a result, it - is transparent to the users. + is transparent to you. </para> </answer> </qandaentry> <qandaentry> <question id="a72"> - <para>What happens when my "aspectized" POJO has field members that - are of Collection class ? + <para>What happens when my instrumented object contains collections? </para> </question> <answer> - <para>When a user puts a POJO into the cache through the call + <para>When an object is passed to <literal>attach</literal> , it will recursively map the field - members into the cache store as well. When the field member is of a - Collection class (e.g., List, Set, or Map), PojoCache will first - map the collection into cache. Then, it will swap out dynamically + members into the cache store as well. If the field member is of a + Collection class (e.g., List, Set, or Map), POJO Cache will first + map the collection into cache. Then, it will swap out the field reference with an corresponding proxy reference. </para> @@ -676,84 +606,17 @@ <qandaentry> <question id="a73"> - <para>What are the limitation of Collection classes in PojoCache?</para> + <para>What are the limitations of using Java Collections in POJO Cache?</para> </question> - <answer> - <para>Use of Collection class in PojoCache helps you to track fine-grained changes - in your collection fields automatically. However, current implementation has the follow - limitation that we plan to address soon. + <para> + List, Set, and Map are supported; however, these APIs do not stipulate + of constraints like whether a null key or value is allowed. Therefore the behavior of an attached collection may differ + slightly from the originals Java implementation. The behavior implemented by POJO Cache follows + java.util.HashSet for any Set type, java.util.ArrayList for any List type, and java.util.HashMap for any Map type.s </para> - <para>Currently, we only support a limited implementation of Collection classes. That is, - we support APIs in List, Set, and Map. However, since the APIs do not stipulate - of constraints like NULL key or value, it makes mapping of user instance to our proxy tricky. - For example, ArrayList would allow NULL value and some other implementation would not. - The Set interface maps to java.util.HashSet implementation. The List interface maps - to java.util.ArrayList implementation. The Map interface maps to java.util.HashMap - implementation. - </para> - <para>Another related issue is the expected performance. For example, the current implementation is ordered, - so - that makes insert/delete from the Collection slow. Performance between Set, Map and List collections also - vary. - Adding items to a Set is slower than a List or Map, since Set does not allow duplicate entries. - </para> </answer> </qandaentry> - - - <qandaentry> - <question id="a74"> - <para>What are the pros and cons of PojoCache?</para> - </question> - - <answer> - <para>As mentioned in the reference doc, PojoCache has the following advantages:</para> - <itemizedlist> - <listitem> - <para>Fine-grained replication and/or persistency. If you use a distributed PojoCache - and once your POJO is put in the cache store, there is no need to use another API to - trigger your changes. Furthermore, the replication are fine-grained field level. Note this - also applies to persistency. - </para> - </listitem> - <listitem> - <para>Fine-grained replication can have potential performance gain if your POJO is big and - the changes are fine-grained, e.g., only to some selected fields. - </para> - </listitem> - <listitem> - <para>POJO can posses object relationship, e.g., multiple referenced. Distributed - PojoCache will handle this transparently for you. - </para> - </listitem> - </itemizedlist> - <para>And here are some cases that you may not want to use PojoCache:</para> - <itemizedlist> - <listitem> - <para>You use only cache. That is you don't need replication or persistency. Then since - everything is operated on the in-memory POJO reference, there is no need for PojoCache. - </para> - </listitem> - <listitem> - <para>You have simple and small POJOs. Your POJO is small in size and also there is no - object relationship, then PojoCache possess not clear advantage to plain cache. - </para> - </listitem> - <listitem> - <para>Your application is bounded by memory usage. Because PojoCache need almost twice as much - of memory (the original POJO in-memory space and also the additional cache store for the - primitive fields), you may not want to use PojoCache. - </para> - </listitem> - <listitem> - <para>Your POJO lifetime is short. That is, you need to create and destroy your POJO often. - Then you need to do "attach" and "detach" often, it will be slow in performance. - </para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> </qandaset> @@ -761,31 +624,26 @@ <title>Passiviation and eviction</title> <qandaentry> <question id="a80"> - <para>Can I use eviction to evict POJO from the memory?</para> + <para>Can I use eviction to evict a POJO from the memory?</para> </question> <answer> - <para>No. In 2.0 release, we have deprecated the POJO-based eviction policy since it has always been - problematic in earlier release. The main reason is that when we evict a POJO from - the memory, the user has no ways of knowing it. So if the POJO is accessed after the - eviction, there won't be any PojoCache interception (e.g., it will be just like ordinary POJO), - but user may still expect that it will be managed by PojoCache. + <para>In 2.0 release, we removed the POJO-based eviction policy since it has always been + problematic in earlier release. You can, however, use the standard Core Cache eviction system to + evict the data that backs the POJO. </para> </answer> </qandaentry> <qandaentry> <question id="a81"> - <para>So what do I do now?</para> + <para>Is passivation supported?</para> </question> <answer> - <para>In order to keep your memory from overflowing, you can use the passivation feature that comes with - the core Cache. Passivation uses the combination of eviction and cache loader such that when the + <para>Yes, in order to reduce memory consumption, you can use the passivation feature that comes with + Core Cache. Passivation uses the combination of eviction and a cache loader such that when the items are old, it will be evicted from memory and store in a cache store (can be DB or file). Next time, when the item needs to be accessed again, we will retrieve it from the cache store. </para> - <para>In this sense, PojoCache level is not aware of the passivation aspect. It is configured through - the underlying cache xml. - </para> </answer> </qandaentry> </qandaset> @@ -794,7 +652,7 @@ <title>Troubleshooting</title> <qandaentry> <question id="a90"> - <para>I am having problems getting PojoCache to work, where can I get information on troubleshooting?</para> + <para>I am having problems getting POJO Cache to work, where can I get information on troubleshooting?</para> </question> <answer> <para>Troubleshooting section can be found in the following Copied: pojo/trunk/src/main/release/etc (from rev 5433, pojo/branches/2.1/src/main/release/etc) Deleted: pojo/trunk/src/main/release/etc/replSync-service.xml =================================================================== --- pojo/branches/2.1/src/main/release/etc/replSync-service.xml 2008-03-15 04:18:42 UTC (rev 5433) +++ pojo/trunk/src/main/release/etc/replSync-service.xml 2008-03-15 04:20:53 UTC (rev 5434) @@ -1,175 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> - - - - - - - -<server> - -  -  -  - - <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" - name="jboss.cache:service=TreeCache"> - - <depends>jboss:service=Naming</depends> - <depends>jboss:service=TransactionManager</depends> - -  - <attribute name="TransactionManagerLookupClass">org.jboss.cache.transaction.GenericTransactionManagerLookup - </attribute> - -  - <attribute name="IsolationLevel">REPEATABLE_READ</attribute> - -  - <attribute name="CacheMode">REPL_SYNC</attribute> - -  - <attribute name="UseReplQueue">false</attribute> - -  - <attribute name="ReplQueueInterval">0</attribute> - -  - <attribute name="ReplQueueMaxElements">0</attribute> - -  - <attribute name="ClusterName">JBossCache-Cluster</attribute> - -  -  - -  - <attribute name="ClusterConfig"> - <config> - <UDP mcast_addr="228.10.10.10" - mcast_port="45588" - tos="8" - ucast_recv_buf_size="20000000" - ucast_send_buf_size="640000" - mcast_recv_buf_size="25000000" - mcast_send_buf_size="640000" - loopback="false" - discard_incompatible_packets="true" - max_bundle_size="64000" - max_bundle_timeout="30" - use_incoming_packet_handler="true" - ip_ttl="2" - enable_bundling="false" - enable_diagnostics="true" - - use_concurrent_stack="true" - - thread_naming_pattern="pl" - - thread_pool.enabled="true" - thread_pool.min_threads="1" - thread_pool.max_threads="25" - thread_pool.keep_alive_time="30000" - thread_pool.queue_enabled="true" - thread_pool.queue_max_size="10" - thread_pool.rejection_policy="Run" - - oob_thread_pool.enabled="true" - oob_thread_pool.min_threads="1" - oob_thread_pool.max_threads="4" - oob_thread_pool.keep_alive_time="10000" - oob_thread_pool.queue_enabled="true" - oob_thread_pool.queue_max_size="10" - oob_thread_pool.rejection_policy="Run"/> - - <PING timeout="2000" num_initial_members="3"/> - <MERGE2 max_interval="30000" min_interval="10000"/> - <FD_SOCK/> - <FD timeout="10000" max_tries="5" shun="true"/> - <VERIFY_SUSPECT timeout="1500"/> - <pbcast.NAKACK max_xmit_size="60000" - use_mcast_xmit="false" gc_lag="0" - retransmit_timeout="300,600,1200,2400,4800" - discard_delivered_msgs="true"/> - <UNICAST timeout="300,600,1200,2400,3600"/> - <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" - max_bytes="400000"/> - <pbcast.GMS print_local_addr="true" join_timeout="5000" - join_retry_timeout="2000" shun="false" - view_bundling="true" view_ack_collection_timeout="5000"/> - <FRAG2 frag_size="60000"/> - <pbcast.STREAMING_STATE_TRANSFER use_reading_thread="true"/> -  - <pbcast.FLUSH timeout="0"/> - </config> - </attribute> - - -  - <attribute name="FetchInMemoryState">true</attribute> - -  - <attribute name="StateRetrievalTimeout">15000</attribute> - -  - <attribute name="SyncReplTimeout">15000</attribute> - -  - <attribute name="LockAcquisitionTimeout">10000</attribute> - -  - <attribute name="UseRegionBasedMarshalling">true</attribute> - </mbean> - - -  -  -  -  -  - - -</server> Copied: pojo/trunk/src/main/release/etc/replSync-service.xml (from rev 5433, pojo/branches/2.1/src/main/release/etc/replSync-service.xml) =================================================================== --- pojo/trunk/src/main/release/etc/replSync-service.xml (rev 0) +++ pojo/trunk/src/main/release/etc/replSync-service.xml 2008-03-15 04:20:53 UTC (rev 5434) @@ -0,0 +1,175 @@ +<?xml version="1.0" encoding="UTF-8"?> + + + + + + + +<server> + +  +  +  + + <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" + name="jboss.cache:service=TreeCache"> + + <depends>jboss:service=Naming</depends> + <depends>jboss:service=TransactionManager</depends> + +  + <attribute name="TransactionManagerLookupClass">org.jboss.cache.transaction.GenericTransactionManagerLookup + </attribute> + +  + <attribute name="IsolationLevel">REPEATABLE_READ</attribute> + +  + <attribute name="CacheMode">REPL_SYNC</attribute> + +  + <attribute name="UseReplQueue">false</attribute> + +  + <attribute name="ReplQueueInterval">0</attribute> + +  + <attribute name="ReplQueueMaxElements">0</attribute> + +  + <attribute name="ClusterName">JBossCache-Cluster</attribute> + +  +  + +  + <attribute name="ClusterConfig"> + <config> + <UDP mcast_addr="228.10.10.10" + mcast_port="45588" + tos="8" + ucast_recv_buf_size="20000000" + ucast_send_buf_size="640000" + mcast_recv_buf_size="25000000" + mcast_send_buf_size="640000" + loopback="false" + discard_incompatible_packets="true" + max_bundle_size="64000" + max_bundle_timeout="30" + use_incoming_packet_handler="true" + ip_ttl="2" + enable_bundling="false" + enable_diagnostics="true" + + use_concurrent_stack="true" + + thread_naming_pattern="pl" + + thread_pool.enabled="true" + thread_pool.min_threads="1" + thread_pool.max_threads="25" + thread_pool.keep_alive_time="30000" + thread_pool.queue_enabled="true" + thread_pool.queue_max_size="10" + thread_pool.rejection_policy="Run" + + oob_thread_pool.enabled="true" + oob_thread_pool.min_threads="1" + oob_thread_pool.max_threads="4" + oob_thread_pool.keep_alive_time="10000" + oob_thread_pool.queue_enabled="true" + oob_thread_pool.queue_max_size="10" + oob_thread_pool.rejection_policy="Run"/> + + <PING timeout="2000" num_initial_members="3"/> + <MERGE2 max_interval="30000" min_interval="10000"/> + <FD_SOCK/> + <FD timeout="10000" max_tries="5" shun="true"/> + <VERIFY_SUSPECT timeout="1500"/> + <pbcast.NAKACK max_xmit_size="60000" + use_mcast_xmit="false" gc_lag="0" + retransmit_timeout="300,600,1200,2400,4800" + discard_delivered_msgs="true"/> + <UNICAST timeout="300,600,1200,2400,3600"/> + <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" + max_bytes="400000"/> + <pbcast.GMS print_local_addr="true" join_timeout="5000" + join_retry_timeout="2000" shun="false" + view_bundling="true" view_ack_collection_timeout="5000"/> + <FRAG2 frag_size="60000"/> + <pbcast.STREAMING_STATE_TRANSFER use_reading_thread="true"/> +  + <pbcast.FLUSH timeout="0"/> + </config> + </attribute> + + +  + <attribute name="FetchInMemoryState">true</attribute> + +  + <attribute name="StateRetrievalTimeout">15000</attribute> + +  + <attribute name="SyncReplTimeout">15000</attribute> + +  + <attribute name="LockAcquisitionTimeout">10000</attribute> + +  + <attribute name="UseRegionBasedMarshalling">true</attribute> + </mbean> + + +  +  +  +  +  + + +</server>

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5433 - in pojo/branches/2.1: src/main/docbook/faq/en and 2 other directories.

by jbosscache-commits＠lists.jboss.org

Author: jason.greene(a)jboss.com Date: 2008-03-15 00:18:42 -0400 (Sat, 15 Mar 2008) New Revision: 5433 Added: pojo/branches/2.1/src/main/release/etc/ pojo/branches/2.1/src/main/release/etc/replSync-service.xml Modified: pojo/branches/2.1/pom.xml pojo/branches/2.1/src/main/docbook/faq/en/master.xml Log: Update FAQ Add descriptor used by tutorial Fix javadc links Modified: pojo/branches/2.1/pom.xml =================================================================== --- pojo/branches/2.1/pom.xml 2008-03-14 16:12:25 UTC (rev 5432) +++ pojo/branches/2.1/pom.xml 2008-03-15 04:18:42 UTC (rev 5433) @@ -4,8 +4,8 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <properties> - <jbosscache-pojo-version>2.1.0.CR4</jbosscache-pojo-version> - <jbosscache-core-version>2.1.0.CR4</jbosscache-core-version> + <jbosscache-pojo-version>2.1.0.GA</jbosscache-pojo-version> + <jbosscache-core-version>2.1.0.GA</jbosscache-core-version> <jboss.aop.version>2.0.0.CR3</jboss.aop.version> <jboss.microcontainer.version>2.0.0.Beta6</jboss.microcontainer.version> <jboss.common-core.version>2.2.1.GA</jboss.common-core.version> @@ -55,6 +55,26 @@ </dependencies> <build> <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>javadoc</goal> + </goals> + <configuration> + <aggregate>${jbosscache.reports.aggregate}</aggregate> + <links> + <link>http://java.sun.com/j2se/1.5.0/docs/api/</link> + <link>http://java.sun.com/javaee/5/docs/api/</link> + <link>http://labs.jboss.org/file-access/default/members/jbosscache/freezone/doc...</link> + </links> + </configuration> + </execution> + </executions> + </plugin> <plugin> <artifactId>maven-assembly-plugin</artifactId> <version>2.2-beta-1</version> Modified: pojo/branches/2.1/src/main/docbook/faq/en/master.xml =================================================================== --- pojo/branches/2.1/src/main/docbook/faq/en/master.xml 2008-03-14 16:12:25 UTC (rev 5432) +++ pojo/branches/2.1/src/main/docbook/faq/en/master.xml 2008-03-15 04:18:42 UTC (rev 5433) @@ -4,9 +4,9 @@ > <article class="faq" lang="en"> <articleinfo> - <title>Frequently Asked Questions about PojoCache</title> - <releaseinfo>Release 2.0.0</releaseinfo> - <pubdate>June 2007</pubdate> + <title>Frequently Asked Questions about POJO Cache</title> + <releaseinfo>Release 2.1.0.GA</releaseinfo> + <pubdate>March 2008</pubdate> <author> <firstname>Ben</firstname> @@ -18,21 +18,25 @@ <surname>Marlow</surname> <email>smarlow(a)novell.com</email> </author> - + <author> + <firstname>Jason</firstname> + <surname>Greene</surname> + <email>jason.greene(a)jboss.com</email> + </author> </articleinfo> - <para>These are frequently asked questions regarding Pojocache.</para> + <para>These are frequently asked questions regarding POJO Cache.</para> <qandaset defaultlabel="qanda"> <title>General Information</title> <qandaentry> <question id="a49"> - <para>What is PojoCache?</para> + <para>What is POJO Cache?</para> </question> <answer> - <para>PojoCache is a fine-grained field-level replicated and + <para>POJO Cache is a fine-grained field-level replicated and transactional POJO (plain old Java object) cache. By POJO, we mean that the cache: 1) automatically manages object mapping and relationship for a client under both local and replicated cache @@ -48,12 +52,12 @@ <para>From a user perspective, once your POJO is managed by the cache, all cache operations are transparent. Therefore, all the usual in-VM POJO method semantics are still preserved, providing - ease of use. For example, if a POJO has been put in PojoCache (by + ease of use. For example, if a POJO has been put in POJO Cache (by calling <literal>attach</literal> , for example), then any POJO get/set method will be - intercepted by PojoCache to provide the data from the + intercepted by POJO Cache to provide the data from the cache. </para> </answer> @@ -61,17 +65,14 @@ <qandaentry> <question id="a1"> - <para>What is the relationship between Cache and PojoCache?</para> + <para>What is the relationship between Core Cache and POJO Cache?</para> </question> <answer> - <para>The core JBoss Cache library - <literal>Cache</literal> - is a traditional generic distributed cache system. - PojoCache uses Cache as the underlying distributed state system to achieve POJO caching. It uses Cache as - a - delegate. As a result, all the replication aspects are configured with the Cache configuration XML. - Additionally, PojoCache also has API to expose the Cache interface (via + <para>Cores Cache is a traditional generic distributed cache system. + POJO Cache uses Core Cache as the underlying distributed state system to achieve object caching. + As a result, all the replication aspects are configured with the Cache configuration XML. + Additionally, POJO Cache also has API to expose the Cache interface (via <literal>getCache()</literal> API). </para> @@ -80,41 +81,39 @@ <qandaentry> <question id="a52"> - <para>What is the difference between Cache and - PojoCache? + <para>What is the difference between Core Cache and + POJO Cache? </para> </question> <answer> - <para>Think of PojoCache as a Cache on steroids. :-) + <para>Think of POJO Cache as a Cache on steroids. :-) Seriously, both are cache stores-- one is a generic cache and the other other one POJO Cache. However, while Cache only provides pure object reference storage (e.g., <literal>put(FQN fqn, Object key, Object value) </literal> - ), PojoCache goes beyond that + ), POJO Cache goes beyond that and performs fine-grained field level replication object mapping and relationship management for a user behind the scenes. As a result, if you have complex object systems that you would like to cache, you - can have PojoCache manage it for you. You simply treat your + can have POJO Cache manage it for you. You simply treat your object systems as they are residing in-memory, e.g., use your regular POJO methods without worrying about cache management. - Furthermore, this is true in replication mode as well. </para> </answer> </qandaentry> <qandaentry> <question id="a521"> - <para>How does PojoCache work then?</para> + <para>How does POJO Cache work then?</para> </question> <answer> - <para>PojoCache uses the so-called AOP technology (aspect oriented programming) to do field level - interception. Currently, it uses - <literal>JBoss Aop</literal> - library to do it. + <para>POJO Cache uses the JBoss AOP project to perform field level + interception. This allows POJO Cache to monitor changes to your object model, and react + accordingly. </para> </answer> </qandaentry> @@ -125,7 +124,7 @@ </question> <answer> - <para>Starting in 2.0 release, we have a separate library for PojoCache, + <para>Starting in 2.0 release, we have a separate library for POJO Cache, <literal>pojocache.jar</literal> that is extra to the core @@ -134,7 +133,7 @@ will need to have a regular xml to configure the core Cache functionality (e.g., replication and locking aspect). In addition, there is also the <literal>pojocache-aop.xml</literal> - that specifies the PojoCache + that specifies the POJO Cache interceptor stack (that can be left as default). </para> <para>Additionally, here are the changed features: @@ -151,14 +150,14 @@ <para>New POJO based events that a user can subscribe to.</para> </listitem> <listitem> - <para>New configuration pojocache-aop.xml specifically for PojoCache, in addition to + <para>New configuration pojocache-aop.xml specifically for POJO Cache, in addition to the regular cache-service.xml for the delegating Cache. </para> </listitem> <listitem> <para>New package namespace ( <literal>org.jboss.cache.pojo)</literal> - for PojoCache. + for POJO Cache. The previous <literal>org.jboss.cache.aop</literal> space has been deprecated. @@ -171,58 +170,43 @@ <qandaentry> <question id="a53"> - <para>What are the steps to use the PojoCache feature?</para> + <para>How do you use POJO Cache?</para> </question> <answer> - <para>In order to use PojoCache, you will need to:</para> + <para>In order to use POJO Cache, you will need to:</para> <itemizedlist> <listitem> - <para>prepare POJO. You can do either via xml declaration or JDK50 annotation. - This is the step to declare your POJO such that it will be instrumented by - <literal>JBoss Aop</literal> - . + <para>Annotate your POJOt with @Replicable. </para> </listitem> <listitem> - <para>instrumentation. You will need to instrument your POJO either at compile- or load-time. - If you do it during compile-time, you use so-called an aop pre-compiler (aopc) to do bytecode - manipulation. - If you do it via load-time, however, you need either a special system class loader or, in JDK50, - you can - use the javaagent option. Either way, - <literal>JBoss Aop</literal> - will byte code manipulate your POJO - class such that all field access can be intercepted. + <para>Instrument your POJO. This can be done at load-time using special JVM arguments (prefered), or at compile time using the + AOP precompiler tool (aopc). See the user guide for more specific details on instrumentation. </para> </listitem> </itemizedlist> - <para>So if you use JDK50, for example, with annotation and load-time instrumentation, then you won't need - any pre-processing step to use PojoCache. For a full example, please refer to the distro examples - directory. - There are numerous PojoCache examples that uses different options. - </para> </answer> </qandaentry> <qandaentry> <question id="a541"> - <para>What is the JDK version required to run PojoCache 2.x?</para> + <para>What is the JDK version required to run POJO Cache 2.x?</para> </question> <answer> - <para>PojoCache 2.x requires JDK5.0 since it uses the annotation extensively.</para> + <para>POJO Cache 2.x requires Java 5 or newer.</para> </answer> </qandaentry> <qandaentry> <question id="a542"> - <para>Can I run PojoCache as a standalone mode?</para> + <para>Can I run POJO Cache as a standalone mode?</para> </question> <answer> - <para>Yes, same as the core Cache library, you can run PojoCache either as a standalone or + <para>Yes, same as the Core Cache library, you can run POJO Cache either as a standalone or inside an application server. </para> </answer> @@ -230,11 +214,11 @@ <qandaentry> <question id="a543"> - <para>What is the JBoss AS recommended version to run PojoCache 2.x?</para> + <para>What is the JBoss AS recommended version to run POJO Cache 2.x?</para> </question> <answer> - <para>PojoCache can be run either in AS4.0.5 (and up) and 5.0. But either way, it will require + <para>POJO Cache can be run either in AS4.0.5 (and up) and 5.0. But either way, it will require JDK5.0 though. </para> </answer> @@ -242,51 +226,29 @@ <qandaentry> <question id="a56"> - <para>Can I pre-compile the aop classes such that I don't need to - use the system classloader and jboss-aop configuration xml during runtime? + <para>Can I pre-compile objects used in POJO Cache, so that I don't have to provide an AOP descriptor? </para> </question> <answer> - <para>Yes. The latest versions of JBossCache have a pre-compiler - option called - <literal>aopc</literal> - . You can use this option to - pre-compile your "aspectized" POJO. Once the classes have been byte - code generated, they can be treated as regular class files, i.e., - you will not need to include any - <literal>jboss-aop.xml</literal> - that specifies the advisable POJO and to specify the JBossAop system - class loader. + <para>Yes. The AOP library included with POJO Cache has a pre-compiler called + <literal>aopc</literal> that can be used to instrument objects in advance. However, + this is not the recommended approach, since your classes become tied to a specific AOP version. + See the instrumentation chapter in the user guide for more information. </para> - - <para>For an example of how to use - <literal>aopc</literal> - , please - see 1) - <literal>tools</literal> - directory for PojoCacheTasks14.xml - and PojoCacheTasks50.xml. Both contain Ant tasks that you can - import to your regular project for - <literal>aopc</literal> - . In addition, please also check out the - <literal>examples</literal> - directory for concrete examples. - </para> </answer> </qandaentry> <qandaentry> <question id="a561"> - <para>In PojoCache 2.x release, do I still need + <para>In POJO Cache 2.x release, do I still need <literal>annoc</literal> ? </para> </question> <answer> - <para>The annoc precompiler is needed for JDK1.4 style annotation. For 2.x release, since - we require the use of JDK5.0, there is no need to use annoc anymore. + <para>No. POJO Cache 2.x requires JDK 5, and recommends load-time instrumentation. Alternatively the offline aopc tool may be used. </para> </answer> </qandaentry> @@ -306,15 +268,11 @@ <qandaentry> <question id="a57a"> - <para>Does PojoCache provide POJO event subscription?</para> + <para>Does POJO Cache provide a listener/event model for catching changes?</para> </question> <answer> - <para>Yes, since 2.0, you can use PojoCacheListener to subscribe to events - such as POJO attach and detach and field updates. And if you need some customization, - you can also use the Obervable pattern directly. TO see an example, please check - out the test case: - <literal>org.jboss.cache.pojo.observer.LocalTest.java</literal> + <para>Yes. See the javadoc for PojoCache.addListener() and @PojoCacheListener. </para> </answer> </qandaentry> @@ -322,33 +280,18 @@ <qandaentry> <question id="a58"> <para>What's in the - <literal>jboss-aop.xml</literal> + <literal>pojocaches-aop.xml</literal> configuration? </para> </question> <answer> <para> - <literal>jboss-aop.xml</literal> - is needed for POJO - instrumentation. In - <literal>jboss-aop.xml</literal> - , you can - declare your POJO (e.g., - <literal>Person</literal> - ) to be - "prepared", a JBossAop term to denote that the object will be - "aspectized" by the system. After this declaration, JBossAop will - invoke any interceptor that associates with this POJO. PojoCache - will dynamically add an - <literal>org.jboss.cache.pojo.interceptor.dynamic.CacheFieldInterceptor</literal> - to this POJO - to perform object mapping and relationship management. + These descriptors are necessary for instrumentation. However, yyou typically do not need to touch them since they include a rule + which matches the classes with an @Replicable annotation. Therefore, all you need to do, is just + annotate your class with @Replicable. Advanced users may decide to customize them with special AOP prepare statements that match + classes which do not have @Replicable. </para> - - <para>Note that to add your POJO, you should declare all the fields - to be "prepared" as in the example. - </para> </answer> </qandaentry> @@ -367,7 +310,7 @@ is essentially a <literal>jboss-aop.xml</literal> , - except it is used specifically for PojoCache. The analogy is similar to JBoss' own + except it is used specifically for POJO Cache. The analogy is similar to JBoss' own MBean service file <literal>jboss-service.xml</literal> , for example. So in our documentation, @@ -378,26 +321,22 @@ <qandaentry> <question id="a59"> - <para>Can I use annotation instead of the xml declaration?</para> + <para>Can I use annotations instead of editing the AOP XML descriptors?</para> </question> <answer> - <para>Yes, in release 2.0, you can use JDK5.0 annotation to - instrument your POJO. Check the documentation for details. + <para>Yes, in release 2.0, we recommend you use the @Replicable annotation, and don't bother with editing the AOP files. </para> </answer> </qandaentry> <qandaentry> <question id="a60"> - <para>What are the pro and con of xml vs. annotation?</para> + <para>Is there a problem with using a custom AOP descriptor over the provided annotations?</para> </question> <answer> - <para>It really depends on your organization environment, I'd say, since this can be turned into a - hot debate. Having said that, I feel strongly that POJO annotation is well suited for PojoCache. This is - because once you specify the annotation, you'd probably change it rarely since there is no parameters to - tune, for example. + <para>The only real benefit to a custom AOP descriptor is if you can't easily add the annotation to the class source (it's not under your control). </para> </answer> </qandaentry> @@ -418,13 +357,13 @@ , when applied has the same effect as declaring a field <literal>transient</literal> - . PojoCache + . POJO Cache won't put this field under management. </para> <para>The second one, <literal>@org.jboss.cache.pojo.Serializable</literal> when applied, - will cause PojoCache to + will cause POJO Cache to treat the field as a Serializable object even when it is <literal>@org.jboss.cache.pojo.Replicable</literal> . @@ -434,14 +373,14 @@ <qandaentry> <question id="a62"> - <para>What about compile-time vs. load-time instrumentation then?</para> + <para>Why do you recommend load-time over compile-time instrumentation?</para> </question> <answer> - <para>Again it depends. But my preference is to do compile-time instrumentation via aopc. I prefer this - approach because it is easier to debug (at least at the development stage). In addition, once I generate - the - new class, there is no more steps needed. + <para> The major problem with compile-time instrumentation is that it adds a binary dependency on your class files to whatever + version of JBoss AOP that was used to run aopc. Once this has been done, the class may not work with a future version of + JBoss AOP (although the AOP team tries to ensure binary compatibility across minor revisions). Load-time doesn't have + this problem since the class is instrumented only in memory, and only when it is loaded. </para> </answer> </qandaentry> @@ -454,8 +393,8 @@ </question> <answer> - <para>Yes, you can use PojoCache to do that. It supports the - notion of object reference. PojoCache manages the unique object + <para>Yes, you can use POJO Cache to do that. It supports the + notion of multiple object references. POJO Cache manages the unique object through association of the dynamic cache interceptor. </para> </answer> @@ -463,32 +402,27 @@ <qandaentry> <question id="a64"> - <para>Do I need to declare all my objects "prepared" in - <literal>jboss-aop.xml</literal> - ? + <para>Do I have to instrument my objects? </para> </question> <answer> - <para>Not necessarily. If there is an object that you don't need the - cache to manage for you, you can leave it out of the declaration. - The cache will treat this object as a "primitive" type. However, the - object will need to implement - <literal>Serializable</literal> - interface for replication. + <para> You can also attach objects that implement + <literal>Serializable</literal>. However, you lose field-level replication and object identity preservation. + This is really only supported as a compatibility measure. It is definately worth useing instrumentation. </para> </answer> </qandaentry> <qandaentry> <question id="a65"> - <para>Can the cache aop intercept update via reflection?</para> + <para>Will POJO Cache intercept changes made from Java Reflection?</para> </question> <answer> - <para>No. The update via reflection will not be intercepted in - JBossAop and therefore PojoCache will not be able to perform the - necessary synchronization. + <para>Yes and No. Since POJO Cache intercepts field changes, any method + of an object that has been annotated with @Replicable will be handled properly when called with reflection. + However, modifying fields using reflection is not currently supported. </para> </answer> </qandaentry> @@ -501,7 +435,7 @@ </question> <answer> - <para>PojoCache currently will ignore the fields with these + <para>POJO Cache currently will ignore the fields with these modifiers. That is, it won't put these fields into the cache (and thus no replication either). </para> @@ -536,13 +470,13 @@ <para>No. Since the Collection classes such as <literal>ArrayList</literal> are java util classes, aop by default - won't instrument these classes. Instead, PojoCache will generate + won't instrument these classes. Instead, POJO Cache will generate a dynamic class proxy for the Collection classes (upon the <literal>attach</literal> call is invoked). The proxy will delegate the operations to a cache interceptor that implements the actual Collection classes APIs. That is, the system classes won't be - invoked when used in PojoCache. + invoked when used in POJO Cache. </para> <para>Internally, the cache interceptor implements the APIs by @@ -566,32 +500,29 @@ <literal>Set</literal> , and - <literal>Map</literal> - dynamic proxy? + <literal>Map</literal> with POJO Cache? </para> </question> <answer> - <para>PojoCache supports classes extending from + <para>POJO Cache supports all classes that implement <literal>List</literal> , <literal>Set</literal> , and <literal>Map</literal> - without users to declare them "aspectized". - It is done via a dynamic proxy. Here is a code snippet to use an - <literal>ArrayList</literal> - proxy class. + without instrumentation. This is done using a dynamic proxy. Here is an example using + <literal>ArrayList</literal>: </para> <programlisting role="JAVA"><![CDATA[ ArrayList list = new ArrayList(); list.add("first"); - cache.attach("list/test", list); // Put the list under the aop cache + cache.attach("/list/test", list); // Put the list under the cache list.add("second"); // Won't work since AOP intercepts the dynamic proxy not the original POJO. - ArrayList myList = (List)cache.find("list/test"); // we are getting a dynamic proxy instead + ArrayList myList = (List)cache.find("/list/test"); // we are getting a dynamic proxy instead myList.add("second"); // it works now myList.add("third"); myList.remove("third"); @@ -619,12 +550,12 @@ ArrayList list = new ArrayList(); list.add("first"); - cache.attach("list", list); // Put the list under the aop cache + cache.attach("/list", list); // Put the list under the aop cache - ArrayList myList = (List)cache.find("list"); // we are getting a dynamic proxy instead + ArrayList myList = (List)cache.find("/list"); // we are getting a dynamic proxy instead myList.add("second"); // it works now - cache.attach("list_alias", myList); // Note you will need to use the proxy here!! + cache.attach("/list_alias", myList); // Note you will need to use the proxy here!! myList.remove("second"); ]]></programlisting> </answer> @@ -634,36 +565,35 @@ <question id="a71"> <para>OK, so I know I am supposed to use proxy when manipulating the Collection classes once they are managed by the cache. But what - happens to Pojos that share the Collection objects, e.g., a + happens to POJOs that share the Collection objects, e.g., a <literal>List</literal> - instance that is shared by 2 Pojos? + instance that is shared by two objects?? </para> </question> <answer> - <para>Pojos that share Collection instance references will be + <para>POJOss that share Collection instance references will be handled by the cache automatically. That is, when you ask the Cache to manage it, the Cache will dynamically swap out the regular Collection references with the dynamic proxy ones. As a result, it - is transparent to the users. + is transparent to you. </para> </answer> </qandaentry> <qandaentry> <question id="a72"> - <para>What happens when my "aspectized" POJO has field members that - are of Collection class ? + <para>What happens when my instrumented object contains collections? </para> </question> <answer> - <para>When a user puts a POJO into the cache through the call + <para>When an object is passed to <literal>attach</literal> , it will recursively map the field - members into the cache store as well. When the field member is of a - Collection class (e.g., List, Set, or Map), PojoCache will first - map the collection into cache. Then, it will swap out dynamically + members into the cache store as well. If the field member is of a + Collection class (e.g., List, Set, or Map), POJO Cache will first + map the collection into cache. Then, it will swap out the field reference with an corresponding proxy reference. </para> @@ -676,84 +606,17 @@ <qandaentry> <question id="a73"> - <para>What are the limitation of Collection classes in PojoCache?</para> + <para>What are the limitations of using Java Collections in POJO Cache?</para> </question> - <answer> - <para>Use of Collection class in PojoCache helps you to track fine-grained changes - in your collection fields automatically. However, current implementation has the follow - limitation that we plan to address soon. + <para> + List, Set, and Map are supported; however, these APIs do not stipulate + of constraints like whether a null key or value is allowed. Therefore the behavior of an attached collection may differ + slightly from the originals Java implementation. The behavior implemented by POJO Cache follows + java.util.HashSet for any Set type, java.util.ArrayList for any List type, and java.util.HashMap for any Map type.s </para> - <para>Currently, we only support a limited implementation of Collection classes. That is, - we support APIs in List, Set, and Map. However, since the APIs do not stipulate - of constraints like NULL key or value, it makes mapping of user instance to our proxy tricky. - For example, ArrayList would allow NULL value and some other implementation would not. - The Set interface maps to java.util.HashSet implementation. The List interface maps - to java.util.ArrayList implementation. The Map interface maps to java.util.HashMap - implementation. - </para> - <para>Another related issue is the expected performance. For example, the current implementation is ordered, - so - that makes insert/delete from the Collection slow. Performance between Set, Map and List collections also - vary. - Adding items to a Set is slower than a List or Map, since Set does not allow duplicate entries. - </para> </answer> </qandaentry> - - - <qandaentry> - <question id="a74"> - <para>What are the pros and cons of PojoCache?</para> - </question> - - <answer> - <para>As mentioned in the reference doc, PojoCache has the following advantages:</para> - <itemizedlist> - <listitem> - <para>Fine-grained replication and/or persistency. If you use a distributed PojoCache - and once your POJO is put in the cache store, there is no need to use another API to - trigger your changes. Furthermore, the replication are fine-grained field level. Note this - also applies to persistency. - </para> - </listitem> - <listitem> - <para>Fine-grained replication can have potential performance gain if your POJO is big and - the changes are fine-grained, e.g., only to some selected fields. - </para> - </listitem> - <listitem> - <para>POJO can posses object relationship, e.g., multiple referenced. Distributed - PojoCache will handle this transparently for you. - </para> - </listitem> - </itemizedlist> - <para>And here are some cases that you may not want to use PojoCache:</para> - <itemizedlist> - <listitem> - <para>You use only cache. That is you don't need replication or persistency. Then since - everything is operated on the in-memory POJO reference, there is no need for PojoCache. - </para> - </listitem> - <listitem> - <para>You have simple and small POJOs. Your POJO is small in size and also there is no - object relationship, then PojoCache possess not clear advantage to plain cache. - </para> - </listitem> - <listitem> - <para>Your application is bounded by memory usage. Because PojoCache need almost twice as much - of memory (the original POJO in-memory space and also the additional cache store for the - primitive fields), you may not want to use PojoCache. - </para> - </listitem> - <listitem> - <para>Your POJO lifetime is short. That is, you need to create and destroy your POJO often. - Then you need to do "attach" and "detach" often, it will be slow in performance. - </para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> </qandaset> @@ -761,31 +624,26 @@ <title>Passiviation and eviction</title> <qandaentry> <question id="a80"> - <para>Can I use eviction to evict POJO from the memory?</para> + <para>Can I use eviction to evict a POJO from the memory?</para> </question> <answer> - <para>No. In 2.0 release, we have deprecated the POJO-based eviction policy since it has always been - problematic in earlier release. The main reason is that when we evict a POJO from - the memory, the user has no ways of knowing it. So if the POJO is accessed after the - eviction, there won't be any PojoCache interception (e.g., it will be just like ordinary POJO), - but user may still expect that it will be managed by PojoCache. + <para>In 2.0 release, we removed the POJO-based eviction policy since it has always been + problematic in earlier release. You can, however, use the standard Core Cache eviction system to + evict the data that backs the POJO. </para> </answer> </qandaentry> <qandaentry> <question id="a81"> - <para>So what do I do now?</para> + <para>Is passivation supported?</para> </question> <answer> - <para>In order to keep your memory from overflowing, you can use the passivation feature that comes with - the core Cache. Passivation uses the combination of eviction and cache loader such that when the + <para>Yes, in order to reduce memory consumption, you can use the passivation feature that comes with + Core Cache. Passivation uses the combination of eviction and a cache loader such that when the items are old, it will be evicted from memory and store in a cache store (can be DB or file). Next time, when the item needs to be accessed again, we will retrieve it from the cache store. </para> - <para>In this sense, PojoCache level is not aware of the passivation aspect. It is configured through - the underlying cache xml. - </para> </answer> </qandaentry> </qandaset> @@ -794,7 +652,7 @@ <title>Troubleshooting</title> <qandaentry> <question id="a90"> - <para>I am having problems getting PojoCache to work, where can I get information on troubleshooting?</para> + <para>I am having problems getting POJO Cache to work, where can I get information on troubleshooting?</para> </question> <answer> <para>Troubleshooting section can be found in the following Added: pojo/branches/2.1/src/main/release/etc/replSync-service.xml =================================================================== --- pojo/branches/2.1/src/main/release/etc/replSync-service.xml (rev 0) +++ pojo/branches/2.1/src/main/release/etc/replSync-service.xml 2008-03-15 04:18:42 UTC (rev 5433) @@ -0,0 +1,175 @@ +<?xml version="1.0" encoding="UTF-8"?> + + + + + + + +<server> + +  +  +  + + <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" + name="jboss.cache:service=TreeCache"> + + <depends>jboss:service=Naming</depends> + <depends>jboss:service=TransactionManager</depends> + +  + <attribute name="TransactionManagerLookupClass">org.jboss.cache.transaction.GenericTransactionManagerLookup + </attribute> + +  + <attribute name="IsolationLevel">REPEATABLE_READ</attribute> + +  + <attribute name="CacheMode">REPL_SYNC</attribute> + +  + <attribute name="UseReplQueue">false</attribute> + +  + <attribute name="ReplQueueInterval">0</attribute> + +  + <attribute name="ReplQueueMaxElements">0</attribute> + +  + <attribute name="ClusterName">JBossCache-Cluster</attribute> + +  +  + +  + <attribute name="ClusterConfig"> + <config> + <UDP mcast_addr="228.10.10.10" + mcast_port="45588" + tos="8" + ucast_recv_buf_size="20000000" + ucast_send_buf_size="640000" + mcast_recv_buf_size="25000000" + mcast_send_buf_size="640000" + loopback="false" + discard_incompatible_packets="true" + max_bundle_size="64000" + max_bundle_timeout="30" + use_incoming_packet_handler="true" + ip_ttl="2" + enable_bundling="false" + enable_diagnostics="true" + + use_concurrent_stack="true" + + thread_naming_pattern="pl" + + thread_pool.enabled="true" + thread_pool.min_threads="1" + thread_pool.max_threads="25" + thread_pool.keep_alive_time="30000" + thread_pool.queue_enabled="true" + thread_pool.queue_max_size="10" + thread_pool.rejection_policy="Run" + + oob_thread_pool.enabled="true" + oob_thread_pool.min_threads="1" + oob_thread_pool.max_threads="4" + oob_thread_pool.keep_alive_time="10000" + oob_thread_pool.queue_enabled="true" + oob_thread_pool.queue_max_size="10" + oob_thread_pool.rejection_policy="Run"/> + + <PING timeout="2000" num_initial_members="3"/> + <MERGE2 max_interval="30000" min_interval="10000"/> + <FD_SOCK/> + <FD timeout="10000" max_tries="5" shun="true"/> + <VERIFY_SUSPECT timeout="1500"/> + <pbcast.NAKACK max_xmit_size="60000" + use_mcast_xmit="false" gc_lag="0" + retransmit_timeout="300,600,1200,2400,4800" + discard_delivered_msgs="true"/> + <UNICAST timeout="300,600,1200,2400,3600"/> + <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" + max_bytes="400000"/> + <pbcast.GMS print_local_addr="true" join_timeout="5000" + join_retry_timeout="2000" shun="false" + view_bundling="true" view_ack_collection_timeout="5000"/> + <FRAG2 frag_size="60000"/> + <pbcast.STREAMING_STATE_TRANSFER use_reading_thread="true"/> +  + <pbcast.FLUSH timeout="0"/> + </config> + </attribute> + + +  + <attribute name="FetchInMemoryState">true</attribute> + +  + <attribute name="StateRetrievalTimeout">15000</attribute> + +  + <attribute name="SyncReplTimeout">15000</attribute> + +  + <attribute name="LockAcquisitionTimeout">10000</attribute> + +  + <attribute name="UseRegionBasedMarshalling">true</attribute> + </mbean> + + +  +  +  +  +  + + +</server>

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5432 - demos/core-demo-gui/trunk.

by jbosscache-commits＠lists.jboss.org

Author: manik.surtani(a)jboss.com Date: 2008-03-14 12:12:25 -0400 (Fri, 14 Mar 2008) New Revision: 5432 Modified: demos/core-demo-gui/trunk/pom.xml Log: Updated POM Modified: demos/core-demo-gui/trunk/pom.xml =================================================================== --- demos/core-demo-gui/trunk/pom.xml 2008-03-14 02:49:48 UTC (rev 5431) +++ demos/core-demo-gui/trunk/pom.xml 2008-03-14 16:12:25 UTC (rev 5432) @@ -10,7 +10,7 @@ </parent> <groupId>org.jboss.cache</groupId> <artifactId>jbosscache-demo</artifactId> - <version>1.0-SNAPSHOT</version> + <version>1.1-SNAPSHOT</version> <name>JBoss Cache - Core Edition GUI Demo</name> <description>JBoss Cache - Core Edition GUI Demo</description> <packaging>jar</packaging> @@ -18,7 +18,7 @@ <dependency> <groupId>org.jboss.cache</groupId> <artifactId>jbosscache-core</artifactId> - <version>2.1.0.CR3</version> + <version>2.1.0.GA</version> </dependency> <dependency> <groupId>jgoodies</groupId>

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5431 - in pojo/trunk/src/main/java/org/jboss/cache/pojo: impl and 2 other directories.

by jbosscache-commits＠lists.jboss.org

Author: jason.greene(a)jboss.com Date: 2008-03-13 22:49:48 -0400 (Thu, 13 Mar 2008) New Revision: 5431 Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/PojoCache.java pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java pojo/trunk/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java pojo/trunk/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java Log: Merge javadoc fixes from branches/2.1 Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/PojoCache.java =================================================================== --- pojo/trunk/src/main/java/org/jboss/cache/pojo/PojoCache.java 2008-03-14 02:48:22 UTC (rev 5430) +++ pojo/trunk/src/main/java/org/jboss/cache/pojo/PojoCache.java 2008-03-14 02:49:48 UTC (rev 5431) @@ -12,6 +12,7 @@ import org.jboss.cache.Cache; import org.jboss.cache.Fqn; +import org.jboss.cache.pojo.annotation.Replicable; import org.jboss.cache.pojo.notification.annotation.PojoCacheListener; /** @@ -23,6 +24,7 @@ * replication via fine-grained maner, i.e., only modified fields are replicated.</p> * * @author Ben Wang + * @author Jason T. Greene * @since 2.0 */ public interface PojoCache @@ -31,7 +33,7 @@ * <p>Attach a POJO into PojoCache. It will also recursively put any * sub-POJO into the cache system. A POJO can be the following and have the * consqeuences when attached:</p> <p/> <li>it is Replicable, that is, it - * has been annotated with {@link @org.jboss.cache.pojo.annotation.Replicable} annotation (or via XML), + * has been annotated with {@link Replicable} annotation (or via XML), * and has * been "instrumented" either compile- or load-time. The POJO will be mapped * recursively to the system and fine-grained replication will be @@ -47,8 +49,8 @@ * @param id An id String to identify the object in the cache. To promote * concurrency, we recommend the use of hierarchical String separating by a * designated separator. Default is "/" but it can be set differently via a - * System property, jbosscache.separator in the future release. E.g., "ben", - * or "student/joe", etc. + * System property, jbosscache.separator in the future release. E.g., "/ben", + * or "/student/joe", etc. * @param pojo object to be inerted into the cache. If null, it will nullify * the fqn node. * @return Existing POJO or null if there is none. @@ -59,26 +61,23 @@ /** * <p>Attach a POJO into PojoCache. It will also recursively put any * sub-POJO into the cache system. A POJO can be the following and have the - * consqeuences when attached:</p> <p/> <li>it is Replicable, that is, it - * has been annotated with {@link @org.jboss.cache.pojo.annotation.Replicable} annotation (or via XML), + * consequences when attached:</p> <p/> <li>it is Replicable, that is, it + * has been annotated with {@link Replicable} annotation (or via XML), * and has * been "instrumented" either compile- or load-time. The POJO will be mapped * recursively to the system and fine-grained replication will be * performed.</li> <li>It is Serializable. The POJO will still be stored in * the cache system. However, it is treated as an "opaque" object per se. * That is, the POJO will neither be intercepted - * (for fine-grained operation) or object relantionship will be + * (for fine-grained operation) or object relationship will be * maintained.</li> * <li>Neither of above. In this case, a user can specify whether it wants * this POJO to be stored (e.g., replicated or persistent). If not, a * PojoCacheException will be thrown.</li> * - * @param id An id String to identify the object in the cache. To promote - * concurrency, we recommend the use of hierarchical String separating by a - * designated separator. Default is "/" but it can be set differently via a - * System property, jbosscache.separator in the future release. E.g., "ben", - * or "student/joe", etc. - * @param pojo object to be inerted into the cache. If null, it will nullify + * @since 2.1 + * @param id the Fqn that specifies the location in the cache to attach the object + * @param pojo object to be inserted into the cache. If null, it will nullify * the fqn node. * @return Existing POJO or null if there is none. * @throws PojoCacheException Throws if there is an error related to the cache operation. @@ -97,6 +96,7 @@ /** * Remove POJO object from the cache. * + * @since 2.1 * @param id location of the object to remove * @return Original value object from this node. * @throws PojoCacheException Throws if there is an error related to the cache operation. @@ -116,6 +116,7 @@ * Determines if an object is attached at a particular location. This is somewhat less expensive * than find() because an object is not created, and internal reference links are not traversed. * + * @since 2.1 * @param id the location in the cache to examine * @return true if an attached object exists, false if not */ @@ -135,6 +136,7 @@ * Retrieve POJO from the cache system. Return null if object does not exist in the cache. * Note that this operation is fast if there is already a POJO instance attached to the cache. * + * @since 2.1 * @param id that associates with this node. * @return Current content value. Null if does not exist. * @throws PojoCacheException Throws if there is an error related to the cache operation. @@ -161,6 +163,7 @@ * now. In addition, it assumes that once a POJO is found with a id, no more POJO is stored * under the children of the id. That is, we don't mix the id with different POJOs. * + * @since 2.1 * @param id The starting place to find all POJOs. * @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found. * @throws PojoCacheException Throws if there is an error related to the cache operation. Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java =================================================================== --- pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java 2008-03-14 02:48:22 UTC (rev 5430) +++ pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java 2008-03-14 02:49:48 UTC (rev 5431) @@ -223,7 +223,7 @@ * Note that caller of this method will take care of synchronization within the <code>fqn</code> sub-tree. * * @param fqn - * @return + * @return detached object * @throws CacheException */ public Object removeObject(Fqn fqn, String field) throws CacheException Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java =================================================================== --- pojo/trunk/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java 2008-03-14 02:48:22 UTC (rev 5430) +++ pojo/trunk/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java 2008-03-14 02:49:48 UTC (rev 5431) @@ -21,7 +21,6 @@ */ package org.jboss.cache.pojo.jmx; -import org.jboss.cache.Cache; import org.jboss.cache.CacheStatus; import org.jboss.cache.config.Configuration; import org.jboss.cache.jmx.LegacyConfiguration; @@ -115,20 +114,20 @@ Configuration getConfiguration(); /** - * Gets whether this object should register a {@link CacheJmxWrapperMBean} - * for the underlying {@link Cache} with JMX. + * Gets whether this object should register a {@link PojoCacheJmxWrapperMBean} + * for the underlying {@link PojoCache} with JMX. * <p/> * Default is <code>true</code>. */ boolean getRegisterPlainCache(); /** - * Sets whether this object should register a {@link CacheJmxWrapperMBean} - * for the underlying {@link Cache} with JMX. + * Sets whether this object should register a {@link PojoCacheJmxWrapperMBean} + * for the underlying {@link PojoCache} with JMX. * <p/> * Default is <code>true</code>. * <p/> - * If <code>true</code>, the <code>CacheJmxWrapperMBean</code> will be + * If <code>true</code>, the <code>PojoCacheJmxWrapperMBean</code> will be * instantiated and registered either as part of the registration of * this object, or during the call to {@link #create()}. */ Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java =================================================================== --- pojo/trunk/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java 2008-03-14 02:48:22 UTC (rev 5430) +++ pojo/trunk/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java 2008-03-14 02:49:48 UTC (rev 5431) @@ -38,7 +38,7 @@ * @param cache * @param originalObject * @param thisObject - * @return + * @return true if reachable * @throws CacheException */ public static boolean isReachable(PojoCacheImpl cache, Object originalObject, Object thisObject)

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5430 - in pojo/branches/2.1/src/main/java/org/jboss/cache/pojo: impl and 2 other directories.

by jbosscache-commits＠lists.jboss.org

Author: jason.greene(a)jboss.com Date: 2008-03-13 22:48:22 -0400 (Thu, 13 Mar 2008) New Revision: 5430 Modified: pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/PojoCache.java pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java Log: Fix javadoc Modified: pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/PojoCache.java =================================================================== --- pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/PojoCache.java 2008-03-13 21:50:21 UTC (rev 5429) +++ pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/PojoCache.java 2008-03-14 02:48:22 UTC (rev 5430) @@ -12,6 +12,7 @@ import org.jboss.cache.Cache; import org.jboss.cache.Fqn; +import org.jboss.cache.pojo.annotation.Replicable; import org.jboss.cache.pojo.notification.annotation.PojoCacheListener; /** @@ -23,6 +24,7 @@ * replication via fine-grained maner, i.e., only modified fields are replicated.</p> * * @author Ben Wang + * @author Jason T. Greene * @since 2.0 */ public interface PojoCache @@ -31,7 +33,7 @@ * <p>Attach a POJO into PojoCache. It will also recursively put any * sub-POJO into the cache system. A POJO can be the following and have the * consqeuences when attached:</p> <p/> <li>it is Replicable, that is, it - * has been annotated with {@link @org.jboss.cache.pojo.annotation.Replicable} annotation (or via XML), + * has been annotated with {@link Replicable} annotation (or via XML), * and has * been "instrumented" either compile- or load-time. The POJO will be mapped * recursively to the system and fine-grained replication will be @@ -47,8 +49,8 @@ * @param id An id String to identify the object in the cache. To promote * concurrency, we recommend the use of hierarchical String separating by a * designated separator. Default is "/" but it can be set differently via a - * System property, jbosscache.separator in the future release. E.g., "ben", - * or "student/joe", etc. + * System property, jbosscache.separator in the future release. E.g., "/ben", + * or "/student/joe", etc. * @param pojo object to be inerted into the cache. If null, it will nullify * the fqn node. * @return Existing POJO or null if there is none. @@ -59,26 +61,23 @@ /** * <p>Attach a POJO into PojoCache. It will also recursively put any * sub-POJO into the cache system. A POJO can be the following and have the - * consqeuences when attached:</p> <p/> <li>it is Replicable, that is, it - * has been annotated with {@link @org.jboss.cache.pojo.annotation.Replicable} annotation (or via XML), + * consequences when attached:</p> <p/> <li>it is Replicable, that is, it + * has been annotated with {@link Replicable} annotation (or via XML), * and has * been "instrumented" either compile- or load-time. The POJO will be mapped * recursively to the system and fine-grained replication will be * performed.</li> <li>It is Serializable. The POJO will still be stored in * the cache system. However, it is treated as an "opaque" object per se. * That is, the POJO will neither be intercepted - * (for fine-grained operation) or object relantionship will be + * (for fine-grained operation) or object relationship will be * maintained.</li> * <li>Neither of above. In this case, a user can specify whether it wants * this POJO to be stored (e.g., replicated or persistent). If not, a * PojoCacheException will be thrown.</li> * - * @param id An id String to identify the object in the cache. To promote - * concurrency, we recommend the use of hierarchical String separating by a - * designated separator. Default is "/" but it can be set differently via a - * System property, jbosscache.separator in the future release. E.g., "ben", - * or "student/joe", etc. - * @param pojo object to be inerted into the cache. If null, it will nullify + * @since 2.1 + * @param id the Fqn that specifies the location in the cache to attach the object + * @param pojo object to be inserted into the cache. If null, it will nullify * the fqn node. * @return Existing POJO or null if there is none. * @throws PojoCacheException Throws if there is an error related to the cache operation. @@ -97,6 +96,7 @@ /** * Remove POJO object from the cache. * + * @since 2.1 * @param id location of the object to remove * @return Original value object from this node. * @throws PojoCacheException Throws if there is an error related to the cache operation. @@ -116,6 +116,7 @@ * Determines if an object is attached at a particular location. This is somewhat less expensive * than find() because an object is not created, and internal reference links are not traversed. * + * @since 2.1 * @param id the location in the cache to examine * @return true if an attached object exists, false if not */ @@ -135,6 +136,7 @@ * Retrieve POJO from the cache system. Return null if object does not exist in the cache. * Note that this operation is fast if there is already a POJO instance attached to the cache. * + * @since 2.1 * @param id that associates with this node. * @return Current content value. Null if does not exist. * @throws PojoCacheException Throws if there is an error related to the cache operation. @@ -161,6 +163,7 @@ * now. In addition, it assumes that once a POJO is found with a id, no more POJO is stored * under the children of the id. That is, we don't mix the id with different POJOs. * + * @since 2.1 * @param id The starting place to find all POJOs. * @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found. * @throws PojoCacheException Throws if there is an error related to the cache operation. Modified: pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java =================================================================== --- pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java 2008-03-13 21:50:21 UTC (rev 5429) +++ pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoCacheDelegate.java 2008-03-14 02:48:22 UTC (rev 5430) @@ -232,7 +232,7 @@ * Note that caller of this method will take care of synchronization within the <code>fqn</code> sub-tree. * * @param fqn - * @return + * @return detached object * @throws CacheException */ public Object removeObject(Fqn fqn, String field) throws CacheException Modified: pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java =================================================================== --- pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java 2008-03-13 21:50:21 UTC (rev 5429) +++ pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/jmx/PojoCacheJmxWrapperMBean.java 2008-03-14 02:48:22 UTC (rev 5430) @@ -21,7 +21,6 @@ */ package org.jboss.cache.pojo.jmx; -import org.jboss.cache.Cache; import org.jboss.cache.CacheStatus; import org.jboss.cache.config.Configuration; import org.jboss.cache.jmx.LegacyConfiguration; @@ -115,20 +114,20 @@ Configuration getConfiguration(); /** - * Gets whether this object should register a {@link CacheJmxWrapperMBean} - * for the underlying {@link Cache} with JMX. + * Gets whether this object should register a {@link PojoCacheJmxWrapperMBean} + * for the underlying {@link PojoCache} with JMX. * <p/> * Default is <code>true</code>. */ boolean getRegisterPlainCache(); /** - * Sets whether this object should register a {@link CacheJmxWrapperMBean} - * for the underlying {@link Cache} with JMX. + * Sets whether this object should register a {@link PojoCacheJmxWrapperMBean} + * for the underlying {@link PojoCache} with JMX. * <p/> * Default is <code>true</code>. * <p/> - * If <code>true</code>, the <code>CacheJmxWrapperMBean</code> will be + * If <code>true</code>, the <code>PojoCacheJmxWrapperMBean</code> will be * instantiated and registered either as part of the registration of * this object, or during the call to {@link #create()}. */ Modified: pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java =================================================================== --- pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java 2008-03-13 21:50:21 UTC (rev 5429) +++ pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/util/ObjectUtil.java 2008-03-14 02:48:22 UTC (rev 5430) @@ -38,7 +38,7 @@ * @param cache * @param originalObject * @param thisObject - * @return + * @return true if reachable * @throws CacheException */ public static boolean isReachable(PojoCacheImpl cache, Object originalObject, Object thisObject)

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5429 - in pojo/trunk/src: main/java/org/jboss/cache/pojo/interceptors/dynamic and 2 other directories.

by jbosscache-commits＠lists.jboss.org

Author: jason.greene(a)jboss.com Date: 2008-03-13 17:50:21 -0400 (Thu, 13 Mar 2008) New Revision: 5429 Added: pojo/trunk/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java pojo/trunk/src/main/java/org/jboss/cache/pojo/interceptors/dynamic/ArrayInterceptor.java pojo/trunk/src/test/java/org/jboss/cache/pojo/LocalTest.java Log: Merge fix for PCACHE-61 Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java =================================================================== --- pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java 2008-03-13 21:47:59 UTC (rev 5428) +++ pojo/trunk/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java 2008-03-13 21:50:21 UTC (rev 5429) @@ -104,10 +104,6 @@ referencedBy_ = new ArrayList(); } - if (referencedBy_.contains(sourceFqn)) - throw new IllegalStateException("PojoReference.incrementRefCount(): source fqn: " + - sourceFqn + " is already present."); - if (util_ == null) util_ = new PojoUtil(); refCount_ = util_.incrementReferenceCount(sourceFqn, refCount_, referencedBy_); // referencedBy_.add(sourceFqn); Modified: pojo/trunk/src/main/java/org/jboss/cache/pojo/interceptors/dynamic/ArrayInterceptor.java =================================================================== --- pojo/trunk/src/main/java/org/jboss/cache/pojo/interceptors/dynamic/ArrayInterceptor.java 2008-03-13 21:47:59 UTC (rev 5428) +++ pojo/trunk/src/main/java/org/jboss/cache/pojo/interceptors/dynamic/ArrayInterceptor.java 2008-03-13 21:50:21 UTC (rev 5429) @@ -30,7 +30,7 @@ import org.jboss.cache.pojo.collection.CachedArrayRegistry; /** - * AOP interceptor which delegates to POJO Cache + * AOP interceptor which delegates to POJO Cache. * * @author Jason T. Greene */ Modified: pojo/trunk/src/test/java/org/jboss/cache/pojo/LocalTest.java =================================================================== --- pojo/trunk/src/test/java/org/jboss/cache/pojo/LocalTest.java 2008-03-13 21:47:59 UTC (rev 5428) +++ pojo/trunk/src/test/java/org/jboss/cache/pojo/LocalTest.java 2008-03-13 21:50:21 UTC (rev 5429) @@ -19,8 +19,10 @@ import org.jboss.cache.Fqn; import org.jboss.cache.pojo.impl.PojoReference; import org.jboss.cache.pojo.test.Address; +import org.jboss.cache.pojo.test.DoubleRef; import org.jboss.cache.pojo.test.Person; import org.jboss.cache.pojo.test.Student; +import org.testng.AssertJUnit; import org.testng.annotations.AfterMethod; import org.testng.annotations.BeforeMethod; import org.testng.annotations.Test; @@ -406,4 +408,15 @@ PojoReference ref = (PojoReference) cache_.getCache().get(fqn, PojoReference.KEY); assertTrue(cache_.exists(ref.getFqn())); } + + public void testDoubleRef() throws Exception + { + DoubleRef ref = new DoubleRef(); + cache_.attach("/test", ref); + + AssertJUnit.assertSame(ref.getOne(), ref.getTwo()); + + ref.setOne(null); + ref.setTwo(null); + } } \ No newline at end of file Copied: pojo/trunk/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java (from rev 5428, pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java) =================================================================== --- pojo/trunk/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java (rev 0) +++ pojo/trunk/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java 2008-03-13 21:50:21 UTC (rev 5429) @@ -0,0 +1,56 @@ +/* +* JBoss, Home of Professional Open Source +* Copyright 2005, JBoss Inc., and individual contributors as indicated +* by the @authors tag. See the copyright.txt in the distribution for a +* full listing of individual contributors. +* +* This is free software; you can redistribute it and/or modify it +* under the terms of the GNU Lesser General Public License as +* published by the Free Software Foundation; either version 2.1 of +* the License, or (at your option) any later version. +* +* This software is distributed in the hope that it will be useful, +* but WITHOUT ANY WARRANTY; without even the implied warranty of +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +* Lesser General Public License for more details. +* +* You should have received a copy of the GNU Lesser General Public +* License along with this software; if not, write to the Free +* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA +* 02110-1301 USA, or see the FSF site: http://www.fsf.org. +*/ +package org.jboss.cache.pojo.test; + +import org.jboss.cache.pojo.annotation.Replicable; + +/** + * Contains two fields referring to the same object reference + * + * @author Jason T. Greene + */ +@Replicable +public class DoubleRef +{ + private Student one = new Student(); + private Student two = one; + + public Student getOne() + { + return one; + } + + public void setOne(Student one) + { + this.one = one; + } + + public Student getTwo() + { + return two; + } + + public void setTwo(Student two) + { + this.two = two; + } +}

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5428 - in pojo/branches/2.1/src: test/java/org/jboss/cache/pojo and 1 other directories.

by jbosscache-commits＠lists.jboss.org

Author: jason.greene(a)jboss.com Date: 2008-03-13 17:47:59 -0400 (Thu, 13 Mar 2008) New Revision: 5428 Added: pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java Modified: pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/LocalTest.java Log: Fix PCACHE-61 Modified: pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java =================================================================== --- pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java 2008-03-13 16:51:00 UTC (rev 5427) +++ pojo/branches/2.1/src/main/java/org/jboss/cache/pojo/impl/PojoInstance.java 2008-03-13 21:47:59 UTC (rev 5428) @@ -104,10 +104,6 @@ referencedBy_ = new ArrayList(); } - if (referencedBy_.contains(sourceFqn)) - throw new IllegalStateException("PojoReference.incrementRefCount(): source fqn: " + - sourceFqn + " is already present."); - if (util_ == null) util_ = new PojoUtil(); refCount_ = util_.incrementReferenceCount(sourceFqn, refCount_, referencedBy_); // referencedBy_.add(sourceFqn); Modified: pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/LocalTest.java =================================================================== --- pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/LocalTest.java 2008-03-13 16:51:00 UTC (rev 5427) +++ pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/LocalTest.java 2008-03-13 21:47:59 UTC (rev 5428) @@ -19,8 +19,10 @@ import org.jboss.cache.Fqn; import org.jboss.cache.pojo.impl.PojoReference; import org.jboss.cache.pojo.test.Address; +import org.jboss.cache.pojo.test.DoubleRef; import org.jboss.cache.pojo.test.Person; import org.jboss.cache.pojo.test.Student; +import org.testng.AssertJUnit; import org.testng.annotations.AfterMethod; import org.testng.annotations.BeforeMethod; import org.testng.annotations.Test; @@ -406,4 +408,15 @@ PojoReference ref = (PojoReference) cache_.getCache().get(fqn, PojoReference.KEY); assertTrue(cache_.exists(ref.getFqn())); } + + public void testDoubleRef() throws Exception + { + DoubleRef ref = new DoubleRef(); + cache_.attach("/test", ref); + + AssertJUnit.assertSame(ref.getOne(), ref.getTwo()); + + ref.setOne(null); + ref.setTwo(null); + } } \ No newline at end of file Added: pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java =================================================================== --- pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java (rev 0) +++ pojo/branches/2.1/src/test/java/org/jboss/cache/pojo/test/DoubleRef.java 2008-03-13 21:47:59 UTC (rev 5428) @@ -0,0 +1,56 @@ +/* +* JBoss, Home of Professional Open Source +* Copyright 2005, JBoss Inc., and individual contributors as indicated +* by the @authors tag. See the copyright.txt in the distribution for a +* full listing of individual contributors. +* +* This is free software; you can redistribute it and/or modify it +* under the terms of the GNU Lesser General Public License as +* published by the Free Software Foundation; either version 2.1 of +* the License, or (at your option) any later version. +* +* This software is distributed in the hope that it will be useful, +* but WITHOUT ANY WARRANTY; without even the implied warranty of +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +* Lesser General Public License for more details. +* +* You should have received a copy of the GNU Lesser General Public +* License along with this software; if not, write to the Free +* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA +* 02110-1301 USA, or see the FSF site: http://www.fsf.org. +*/ +package org.jboss.cache.pojo.test; + +import org.jboss.cache.pojo.annotation.Replicable; + +/** + * Contains two fields referring to the same object reference + * + * @author Jason T. Greene + */ +@Replicable +public class DoubleRef +{ + private Student one = new Student(); + private Student two = one; + + public Student getOne() + { + return one; + } + + public void setOne(Student one) + { + this.one = one; + } + + public Student getTwo() + { + return two; + } + + public void setTwo(Student two) + { + this.two = two; + } +}

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5427 - pojo/branches/2.1.

by jbosscache-commits＠lists.jboss.org

Author: galder.zamarreno(a)jboss.com Date: 2008-03-13 12:51:00 -0400 (Thu, 13 Mar 2008) New Revision: 5427 Modified: pojo/branches/2.1/pom.xml Log: [PCACHE-60] Fixed commons logging version. Modified: pojo/branches/2.1/pom.xml =================================================================== --- pojo/branches/2.1/pom.xml 2008-03-13 16:49:08 UTC (rev 5426) +++ pojo/branches/2.1/pom.xml 2008-03-13 16:51:00 UTC (rev 5427) @@ -9,7 +9,7 @@ <jboss.aop.version>2.0.0.CR3</jboss.aop.version> <jboss.microcontainer.version>2.0.0.Beta6</jboss.microcontainer.version> <jboss.common-core.version>2.2.1.GA</jboss.common-core.version> - <commons-logging.version>1.0.4.GA</commons-logging.version> + <commons-logging.version>1.0.4</commons-logging.version> <jboss.javaee.version>5.0.0.Beta3</jboss.javaee.version> </properties> <parent>

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5426 - pojo/branches/2.1.

by jbosscache-commits＠lists.jboss.org

Author: galder.zamarreno(a)jboss.com Date: 2008-03-13 12:49:08 -0400 (Thu, 13 Mar 2008) New Revision: 5426 Modified: pojo/branches/2.1/pom.xml Log: [PCACHE-60] Added JBossAS profile Modified: pojo/branches/2.1/pom.xml =================================================================== --- pojo/branches/2.1/pom.xml 2008-03-13 03:20:05 UTC (rev 5425) +++ pojo/branches/2.1/pom.xml 2008-03-13 16:49:08 UTC (rev 5426) @@ -7,6 +7,10 @@ <jbosscache-pojo-version>2.1.0.CR4</jbosscache-pojo-version> <jbosscache-core-version>2.1.0.CR4</jbosscache-core-version> <jboss.aop.version>2.0.0.CR3</jboss.aop.version> + <jboss.microcontainer.version>2.0.0.Beta6</jboss.microcontainer.version> + <jboss.common-core.version>2.2.1.GA</jboss.common-core.version> + <commons-logging.version>1.0.4.GA</commons-logging.version> + <jboss.javaee.version>5.0.0.Beta3</jboss.javaee.version> </properties> <parent> <groupId>org.jboss.cache</groupId> @@ -40,7 +44,7 @@ <dependency> <groupId>commons-logging</groupId> <artifactId>commons-logging</artifactId> - <version>1.0.4</version> + <version>${commons-logging.version}</version> </dependency> <dependency> <groupId>net.jcip</groupId> @@ -109,11 +113,6 @@  <dependencies> <dependency> - <groupId>commons-logging</groupId> - <artifactId>commons-logging</artifactId> - <version>1.0.4</version> - </dependency> - <dependency> <groupId>org.jboss.cache</groupId> <artifactId>jbosscache-core</artifactId> <version>${jbosscache-core-version}</version> @@ -123,6 +122,26 @@ <artifactId>jboss-aop</artifactId> <version>${jboss.aop.version}</version> </dependency> + <dependency> + <groupId>org.jboss.microcontainer</groupId> + <artifactId>jboss-container</artifactId> + <version>${jboss.microcontainer.version}</version> + </dependency> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jboss-common-core</artifactId> + <version>${jboss.common-core.version}</version> + </dependency> + <dependency> + <groupId>commons-logging</groupId> + <artifactId>commons-logging</artifactId> + <version>${commons-logging.version}</version> + </dependency> + <dependency> + <groupId>org.jboss.javaee</groupId> + <artifactId>jboss-javaee</artifactId> + <version>${jboss.javaee.version}</version> + </dependency> </dependencies> <executions> <execution> @@ -310,4 +329,56 @@ <url>http://repository.jboss.org/maven2</url> </repository> </repositories> + + <profiles> + <profile> + <id>JBossAS</id> + <activation> + <activeByDefault>false</activeByDefault> + </activation> + <properties> + <jbosscache-pojo-version>2.1.0.CR4-JBossAS</jbosscache-pojo-version> + <jbosscache-core-version>2.1.0-SNAPSHOT-JBossAS</jbosscache-core-version> + <jboss.aop.version>2.0.0.CR7</jboss.aop.version> + <jboss.microcontainer.version>2.0.0.Beta10</jboss.microcontainer.version> + <jboss.common-core.version>2.2.3.GA</jboss.common-core.version> + <commons-logging.version>1.1.0.jboss</commons-logging.version> + <jboss.javaee.version>5.0.0.Beta3Update1</jboss.javaee.version> + </properties> + <dependencies> + <dependency> + <groupId>jgroups</groupId> + <artifactId>jgroups</artifactId> + <version>2.6.2</version> + </dependency> + <dependency> + <groupId>org.jboss.javaee</groupId> + <artifactId>jboss-javaee</artifactId> + <version>${jboss.javaee.version}</version> + </dependency> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jboss-common-core</artifactId> + <version>${jboss.common-core.version}</version> + </dependency> + <dependency> + <groupId>commons-logging</groupId> + <artifactId>commons-logging</artifactId> + <version>${commons-logging.version}</version> + </dependency> + <dependency> + <groupId>org.jboss.transaction</groupId> + <artifactId>jboss-jta</artifactId> + <version>4.3.0.BETA2</version> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.jboss.microcontainer</groupId> + <artifactId>jboss-container</artifactId> + <version>${jboss.microcontainer.version}</version> + </dependency> + </dependencies> + </profile> + </profiles> + </project>

16 years, 1 month

1
0
0 / 0

JBoss Cache SVN: r5425 - in pojo/branches/2.1/src/main/docbook: userguide/en and 1 other directories.

by jbosscache-commits＠lists.jboss.org

Author: jason.greene(a)jboss.com Date: 2008-03-12 23:20:05 -0400 (Wed, 12 Mar 2008) New Revision: 5425 Modified: pojo/branches/2.1/src/main/docbook/tutorial/en/master.xml pojo/branches/2.1/src/main/docbook/userguide/en/master.xml pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml Log: Update docs Modified: pojo/branches/2.1/src/main/docbook/tutorial/en/master.xml =================================================================== --- pojo/branches/2.1/src/main/docbook/tutorial/en/master.xml 2008-03-12 21:37:31 UTC (rev 5424) +++ pojo/branches/2.1/src/main/docbook/tutorial/en/master.xml 2008-03-13 03:20:05 UTC (rev 5425) @@ -1,9 +1,9 @@ <?xml version="1.0" encoding="UTF-8"?> <article lang="en"> <articleinfo> - <title>PojoCache Tutorial</title> - <releaseinfo>Release 2.0.0</releaseinfo> - <pubdate>June 2007</pubdate> + <title>POJO Cache Tutorial</title> + <releaseinfo>Release 2.1.0</releaseinfo> + <pubdate>March 2008</pubdate> <author> <firstname>Ben</firstname> <surname>Wang</surname> @@ -19,9 +19,9 @@ <section> <title>Introduction</title> - <para>PojoCache is an in-memory, transactional, and replicated POJO (plain old Java object) cache system that + <para>POJO Cache is an in-memory, transactional, and replicated POJO (plain old Java object) cache system that allows users to operate on a POJO transparently without active user management of either replication or - persistency aspects. This tutorial focuses on the usage of the PojoCache API. + persistency aspects. This tutorial focuses on the usage of the POJO Cache API. </para> <para>For details of configuration, usage and APIs, please refer to the <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html">users manual</ulink>. @@ -33,7 +33,7 @@ <itemizedlist> <listitem> - <para>PojoCache creation and modification</para> + <para>POJO Cache creation and modification</para> </listitem> <listitem> @@ -41,7 +41,7 @@ </listitem> <listitem> - <para>Using Collections in PojoCache</para> + <para>Using Collections in POJO Cache</para> </listitem> <listitem> @@ -57,17 +57,17 @@ <para>First download the JBoss Cache 2.x distribution from <ulink url="http://labs.jboss.org/portal/jbosscache/download/index.html">the download page</ulink> . You probably want the - <literal>JBossCache-pojo-2.X.Y.zip</literal> + <literal>jbosscache-pojo-2.X.Y.zip</literal> distribution. Unzip it, and you will get a directory containing the distribution, such as - <literal>JBossCache-pojo-2.X.Y</literal> + <literal>jbosscache-pojo-2.X.Y</literal> . For the sake of this tutorial, I will refer to this as - <literal>PojoCache</literal> + <literal>POJO Cache</literal> . </para> <para>The configuration files are located under the - <literal>PojoCache/etc</literal> + <literal>jbosscache-pojo/etc</literal> directory. You can modify the behavior of the underlying cache through editing the various configuration files. </para> @@ -89,8 +89,8 @@ <listitem> <para> <literal>pojocache-aop.xml</literal> - . PojoCache configuration file that contains, amongst other things, the annotation to use on POJOs so - that they're aspectised. For more information, please the PojoCache + . POJO Cache configuration file that contains, amongst other things, the annotation to use on POJOs so + that they're aspectised. For more information, please the POJO Cache <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html">users manual</ulink> . </para> @@ -102,7 +102,7 @@ <title>Script</title> <para>The only script needed for this tutorial is the - <literal>PojoCache/build.xml</literal> + <literal>jbosscache-pojo/build.xml</literal> ant script. </para> </section> @@ -110,7 +110,7 @@ <section> <title>Example POJOs</title> - <para>The example POJO classes used for PojoCache demo are: + <para>The example POJO classes used for POJO Cache demo are: <literal>org.jboss.cache.pojo.test.Person</literal> and <literal>org.jboss.cache.pojo.test.Address</literal> @@ -212,7 +212,7 @@ <itemizedlist> <listitem> <literal>cache</literal> - - a reference to the PojoCache interface, used by the GUI instance. + - a reference to the POJO Cache interface, used by the GUI instance. </listitem> <listitem> <literal>transactionManager</literal> @@ -234,14 +234,14 @@ <section> <title>Tutorials</title> It is recommended that you shut down and restart the demo GUI for each of the following tutorials, to ensure - clean caches every time. To inspect POJO attribute changes via GUI, please refer to the PojoCache + clean caches every time. To inspect POJO attribute changes via GUI, please refer to the POJO Cache <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html">user manual </ulink> to understand how the POJOs are mapped internally in the cache. <section> - <title>PojoCache API, POJO manipulation, and Replication</title> + <title>POJO Cache API, POJO manipulation, and Replication</title> <para> For this tutorial, start two instance of the demo GUI. In this tutorial, we will: Modified: pojo/branches/2.1/src/main/docbook/userguide/en/master.xml =================================================================== --- pojo/branches/2.1/src/main/docbook/userguide/en/master.xml 2008-03-12 21:37:31 UTC (rev 5424) +++ pojo/branches/2.1/src/main/docbook/userguide/en/master.xml 2008-03-13 03:20:05 UTC (rev 5425) @@ -18,8 +18,8 @@ <bookinfo> <title>POJO Cache</title> <subtitle>User Documentation</subtitle> - <releaseinfo>Release 2.0.0</releaseinfo> - <pubdate>July 2007</pubdate> + <releaseinfo>Release 2.1.0.GA</releaseinfo> + <pubdate>March 2008</pubdate> <author> <firstname>Ben</firstname> Modified: pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml =================================================================== --- pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml 2008-03-12 21:37:31 UTC (rev 5424) +++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml 2008-03-13 03:20:05 UTC (rev 5425) @@ -1,13 +1,21 @@ +<?xml version="1.0" encoding="UTF-8"?> <chapter id="api"> + <title>API Overview</title> - <title>API Overview</title> - <para>This section provides a brief overview of the POJO Cache APIs. Please consult the javadoc for the full API.</para> + <para> + This section provides a brief overview of the POJO Cache APIs. + Please consult the javadoc for the full API. + </para> - <sect1> - <title>PojoCacheFactory Class</title> - <para>PojoCacheFactory provides a couple of static methods to instantiate and obtain a PojoCache instance.</para> -<programlisting role="JAVA"><![CDATA[ -/** + <sect1> + <title>PojoCacheFactory Class</title> + + <para> + PojoCacheFactory provides a couple of static methods to + instantiate and obtain a PojoCache instance. + </para> + + <programlisting role="JAVA"><![CDATA[/** * Create a PojoCache instance. Note that this will start the cache life cycle automatically. * @param config A configuration string that represents the file name that is used to * configure the underlying Cache instance. @@ -30,30 +38,31 @@ * @param start If true, it will start the cache life cycle. * @return PojoCache */ -public static PojoCache createInstance(Configuration config, boolean start); -]]></programlisting> - <para>For example, to obtain a PojoCache instance and start the cache lifestyle automatically, - we can do:</para> -<programlisting role="JAVA"><![CDATA[ - String configFile = "META-INF/replSync-service.xml"; - PojoCache cache = PojoCacheFactory.createInstance(configFile); -]]></programlisting> - </sect1> +public static PojoCache createInstance(Configuration config, boolean start);]]></programlisting> + <para> + For example, to obtain a PojoCache instance and start the cache + lifestyle automatically, we can do: + </para> + <programlisting role="JAVA"><![CDATA[String configFile = "META-INF/replSync-service.xml"; +PojoCache cache = PojoCacheFactory.createInstance(configFile);]]> + </programlisting> + </sect1> - <sect1> - <title>PojoCache Interface</title> - <para> - <literal>PojoCache</literal> is the main interface for POJO Cache operations. - Since most of the cache interaction is performed against the application domain model, - there are only a few methods on this interface. - </para> + <sect1> + <title>PojoCache Interface</title> - <sect2> + <para> + <literal>PojoCache</literal> + is the main interface for POJO Cache operations. Since most of the + cache interaction is performed against the application domain + model, there are only a few methods on this interface. + </para> + + <sect2> <title>Attachment</title> -<programlisting role="JAVA"><![CDATA[ - /** + <programlisting role="JAVA"><![CDATA[/** * Attach a POJO into PojoCache. It will also recursively put any sub-POJO into * the cache system. A POJO can be the following and have the consequences when attached: * @@ -72,66 +81,84 @@ * @param id An id String to identify the object in the cache. To promote concurrency, we * recommend the use of hierarchical String separating by a designated separator. Default * is "/" but it can be set differently via a System property, jbosscache.separator - * in the future release. E.g., "ben", or "student/joe", etc. + * in the future release. E.g., "/ben", or "/student/joe", etc. * @param pojo object to be inserted into the cache. If null, it will nullify the fqn node. * @return Existing POJO or null if there is none. * @throws PojoCacheException Throws if there is an error related to the cache operation. */ - Object attach(String id, Object pojo) throws PojoCacheException; -]]></programlisting> - <para> - As described in the above javadoc, this method "attaches" the passed object to the cache - at the specified location (<literal>id</literal>). - The passed in object (<literal>pojo</literal>) must have been instrumented (using the <literal>@Replicable</literal> annotation) - or implement the <literal>Serializable</literal> interface. - </para> + Object attach(String id, Object pojo) throws PojoCacheException;]]></programlisting> - <para> - If the object is not instrumented, but serializable, POJO Cache will simply treat it as an opaque "primitive" type. That is, - it will simply store it without mapping the object's fields into the cache. Replication is done on the object wide - level and therefore it will not be fine-grained. - </para> + <para> + As described in the above javadoc, this method "attaches" the + passed object to the cache at the specified location ( + <literal>id</literal> + ). The passed in object ( + <literal>pojo</literal> + ) must have been instrumented (using the + <literal>@Replicable</literal> + annotation) or implement the + <literal>Serializable</literal> + interface. + </para> - <para>If the object has references to other objects, this call will issue - <literal>attach()</literal> calls - recursively until the entire object graph is - traversed. In addition, object identity and object references are preserved. So both circular and multiply referenced objects - are mapped as expected. - </para> + <para> + If the object is not instrumented, but serializable, POJO Cache + will simply treat it as an opaque "primitive" type. That is, it + will simply store it without mapping the object's fields into + the cache. Replication is done on the object wide level and + therefore it will not be fine-grained. + </para> - <para>The return value after the call is the previous object under <literal>id</literal>, if any. As a result, a successful call i - will replace that old value with the new instance. Note that a user will only need to - issue this call once for each top-level object. Further calls can be made directly on the graph, and they will be mapped as - expected. - </para> -</sect2> - <sect2> - <title>Detachment</title> + <para> + If the object has references to other objects, this call will + issue + <literal>attach()</literal> + calls recursively until the entire object graph is traversed. In + addition, object identity and object references are preserved. + So both circular and multiply referenced objects are mapped as + expected. + </para> -<programlisting role="JAVA"><![CDATA[ - /** + <para> + The return value after the call is the previous object under + <literal>id</literal> + , if any. As a result, a successful call i will replace that old + value with the new instance. Note that a user will only need to + issue this call once for each top-level object. Further calls + can be made directly on the graph, and they will be mapped as + expected. + </para> + </sect2> + + <sect2> + <title>Detachment</title> + + <programlisting role="JAVA"><![CDATA[/** * Remove POJO object from the cache. * * @param id Is string that associates with this node. * @return Original value object from this node. * @throws PojoCacheException Throws if there is an error related to the cache operation. */ - Object detach(String id) throws PojoCacheException; -]]></programlisting> + Object detach(String id) throws PojoCacheException;]]></programlisting> - <para> - This call will detach the POJO from the cache by removing the contents under <literal>id</literal> - and return the POJO instance stored there (null if it doesn't exist). If successful, further operations against - this object will not affect the cache. - Note this call will also remove everything stored under <literal>id</literal> even if you have put - other plain cache data there. - </para> - </sect2> + <para> + This call will detach the POJO from the cache by removing the + contents under + <literal>id</literal> + and return the POJO instance stored there (null if it doesn't + exist). If successful, further operations against this object + will not affect the cache. Note this call will also remove + everything stored under + <literal>id</literal> + even if you have put other plain cache data there. + </para> + </sect2> - <sect2> + <sect2> <title>Query</title> -<programlisting role="JAVA"><![CDATA[ - /** + + <programlisting role="JAVA"><![CDATA[/** * Retrieve POJO from the cache system. Return null if object does not exist in the cache. * Note that this operation is fast if there is already a POJO instance attached to the cache. * @@ -139,21 +166,21 @@ * @return Current content value. Null if does not exist. * @throws PojoCacheException Throws if there is an error related to the cache operation. */ - Object find(String id) throws PojoCacheException; -]]></programlisting> + Object find(String id) throws PojoCacheException;]]></programlisting> + <para> -This call will - return the current object content located under - <literal>id</literal>. This method call is useful when you don't have the exact POJO reference. - For example, when you fail over to the - replicated node, you want to get the object reference from the replicated cache instance. - In this case, PojoCache will create a new Java object if it does not exist and - then add the cache interceptor such that every future access will be - in sync with the underlying cache store. + This call will return the current object content located under + <literal>id</literal> + . This method call is useful when you don't have the exact POJO + reference. For example, when you fail over to the replicated + node, you want to get the object reference from the replicated + cache instance. In this case, PojoCache will create a new Java + object if it does not exist and then add the cache interceptor + such that every future access will be in sync with the + underlying cache store. </para> -<programlisting role="JAVA"><![CDATA[ - /** + <programlisting role="JAVA"><![CDATA[/** * Query all managed POJO objects under the id recursively. Note that this will not return * the sub-object POJOs, e.g., if Person has a sub-object of Address, it * won't return Address pojo. Also note also that this operation is not thread-safe @@ -164,19 +191,110 @@ * @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found. * @throws PojoCacheException Throws if there is an error related to the cache operation. */ - Map findAll(String id) throws PojoCacheException; -]]></programlisting> + Map findAll(String id) throws PojoCacheException;]]></programlisting> <para> -This call will return all the managed POJOs under cache with a base Fqn name. It is recursive, meaning that - it will traverse all the sub-trees to find the POJOs under that base. For example, if you specify - the fqn to be root, e.g., - <code>"/"</code> - , then it will return all the - managed POJOs under the cache. + This call will return all the managed POJOs under cache with a + base Fqn name. It is recursive, meaning that it will traverse + all the sub-trees to find the POJOs under that base. For + example, if you specify the fqn to be root, e.g., + <code>"/"</code> + , then it will return all the managed POJOs under the cache. </para> - </sect2> + </sect2> + </sect1> -</sect1> + <sect1> + <title>POJO Annotations</title> + <para> + There are currently three annotations that can be used on attached + objects in POJO Cache: + <literal>@Replicable</literal> + , + <literal>@Transient</literal> + , and + <literal>@Serializable</literal> + . All of which affect how the annotated object is replicated. + </para> + + <sect2> + <title>@Replicable annotation</title> + + <para> + The + <literal>@org.jboss.cache.annotation.Replicable</literal> + annotation is used to mark classes for instrumentation. Once + instrumented, individual field changes can be replicated + separately. See the instrumentation chapter for more information + on this process. + </para> + + <para> + The following example will replicate changes to resource and + name separately: + </para> + + <programlisting role="JAVA"><![CDATA[@Replicable +public class Gadget +{ + private Resource resource; + private String name; +}]]> </programlisting> + </sect2> + + <sect2> + <title>@Transient annotation</title> + + <para> + The <literal>@org.jboss.cache.annotation.Transient</literal> annotation is used to + indicate that a field should not be replicable. This allows + non-transient fields to be included in normal Java serialization + output, but not when replicated by POJO Cache. + </para> + + <para> + The following object will not replicate changes to resource. + </para> + + <programlisting role="JAVA"><![CDATA[@Replicable +public class Gadget +{ + // resource won't be replicated + @Transient + private Resource resource; +} ]]></programlisting> + + </sect2> + + <sect2> + <title>@Serializable annotation</title> + + <para> + The + <literal>@org.jboss.cache.annotation.Serializable</literal> + annotation indicates a field should be treated as a serialized + attribute. This, of course, requires that the type of the field + implement + <literal>Serializable</literal> + . If the marked field type has an @Replicable annotation, it + will be ignored. + <literal></literal> + </para> + + <programlisting role="JAVA"><![CDATA[@Replicable +public class Gadget +{ + // resource won't be replicated + @Transient + private Resource resource; + + // serialized even if SpecialAddress is @Replicable + @Serializable + private SpecialAddress specialAddress; + + // other state variables +}]]> </programlisting> + </sect2> + </sect1> </chapter> Modified: pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml =================================================================== --- pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-03-12 21:37:31 UTC (rev 5424) +++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-03-13 03:20:05 UTC (rev 5425) @@ -2,94 +2,136 @@ <chapter id="instrumentation"> <title>Instrumentation</title> - <para>In order to store an object in POJO Cache, it must be either - instrumented or made serializable. Instrumentation is the most optimal - approach since it preserves object identity and provides field granular - replication. POJO Cache currently uses the JBoss AOP project to provide - instrumentation, so the same processes described in the AOP documentation - are used with POJO Cache.</para> + <para> + In order to store an object in POJO Cache, it must be either + instrumented or made serializable. Instrumentation is the most + optimal approach since it preserves object identity and provides + field granular replication. POJO Cache currently uses the JBoss AOP + project to provide instrumentation, so the same processes described + in the AOP documentation are used with POJO Cache. + </para> - <para>The primary input to JBoss AOP is the AOP binding file, which is - responsible for specifying which classes should be instrumented. POJO Cache - provides a binding file, <literal>pojocache-aop.xml</literal> , which - matches all classes that have been annotated with the - <literal>@Replicable</literal> annotation. Advanced users may choose to - alter this definition to instrument classes in other various interesting - ways. However, it is recommended to just stick with the default annotation - binding.</para> + <para> + The primary input to JBoss AOP is the AOP binding file, which is + responsible for specifying which classes should be instrumented. + POJO Cache provides a binding file, + <literal>pojocache-aop.xml</literal> + , which matches all classes that have been annotated with the + <literal>@Replicable</literal> + annotation. Advanced users may choose to alter this definition to + instrument classes in other various interesting ways. However, it is + recommended to just stick with the default annotation binding. + </para> - <para>The instrumentation process can be executed at either load-time, or - compile-time. Load-time instrumentation uses a Java agent to intercept and - modify classes as they are loaded; whereas compile-time instrumentation - requires running <literal>aopc</literal> as part of the compilation - process.</para> + <para> + The instrumentation process can be executed at either load-time, or + compile-time. Load-time instrumentation uses a Java agent to + intercept and modify classes as they are loaded; whereas + compile-time instrumentation requires running + <literal>aopc</literal> + as part of the compilation process. + </para> <note> - <para>Load-time is the recommended approach, since compile-time - instrumentation adds hard dependencies to the weaved bytecode which ties - the output to a particular version of JBoss AOP.</para> + <para> + Load-time is the recommended approach, since compile-time + instrumentation adds hard dependencies to the weaved bytecode + which ties the output to a particular version of JBoss AOP. + </para> </note> <sect1> <title>Load-time instrumentation</title> - <para>Load-time instrumentation uses a Java agent to intercept all classes - loaded by the JVM. As they are loaded JBoss AOP instruments them, allowing - POJO Cache to monitor field changes. To enable load time instrumentation - the JVM must be started with the following specified:</para> + <para> + Load-time instrumentation uses a Java agent to intercept all + classes loaded by the JVM. As they are loaded JBoss AOP + instruments them, allowing POJO Cache to monitor field changes. To + enable load time instrumentation the JVM must be started with the + following specified: + </para> <orderedlist> <listitem> - <para>The <literal>jboss.aop.path</literal> system property set to the - location of <literal>pojocache-aop.xml</literal></para> + <para> + The + <literal>jboss.aop.path</literal> + system property set to the location of + <literal>pojocache-aop.xml</literal> + </para> </listitem> <listitem> - <para>A javaagent argument which includes - <emphasis>jboss-aop-jdk50.jar</emphasis></para> + <para> + A javaagent argument which includes + <emphasis>jboss-aop-jdk50.jar</emphasis> + </para> </listitem> </orderedlist> - <para>These requirements lead to the following example ant task:</para> + <para> + These requirements lead to the following example ant task: + </para> - <programlisting role="XML"><![CDATA[ -<java classname="Foo" fork="yes"> + <programlisting role="XML"><![CDATA[<java classname="Foo" fork="yes"> <jvmarg value="-javaagent:lib/jboss-aop.jar"/> <jvmarg value="-Djboss.aop.path=etc/META-INF/pojocache-aop.xml"/> <classpath refid="test.classpath"/> -</java> +</java>]]></programlisting> + + <para> + There is also a + <emphasis>pojo-run</emphasis> + command line script in the POJO Cache distribution that passes the + proper arguments to the JVM for you. + </para> + + <programlisting role="XML"><![CDATA[$ pojo-run -classpath myclasses org.foo.Bar ]]></programlisting> - <para>Once the JVM is executed in this manner, any class with the - <literal>@Replicable</literal> annotation will be instrumented when it is - loaded.</para> + <para> + Once the JVM is executed in this manner, any class with the + <literal>@Replicable</literal> + annotation will be instrumented when it is loaded. + </para> </sect1> <sect1> <title>Compile-time instrumentation</title> - <para>While load-time is the preffered approach, it is also possible to - instrument classes at compile-time. To do this, the aopc tool is used, - with the following requirements:</para> + <para> + While load-time is the preferred approach, it is also possible to + instrument classes at compile-time. To do this, the aopc tool is + used, with the following requirements: + </para> <orderedlist> <listitem> - <para>The <literal>aoppath</literal> option must point to the location - of pojocache-aop.xml</para> + <para> + The + <literal>aoppath</literal> + option must point to the location of pojocache-aop.xml + </para> </listitem> <listitem> - <para>The <literal>src</literal> option must point to the location of - your class files that are to be instrumented. This is typically the - output folder of a <literal>javac</literal> run.</para> + <para> + The + <literal>src</literal> + option must point to the location of your class files that are + to be instrumented. This is typically the output folder of a + <literal>javac</literal> + run. + </para> </listitem> </orderedlist> - <para>The following is an example ant task which performs compile-time - instrumentation:</para> + <para> + The following is an example ant task which performs compile-time + instrumentation: + </para> - <programlisting role="XML"><![CDATA[ -<taskdef name="aopc" classname="org.jboss.aop.ant.AopC" classpathref="aop.classpath"/> + <programlisting role="XML"><![CDATA[<taskdef name="aopc" classname="org.jboss.aop.ant.AopC" classpathref="aop.classpath"/> <target name="aopc" depends="compile" description="Precompile aop class"> <aopc compilerclasspathref="aop.classpath" verbose="true"> <src path="${build}"/> @@ -98,231 +140,47 @@ <classpath path="${build}"/> <classpath refid="lib.classpath"/> </aopc> -</target> -]]></programlisting><para>In this example, once the aopc target - is executeed the clasess in the build directory are modified. They can - then be packaged in a jar and loaded using the normal Java - mechanisms.</para> +</target>]]></programlisting> + + <para> + In this example, once the aopc target is executed the classes in + the build directory are modified. They can then be packaged in a + jar and loaded using the normal Java mechanisms. + </para> </sect1> <sect1> <title>Understanding the provided AOP descriptor</title> - <para>The advanced user might decide to alter the provided AOP descritor. - In order to do this, it is important to understand the reaons behind what - is provided, and what is required by POJO Cache. Previous sections have - mentioned that any class with the <literal>@Replicable</literal> - annotation will be instrumented. This happens, because the provided AOP - descriptor, <literal>pojocache-aop.xml</literal>, has a perpare statement - which matches any class (or subclass) using the annotation. This is shown - in the following snippet:</para> + <para> + The advanced user might decide to alter the provided AOP + descriptor. In order to do this, it is important to understand the + reasons behind what is provided, and what is required by POJO + Cache. Previous sections have mentioned that any class with the + <literal>@Replicable</literal> + annotation will be instrumented. This happens, because the + provided AOP descriptor, + <literal>pojocache-aop.xml</literal> + , has a prepare statement which matches any class (or subclass) + using the annotation. This is shown in the following snippet: + </para> - <programlisting role="XML"><![CDATA[ -<prepare expr="field(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}->*)"/> + <programlisting role="XML"><![CDATA[<prepare expr="field(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}->*)"/> ]]></programlisting> - <para>More specifically, any code which accesses a field on a class which - has been annotated with <literal>@Replicable</literal>, will be - instrumented: The "field" pointcut in the expression matches both read and - write operations. The wildcard "*" indicates that all java protection - modes are intercepted (private, package, protected, public). The - <literal>$instanceof</literal> expression refers to any annotation that - subclasses <literal>@Replicable</literal>. Finally, the ending wildcard - allows the matched field to have any name.</para> + <para> + More specifically, any code which accesses a field on a class + which has been annotated with + <literal>@Replicable</literal> + , will be instrumented: The "field" pointcut in the expression + matches both read and write operations. The wildcard "*" indicates + that all java protection modes are intercepted (private, package, + protected, public). The + <literal>$instanceof</literal> + expression refers to any annotation that subclasses + <literal>@Replicable</literal> + . Finally, the ending wildcard allows the matched field to have + any name. + </para> </sect1> - - <sect1> - <title>Annotation</title> - - <para>Annotation is a new feature in Java 5.0 that when declared can - contain metadata at compile and run time. It is well suited for aop - declaration since there will be no need for external metadata xml - descriptor.</para> - - <sect2> - - - <title>POJO annotation for instrumentation</title> - - - - <para>To support annotation (in order to simplify user's development - effort), the JBoss Cache distribution ships with a - <literal>pojocache-aop.xml</literal> under the - <literal>resources</literal> directory. For reference, here is - annotation definition from <literal>pojocache-aop.xml</literal> again : - </para> - <programlisting role="XML"><![CDATA[ -<aop> - <prepare expr="field(*(a)org.jboss.cache.pojo.annotation.Replicable->*)"/> -</aop> - ]]></programlisting><para>Basically, it simply states that any annotation - with both marker interfaces will be "aspectized" accordingly.</para> - - - - <para>Here is a code snippet that illustrate the declaration:</para> - - - - <programlisting role="JAVA"><![CDATA[ -(a)org.jboss.cache.pojo.annotation.Replicable public class -Person {...} - ]]></programlisting> - - The above declaration will instrument the class - - <literal>Person</literal> - - and all of its sub-classes. That is, if - - <literal>Student</literal> - - sub-class from - - <literal>Personal</literal> - - , then it will get instrumented automatically without further annotation declaration. - </sect2> - - <sect2> - <title>JDK5.0 field level annotations</title> - - <para>In Release 2.0, we have added two additional field level - annotations for customized behavior. The first one is - <code>@org.jboss.cache.pojo.annotation.Transient</code> . When applied - to a field variable, it has the same effect as the Java language - <code>transient</code> keyword. That is, PojoCache won't put this field - into cache management (and therefore no replication).</para> - - <para>The second one is <code> - @org.jboss.cache.pojo.annotation.Serializable </code> , when applied to - a field variable, PojoCache will treat this variable as - <code>Serializable</code> , even when it is <code>Replicable</code> . - However, the field will need to implement the <code>Serializable</code> - interface such that it can be replicated.</para> - - <para>Here is a code snippet that illustrates usage of these two - annotations. Assuming that you have a Gadget class: </para> - <programlisting role="JAVA"><![CDATA[ -public class Gadget -{ - // resource won't be replicated - @Transient - Resource resource; - - // specialAddress is treated as a Serializable object but still has object relationship - @Serializable - SpecialAddress specialAddress; - - // other state variables -} - ]]></programlisting><para>Then when we do:</para><programlisting role="JAVA"><![CDATA[ - Gadget gadget = new Gadget(); - Resource resource = new Resource(); - SpecialAddress specialAddress = new SpecialAddress(); - - // setters - gadget.setResource(resource); - gadget.setSpecialAddress(specialAddress); - - // put into PojoCache management - cache1.putObject("/gadget", gadget); - - // retrieve it from another cache instance - Gadget g2 = (Gadget) cache2.getObject("/gadget"); - - // This is should be null because of @Transient tag so it is not replicated. - g2.getResource(); - - SepcialAddress d2 = g2.getSpecialAddress(); - d2.setName("inet"); // This won't get replicated automatically because of @Serializable tag - ge.setSpecialAddress(d2); // Now this will. - ]]></programlisting> - </sect2> - </sect1> - - <sect1> - <title>Weaving</title> - - <para>As already mentioned, a user can use the aop precompiler ( - <literal>aopc</literal> ) to precompile the POJO classes such that, during - runtime, there is no additional system class loader needed. The - precompiler will read in <literal>pojocache-aop.xml</literal> and weave - the POJO byte code at compile time. This is a convenient feature to make - the aop less intrusive.</para> - - <para>Below is an Ant snippet that defines the library needed for the - various Ant targets that we are listing here. User can refer to the - <literal>build.xml</literal> in the distribution for full details. - </para> - <programlisting role="XML"><![CDATA[ -<path id="aop.classpath"> - <fileset dir="${lib}"> - <include name="**/*.jar" /> - <exclude name="**/jboss-cache.jar" /> - <exclude name="**/j*unit.jar" /> - <exclude name="**/bsh*.jar" /> - </fileset> -</path> - ]]></programlisting> - - <sect2> - <title>Ant target for running load-time instrumentation using - specialized class loader</title> - - <para>In JDK5.0, you can use the <code>javaagent</code> option that does - not require a separate Classloader. Here are the ant snippet from - <code>one-test-pojo</code> , for example.</para> - <programlisting role="XML"><![CDATA[ -<target name="one.test.pojo" depends="compile" description="run one junit test case."> - <junit printsummary="yes" timeout="${junit.timeout}" fork="yes"> - <jvmarg value="-Djboss.aop.path=${output}/resources/pojocache-aop.xml"/> - <jvmarg value="-javaagent:${lib}/jboss-aop-jdk50.jar"/> - <classpath path="${output}/etc" /> - <sysproperty key="log4j.configuration" value="file:${output}/etc/log4j.xml" /> - <classpath refid="lib.classpath"/> - <classpath refid="build.classpath"/> - <formatter type="xml" usefile="true"/> - <test name="${test}" todir="${reports}"/> - </junit> -</target> - ]]></programlisting> - </sect2> - - <sect2> - <title>Ant target for aopc</title> - - <para>Below is the code snippet for the <literal>aopc</literal> Ant - target. Running this target will do compile-time weaving of the POJO - classes specified.</para> - - <programlisting role="XML"><![CDATA[ -<taskdef name="aopc" classname="org.jboss.aop.ant.AopC" classpathref="aop.classpath"/> -<target name="aopc" depends="compile" description="Precompile aop class"> - <aopc compilerclasspathref="aop.classpath" verbose="true"> - <src path="${build}"/> - <include name="org/jboss/cache/aop/test/**/*.class"/> - <aoppath path="${output}/resources/pojocache-aop.xml"/> - <classpath path="${build}"/> - <classpath refid="lib.classpath"/> - </aopc> -</target> - ]]></programlisting> - - <para>Below is a snapshot of files that are generated when aopc is - applied. Notice that couple extra classes have been generated because of - <literal>aopc</literal> .</para> - - <figure> - <title>Classes generated after aopc</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/classes.png" /> - </imageobject> - </mediaobject> - </figure> - </sect2> - </sect1> -</chapter> \ No newline at end of file +</chapter>

16 years, 1 month

1
0
0 / 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

jbosscache-commits March 2008