src/site/xdoc/server.xml - directmemory - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>

 <!--
   ~ Licensed to the Apache Software Foundation (ASF) under one
   ~ or more contributor license agreements.  See the NOTICE file
   ~ distributed with this work for additional information
   ~ regarding copyright ownership.  The ASF licenses this file
   ~ to you under the Apache License, Version 2.0 (the
   ~ "License"); you may not use this file except in compliance
   ~ with the License.  You may obtain a copy of the License at
   ~
   ~  http://www.apache.org/licenses/LICENSE-2.0
   ~
   ~ Unless required by applicable law or agreed to in writing,
   ~ software distributed under the License is distributed on an
   ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   ~ KIND, either express or implied.  See the License for the
   ~ specific language governing permissions and limitations
   ~ under the License.
   -->
 <document>
   <properties>
     <title>Apache DirectMemory Server Side</title>
     <author>Olivier Lamy</author>
   </properties>
   <body>
     <macro name="toc">

     </macro>
     <section name="DirectMemory Server">
       <p>Apache DirectMemory has a server implementation (a servlet) to provide you a way to store your project remotely and to share those cached objects with various applications.</p>
       <p>Server side and client side (Java only) are provided.</p>
       <p>The exchange are based on http(s) exchange with the following implementations/format:
         <ul>
           <li>JSON format</li>
           <li>"binary" format: parameters are send via http headers</li>
           <li>text/plain format: you can send a text value(json object, xml etc..), the server will serialize the content and store it for you.</li>
         </ul>
       </p>
     </section>
     <section name="Exchange formats">
       <p>We simply use HTTP method names to resolve the action to proceed and depends on the Accept or Content-Type headers the format will be different :
         <ul>
           <li>GET to retrieve content ${webPath}/${key}</li>
           <li>DELETE to delete content ${webPath}/${key}</li>
           <li>PUT/POST to add some content in cache ${webPath}/${key}</li>
         </ul>
       </p>
       <subsection name="HTTP Methods">
         <subsection name="PUT/POST">
           <p>
             PUT/POST are used for adding/updating content in cache.<br/>
             Note: if the content was not put in cache, you will receive a 204 (Not Content)
           </p>
         </subsection>
         <subsection name="GET">
           <p>
             GET is used to retrieve content from the cache.<br/>
             <b>If not content is found for the key, you will receive the http code 204 (No content)</b>
           </p>
         </subsection>
         <subsection name="DELETE">
           <p>
             DELETE is used to removed content from cache<br/>
             Note: if the entry was not available in the server you will receive a 204 (Not Content)
           </p>
         </subsection>
       </subsection>
       <subsection name="Http Headers">
         <p>see various exchange type for dedicated http headers</p>
         <p>
          Common http headers:
           <ul>
             <li>X-DirectMemory-SerializeSize: returns bytes number stored on server side.</li>
           </ul>
         </p>
       </subsection>
     </section>
     <section name="JSON Exchange">
       <subsection name="JSON PUT Content">
         <p>
           JSON Request to put content in cache Content-Type: application/json
           <source>
   {"expiresIn":123,
     "cacheContent":"rO0ABXNydmEvbGFuZy9TdHJpbmc7eHB0AAhCb3JkZWF1eA=="}
           </source>
           To put this content in DirectMemory Cache Server, just use a PUT request on path ${webPath}/DirectMemoryServlet/${key}.<br/>
         </p>
       </subsection>
       <subsection name="JSON GET Content">
         <p>Use a GET request on ${webPath}/DirectMemoryServlet/${key} and you will receive the JSON response:
           <source>
             {"key":"foo","cacheContent":"Zm9vIGJhcg=="}
           </source>
         </p>
       </subsection>
       <subsection name="JSON DELETE Content">
         <p>Use a DELETE request on ${webPath}/DirectMemoryServlet/${key}.</p>
       </subsection>
     </section>
     <section name="Binary Exchange">
       <subsection name="Binary PUT Content">
         <p>
           PUT Request to put content in cache Content-Type: application/x-java-serialized-object.<br/>
           To put this content in DirectMemory Cache Server, just use a PUT request on path ${webPath}/DirectMemoryServlet/${key}.<br/>
           ExpiresIn value can be set with http header: X-DirectMemory-ExpiresIn<br/>
           The http request body will contains the serialized object value.<br/>
         </p>
       </subsection>
       <subsection name="Binary GET Content">
         <p>
           Use a GET request on ${webPath}/DirectMemoryServlet/${key} and you will receive the binary form of the object.
         </p>
       </subsection>
       <subsection name="Binary DELETE Content">
         <p>Use a DELETE request on ${webPath}/DirectMemoryServlet/${key}.</p>
       </subsection>
     </section>
     <section name="text/plain Exchange">
       <subsection name="text/plain PUT Content">
         <p>
           PUT Request to put content in cache <code>Content-Type: text/plain.</code><br/>
           To put this content in DirectMemory Cache Server, just use a PUT request on path ${webPath}/DirectMemoryServlet/${key}.<br/>
           ExpiresIn value can be set with http header: X-DirectMemory-ExpiresIn<br/>
           The http request body will contains a String value which will be serialized on server side and stored in directMemory.<br/>
           You can specify the Serializer to use with the http header: "X-DirectMemory-Serializer" (must contains the full class name).<br/>
         </p>
       </subsection>
       <subsection name="text/plain GET Content">
         <p>
           Use a GET request on ${webPath}/DirectMemoryServlet/${key} and you will receive the stored String.
         </p>
       </subsection>
       <subsection name="text/plain DELETE Content">
         <p>Use a DELETE request on ${webPath}/DirectMemoryServlet/${key}.</p>
       </subsection>
     </section>

     <section name="Java Client API">
       <subsection name="Client Configuration">
         <p>Before using the client api, you must configure it using the following pattern:
           <macro name="snippet">
             <param name="id" value="client-configuration"/>
             <param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
           </macro>
           Here you have a configured client. Have a look at DirectMemoryServerClientConfiguration javadoc for advanced options.
         </p>
       </subsection>
       <subsection name="PUT Content">
         <p>
         With the Java client is something like:
           <macro name="snippet">
             <param name="id" value="client-put"/>
             <param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
           </macro>
       </p>
       </subsection>
       <subsection name="GET Content">
         <p>With the Java api:
           <macro name="snippet">
             <param name="id" value="client-get"/>
             <param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
           </macro>
           You must check the method (response.isFound()) if true retrieve the object with: Wine wine = response.getResponse();
         </p>
       </subsection>
       <subsection name="DELETE Content">
         <p>With the Java api:
           <macro name="snippet">
             <param name="id" value="client-delete"/>
             <param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
           </macro>
         </p>
       </subsection>
     </section>
   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>

	<!--
	~ Licensed to the Apache Software Foundation (ASF) under one
	~ or more contributor license agreements. See the NOTICE file
	~ distributed with this work for additional information
	~ regarding copyright ownership. The ASF licenses this file
	~ to you under the Apache License, Version 2.0 (the
	~ "License"); you may not use this file except in compliance
	~ with the License. You may obtain a copy of the License at
	~
	~ http://www.apache.org/licenses/LICENSE-2.0
	~
	~ Unless required by applicable law or agreed to in writing,
	~ software distributed under the License is distributed on an
	~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	~ KIND, either express or implied. See the License for the
	~ specific language governing permissions and limitations
	~ under the License.
	-->
	<document>
	<properties>
	<title>Apache DirectMemory Server Side</title>
	<author>Olivier Lamy</author>
	</properties>
	<body>
	<macro name="toc">

	</macro>
	<section name="DirectMemory Server">
	<p>Apache DirectMemory has a server implementation (a servlet) to provide you a way to store your project remotely and to share those cached objects with various applications.</p>
	<p>Server side and client side (Java only) are provided.</p>
	<p>The exchange are based on http(s) exchange with the following implementations/format:
	<ul>
	<li>JSON format</li>
	<li>"binary" format: parameters are send via http headers</li>
	<li>text/plain format: you can send a text value(json object, xml etc..), the server will serialize the content and store it for you.</li>
	</ul>
	</p>
	</section>
	<section name="Exchange formats">
	<p>We simply use HTTP method names to resolve the action to proceed and depends on the Accept or Content-Type headers the format will be different :
	<ul>
	<li>GET to retrieve content ${webPath}/${key}</li>
	<li>DELETE to delete content ${webPath}/${key}</li>
	<li>PUT/POST to add some content in cache ${webPath}/${key}</li>
	</ul>
	</p>
	<subsection name="HTTP Methods">
	<subsection name="PUT/POST">
	<p>
	PUT/POST are used for adding/updating content in cache.<br/>
	Note: if the content was not put in cache, you will receive a 204 (Not Content)
	</p>
	</subsection>
	<subsection name="GET">
	<p>
	GET is used to retrieve content from the cache.<br/>
	<b>If not content is found for the key, you will receive the http code 204 (No content)</b>
	</p>
	</subsection>
	<subsection name="DELETE">
	<p>
	DELETE is used to removed content from cache<br/>
	Note: if the entry was not available in the server you will receive a 204 (Not Content)
	</p>
	</subsection>
	</subsection>
	<subsection name="Http Headers">
	<p>see various exchange type for dedicated http headers</p>
	<p>
	Common http headers:
	<ul>
	<li>X-DirectMemory-SerializeSize: returns bytes number stored on server side.</li>
	</ul>
	</p>
	</subsection>
	</section>
	<section name="JSON Exchange">
	<subsection name="JSON PUT Content">
	<p>
	JSON Request to put content in cache Content-Type: application/json
	<source>
	{"expiresIn":123,
	"cacheContent":"rO0ABXNydmEvbGFuZy9TdHJpbmc7eHB0AAhCb3JkZWF1eA=="}
	</source>
	To put this content in DirectMemory Cache Server, just use a PUT request on path ${webPath}/DirectMemoryServlet/${key}.<br/>
	</p>
	</subsection>
	<subsection name="JSON GET Content">
	<p>Use a GET request on ${webPath}/DirectMemoryServlet/${key} and you will receive the JSON response:
	<source>
	{"key":"foo","cacheContent":"Zm9vIGJhcg=="}
	</source>
	</p>
	</subsection>
	<subsection name="JSON DELETE Content">
	<p>Use a DELETE request on ${webPath}/DirectMemoryServlet/${key}.</p>
	</subsection>
	</section>
	<section name="Binary Exchange">
	<subsection name="Binary PUT Content">
	<p>
	PUT Request to put content in cache Content-Type: application/x-java-serialized-object.<br/>
	To put this content in DirectMemory Cache Server, just use a PUT request on path ${webPath}/DirectMemoryServlet/${key}.<br/>
	ExpiresIn value can be set with http header: X-DirectMemory-ExpiresIn<br/>
	The http request body will contains the serialized object value.<br/>
	</p>
	</subsection>
	<subsection name="Binary GET Content">
	<p>
	Use a GET request on ${webPath}/DirectMemoryServlet/${key} and you will receive the binary form of the object.
	</p>
	</subsection>
	<subsection name="Binary DELETE Content">
	<p>Use a DELETE request on ${webPath}/DirectMemoryServlet/${key}.</p>
	</subsection>
	</section>
	<section name="text/plain Exchange">
	<subsection name="text/plain PUT Content">
	<p>
	PUT Request to put content in cache <code>Content-Type: text/plain.</code><br/>
	To put this content in DirectMemory Cache Server, just use a PUT request on path ${webPath}/DirectMemoryServlet/${key}.<br/>
	ExpiresIn value can be set with http header: X-DirectMemory-ExpiresIn<br/>
	The http request body will contains a String value which will be serialized on server side and stored in directMemory.<br/>
	You can specify the Serializer to use with the http header: "X-DirectMemory-Serializer" (must contains the full class name).<br/>
	</p>
	</subsection>
	<subsection name="text/plain GET Content">
	<p>
	Use a GET request on ${webPath}/DirectMemoryServlet/${key} and you will receive the stored String.
	</p>
	</subsection>
	<subsection name="text/plain DELETE Content">
	<p>Use a DELETE request on ${webPath}/DirectMemoryServlet/${key}.</p>
	</subsection>
	</section>

	<section name="Java Client API">
	<subsection name="Client Configuration">
	<p>Before using the client api, you must configure it using the following pattern:
	<macro name="snippet">
	<param name="id" value="client-configuration"/>
	<param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
	</macro>
	Here you have a configured client. Have a look at DirectMemoryServerClientConfiguration javadoc for advanced options.
	</p>
	</subsection>
	<subsection name="PUT Content">
	<p>
	With the Java client is something like:
	<macro name="snippet">
	<param name="id" value="client-put"/>
	<param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
	</macro>
	</p>
	</subsection>
	<subsection name="GET Content">
	<p>With the Java api:
	<macro name="snippet">
	<param name="id" value="client-get"/>
	<param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
	</macro>
	You must check the method (response.isFound()) if true retrieve the object with: Wine wine = response.getResponse();
	</p>
	</subsection>
	<subsection name="DELETE Content">
	<p>With the Java api:
	<macro name="snippet">
	<param name="id" value="client-delete"/>
	<param name="url" value="http://svn.apache.org/repos/asf/directmemory/trunk/server/directmemory-server/src/test/java/org/apache/directmemory/server/services/AbstractServletWithClientTest.java"/>
	</macro>
	</p>
	</subsection>
	</section>
	</body>
	</document>