From jbosscache-commits at lists.jboss.org Wed Mar 12 23:20:05 2008 Content-Type: multipart/mixed; boundary="===============4746104211864296440==" MIME-Version: 1.0 From: jbosscache-commits at lists.jboss.org To: jbosscache-commits at lists.jboss.org Subject: [jbosscache-commits] JBoss Cache SVN: r5425 - in pojo/branches/2.1/src/main/docbook: userguide/en and 1 other directories. Date: Wed, 12 Mar 2008 23:20:05 -0400 Message-ID: --===============4746104211864296440== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@
- PojoCache Tutorial - Release 2.0.0 - June 2007 + POJO Cache Tutorial + Release 2.1.0 + March 2008 Ben Wang @@ -19,9 +19,9 @@
Introduction = - PojoCache is an in-memory, transactional, and replicated POJO = (plain old Java object) cache system that + 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 us= er management of either replication or - persistency aspects. This tutorial focuses on the usage of the Po= joCache API. + persistency aspects. This tutorial focuses on the usage of the PO= JO Cache API. For details of configuration, usage and APIs, please refer to = the users manual. @@ -33,7 +33,7 @@ = - PojoCache creation and modification + POJO Cache creation and modification = @@ -41,7 +41,7 @@ = - Using Collections in PojoCache + Using Collections in POJO Cache = @@ -57,17 +57,17 @@ First download the JBoss Cache 2.x distribution from the download page . You probably want the - JBossCache-pojo-2.X.Y.zip + jbosscache-pojo-2.X.Y.zip distribution. Unzip it, and you will get a directory containing t= he distribution, such as - JBossCache-pojo-2.X.Y + jbosscache-pojo-2.X.Y . For the sake of this tutorial, I will refer to this as - PojoCache + POJO Cache . = The configuration files are located under the - PojoCache/etc + jbosscache-pojo/etc directory. You can modify the behavior of the underlying cache th= rough editing the various configuration files. = @@ -89,8 +89,8 @@ pojocache-aop.xml - . PojoCache configuration file that contains, amongst other= things, the annotation to use on POJOs so - that they're aspectised. For more information, please the P= ojoCache + . POJO Cache configuration file that contains, amongst othe= r things, the annotation to use on POJOs so + that they're aspectised. For more information, please the P= OJO Cache users manual . @@ -102,7 +102,7 @@ Script = The only script needed for this tutorial is the - PojoCache/build.xml + jbosscache-pojo/build.xml ant script.
@@ -110,7 +110,7 @@
Example POJOs = - The example POJO classes used for PojoCache demo are: + The example POJO classes used for POJO Cache demo are: org.jboss.cache.pojo.test.Person and org.jboss.cache.pojo.test.Address @@ -212,7 +212,7 @@ cache - - a reference to the PojoCache interface, used by the GUI i= nstance. + - a reference to the POJO Cache interface, used by the GUI = instance. transactionManager @@ -234,14 +234,14 @@
Tutorials It is recommended that you shut down and restart the demo GUI for ea= ch 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 user manual to understand how the POJOs are mapped internally in the cache. =
- PojoCache API, POJO manipulation, and Replication + POJO Cache API, POJO manipulation, and Replication 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- pojo/branches/2.1/src/main/docbook/userguide/en/master.xml 2008-03-12 2= 1:37:31 UTC (rev 5424) +++ pojo/branches/2.1/src/main/docbook/userguide/en/master.xml 2008-03-13 0= 3:20:05 UTC (rev 5425) @@ -18,8 +18,8 @@ POJO Cache User Documentation - Release 2.0.0 - July 2007 + Release 2.1.0.GA + March 2008 = Ben Modified: pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ + + API Overview = - API Overview - This section provides a brief overview of the POJO Cache APIs. Pl= ease consult the javadoc for the full API. + + This section provides a brief overview of the POJO Cache APIs. + Please consult the javadoc for the full API. + = - - PojoCacheFactory Class - PojoCacheFactory provides a couple of static methods to instan= tiate and obtain a PojoCache instance. - + PojoCacheFactory Class + + + PojoCacheFactory provides a couple of static methods to + instantiate and obtain a PojoCache instance. + + + - For example, to obtain a PojoCache instance and start the cach= e lifestyle automatically, - we can do: - - +public static PojoCache createInstance(Configuration config, boolean start= );]]> + + For example, to obtain a PojoCache instance and start the cache + lifestyle automatically, we can do: + = + + + = - - PojoCache Interface - - PojoCache is the main interface for POJO Cache= operations. = - Since most of the cache interaction is performed against the appl= ication domain model, = - there are only a few methods on this interface. - + + PojoCache Interface = - + + PojoCache + 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. + + + Attachment = - - - As described in the above javadoc, this method "attaches" the= passed object to the cache = - at the specified location (id). - The passed in object (pojo) must have been= instrumented (using the @Replicable annotation) = - or implement the Serializable interface. = - + Object attach(String id, Object pojo) throws PojoCacheException;]]> = - - If the object is not instrumented, but serializable, POJO C= ache 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. - + + As described in the above javadoc, this method "attaches" the + passed object to the cache at the specified location ( + id + ). The passed in object ( + pojo + ) must have been instrumented (using the + @Replicable + annotation) or implement the + Serializable + interface. + = - If the object has references to other objects, this call= will issue - attach() calls - recursively until the entire object graph is - traversed. In addition, object identity and object referenc= es are preserved. So both circular and multiply referenced objects - are mapped as expected. = - + + 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. + = - The return value after the call is the previous object u= nder id, 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 cal= ls can be made directly on the graph, and they will be mapped as - expected. - - - - Detachment + + If the object has references to other objects, this call will + issue + attach() + 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. + = - + The return value after the call is the previous object under + id + , 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. + + + + + Detachment + + + Object detach(String id) throws PojoCacheException;]]> = - - This call will detach the POJO from the cache by removing t= he contents under id - 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 id even if you have put - other plain cache data there. - - + + This call will detach the POJO from the cache by removing the + contents under + id + 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 + id + even if you have put other plain cache data there. + + = - + Query - + Object find(String id) throws PojoCacheException;]]> + -This call will - return the current object content located under - id. 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 re= plicated 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 + id + . 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. = - + Map findAll(String id) throws PojoCacheException;]]> = -This call will return all the managed POJOs under cache with a base Fqn na= me. It is recursive, meaning that - it will traverse all the sub-trees to find the POJOs under that b= ase. For example, if you specify - the fqn to be root, e.g., - "/" - , 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., + "/" + , then it will return all the managed POJOs under the cache. - + + = - + + POJO Annotations = + + There are currently three annotations that can be used on attached + objects in POJO Cache: + @Replicable + , + @Transient + , and + @Serializable + . All of which affect how the annotated object is replicated. + + + + @Replicable annotation + + + The + @org.jboss.cache.annotation.Replicable + 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. + + + + The following example will replicate changes to resource and + name separately: + + + + + + + @Transient annotation + + + The @org.jboss.cache.annotation.Transient annot= ation 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. + + + + The following object will not replicate changes to resource. + + + + + + + + @Serializable annotation + + + The + @org.jboss.cache.annotation.Serializable + annotation indicates a field should be treated as a serialized + attribute. This, of course, requires that the type of the field + implement + Serializable + . If the marked field type has an @Replicable annotation, it + will be ignored. + + + + + + Modified: pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumen= tation.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ Instrumentation = - 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. + + 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. + = - The primary input to JBoss AOP is the AOP binding file, which is - responsible for specifying which classes should be instrumented. POJO Ca= che - provides a binding file, pojocache-aop.xml , which - matches all classes that have been annotated with the - @Replicable 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 annotati= on - binding. + + 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, + pojocache-aop.xml + , which matches all classes that have been annotated with the + @Replicable + 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. + = - The instrumentation process can be executed at either load-time, or - compile-time. Load-time instrumentation uses a Java agent to intercept a= nd - modify classes as they are loaded; whereas compile-time instrumentation - requires running aopc as part of the compilation - process. + + 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 + aopc + as part of the compilation process. + = - Load-time is the recommended approach, since compile-time - instrumentation adds hard dependencies to the weaved bytecode which ti= es - the output to a particular version of JBoss AOP. + + 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. + = Load-time instrumentation = - Load-time instrumentation uses a Java agent to intercept all cla= sses - loaded by the JVM. As they are loaded JBoss AOP instruments them, allo= wing - POJO Cache to monitor field changes. To enable load time instrumentati= on - the JVM must be started with the following specified: + + 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: + = - The jboss.aop.path system property set to= the - location of pojocache-aop.xml + + The + jboss.aop.path + system property set to the location of + pojocache-aop.xml + = - A javaagent argument which includes - jboss-aop-jdk50.jar + + A javaagent argument which includes + jboss-aop-jdk50.jar + = - These requirements lead to the following example ant task: + + These requirements lead to the following example ant task: + = - + - +]]> + + + There is also a + pojo-run + command line script in the POJO Cache distribution that passes the + proper arguments to the JVM for you. + + + = - Once the JVM is executed in this manner, any class with the - @Replicable annotation will be instrumented when it= is - loaded. + + Once the JVM is executed in this manner, any class with the + @Replicable + annotation will be instrumented when it is loaded. + = Compile-time instrumentation = - 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: + + 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: + = - The aoppath option must point to the loca= tion - of pojocache-aop.xml + + The + aoppath + option must point to the location of pojocache-aop.xml + = - The src option must point to the location= of - your class files that are to be instrumented. This is typically the - output folder of a javac run. + + The + src + option must point to the location of your class files that are + to be instrumented. This is typically the output folder of a + javac + run. + = - The following is an example ant task which performs compile-time - instrumentation: + + The following is an example ant task which performs compile-time + instrumentation: + = - + @@ -98,231 +140,47 @@ - -]]>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. +]]> + + + 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. + = Understanding the provided AOP descriptor = - The advanced user might decide to alter the provided AOP descrit= or. - In order to do this, it is important to understand the reaons behind w= hat - is provided, and what is required by POJO Cache. Previous sections have - mentioned that any class with the @Replicable - annotation will be instrumented. This happens, because the provided AOP - descriptor, pojocache-aop.xml, has a perpare statem= ent - which matches any class (or subclass) using the annotation. This is sh= own - in the following snippet: + + 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 + @Replicable + annotation will be instrumented. This happens, because the + provided AOP descriptor, + pojocache-aop.xml + , has a prepare statement which matches any class (or subclass) + using the annotation. This is shown in the following snippet: + = - *)"/> + *)"/> ]]> = - More specifically, any code which accesses a field on a class wh= ich - has been annotated with @Replicable, 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 - $instanceof expression refers to any annotation that - subclasses @Replicable. Finally, the ending wildcard - allows the matched field to have any name. + + More specifically, any code which accesses a field on a class + which has been annotated with + @Replicable + , 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 + $instanceof + expression refers to any annotation that subclasses + @Replicable + . Finally, the ending wildcard allows the matched field to have + any name. + - - - Annotation - - 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. - - - = - - POJO annotation for instrumentation - - = - - To support annotation (in order to simplify user's development - effort), the JBoss Cache distribution ships with a - pojocache-aop.xml under the - resources directory. For reference, here is - annotation definition from pojocache-aop.xml agai= n : - - - *)= "/> - - ]]>Basically, it simply states that any= annotation - with both marker interfaces will be "aspectized" accordingly. - - = - - Here is a code snippet that illustrate the declaration: - - = - - - - The above declaration will instrument the class = - - Person - - and all of its sub-classes. That is, if = - - Student - - sub-class from = - - Personal - - , then it will get instrumented automatically without further annot= ation declaration. = - - - - JDK5.0 field level annotations - - In Release 2.0, we have added two additional field level - annotations for customized behavior. The first one is - @org.jboss.cache.pojo.annotation.Transient . When appli= ed - to a field variable, it has the same effect as the Java language - transient keyword. That is, PojoCache won't put this fi= eld - into cache management (and therefore no replication). - - The second one is - @org.jboss.cache.pojo.annotation.Serializable , when applied= to - a field variable, PojoCache will treat this variable as - Serializable , even when it is Replicable . - However, the field will need to implement the Serializable - interface such that it can be replicated. - - Here is a code snippet that illustrates usage of these two - annotations. Assuming that you have a Gadget class: - Then when we do: - - - - - Weaving - - As already mentioned, a user can use the aop precompiler ( - aopc ) to precompile the POJO classes such that, du= ring - runtime, there is no additional system class loader needed. The - precompiler will read in pojocache-aop.xml and weave - the POJO byte code at compile time. This is a convenient feature to ma= ke - the aop less intrusive. - - 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 - build.xml in the distribution for full details. - - - - - - - - - - ]]> - - - Ant target for running load-time instrumentation using - specialized class loader - - In JDK5.0, you can use the javaagent option that = does - not require a separate Classloader. Here are the ant snippet from - one-test-pojo , for example. - - - - - - - - - - - - - ]]> - - - - Ant target for aopc - - Below is the code snippet for the aopc Ant - target. Running this target will do compile-time weaving of the POJO - classes specified. - - - - - - - - - - - - ]]> - - Below is a snapshot of files that are generated when aopc is - applied. Notice that couple extra classes have been generated becaus= e of - aopc . - -
- Classes generated after aopc - - - - - - -
- - - \ No newline at end of file + --===============4746104211864296440==--