blob: e0c77f798e8d317ab20fce3dda9074b26223ca2d [file] [log] [blame]
<?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>