+ move docs into a different folder

+ added more docs on serialization

docs/reference/serialization.xml

@@ -1,20 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-<chapter id="Serialization">
-  <title>Bootstrapping GemFire through the Spring container</title>
-
-	<para>
-	</para>
-
-	<section id="serialization:wiring">
-		<title>Wiring deserialized instances</title>
-		<para></para>
-	</section>
-
-	<section id="serialization:instance-generator">
-		<title>Auto-generating custom <classname>Instantiator</classname>s</title>
-		<para></para>
-	</section>
-	
-</chapter>

docs/src/docbkx/index.xml

@@ -38,9 +38,11 @@
 
       <xi:include href="reference/introduction.xml"/>
       <xi:include href="reference/bootstrap.xml"/>
-      <xi:include href="reference/serialization.xml"/>
       <xi:include href="reference/data.xml"/>
+      <xi:include href="reference/serialization.xml"/>
+      <!--
       <xi:include href="reference/test.xml"/>
+      -->
   </part>
   <part id="resources">
       <title>Other Resources</title>

docs/src/docbkx/reference/bootstrap.xml

@@ -30,7 +30,7 @@
 		the user can pass in a GemFire configuration:</para>
 		
 		<programlisting language="xml"><![CDATA[<bean id="cache-with-xml" class="org.springframework.data.gemfire.CacheFactoryBean">
-	<property name="cacheXml" value="classpath:cache.xml"/>
+    <property name="cacheXml" value="classpath:cache.xml"/>
 </bean>]]></programlisting>
 		
 		<para>In this example, if the cache needs to be created, it will use the file named <literal>cache.xml</literal> located in the classpath root. Note that
@@ -42,11 +42,11 @@
 		</para>
 
 		<programlisting language="xml"><![CDATA[<bean id="cache-with-props" class="org.springframework.data.gemfire.CacheFactoryBean">
-	<property name="properties">
-		<props>
-			<prop key="bind-address">127.0.0.1</prop>
-		</props>
-	</property>
+    <property name="properties">
+        <props>
+           <prop key="bind-address">127.0.0.1</prop>
+        </props>
+    </property>
 </bean>]]></programlisting>
 		 
 		<para>So far our examples relied on the primary Spring names (<literal>beans</literal>). 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">
 	
 	<bean id="cache-with-props" class="org.springframework.data.gemfire.CacheFactoryBean">
-		<property name="properties">
-			<util:properties location="classpath:/deployment/env.properties"/>
-		</property>
+	    <property name="properties">
+	        <util:properties location="classpath:/deployment/env.properties"/>
+	    </property>
 	</bean>	
 </beans>]]></programlisting>
 		
@@ -84,7 +84,7 @@
 
 		<programlisting language="xml"><![CDATA[<bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean">
 	<property name="cache">
-		<bean class="org.springframework.data.gemfire.CacheFactoryBean"/>
+	    <bean class="org.springframework.data.gemfire.CacheFactoryBean"/>
 	</property>
 	<property name="name" value="basic"/>
 </bean>]]></programlisting>
@@ -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">
 	
-	<!-- shared cache across regions -->
-	<bean id="cache" class="org.springframework.data.gemfire.CacheFactoryBean"/>
+    <!-- shared cache across regions -->
+    <bean id="cache" class="org.springframework.data.gemfire.CacheFactoryBean"/>
 	
-	<!-- region named 'basic' -->
-	<bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"/>
+    <!-- region named 'basic' -->
+    <bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"/>
 
-	<!-- region with a name different then the bean definition -->
-	<bean id="root-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache" p:name="default-region"/>
+    <!-- region with a name different then the bean definition -->
+    <bean id="root-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache" p:name="default-region"/>
 </beans>]]></programlisting>
 		
 		<para>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

docs/src/docbkx/reference/data.xml

@@ -32,7 +32,7 @@
 		<para>For Gemfire, SGI provides a dedicated, per-cache, transaction manager that once declared, allows actions on the <interfacename>Region</interfacename>s to be grouped and executed atomically through
 		Spring:</para>
 		
-		<programlisting><![CDATA[<bean id="transaction-manager" class="org.springframework.data.gemfire.GemfireTransactionManager" p:cache-ref="cache"/>]]></programlisting>
+		<programlisting language="xml"><![CDATA[<bean id="transaction-manager" class="org.springframework.data.gemfire.GemfireTransactionManager" p:cache-ref="cache"/>]]></programlisting>
 		
 		<para>Note that currently GemFire supports optimistic transactions with <emphasis>read committed</emphasis> isolation. Further more to guarantee this isolation, developers should
 		avoid making <emphasis>in-place</emphasis> 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 @@
 	<section id="apis:declarable">
 		<title>Wiring <interfacename>Declarable</interfacename> components</title>
 		
-		<para>GemFire XML configuration (usually named <literal>cache.xml</literal> allows <emphasis>user</emphasis> objects to be declared as part of the fabric config. Usually these objects
-		are <interfacename>CacheLoader</interfacename>s or other pluggable components into GemFire. Out of the box, each such type declared through XML must implement the <interfacename>Declarable</interfacename> 
-		interface which allows arbitrary parameters to be passed to the declared class through a <classname>Properties</classname> instance.</para>
-		
 		<sidebar>
 			<title>Eliminate <interfacename>Declarable</interfacename> components</title>
 			<para>One can configure custom types entirely inside through Spring as mentioned in <xref linkend="bootstrap:region"/>. That way, one does not have to implement the
 			<interfacename>Declarable</interfacename> 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).</para>
 		</sidebar>
+
+		<para>GemFire XML configuration (usually named <literal>cache.xml</literal> allows <emphasis>user</emphasis> objects to be declared as part of the fabric config. Usually these objects
+		are <interfacename>CacheLoader</interfacename>s or other pluggable components into GemFire. Out of the box, each such type declared through XML must implement the <interfacename>Declarable</interfacename> 
+		interface which allows arbitrary parameters to be passed to the declared class through a <classname>Properties</classname> instance.</para>
 		
 		<para>Consider the following declaration (taken from the <interfacename>Declarable</interfacename> javadoc):</para>
 		
@@ -65,8 +65,9 @@
 </cache-loader>]]></programlisting>
 
 		<para>To simplify the task of parsing, converting the parameters and initializing the object, SGI offers a base class (<classname>WiringDeclarableSupport</classname>) 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 
-		<classname>WiringDeclarableSupport</classname> which automatically locates the declaring <interfacename>BeanFactory</interfacename> and performs wiring as part of the initialization process.
+		user objects to be wired through a <emphasis>template</emphasis> 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 <classname>WiringDeclarableSupport</classname> which automatically locates the declaring <interfacename>BeanFactory</interfacename> and performs wiring as
+		part of the initialization process.
 		</para>
 		
 		<sidebar>
@@ -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)</para>
 		</sidebar>
 		
+		<section id="apis:declarable:template-wiring">
+			<title>Using <emphasis>template</emphasis> definitions</title>
+			
+			<para>When used <classname>WiringDeclarableSupport</classname> 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 <classname>DBLoader</classname> declaration would look in that case:</para>
+			
+			<programlisting language="java" ><![CDATA[public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
+	private DataSource dataSource;
+	
+	public void setDataSource(DataSource ds){
+		this.dataSource = ds;
+	}
+	
+	public Object load(LoaderHelper helper) { ... }
+}]]></programlisting>
+			
+			<programlisting language="xml"><![CDATA[<cache-loader>
+   <class-name>com.company.app.DBLoader</class-name>
+   <!-- no parameter is passed (use the bean implicit name
+   		that is the class name) -->
+</cache-loader>]]></programlisting>
+			
+			<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       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">
+
+	 <bean id="dataSource" ... />
+	             
+     <!-- template bean definition -->
+     <bean id="com.company.app.DBLoader" abstract="true" p:dataSource-ref="dataSource"/>
+</beans>]]></programlisting>
+					
+			<para>In the scenario above, as no parameter was specified, a bean with id/name <literal>com.company.app.DBLoader</literal> 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 <literal>bean-name</literal> parameter
+			in the GemFire configuration:</para>
+			
+					<programlisting language="xml"><![CDATA[<cache-loader>
+   <class-name>com.company.app.DBLoader</class-name>
+   <!-- pass the bean definition template name
+        as parameter -->
+   <parameter name="bean-name">
+     <string>template-bean</string>
+   </parameter>
+</cache-loader>]]></programlisting>
+			
+			<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       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">
+
+	 <bean id="dataSource" ... />
+	             
+     <!-- template bean definition -->   
+     <bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/>
+     
+</beans>]]></programlisting>
+
+			<note><para>The <emphasis>template</emphasis> bean definitions do not have to be declared in XML - any format is allowed (Groovy, annotations, etc..).</para></note>
+
+		</section>
+
 		<section id="apis:declarable:autowiring">
 			<title>Using Auto/Annotation-wiring</title>
 			
-			<para>If no parameters are given, <classname>WiringDeclarableSupport</classname> will <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-autowire">autowire</ulink>
-			the declaring instance. In short, this means that unless any <emphasis>metadata</emphasis> 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
+			<para>If no bean definition is found, by default, <classname>WiringDeclarableSupport</classname> will 
+			<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-autowire">autowire</ulink>
+			the declaring instance. In short, this means that unless any <emphasis>metadata</emphasis> 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
 			<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-annotation-config">chapter</ulink> in the Spring documentation for more information
 			on the supported annotations and enabling factors.
 			</para>
@@ -99,8 +169,7 @@
    <class-name>com.company.app.DBLoader</class-name>
    <!-- no need to declare any parameters anymore
         since the class is auto-wired -->
-</cache-loader>]]>
-			</programlisting>
+</cache-loader>]]></programlisting>
 			
 			<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <beans xmlns="http://www.springframework.org/schema/beans"
@@ -114,57 +183,12 @@
      <!-- enable annotation processing -->   
      <context:annotation-config/>
      
-</beans>]]>
-			</programlisting>
+</beans>]]></programlisting>
 			
 			<para>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 <interfacename>DataSource</interfacename> 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 <classname>DBLoader</classname> code.</para>
 		</section>
 		
-		<section id="apis:declarable:template-wiring">
-			<title>Using <emphasis>template</emphasis> definitions</title>
-			
-			<para>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
-			<classname>DBLoader</classname> declaration would look in that case:</para>
-			
-			<programlisting language="java" ><![CDATA[public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
-	private DataSource dataSource;
-	
-	public void setDataSource(DataSource ds){
-		this.dataSource = ds;
-	}
-	
-	public Object load(LoaderHelper helper) { ... }
-}]]></programlisting>
-					
-			<programlisting language="xml"><![CDATA[<cache-loader>
-   <class-name>com.company.app.DBLoader</class-name>
-   <!-- pass the bean definition template name
-        as parameter -->
-   <parameter name="bean-name">
-     <string>template-bean</string>
-   </parameter>
-</cache-loader>]]>
-			</programlisting>
-			
-			<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<beans xmlns="http://www.springframework.org/schema/beans"
-       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       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">
-
-	 <bean id="dataSource" ... />
-	             
-     <!-- template bean definition -->   
-     <bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/>
-     
-</beans>]]>
-			</programlisting>
-			
-			<note><para>The <emphasis>template</emphasis> bean definitions do not have to be declared in XML - any format is allowed (Groovy, annotations, etc..).</para></note>		
-		</section>
-		
 	</section>
 </chapter>

docs/src/docbkx/reference/introduction.xml

@@ -4,14 +4,14 @@
    <para>This part of the reference documentation explains the core functionality
    offered by Spring GemFire integration.</para>
 
-   <para><xref linkend="bootstrapping"/> describes the configuration support provided for
+   <para><xref linkend="bootstrap"/> describes the configuration support provided for
    bootstrapping, initializing and accessing a GemFire cache or region.</para>
    
    <para><xref linkend="serialization"/> describes the enhancements for GemFire 
-   (de)serialization process and managment of associated objects.
+   (de)serialization process and management of associated objects.
    </para>
 
-   <para><xref linkend="data"/> explains the integration between GemFire API and
+   <para><xref linkend="apis"/> explains the integration between GemFire API and
    the various "data" features available in Spring, such as transaction management
    and exception translation.
    </para>

docs/src/docbkx/reference/serialization.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="serialization">
+  <title>Working with GemFire Serialization</title>
+
+	<para>
+	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 <ulink url="http://community.gemstone.com/display/gemfire/Interoperability">platforms</ulink> (such as 
+	<ulink url="http://community.gemstone.com/display/gemfire/Serialization+in+Java">Java</ulink>, 
+	<ulink url="http://community.gemstone.com/display/gemfire/Serialization+in+.NET">.NET</ulink> and C++). 
+	This chapter discusses the various ways in which SGI simplifies and improves GemFire custom serialization in Java.
+	</para>
+
+	<section id="serialization:wiring">
+		<title>Wiring deserialized instances</title>
+		
+		<para>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 
+		<ulink url="http://www.gemstone.com/docs/6.0.1/product/docs/japi/com/gemstone/gemfire/Instantiator.html"><classname>Instantiator</classname></ulink> that performs 
+		wiring for each new instance created by GemFire during deserialization.</para>
+		
+		<para>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 <emphasis>rich domain objects</emphasis> in a transparent manner (Spring users might find this approach similar to that of 
+		<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/aop.html#aop-atconfigurable"><literal>@Configurable</literal></ulink>). 
+		The <classname>WiringInstantiator</classname> works just like <classname>WiringDeclarableSupport</classname>, trying to first locate a bean definition as a wiring template
+		and following to autowiring otherwise. Please refer to the previous section (<link linkend="apis:declarable"/>)	for more details on wiring functionality.</para>
+		
+		<para>To use this <classname>Instantiator</classname>, simply declare it as a usual bean:</para>
+		
+		<programlisting language="xml"><![CDATA[<bean id="instantiator" class="org.springframework.data.gemfire.serialization.WiringInstantiator">
+	<!-- DataSerializable type -->
+	<constructor-arg>org.pkg.SomeDataSerializableClass</constructor-arg>
+	<!-- type id -->
+	<constructor-arg>95</constructor-arg>
+</bean>]]></programlisting>
+		
+		<para>During the container startup, once it is being initialized, the <literal>instantiator</literal> will, by default, register itself with the GemFire system and perform
+		wiring on all instances of <classname>SomeDataSerializableClass</classname> created by GemFire during deserialization.</para>
+	</section>
+
+	<section id="serialization:instance-generator">
+		<title>Auto-generating custom <classname>Instantiator</classname>s</title>
+		<para>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 <classname>Instatiator</classname> classes which instantiate a new type (using the default constructor) without the use of reflection:</para>
+		
+		<programlisting language="xml"><![CDATA[<bean id="instantiator-factory" class="org.springframework.data.gemfire.serialization.InstantiatorFactoryBean">
+	<property name="customTypes">
+		<map>
+			<entry key="org.pkg.CustomTypeA" value="1025"/>
+			<entry key="org.pkg.CustomTypeB" value="1026"/>
+		</map>
+	</property>
+</bean>]]></programlisting>
+
+		<para>The definition above, automatically generated two <classname>Instantiator</classname>s for two classes, namely <classname>CustomTypeA</classname> and <classname>CustomTypeB</classname>
+		and registers them with GemFire, under user id <literal>1025</literal> and <literal>1026</literal>. The two instantiators avoid the use of reflection and create the instances directly
+		through Java code.</para>
+	</section>
+</chapter>