Skip to content

HTTPS clone URL

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
<html>
<head>
<link rel="shortcut icon" href=images/pluto-symbol.jpg type="image/x-icon" />
<title>
The Pluton Framework: Java Service API
</title>
</head>
<body>
<center>
<a href=index.html>
<img height=100 src=images/pluto-charon.jpg ALT="[Pluto Charon Image]">
</a>
</center>
<h2 align=center>The Pluton Framework: Java Service API</h2>
<h3>Table of Contents</h3>
<ol>
<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>com.yahoo.pluton.Service</code></a>
</ol>
<a name=Introduction>
<h3>Introduction</h3>
The Java API is a thin wrapper around a
<a href=http://en.wikipedia.org/wiki/Java_Native_Interface>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.
<p>
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.
<p>
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.
<p>
<table border=1 width="75%">
<td>
<pre>
01: import com.yahoo.pluton.Service;
02:
03: class testService0 {
04: public static void main(String[] args) throws Throwable {
05:
06: com.yahoo.pluton.Service s = new com.yahoo.pluton.Service("test service");
07: s.initialize();
08: while (s.getRequest()) {
09: byte[] r = s.getRequestDataBytes();
10: s.sendResponseBytes(r);
11: }
12: s.terminate();
13: }
14: }
</pre>
</table>
<p>
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>.
<p>
Line <code>06:</code> shows the construction of
a <code>com.yahoo.pluton.Service</code> object which corresponds to the
C++
<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:
<pre>
import com.yahoo.pluton.Service;
</pre>
<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:
<pre>
javac -classpath /usr/local/lib/jars/pluton.jar yourProgram.java
</pre>
<p>
and similarly to run your class:
<pre>
java -classpath /usr/local/lib/jars/pluton.jar:. yourClass
</pre>
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>
<h3>com.yahoo.pluton.Service</h3>
<p>
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:
<ul>
<li>where
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.
</ul>
<p>
<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>
<td></tr>
<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>
<td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#getRequest>boolean getRequest()</a><td>Yes<td>
<td></tr>
<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
<td></tr>
<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
<td></tr>
<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
<td></tr>
<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
<td>Exception</tr>
<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
<td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#getServiceApplication>String getServiceApplication()</a><td>No<td>
No parameter is passed to this routine
<td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#getServiceFunction>String getServiceFunction()</a><td>No<td>
No parameter is passed to this routine
<td></tr>
<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>
<td></tr>
<tr valign=top><th align=left><a href=serviceAPI.html#getClientName>String getClientName()</a><td>No<td>
No parameter is passed to this routine
<td></tr>
<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
<td></tr>
</table>
<p>
<hr>
<font size=-1>
$Id: javaServiceAPI.html 260483 2009-10-16 18:47:56Z markd $
&copy; Copyright Yahoo! Inc, 2008, 2009
</font>
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.