Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 82bbab17c0
Fetching contributors…

Cannot retrieve contributors at this time

231 lines (175 sloc) 7.829 kb
<link rel="shortcut icon" href=images/pluto-symbol.jpg type="image/x-icon" />
The Pluton Framework: Java Service API
<a href=index.html>
<img height=100 src=images/pluto-charon.jpg ALT="[Pluto Charon Image]">
<h2 align=center>The Pluton Framework: Java Service API</h2>
<h3>Table of Contents</h3>
<li><a href=#Introduction>Introduction</a>
<li><a href=#threads>A note about thread-safety</a>
<li><a href=#Sample>Sample Program</a>
<li><a href=#import><code>import</code> requirements</a>
<li><a href=#classpath><code>classpath</code> settings</a>
<li><a href=#Service><code></code></a>
<a name=Introduction>
The Java API is a thin wrapper around a
<a href=>JNI</a>
interface to the core C++ pluton library.
The Java API is semantically identical to its C++ counterparts; the
main differences being syntactic variations that better match the Java
programming model.
This document highlights the differences between the C++ API and the
Java API. For a complete description of the semantics please refer to the
C++ <a href=serviceAPI.html>service</a> APIs.
<a name=threads>
<h3>A note about thread-safety</h3>
Unlike the client library for Java, the pluton service library is <b>not</b> thread-safe
and <b>not</b> reentrant. This is on purpose. The reason being that the whole request exchange
mechanism of pluton is purposely designed to have a single request at a time presented to a service
instance. If multiple threads called any of the service methods simultaneously it is possible that
different responses will go to different clients.
This is not to say that the Java service program cannot use threads, just that access to the pluton
exchange <b>must</b> only occur with one thread and be completely serial. There is nothing stopping
the service from running multiple threads to process the request data if that makes sense.
<a name=Sample>
<h3>Sample Program</h3>
This sample Java client demonstrates accepting a request and returning
a response.
<table border=1 width="75%">
01: import;
03: class testService0 {
04: public static void main(String[] args) throws Throwable {
06: s = new"test service");
07: s.initialize();
08: while (s.getRequest()) {
09: byte[] r = s.getRequestDataBytes();
10: s.sendResponseBytes(r);
11: }
12: s.terminate();
13: }
14: }
Those familiar with the C++ API will recognize the
interfaces and programming model. Unique to Java is the <code>import</code> at
lines <code>01:</code>.
Line <code>06:</code> shows the construction of
a <code></code> object which corresponds to the
<a href=serviceAPI.html#construct><code>pluton::service</code></a>
and lines <code>08:</code> to <code>10:</code> the typical service loop getting requests
and sending responses.
<a name=import>
<h3><code>import</code> requirements</h3>
All Java service programs should identify their dependency with:
<a name=classpath>
<h3><code>classpath</code> settings</h3>
The Java pluton classes are bundled in a <code>jar</code> which is
normally installed at <code>/usr/local/lib/jars/pluton.jar</code>.
To compile your program, add the jar path to
your <code>-classpath</code> option, ie:
javac -classpath /usr/local/lib/jars/pluton.jar
and similarly to run your class:
java -classpath /usr/local/lib/jars/pluton.jar:. yourClass
The <code>:.</code> at the end of the <code>classpath</code> parameter
tells the <code>java</code> command knows where to search for your
class file.
<a name=Service>
This table lists the available Java <a href=serviceAPI.html><code>pluton::service</code></a>
APIs and highlights any differences that exist between them and their C++ counterparts. In general:
the C++ interface uses <code>std::string</code> the Java interface
uses <code>String</code>
<li>Error returns have been converted to
exceptions to match the programming model expected by Java programmers
<li>the return
type is <code>void</code> unless indicated otherwise.
<table border=1>
<tr valign=top><th align=left>Java Method<th align=left>Same as C++<th align=left>Comments<th>Exceptions Thrown</tr>
<tr valign=top><th nowrap align=left><a href=serviceAPI.html#construct>Service()</a><td>Yes<td><td></tr>
<tr valign=top><th nowrap align=left><a href=serviceAPI.html#construct>Service(String name)</a><td>Yes<td><td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#getAPIVersion>String getAPIVersion()</a><td>Yes<td><td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#initialize>boolean initialize()</a><td>Yes<td><td>Exception</tr>
<tr valign=top><th align=left><a href=serviceAPI.html#hasFault>boolean hasFault()</a><td>Yes<td><td></tr>
<tr valign=top><th align=left>int getFaultCode()<td>No<td>
Equivalent to <code><a href=fault.html#getFaultCode>pluton::client().getFault::getFaultCode()</code></a>
<tr valign=top><th align=left>String getFaultMessage(String prefix, boolean format)<td>No<td>
Equivalent to <code><a href=fault.html#getMessage>pluton::client().getFault::getMessage()</code></a>
<tr valign=top><th align=left><a href=serviceAPI.html#getRequest>boolean getRequest()</a><td>Yes<td>
<tr valign=top><th align=left><a href=serviceAPI.html#getRequestData>String getRequestData()</a><td>Variant<td>
Request data is converted using the platform's default charset
<tr valign=top><th align=left><a href=serviceAPI.html#getRequestData>byte[] getRequestDataBytes()</a><td>Variant<td>
Request data is transferred "as-is" into the byte array
<tr valign=top><th align=left><a href=serviceAPI.html#sendResponse>sendResponse(String)</a><td>Variant<td>
String is converted to UTF-8 when transferred to the client
<tr valign=top><th align=left><a href=serviceAPI.html#sendResponse>sendResponseBytes(byte[])</a><td>Variant<td>
String is transferred "as-is" to the client
<tr valign=top><th align=left><a href=serviceAPI.html#sendFault>sendFault(int, String)</a><td>Yes<td><td>Exception</tr>
<tr valign=top><th align=left><a href=serviceAPI.html#terminate>terminate()</a><td>Yes<td><td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#getServiceKey>String getServiceKey()</a><td>No<td>
No parameter is passed to this routine
<tr valign=top><th align=left><a href=serviceAPI.html#getServiceApplication>String getServiceApplication()</a><td>No<td>
No parameter is passed to this routine
<tr valign=top><th align=left><a href=serviceAPI.html#getServiceFunction>String getServiceFunction()</a><td>No<td>
No parameter is passed to this routine
<tr valign=top><th align=left><a href=serviceAPI.html#getServiceVersion>int getServiceVersion()</a><td>Yes<td><td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#getSerializationType>String getSerializationType()</a><td>Yes<td>
<tr valign=top><th align=left><a href=serviceAPI.html#getClientName>String getClientName()</a><td>No<td>
No parameter is passed to this routine
<tr valign=top><th align=left><a href=serviceAPI.html#getContext>String getContext(String key)</a><td>No<td>
Context value is returned as the return value
<font size=-1>
$Id: javaServiceAPI.html 260483 2009-10-16 18:47:56Z markd $
&copy; Copyright Yahoo! Inc, 2008, 2009
Jump to Line
Something went wrong with that request. Please try again.