From fa950ee38dea4b58f0c2b59a3e9ff76e9ee33ab5 Mon Sep 17 00:00:00 2001 From: erickson Date: Fri, 11 May 2007 22:53:43 +0000 Subject: [PATCH] added a lot of documentation git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@885 9efc2488-bf62-4759-914b-345cdb29e865 --- src/java/org/opensrf/ClientSession.java | 46 ++++++++++----- src/java/org/opensrf/Message.java | 14 ++++- src/java/org/opensrf/Method.java | 19 ++++++ src/java/org/opensrf/Request.java | 52 +++++++++++++++++ src/java/org/opensrf/Result.java | 8 +++ src/java/org/opensrf/Session.java | 12 +++- src/java/org/opensrf/Stack.java | 16 +++-- .../org/opensrf/net/xmpp/XMPPMessage.java | 58 ------------------- .../org/opensrf/net/xmpp/XMPPSession.java | 6 ++ src/java/org/opensrf/test/TestClient.java | 1 + src/java/org/opensrf/util/Config.java | 24 +++++++- src/java/org/opensrf/util/JSONException.java | 3 + src/java/org/opensrf/util/JSONReader.java | 15 +++++ src/java/org/opensrf/util/JSONWriter.java | 8 +++ src/java/org/opensrf/util/OSRFObject.java | 14 ++--- src/java/org/opensrf/util/OSRFRegistry.java | 10 +++- .../org/opensrf/util/OSRFSerializable.java | 3 + 17 files changed, 217 insertions(+), 92 deletions(-) diff --git a/src/java/org/opensrf/ClientSession.java b/src/java/org/opensrf/ClientSession.java index db44606..09cfce1 100644 --- a/src/java/org/opensrf/ClientSession.java +++ b/src/java/org/opensrf/ClientSession.java @@ -1,6 +1,8 @@ package org.opensrf; import java.util.Date; import java.util.List; +import java.util.Map; +import java.util.HashMap; import java.util.ArrayList; import java.util.Random; import java.util.Arrays; @@ -15,11 +17,21 @@ public class ClientSession extends Session { /** The remote service to communicate with */ private String service; + /** OpenSRF domain */ private String domain; + /** Router name */ private String router; + + /** + * original remote node. The current remote node will change based + * on server responses. This is used to reset the remote node to + * its original state. + */ private String origRemoteNode; + /** The next request id */ private int nextId; - private List requests; + /** The requests this session has sent */ + private Map requests; /** * Creates a new client session. Initializes the @@ -35,13 +47,13 @@ public class ClientSession extends Session { origRemoteNode = getRemoteNode(); - /* create a random thread */ + /** create a random thread */ long time = new Date().getTime(); Random rand = new Random(time); setThread(rand.nextInt()+""+rand.nextInt()+""+time); - requests = new ArrayList(); nextId = 0; + requests = new HashMap(); cacheSession(); } @@ -76,11 +88,10 @@ public class ClientSession extends Session { } - public Request request(Request req) throws SessionException { + private Request request(Request req) throws SessionException { if(getConnectState() != ConnectState.CONNECTED) resetRemoteId(); - //requests.set(req.getId(), req); - requests.add(req); + requests.put(new Integer(req.getId()), req); req.send(); return req; } @@ -95,23 +106,19 @@ public class ClientSession extends Session { /** - * Pushes a response onto the queue of the appropriate request. - * @param msg The the received RESULT Message whose payload - * contains a Result object. + * Pushes a response onto the result queue of the appropriate request. + * @param msg The received RESULT Message */ public void pushResponse(Message msg) { - Request req; - - try { - req = requests.get(msg.getId()); - } catch(IndexOutOfBoundsException e) { - /** LOG that an unexpected response arrived */ + Request req = requests.get(new Integer(msg.getId())); + if(req == null) { + /** LOG that we've received a result to a non-existant request */ return; } - OSRFObject payload = (OSRFObject) msg.get("payload"); + /** build a result and push it onto the request's result queue */ req.pushResponse( new Result( payload.getString("status"), @@ -120,5 +127,12 @@ public class ClientSession extends Session { ) ); } + + /** + * Removes a request for this session's request set + */ + public void cleanupRequest(int reqId) { + requests.remove(new Integer(reqId)); + } } diff --git a/src/java/org/opensrf/Message.java b/src/java/org/opensrf/Message.java index 35e3e59..fd8ad8c 100644 --- a/src/java/org/opensrf/Message.java +++ b/src/java/org/opensrf/Message.java @@ -4,6 +4,7 @@ import org.opensrf.util.*; public class Message implements OSRFSerializable { + /** Message types */ public static final String REQUEST = "REQUEST"; public static final String STATUS = "STATUS"; public static final String RESULT = "RESULT"; @@ -12,12 +13,12 @@ public class Message implements OSRFSerializable { /** Message ID. This number is used to relate requests to responses */ private int id; - /** String of message. */ + /** type of message. */ private String type; /** message payload */ private Object payload; - /** Go ahead and register the Message object */ + /** Create a registry for the osrfMessage object */ private static OSRFRegistry registry = OSRFRegistry.registerObject( "osrfMessage", @@ -32,6 +33,12 @@ public class Message implements OSRFSerializable { setId(id); setString(type); } + + /** + * @param id This message's ID + * @param type The type of message + * @param payload The message payload + */ public Message(int id, String type, Object payload) { this(id, type); setPayload(payload); @@ -70,6 +77,9 @@ public class Message implements OSRFSerializable { return null; } + /** + * @return The osrfMessage registry. + */ public OSRFRegistry getRegistry() { return registry; } diff --git a/src/java/org/opensrf/Method.java b/src/java/org/opensrf/Method.java index cd31a9d..b708d4f 100644 --- a/src/java/org/opensrf/Method.java +++ b/src/java/org/opensrf/Method.java @@ -6,28 +6,44 @@ import org.opensrf.util.*; public class Method extends OSRFObject { + /** The method API name */ private String name; + /** The ordered list of method params */ private List params; + /** Create a registry for the osrfMethod object */ private static OSRFRegistry registry = OSRFRegistry.registerObject( "osrfMethod", OSRFRegistry.WireProtocol.HASH, new String[] {"method", "params"}); + /** + * @param name The method API name + */ public Method(String name) { this.name = name; this.params = new ArrayList(8); } + /** + * @param name The method API name + * @param params The ordered list of params + */ public Method(String name, List params) { this.name = name; this.params = params; } + /** + * @return The method API name + */ public String getName() { return name; } + /** + * @return The ordered list of params + */ public List getParams() { return params; } @@ -51,6 +67,9 @@ public class Method extends OSRFObject { return null; } + /** + * @return The osrfMethod registry. + */ public OSRFRegistry getRegistry() { return registry; } diff --git a/src/java/org/opensrf/Request.java b/src/java/org/opensrf/Request.java index 4c61ec5..001ce43 100644 --- a/src/java/org/opensrf/Request.java +++ b/src/java/org/opensrf/Request.java @@ -7,13 +7,25 @@ import org.opensrf.net.xmpp.XMPPException; public class Request { + /** This request's controlling session */ private ClientSession session; + /** The method */ private Method method; + /** The ID of this request */ private int id; + /** Queue of Results */ private Queue resultQueue; + /** If true, the receive timeout for this request should be reset */ private boolean resetTimeout; + + /** If true, the server has indicated that this request is complete. */ private boolean complete; + /** + * @param ses The controlling session for this request. + * @param id This request's ID. + * @param method The requested method. + */ public Request(ClientSession ses, int id, Method method) { this.session = ses; this.id = id; @@ -23,23 +35,46 @@ public class Request { resetTimeout = false; } + /** + * @param ses The controlling session for this request. + * @param id This request's ID. + * @param methodName The requested method's API name. + */ public Request(ClientSession ses, int id, String methodName) { this(ses, id, new Method(methodName)); } + /** + * @param ses The controlling session for this request. + * @param id This request's ID. + * @param methodName The requested method's API name. + * @param params The list of request params + */ public Request(ClientSession ses, int id, String methodName, List params) { this(ses, id, new Method(methodName, params)); } + /** + * Sends the request to the server. + */ public void send() throws SessionException { session.send(new Message(id, Message.REQUEST, method)); } + /** + * Receives the next result for this request. This method + * will wait up to the specified number of milliseconds for + * a response. + * @param millis Number of milliseconds to wait for a result. If + * negative, this method will wait indefinitely. + * @return The result or null if none arrives in time + */ public Result recv(long millis) throws SessionException { Result result = null; if(millis < 0) { + /** wait potentially forever for a result to arrive */ session.waitForMessage(millis); if((result = resultQueue.poll()) != null) return result; @@ -47,6 +82,12 @@ public class Request { } else { while(millis >= 0) { + + /** wait up to millis milliseconds for a result. waitForMessage() + * will return if a response to any request arrives, so we keep track + * of how long we've been waiting in total for a response to + * this request + */ long start = new Date().getTime(); session.waitForMessage(millis); millis -= new Date().getTime() - start; @@ -58,6 +99,10 @@ public class Request { return null; } + /** + * Pushes a result onto the result queue + * @param result The result to push + */ public void pushResponse(Result result) { resultQueue.offer(result); } @@ -68,4 +113,11 @@ public class Request { public int getId() { return id; } + + /** + * Removes this request from the controlling session's request set + */ + public void cleanup() { + session.cleanupRequest(id); + } } diff --git a/src/java/org/opensrf/Result.java b/src/java/org/opensrf/Result.java index 4fd065b..80b71dd 100644 --- a/src/java/org/opensrf/Result.java +++ b/src/java/org/opensrf/Result.java @@ -23,6 +23,11 @@ public class Result implements OSRFSerializable { new String[] {"status", "statusCode", "content"}); + /** + * @param status The status message for this result + * @param statusCode The status code + * @param content The content of the result + */ public Result(String status, int statusCode, Object content) { this.status = status; this.statusCode = statusCode; @@ -90,6 +95,9 @@ public class Result implements OSRFSerializable { return null; } + /** + * @return The osrfMethod registry. + */ public OSRFRegistry getRegistry() { return registry; } diff --git a/src/java/org/opensrf/Session.java b/src/java/org/opensrf/Session.java index 01f1d21..3dc81f9 100644 --- a/src/java/org/opensrf/Session.java +++ b/src/java/org/opensrf/Session.java @@ -21,7 +21,7 @@ public abstract class Session { /** the current connection state */ private ConnectState connectState; - /** The (jabber) address of the remote party we are communicating with */ + /** The address of the remote party we are communicating with */ private String remoteNode; /** @@ -85,13 +85,23 @@ public abstract class Session { return sessionCache.get(thread); } + /** + * Puts this session into session cache. + */ protected void cacheSession() { sessionCache.put(thread, this); } + /** + * Sets the remote address + * @param nodeName The name of the remote node. + */ public void setRemoteNode(String nodeName) { remoteNode = nodeName; } + /** + * @return The remote node + */ public String getRemoteNode() { return remoteNode; } diff --git a/src/java/org/opensrf/Stack.java b/src/java/org/opensrf/Stack.java index 58a39a5..6db285e 100644 --- a/src/java/org/opensrf/Stack.java +++ b/src/java/org/opensrf/Stack.java @@ -12,6 +12,7 @@ public class Stack { if(msg == null) return; + /** fetch this session from the cache */ Session ses = Session.findCachedSession(msg.getThread()); if(ses == null) { @@ -35,9 +36,10 @@ public class Stack { OSRFObject obj = null; long start = new Date().getTime(); + /** cycle through the messages and push them up the stack */ while(itr.hasNext()) { - /** Construct a Message object from the generic OSRFObject returned from parsing */ + /** Construct a Message object from the parsed generic OSRFObject */ obj = (OSRFObject) itr.next(); processOSRFMessage( @@ -53,20 +55,26 @@ public class Stack { /** LOG the duration */ } - public static void processOSRFMessage(Session ses, Message msg) { + private static void processOSRFMessage(Session ses, Message msg) { if( ses instanceof ClientSession ) processResponse((ClientSession) ses, msg); else processRequest((ServerSession) ses, msg); } - public static void processResponse(ClientSession session, Message msg) { + /** + * Process a server response + */ + private static void processResponse(ClientSession session, Message msg) { if(msg.RESULT.equals(msg.getType())) { session.pushResponse(msg); return; } } - public static void processRequest(ServerSession session, Message msg) { + /** + * Process a client request + */ + private static void processRequest(ServerSession session, Message msg) { } } diff --git a/src/java/org/opensrf/net/xmpp/XMPPMessage.java b/src/java/org/opensrf/net/xmpp/XMPPMessage.java index f1f0d55..b6e2c76 100644 --- a/src/java/org/opensrf/net/xmpp/XMPPMessage.java +++ b/src/java/org/opensrf/net/xmpp/XMPPMessage.java @@ -2,20 +2,6 @@ package org.opensrf.net.xmpp; import java.io.*; - -/* - * uncomment to use the DOM serialization code... - -import org.w3c.dom.*; -import org.apache.xerces.dom.DocumentImpl; -import org.apache.xerces.dom.DOMImplementationImpl; -import org.apache.xml.serialize.OutputFormat; -import org.apache.xml.serialize.Serializer; -import org.apache.xml.serialize.SerializerFactory; -import org.apache.xml.serialize.XMLSerializer; -*/ - - /** * Models a single XMPP message. */ @@ -110,50 +96,6 @@ public class XMPPMessage { } } } - - - - /** - * This is a DOM implementataion of message serialization. - * I'm inclined to think the stringbuffer version is faster, but - * I have no proof. - */ - /* - public String __toXML() { - - Document doc = new DocumentImpl(); - Element message = doc.createElement("message"); - Element body = doc.createElement("body"); - Element thread = doc.createElement("thread"); - - doc.appendChild(message); - message.setAttribute("to", getTo()); - message.setAttribute("from", getFrom()); - message.appendChild(body); - message.appendChild(thread); - - body.appendChild(doc.createTextNode(getBody())); - thread.appendChild(doc.createTextNode(getThread())); - - XMLSerializer serializer = new XMLSerializer(); - StringWriter strWriter = new StringWriter(); - OutputFormat outFormat = new OutputFormat(); - - outFormat.setEncoding("UTF-8"); - outFormat.setVersion("1.0"); - outFormat.setIndenting(false); - outFormat.setOmitXMLDeclaration(true); - - serializer.setOutputCharStream(strWriter); - serializer.setOutputFormat(outFormat); - - try { - serializer.serialize(doc); - } catch(IOException ioe) { - } - return strWriter.toString(); - } - */ } diff --git a/src/java/org/opensrf/net/xmpp/XMPPSession.java b/src/java/org/opensrf/net/xmpp/XMPPSession.java index bcd304e..ce7e36c 100644 --- a/src/java/org/opensrf/net/xmpp/XMPPSession.java +++ b/src/java/org/opensrf/net/xmpp/XMPPSession.java @@ -52,10 +52,16 @@ public class XMPPSession { this.port = port; } + /** + * Returns the global, process-wide session + */ public static XMPPSession getGlobalSession() { return globalSession; } + /** + * Sets the global, process-wide section + */ public static void setGlobalSession(XMPPSession ses) { globalSession = ses; } diff --git a/src/java/org/opensrf/test/TestClient.java b/src/java/org/opensrf/test/TestClient.java index 3b9920f..8cd7865 100644 --- a/src/java/org/opensrf/test/TestClient.java +++ b/src/java/org/opensrf/test/TestClient.java @@ -4,6 +4,7 @@ import org.opensrf.util.*; import org.opensrf.net.xmpp.*; import java.io.PrintStream; import java.util.Map; +import java.util.Date; public class TestClient { diff --git a/src/java/org/opensrf/util/Config.java b/src/java/org/opensrf/util/Config.java index 388afc7..03de8ac 100644 --- a/src/java/org/opensrf/util/Config.java +++ b/src/java/org/opensrf/util/Config.java @@ -16,8 +16,16 @@ public class Config { private static Config config; /** The object form of the parsed config */ private Map configObject; + /** + * The log parsing context. This is used as a prefix to the + * config item search path. This allows config XML chunks to + * be inserted into arbitrary XML files. + */ private String context; + /** + * @param context The config context + */ public Config(String context) { this.context = context; } @@ -56,8 +64,17 @@ public class Config { } } + /** + * Gets the int value at the given path + * @param path The search path + */ public static int getInt(String path) throws ConfigException { - return Integer.parseInt(getString(path)); + try { + return Integer.parseInt(getString(path)); + } catch(Exception e) { + throw new + ConfigException("No config int found at " + path); + } } /** @@ -79,6 +96,11 @@ public class Config { } } + /** + * Returns the first item in the list found at the given path. If + * no list is found, ConfigException is thrown. + * @param path The search path + */ public static Object getFirst(String path) throws ConfigException { Object obj = get(path); if(obj instanceof List) diff --git a/src/java/org/opensrf/util/JSONException.java b/src/java/org/opensrf/util/JSONException.java index 69a5c20..ec28e1d 100644 --- a/src/java/org/opensrf/util/JSONException.java +++ b/src/java/org/opensrf/util/JSONException.java @@ -1,4 +1,7 @@ package org.opensrf.util; +/** + * Used to indicate JSON parsing errors + */ public class JSONException extends Exception { public JSONException(String s) { super(s); diff --git a/src/java/org/opensrf/util/JSONReader.java b/src/java/org/opensrf/util/JSONReader.java index 85ce58a..634c249 100644 --- a/src/java/org/opensrf/util/JSONReader.java +++ b/src/java/org/opensrf/util/JSONReader.java @@ -19,8 +19,12 @@ public class JSONReader { /** Special OpenSRF serializable object payload key */ public static final String JSON_PAYLOAD_KEY = "__p"; + /** The JSON string to parser */ private String json; + /** + * @param The JSON to parse + */ public JSONReader(String json) { this.json = json; } @@ -40,6 +44,10 @@ public class JSONReader { } } + /** + * Assumes that a JSON array will be read. Returns + * the resulting array as a list. + */ public List readArray() throws JSONException { Object o = read(); try { @@ -49,6 +57,10 @@ public class JSONReader { } } + /** + * Assumes that a JSON object will be read. Returns + * the resulting object as a map. + */ public Map readObject() throws JSONException { Object o = read(); try { @@ -59,6 +71,9 @@ public class JSONReader { } + /** + * Recurse through the object and turn items into maps, lists, etc. + */ private Object readSubObject(Object obj) throws JSONException { if( obj == null || diff --git a/src/java/org/opensrf/util/JSONWriter.java b/src/java/org/opensrf/util/JSONWriter.java index c5a653d..6af7e3e 100644 --- a/src/java/org/opensrf/util/JSONWriter.java +++ b/src/java/org/opensrf/util/JSONWriter.java @@ -12,6 +12,9 @@ public class JSONWriter { /** The object to serialize to JSON */ private Object obj; + /** + * @param obj The object to encode + */ public JSONWriter(Object obj) { this.obj = obj; } @@ -37,6 +40,9 @@ public class JSONWriter { write(obj, sb); } + /** + * Encodes the object as JSON into the provided buffer + */ public void write(Object obj, StringBuffer sb) { /** JSON null */ @@ -141,6 +147,7 @@ public class JSONWriter { if( reg.getWireProtocol() == OSRFRegistry.WireProtocol.ARRAY ) { + /** encode arrays as lists */ List list = new ArrayList(fields.length); for(String s : fields) list.add(obj.get(s)); @@ -148,6 +155,7 @@ public class JSONWriter { } else { + /** encode hashes as maps */ Map subMap = new HashMap(); for(String s : fields) subMap.put(s, obj.get(s)); diff --git a/src/java/org/opensrf/util/OSRFObject.java b/src/java/org/opensrf/util/OSRFObject.java index 65a340b..1050706 100644 --- a/src/java/org/opensrf/util/OSRFObject.java +++ b/src/java/org/opensrf/util/OSRFObject.java @@ -16,14 +16,6 @@ public class OSRFObject extends HashMap implements OSRFSerializa public OSRFObject() { } - - /* - public OSRFObject(String netClass, Map map) { - super(map); - registry = OSRFRegistry.getRegistry(netClass); - } - */ - /** * Creates a new object with the provided registry */ @@ -32,7 +24,6 @@ public class OSRFObject extends HashMap implements OSRFSerializa registry = reg; } - /** * @return This object's registry */ @@ -47,11 +38,16 @@ public class OSRFObject extends HashMap implements OSRFSerializa return super.get(field); } + /** Returns the string value found at the given field */ public String getString(String field) { return (String) get(field); } + /** Returns the int value found at the given field */ public int getInt(String field) { + Object o = get(field); + if(o instanceof String) + return Integer.parseInt((String) o); return ((Integer) get(field)).intValue(); } } diff --git a/src/java/org/opensrf/util/OSRFRegistry.java b/src/java/org/opensrf/util/OSRFRegistry.java index 8a59913..f5fe7cb 100644 --- a/src/java/org/opensrf/util/OSRFRegistry.java +++ b/src/java/org/opensrf/util/OSRFRegistry.java @@ -79,16 +79,24 @@ public class OSRFRegistry { return -1; } + /** Returns the wire protocol of this object */ public WireProtocol getWireProtocol() { return this.wireProtocol; } + /** Returns the netClass ("hint") of this object */ public String getNetClass() { return this.netClass; } /** - * Creates a new registry object */ + * Creates a new registry object. + * @param netClass The network class/hint + * @param wireProtocol The wire protocol + * @param fields The array of field names. For array-based objects, + * the fields array must be sorted in accordance with the sorting + * of the objects in the array. + */ public OSRFRegistry(String netClass, WireProtocol wireProtocol, String fields[]) { this.netClass = netClass; this.wireProtocol = wireProtocol; diff --git a/src/java/org/opensrf/util/OSRFSerializable.java b/src/java/org/opensrf/util/OSRFSerializable.java index 23d5896..64b5d6f 100644 --- a/src/java/org/opensrf/util/OSRFSerializable.java +++ b/src/java/org/opensrf/util/OSRFSerializable.java @@ -10,6 +10,9 @@ public interface OSRFSerializable { */ public abstract OSRFRegistry getRegistry(); + /** + * Returns the object found at the given field + */ public abstract Object get(String field); } -- 2.43.2