From 52ae4a3af2043cf2f2ca9a952e9ee3b3602de950 Mon Sep 17 00:00:00 2001
From: Bill Erickson <berick@esilibrary.com>
Date: Tue, 28 Feb 2012 08:19:30 -0500
Subject: [PATCH] Java HTTP gateway, docs

Signed-off-by: Bill Erickson <berick@esilibrary.com>
---
 .../org/opensrf/net/http/GatewayConnection.java    | 44 +++++++++++++++++-----
 .../opensrf/net/http/GatewayRequestHandler.java    |  4 ++
 2 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/src/java/org/opensrf/net/http/GatewayConnection.java b/src/java/org/opensrf/net/http/GatewayConnection.java
index beab024..ac62169 100644
--- a/src/java/org/opensrf/net/http/GatewayConnection.java
+++ b/src/java/org/opensrf/net/http/GatewayConnection.java
@@ -1,22 +1,34 @@
 package org.opensrf.net.http;
 
-import org.opensrf.*;
-import org.opensrf.util.*;
-
 import java.net.URL;
 import java.net.MalformedURLException;
 import java.util.Queue;
 import java.util.concurrent.ConcurrentLinkedQueue;
+import org.opensrf.*;
+import org.opensrf.util.*;
+
+
+/**
+ * Manages connection parameters and thread limiting for opensrf json gateway connections.
+ */
 
 public class GatewayConnection {
 
-    private String proto; /* http, https */
+    /** http or https */
+    private String proto;
+    /** server name */
     private String host;
+    /** URL path to the gateway, defaults to defaultPath */
     private String path;
+    /** Compiled URL object */
     private URL url;
+    /** Number of threads currently communicating with the server */
     protected int activeThreads;
+    /** Queue of pending async requests */
     protected Queue<GatewayRequest> pendingThreadQueue;
+    /** maximum number of actively communicating threads allowed */
     protected int maxThreads = 10;
+    /** URL path for the gateway */
     public static final String defaultPath = "/osrf-gateway-v1";
 
     public GatewayConnection(String proto, String host) {
@@ -36,11 +48,14 @@ public class GatewayConnection {
         return maxThreads;
     }
 
+    /** 
+     * Set the maximum number of actively communicating threads allowed 
+     */
     public void setMaxThreads(int max) {
         maxThreads = max;
     }
 
-    public URL getUrl() throws java.net.MalformedURLException {
+    protected URL getUrl() throws java.net.MalformedURLException {
         try {
             if (url == null) {
                 url = new URL(proto + "://" + host + path);
@@ -55,6 +70,19 @@ public class GatewayConnection {
         return new GatewayRequest(this, service, method);
     }
 
+    /**
+     * Launches or queues an asynchronous request.
+     *
+     * If the maximum active thread count has not been reached,
+     * start a new thread and use it to send and receive the request.
+     * The response is passed to the request's GatewayRequestHandler
+     * onComplete().  After complete, if the number of active threads
+     * is still lower than the max, one request will be pulled (if 
+     * present) from the async queue and fired.
+     *
+     * If there are too many active threads, the main request is
+     * pushed onto the async queue for later processing
+     */
     protected void manageAsyncRequest(final GatewayRequest request) {
 
         if (activeThreads >= maxThreads) {
@@ -64,10 +92,8 @@ public class GatewayConnection {
 
         activeThreads++;
 
-        /*
-         * Send the request receive the response, fire off the next 
-         * thread if necessary, then pass the result to the handler
-         */
+         //Send the request receive the response, fire off the next 
+         //thread if necessary, then pass the result to the handler
         Runnable r = new Runnable() {
             public void run() {
 
diff --git a/src/java/org/opensrf/net/http/GatewayRequestHandler.java b/src/java/org/opensrf/net/http/GatewayRequestHandler.java
index 3a62769..48ceeda 100644
--- a/src/java/org/opensrf/net/http/GatewayRequestHandler.java
+++ b/src/java/org/opensrf/net/http/GatewayRequestHandler.java
@@ -1,5 +1,9 @@
 package org.opensrf.net.http;
 
+/*
+ * Handler for async gateway request responses
+ */
+
 public interface GatewayRequestHandler {
     public void onComplete(Object payload);
 }
-- 
2.11.0