From 151fa7cf9bb917aadfff34012e3bc47920622051 Mon Sep 17 00:00:00 2001
From: Jakub Skoczen <jakub@indexdata.dk>
Date: Tue, 10 Nov 2015 12:56:16 +0100
Subject: [PATCH] Add documentation.

---
 src/main/java/org/yaz4j/async/AsyncConnection.java |   38 +++++++++++++++++++-
 .../java/org/yaz4j/async/AsyncConnections.java     |   15 +++++++-
 src/main/java/org/yaz4j/async/package-info.java    |   16 +++++++++
 3 files changed, 67 insertions(+), 2 deletions(-)
 create mode 100644 src/main/java/org/yaz4j/async/package-info.java

diff --git a/src/main/java/org/yaz4j/async/AsyncConnection.java b/src/main/java/org/yaz4j/async/AsyncConnection.java
index 3fa0c81..9e8148e 100644
--- a/src/main/java/org/yaz4j/async/AsyncConnection.java
+++ b/src/main/java/org/yaz4j/async/AsyncConnection.java
@@ -15,7 +15,11 @@ import static org.yaz4j.jni.yaz4jlib.*;
 import org.yaz4j.util.Unstable;
 
 /**
- *
+ * Represents an asynchronous connection, all methods of this class 
+ * (e.g connect, search) are non-blocking.
+ * 
+ * Note that async support is missing for scan and extended services at this point.
+ * 
  * @author jakub
  */
 @Unstable
@@ -29,14 +33,26 @@ public class AsyncConnection extends Connection {
   SearchHandler sh;
   RecordHandler rh;
   
+  /**
+   * Invoked immediately in response to the search request. 
+   * 
+   * Allows to read things the hit count and facets. Records should be read
+   * and processed in the record handler.
+   */
   public interface SearchHandler {
     public void handle(ResultSet rs);
   }
   
+  /**
+   * Invoked for every retrieved record.
+   */
   public interface RecordHandler {
     public void handle(Record r);
   }
   
+  /**
+   * Invoked for any protocol or connection level error.
+   */
   public interface ErrorHandler {
     public void handle(ZoomException e);
   }
@@ -54,21 +70,41 @@ public class AsyncConnection extends Connection {
     return null;
   }
   
+  /**
+   * Register a hander for the search response.
+   * @param sh search response handler
+   * @return 
+   */
   public AsyncConnection onSearch(SearchHandler sh) {
     this.sh = sh;
     return this;
   }
   
+  /**
+   * Register a handler for each retrieved record.
+   * @param rh record handler
+   * @return 
+   */
   public AsyncConnection onRecord(RecordHandler rh) {
     this.rh = rh;
     return this;
   }
   
+  /**
+   * Register a handler for a connection level errors.
+   * @param eh error handler
+   * @return 
+   */
   public AsyncConnection onError(ErrorHandler eh) {
     this.eh = eh;
     return this;
   }
   
+  /**
+   * Register a handler for record level errors (e.g decoding).
+   * @param reh record error handler
+   * @return 
+   */
   public AsyncConnection onRecordError(ErrorHandler reh) {
     this.reh = reh;
     return this;
diff --git a/src/main/java/org/yaz4j/async/AsyncConnections.java b/src/main/java/org/yaz4j/async/AsyncConnections.java
index 23a48ed..c84abf5 100644
--- a/src/main/java/org/yaz4j/async/AsyncConnections.java
+++ b/src/main/java/org/yaz4j/async/AsyncConnections.java
@@ -14,21 +14,34 @@ import static java.lang.System.out;
 import org.yaz4j.util.Unstable;
 
 /**
- *
+ * Allows to group and execute asynchronous connections within an event loop.
+ * 
  * @author jakub
  */
 @Unstable
 public class AsyncConnections {
   private List<AsyncConnection> conns = new ArrayList<AsyncConnection>();
   
+  /**
+   * Include async connection in the event loop processing.
+   * @param conn 
+   */
   public void add(AsyncConnection conn) {
     conns.add(conn);
   }
 
+  /**
+   * List all included connections.
+   * @return 
+   */
   public List<AsyncConnection> getConnections() {
     return conns;
   }
   
+  /**
+   * Start the event loop, which effectively executes and processes all 
+   * async connections.
+   */
   public void start() {
     SWIGTYPE_p_p_ZOOM_connection_p c_conns = new_zoomConnectionArray(conns.size());
     try {
diff --git a/src/main/java/org/yaz4j/async/package-info.java b/src/main/java/org/yaz4j/async/package-info.java
new file mode 100644
index 0000000..ef84756
--- /dev/null
+++ b/src/main/java/org/yaz4j/async/package-info.java
@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 1995-2013, Index Data
+ * All rights reserved.
+ * See the file LICENSE for details.
+ */
+/**
+ * Asynchronous ZOOOM API for developing non-blocking, multi-target applications.
+ * 
+ * This package is highly experimental: classes and interfaces
+ * may be marked as @Unstable. Don't be surprised by breaking changes to those
+ * types.
+ * 
+ * For background:
+ * @see <a href="http://www.indexdata.com/yaz/doc/zoom.events.html">ZOOM-API</a>
+ */
+package org.yaz4j.async;
-- 
1.7.10.4