diff --git a/docs/reference/serialization.xml b/docs/reference/serialization.xml deleted file mode 100644 index 7a146237..00000000 --- a/docs/reference/serialization.xml +++ /dev/null @@ -1,20 +0,0 @@ - - - - Bootstrapping GemFire through the Spring container - - - - -
- Wiring deserialized instances - -
- -
- Auto-generating custom <classname>Instantiator</classname>s - -
- -
\ No newline at end of file diff --git a/docs/index.xml b/docs/src/docbkx/index.xml similarity index 99% rename from docs/index.xml rename to docs/src/docbkx/index.xml index b21cbcf2..f63d8587 100644 --- a/docs/index.xml +++ b/docs/src/docbkx/index.xml @@ -38,9 +38,11 @@ - + + Other Resources diff --git a/docs/introduction/introduction.xml b/docs/src/docbkx/introduction/introduction.xml similarity index 100% rename from docs/introduction/introduction.xml rename to docs/src/docbkx/introduction/introduction.xml diff --git a/docs/introduction/requirements.xml b/docs/src/docbkx/introduction/requirements.xml similarity index 100% rename from docs/introduction/requirements.xml rename to docs/src/docbkx/introduction/requirements.xml diff --git a/docs/links.xml b/docs/src/docbkx/links.xml similarity index 100% rename from docs/links.xml rename to docs/src/docbkx/links.xml diff --git a/docs/preface.xml b/docs/src/docbkx/preface.xml similarity index 100% rename from docs/preface.xml rename to docs/src/docbkx/preface.xml diff --git a/docs/reference/bootstrap.xml b/docs/src/docbkx/reference/bootstrap.xml similarity index 91% rename from docs/reference/bootstrap.xml rename to docs/src/docbkx/reference/bootstrap.xml index e95788c2..40249f35 100644 --- a/docs/reference/bootstrap.xml +++ b/docs/src/docbkx/reference/bootstrap.xml @@ -30,7 +30,7 @@ the user can pass in a GemFire configuration: - + ]]> In this example, if the cache needs to be created, it will use the file named cache.xml located in the classpath root. Note that @@ -42,11 +42,11 @@ - - - 127.0.0.1 - - + + + 127.0.0.1 + + ]]> So far our examples relied on the primary Spring names (beans). However one is free to add other namespaces to simplify or enhance the configuration. @@ -60,9 +60,9 @@ http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"> - - - + + + ]]> @@ -84,7 +84,7 @@ - + ]]> @@ -99,14 +99,14 @@ xmlns:p="http://www.springframework.org/schema/p" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> - - + + - - + + - - + + ]]> It is worth pointing out, that for the vast majority of cases configuring the cache loader, listener and writer through the Spring container is preferred since the same instances diff --git a/docs/reference/data.xml b/docs/src/docbkx/reference/data.xml similarity index 76% rename from docs/reference/data.xml rename to docs/src/docbkx/reference/data.xml index ed2475e1..1a407a59 100644 --- a/docs/reference/data.xml +++ b/docs/src/docbkx/reference/data.xml @@ -32,7 +32,7 @@ For Gemfire, SGI provides a dedicated, per-cache, transaction manager that once declared, allows actions on the Regions to be grouped and executed atomically through Spring: - ]]> + ]]> Note that currently GemFire supports optimistic transactions with read committed isolation. Further more to guarantee this isolation, developers should avoid making in-place changes, that is manually modifying the values present in the cache. To prevent this from happening, the transaction manager configured the cache @@ -44,16 +44,16 @@
Wiring <interfacename>Declarable</interfacename> components - GemFire XML configuration (usually named cache.xml allows user objects to be declared as part of the fabric config. Usually these objects - are CacheLoaders or other pluggable components into GemFire. Out of the box, each such type declared through XML must implement the Declarable - interface which allows arbitrary parameters to be passed to the declared class through a Properties instance. - Eliminate <interfacename>Declarable</interfacename> components One can configure custom types entirely inside through Spring as mentioned in . That way, one does not have to implement the Declarable interface and gets access to all the features of the Spring IoC container (including not just dependency injection but also life-cycle and instance management). + + GemFire XML configuration (usually named cache.xml allows user objects to be declared as part of the fabric config. Usually these objects + are CacheLoaders or other pluggable components into GemFire. Out of the box, each such type declared through XML must implement the Declarable + interface which allows arbitrary parameters to be passed to the declared class through a Properties instance. Consider the following declaration (taken from the Declarable javadoc): @@ -65,8 +65,9 @@ ]]> To simplify the task of parsing, converting the parameters and initializing the object, SGI offers a base class (WiringDeclarableSupport) that allows GemFire - user objects to be wired through autowiring or based on declarations available inside the Spring container. To take advantage of this feature, the user objects need to extends - WiringDeclarableSupport which automatically locates the declaring BeanFactory and performs wiring as part of the initialization process. + user objects to be wired through a template bean definition or, in case that is missing perform autowiring through the Spring container. To take advantage of this feature, + the user objects need to extends WiringDeclarableSupport which automatically locates the declaring BeanFactory and performs wiring as + part of the initialization process. @@ -75,12 +76,81 @@ there are no other ways in which third parties can take care of the object creation outside GemFire. This feature is planned for the up-coming GemFire release (6.5) +
+ Using <emphasis>template</emphasis> definitions + + When used WiringDeclarableSupport tries to first locate an existing bean definition and use that as wiring template. Unless specified, the component + class name will be used as an implicit bean definition name. + + Let's see how our DBLoader declaration would look in that case: + + + + + com.company.app.DBLoader + +]]> + + + + + + + + +]]> + + In the scenario above, as no parameter was specified, a bean with id/name com.company.app.DBLoader was searched for. The found bean definition is used + as a template for wiring the instance created by GemFire. For cases where the bean name uses a different convention, one can pass in the bean-name parameter + in the GemFire configuration: + + + com.company.app.DBLoader + + + template-bean + +]]> + + + + + + + + + +]]> + + The template bean definitions do not have to be declared in XML - any format is allowed (Groovy, annotations, etc..). + +
+
Using Auto/Annotation-wiring - If no parameters are given, WiringDeclarableSupport will autowire - the declaring instance. In short, this means that unless any metadata is offered by the instance, the container will find the object setters and try to automatically satisfy - these dependencies. However, one can also use JDK 5 annotations to provide additional information to the auto-wiring process. We strongly recommend reading the dedicated + If no bean definition is found, by default, WiringDeclarableSupport will + autowire + the declaring instance. In short, this means that unless any metadata is offered by the instance, the container will find the object setters and try to automatically + satisfy these dependencies. However, one can also use JDK 5 annotations to provide additional information to the auto-wiring process. We strongly recommend reading the dedicated chapter in the Spring documentation for more information on the supported annotations and enabling factors. @@ -99,8 +169,7 @@ com.company.app.DBLoader -]]> - +]]> -]]> - +]]> By using the JSR-330 annotations, the cache loader code has been simplified since the location and creation of the DataSource has been externalized and the user code is concerned only with the loading process. The DataSource might be transactional, created lazily, shared between multiple objects or retrieved from JNDI - these aspects can be easily configured and changed through the Spring container without touching the DBLoader code.
-
- Using <emphasis>template</emphasis> definitions - - For cases where auto/annotation-wiring is not enough (or not an option), one can instruct SGI class to use an existing bean definition as a template for wiring. Let's see how our - DBLoader declaration would look in that case: - - - - - com.company.app.DBLoader - - - template-bean - -]]> - - - - - - - - - - -]]> - - - The template bean definitions do not have to be declared in XML - any format is allowed (Groovy, annotations, etc..). -
-
\ No newline at end of file diff --git a/docs/reference/introduction.xml b/docs/src/docbkx/reference/introduction.xml similarity index 73% rename from docs/reference/introduction.xml rename to docs/src/docbkx/reference/introduction.xml index 6d139fe1..6c2eb6a0 100644 --- a/docs/reference/introduction.xml +++ b/docs/src/docbkx/reference/introduction.xml @@ -4,14 +4,14 @@ This part of the reference documentation explains the core functionality offered by Spring GemFire integration. - describes the configuration support provided for + describes the configuration support provided for bootstrapping, initializing and accessing a GemFire cache or region. describes the enhancements for GemFire - (de)serialization process and managment of associated objects. + (de)serialization process and management of associated objects. - explains the integration between GemFire API and + explains the integration between GemFire API and the various "data" features available in Spring, such as transaction management and exception translation. diff --git a/docs/src/docbkx/reference/serialization.xml b/docs/src/docbkx/reference/serialization.xml new file mode 100644 index 00000000..a8400844 --- /dev/null +++ b/docs/src/docbkx/reference/serialization.xml @@ -0,0 +1,62 @@ + + + + Working with GemFire Serialization + + + To improve overall performance of the data fabric, GemFire supports a dedicated serialization protocol that is + both faster and offers more compact results over the standard Java serialization and works transparently + across various language platforms (such as + Java, + .NET and C++). + This chapter discusses the various ways in which SGI simplifies and improves GemFire custom serialization in Java. + + +
+ Wiring deserialized instances + + It is fairly common for objects serialized to have transient data, that is dependent on the node or environment where it lives at a certain point in time. + Serializing such information is useless (and potentially even dangerous) since it is local to a certain VM/machine. For such cases, SGI offers a special + Instantiator that performs + wiring for each new instance created by GemFire during deserialization. + + Through such a mechanism, one can rely on the Spring container to inject (and manage) certain dependencies making it easy to split transient from persistent data + and have rich domain objects in a transparent manner (Spring users might find this approach similar to that of + @Configurable). + The WiringInstantiator works just like WiringDeclarableSupport, trying to first locate a bean definition as a wiring template + and following to autowiring otherwise. Please refer to the previous section () for more details on wiring functionality. + + To use this Instantiator, simply declare it as a usual bean: + + + + org.pkg.SomeDataSerializableClass + + 95 +]]> + + During the container startup, once it is being initialized, the instantiator will, by default, register itself with the GemFire system and perform + wiring on all instances of SomeDataSerializableClass created by GemFire during deserialization. +
+ +
+ Auto-generating custom <classname>Instantiator</classname>s + For data intensive applications, a big number of instances might be created on each machine as data flows in. Out of the box, GemFire uses reflection to create new types + but for some scenarios, this might prove to be expensive (it's always good to perform profiling to quantify whether this is the case or not). For such cases, SGI allows the + automatic generation of Instatiator classes which instantiate a new type (using the default constructor) without the use of reflection: + + + + + + + + +]]> + + The definition above, automatically generated two Instantiators for two classes, namely CustomTypeA and CustomTypeB + and registers them with GemFire, under user id 1025 and 1026. The two instantiators avoid the use of reflection and create the instances directly + through Java code. +
+
\ No newline at end of file diff --git a/docs/reference/testing.xml b/docs/src/docbkx/reference/testing.xml similarity index 100% rename from docs/reference/testing.xml rename to docs/src/docbkx/reference/testing.xml diff --git a/docs/resources/css/highlight.css b/docs/src/docbkx/resources/css/highlight.css similarity index 100% rename from docs/resources/css/highlight.css rename to docs/src/docbkx/resources/css/highlight.css diff --git a/docs/resources/css/html.css b/docs/src/docbkx/resources/css/html.css similarity index 100% rename from docs/resources/css/html.css rename to docs/src/docbkx/resources/css/html.css diff --git a/docs/resources/images/admons/blank.png b/docs/src/docbkx/resources/images/admons/blank.png similarity index 100% rename from docs/resources/images/admons/blank.png rename to docs/src/docbkx/resources/images/admons/blank.png diff --git a/docs/resources/images/admons/caution.gif b/docs/src/docbkx/resources/images/admons/caution.gif similarity index 100% rename from docs/resources/images/admons/caution.gif rename to docs/src/docbkx/resources/images/admons/caution.gif diff --git a/docs/resources/images/admons/caution.png b/docs/src/docbkx/resources/images/admons/caution.png similarity index 100% rename from docs/resources/images/admons/caution.png rename to docs/src/docbkx/resources/images/admons/caution.png diff --git a/docs/resources/images/admons/caution.tif b/docs/src/docbkx/resources/images/admons/caution.tif similarity index 100% rename from docs/resources/images/admons/caution.tif rename to docs/src/docbkx/resources/images/admons/caution.tif diff --git a/docs/resources/images/admons/draft.png b/docs/src/docbkx/resources/images/admons/draft.png similarity index 100% rename from docs/resources/images/admons/draft.png rename to docs/src/docbkx/resources/images/admons/draft.png diff --git a/docs/resources/images/admons/home.gif b/docs/src/docbkx/resources/images/admons/home.gif similarity index 100% rename from docs/resources/images/admons/home.gif rename to docs/src/docbkx/resources/images/admons/home.gif diff --git a/docs/resources/images/admons/home.png b/docs/src/docbkx/resources/images/admons/home.png similarity index 100% rename from docs/resources/images/admons/home.png rename to docs/src/docbkx/resources/images/admons/home.png diff --git a/docs/resources/images/admons/important.gif b/docs/src/docbkx/resources/images/admons/important.gif similarity index 100% rename from docs/resources/images/admons/important.gif rename to docs/src/docbkx/resources/images/admons/important.gif diff --git a/docs/resources/images/admons/important.png b/docs/src/docbkx/resources/images/admons/important.png similarity index 100% rename from docs/resources/images/admons/important.png rename to docs/src/docbkx/resources/images/admons/important.png diff --git a/docs/resources/images/admons/important.tif b/docs/src/docbkx/resources/images/admons/important.tif similarity index 100% rename from docs/resources/images/admons/important.tif rename to docs/src/docbkx/resources/images/admons/important.tif diff --git a/docs/resources/images/admons/next.gif b/docs/src/docbkx/resources/images/admons/next.gif similarity index 100% rename from docs/resources/images/admons/next.gif rename to docs/src/docbkx/resources/images/admons/next.gif diff --git a/docs/resources/images/admons/next.png b/docs/src/docbkx/resources/images/admons/next.png similarity index 100% rename from docs/resources/images/admons/next.png rename to docs/src/docbkx/resources/images/admons/next.png diff --git a/docs/resources/images/admons/note.gif b/docs/src/docbkx/resources/images/admons/note.gif similarity index 100% rename from docs/resources/images/admons/note.gif rename to docs/src/docbkx/resources/images/admons/note.gif diff --git a/docs/resources/images/admons/note.png b/docs/src/docbkx/resources/images/admons/note.png similarity index 100% rename from docs/resources/images/admons/note.png rename to docs/src/docbkx/resources/images/admons/note.png diff --git a/docs/resources/images/admons/note.tif b/docs/src/docbkx/resources/images/admons/note.tif similarity index 100% rename from docs/resources/images/admons/note.tif rename to docs/src/docbkx/resources/images/admons/note.tif diff --git a/docs/resources/images/admons/prev.gif b/docs/src/docbkx/resources/images/admons/prev.gif similarity index 100% rename from docs/resources/images/admons/prev.gif rename to docs/src/docbkx/resources/images/admons/prev.gif diff --git a/docs/resources/images/admons/prev.png b/docs/src/docbkx/resources/images/admons/prev.png similarity index 100% rename from docs/resources/images/admons/prev.png rename to docs/src/docbkx/resources/images/admons/prev.png diff --git a/docs/resources/images/admons/tip.gif b/docs/src/docbkx/resources/images/admons/tip.gif similarity index 100% rename from docs/resources/images/admons/tip.gif rename to docs/src/docbkx/resources/images/admons/tip.gif diff --git a/docs/resources/images/admons/tip.png b/docs/src/docbkx/resources/images/admons/tip.png similarity index 100% rename from docs/resources/images/admons/tip.png rename to docs/src/docbkx/resources/images/admons/tip.png diff --git a/docs/resources/images/admons/tip.tif b/docs/src/docbkx/resources/images/admons/tip.tif similarity index 100% rename from docs/resources/images/admons/tip.tif rename to docs/src/docbkx/resources/images/admons/tip.tif diff --git a/docs/resources/images/admons/toc-blank.png b/docs/src/docbkx/resources/images/admons/toc-blank.png similarity index 100% rename from docs/resources/images/admons/toc-blank.png rename to docs/src/docbkx/resources/images/admons/toc-blank.png diff --git a/docs/resources/images/admons/toc-minus.png b/docs/src/docbkx/resources/images/admons/toc-minus.png similarity index 100% rename from docs/resources/images/admons/toc-minus.png rename to docs/src/docbkx/resources/images/admons/toc-minus.png diff --git a/docs/resources/images/admons/toc-plus.png b/docs/src/docbkx/resources/images/admons/toc-plus.png similarity index 100% rename from docs/resources/images/admons/toc-plus.png rename to docs/src/docbkx/resources/images/admons/toc-plus.png diff --git a/docs/resources/images/admons/up.gif b/docs/src/docbkx/resources/images/admons/up.gif similarity index 100% rename from docs/resources/images/admons/up.gif rename to docs/src/docbkx/resources/images/admons/up.gif diff --git a/docs/resources/images/admons/up.png b/docs/src/docbkx/resources/images/admons/up.png similarity index 100% rename from docs/resources/images/admons/up.png rename to docs/src/docbkx/resources/images/admons/up.png diff --git a/docs/resources/images/admons/warning.gif b/docs/src/docbkx/resources/images/admons/warning.gif similarity index 100% rename from docs/resources/images/admons/warning.gif rename to docs/src/docbkx/resources/images/admons/warning.gif diff --git a/docs/resources/images/admons/warning.png b/docs/src/docbkx/resources/images/admons/warning.png similarity index 100% rename from docs/resources/images/admons/warning.png rename to docs/src/docbkx/resources/images/admons/warning.png diff --git a/docs/resources/images/admons/warning.tif b/docs/src/docbkx/resources/images/admons/warning.tif similarity index 100% rename from docs/resources/images/admons/warning.tif rename to docs/src/docbkx/resources/images/admons/warning.tif diff --git a/docs/resources/images/callouts/1.png b/docs/src/docbkx/resources/images/callouts/1.png similarity index 100% rename from docs/resources/images/callouts/1.png rename to docs/src/docbkx/resources/images/callouts/1.png diff --git a/docs/resources/images/callouts/10.png b/docs/src/docbkx/resources/images/callouts/10.png similarity index 100% rename from docs/resources/images/callouts/10.png rename to docs/src/docbkx/resources/images/callouts/10.png diff --git a/docs/resources/images/callouts/11.png b/docs/src/docbkx/resources/images/callouts/11.png similarity index 100% rename from docs/resources/images/callouts/11.png rename to docs/src/docbkx/resources/images/callouts/11.png diff --git a/docs/resources/images/callouts/12.png b/docs/src/docbkx/resources/images/callouts/12.png similarity index 100% rename from docs/resources/images/callouts/12.png rename to docs/src/docbkx/resources/images/callouts/12.png diff --git a/docs/resources/images/callouts/13.png b/docs/src/docbkx/resources/images/callouts/13.png similarity index 100% rename from docs/resources/images/callouts/13.png rename to docs/src/docbkx/resources/images/callouts/13.png diff --git a/docs/resources/images/callouts/14.png b/docs/src/docbkx/resources/images/callouts/14.png similarity index 100% rename from docs/resources/images/callouts/14.png rename to docs/src/docbkx/resources/images/callouts/14.png diff --git a/docs/resources/images/callouts/15.png b/docs/src/docbkx/resources/images/callouts/15.png similarity index 100% rename from docs/resources/images/callouts/15.png rename to docs/src/docbkx/resources/images/callouts/15.png diff --git a/docs/resources/images/callouts/2.png b/docs/src/docbkx/resources/images/callouts/2.png similarity index 100% rename from docs/resources/images/callouts/2.png rename to docs/src/docbkx/resources/images/callouts/2.png diff --git a/docs/resources/images/callouts/3.png b/docs/src/docbkx/resources/images/callouts/3.png similarity index 100% rename from docs/resources/images/callouts/3.png rename to docs/src/docbkx/resources/images/callouts/3.png diff --git a/docs/resources/images/callouts/4.png b/docs/src/docbkx/resources/images/callouts/4.png similarity index 100% rename from docs/resources/images/callouts/4.png rename to docs/src/docbkx/resources/images/callouts/4.png diff --git a/docs/resources/images/callouts/5.png b/docs/src/docbkx/resources/images/callouts/5.png similarity index 100% rename from docs/resources/images/callouts/5.png rename to docs/src/docbkx/resources/images/callouts/5.png diff --git a/docs/resources/images/callouts/6.png b/docs/src/docbkx/resources/images/callouts/6.png similarity index 100% rename from docs/resources/images/callouts/6.png rename to docs/src/docbkx/resources/images/callouts/6.png diff --git a/docs/resources/images/callouts/7.png b/docs/src/docbkx/resources/images/callouts/7.png similarity index 100% rename from docs/resources/images/callouts/7.png rename to docs/src/docbkx/resources/images/callouts/7.png diff --git a/docs/resources/images/callouts/8.png b/docs/src/docbkx/resources/images/callouts/8.png similarity index 100% rename from docs/resources/images/callouts/8.png rename to docs/src/docbkx/resources/images/callouts/8.png diff --git a/docs/resources/images/callouts/9.png b/docs/src/docbkx/resources/images/callouts/9.png similarity index 100% rename from docs/resources/images/callouts/9.png rename to docs/src/docbkx/resources/images/callouts/9.png diff --git a/docs/resources/images/i21-banner-rhs.jpg b/docs/src/docbkx/resources/images/i21-banner-rhs.jpg similarity index 100% rename from docs/resources/images/i21-banner-rhs.jpg rename to docs/src/docbkx/resources/images/i21-banner-rhs.jpg diff --git a/docs/resources/images/s2-banner-rhs.png b/docs/src/docbkx/resources/images/s2-banner-rhs.png similarity index 100% rename from docs/resources/images/s2-banner-rhs.png rename to docs/src/docbkx/resources/images/s2-banner-rhs.png diff --git a/docs/resources/images/s2_box_logo.png b/docs/src/docbkx/resources/images/s2_box_logo.png similarity index 100% rename from docs/resources/images/s2_box_logo.png rename to docs/src/docbkx/resources/images/s2_box_logo.png diff --git a/docs/resources/images/xdev-spring_logo.jpg b/docs/src/docbkx/resources/images/xdev-spring_logo.jpg similarity index 100% rename from docs/resources/images/xdev-spring_logo.jpg rename to docs/src/docbkx/resources/images/xdev-spring_logo.jpg diff --git a/docs/resources/xsl/fopdf.xsl b/docs/src/docbkx/resources/xsl/fopdf.xsl similarity index 100% rename from docs/resources/xsl/fopdf.xsl rename to docs/src/docbkx/resources/xsl/fopdf.xsl diff --git a/docs/resources/xsl/highlight-fo.xsl b/docs/src/docbkx/resources/xsl/highlight-fo.xsl similarity index 100% rename from docs/resources/xsl/highlight-fo.xsl rename to docs/src/docbkx/resources/xsl/highlight-fo.xsl diff --git a/docs/resources/xsl/highlight.xsl b/docs/src/docbkx/resources/xsl/highlight.xsl similarity index 100% rename from docs/resources/xsl/highlight.xsl rename to docs/src/docbkx/resources/xsl/highlight.xsl diff --git a/docs/resources/xsl/html.xsl b/docs/src/docbkx/resources/xsl/html.xsl similarity index 100% rename from docs/resources/xsl/html.xsl rename to docs/src/docbkx/resources/xsl/html.xsl diff --git a/docs/resources/xsl/html_chunk.xsl b/docs/src/docbkx/resources/xsl/html_chunk.xsl similarity index 100% rename from docs/resources/xsl/html_chunk.xsl rename to docs/src/docbkx/resources/xsl/html_chunk.xsl