Documentation and examples

Author: alaisi

.gitignore

@@ -2,3 +2,6 @@ target/
 .settings/
 .classpath
 .project
+.idea
+*.iml
+

README.md

@@ -20,7 +20,15 @@ Pg-async-driver is available on [Maven Central](http://search.maven.org/#search|
 
 ```java
 ConnectionPool pool = ...;
-pool.query("SELECT 'Hello world!' AS message", new ResultHandler() {
+pool.query("select 'Hello world!' as message",
+    result -> System.out.println(result.get(0).getString("message") ),
+    error  -> error.printStackTrace() );
+```
+Or with Java <= 7:
+
+```java
+ConnectionPool pool = ...;
+pool.query("select 'Hello world!' as message", new ResultHandler() {
     @Override
     public void onResult(ResultSet result) {
         System.out.println(result.get(0).getString("message"));
@@ -33,15 +41,6 @@ pool.query("SELECT 'Hello world!' AS message", new ResultHandler() {
 });
 ```
 
-Or with Java 8:
-
-```java
-ConnectionPool pool = ...;
-pool.query("SELECT 'Hello world!' AS message",
-    (result) -> System.out.println(result.get(0).getString("message")),
-    (error) -> error.printStackTrace() );
-```
-
 ### Connection pools
 
 Connection pools are created with [`com.github.pgasync.ConnectionPoolBuilder`](https://github.com/alaisi/pg-async-driver/blob/master/src/main/java/com/github/pgasync/ConnectionPoolBuilder.java)
@@ -55,15 +54,36 @@ ConnectionPool pool = return new ConnectionPoolBuilder()
     .build();
 ```
 
-Each connection pool will start one IO thread used in communicating with PostgreSQL backend.
+Each connection pool will start one IO thread used in communicating with PostgreSQL backend and executing callbacks.
 
 ### Prepared statements
 
-TODO
+Prepared statements use native PostgreSQL syntax $<index>. Supported parameter types are all primitive types, `String`, temporal types in `java.sql` package and `byte[]`.
+
+```java
+pool.query("insert into message(id, body) values($1, $2)", Arrays.asList(123, "hello"),
+    result -> System.out.printf("Inserted %d rows", result.updatedRows() ),
+    error  -> error.printStackTrace() );
+```
 
 ### Transactions
 
-TODO
+A transactional unit of work is started with `begin()`. Queries issued against connection passed to callback are executed in the same transaction. The transaction must always be committed or rolled back.
+
+```java
+ErrorHandler err = error -> error.printStackTrace();
+pool.begin((connection, transaction) -> {
+    connection.query("select 1 as id",
+        result -> {
+            System.out.println("Result is %d", result.get(0).getLong("id"));
+            transaction.commit(() -> System.out.println("Transaction committed"), err);
+        },
+        error -> {
+            System.out.println("Query failed");
+            transaction.rollback(() -> System.out.println("Transaction rolled back"), err);
+        })
+}, err)
+```
 
 ## References
 * [Scala postgresql-async](https://raw.github.com/mauricio/postgresql-async)

src/main/java/com/github/pgasync/Connection.java

@@ -44,8 +44,8 @@ public interface Connection {
      * 
      * @param sql SQL to execute
      * @param params List of parameters
-     * @param onResult
-     * @param onError
+     * @param onResult Called when query is completed
+     * @param onError Called on exception thrown
      */
     void query(String sql, List/*<Object>*/ params, ResultHandler onResult, ErrorHandler onError);
 

src/main/java/com/github/pgasync/ResultSet.java

@@ -24,12 +24,25 @@
  */
 public interface ResultSet extends Iterable<Row> {
 
+    /**
+     * @return Row iterator
+     */
     Iterator<Row> iterator();
 
+    /**
+     * @param index Row index starting from 0
+     * @return Row, never null
+     */
     Row get(int index);
 
+    /**
+     * @return Amount of result rows.
+     */
     int size();
 
+    /**
+     * @return Amount of modified rows.
+     */
     int updatedRows();
 
 }

src/main/java/com/github/pgasync/Transaction.java

@@ -18,7 +18,7 @@
 import com.github.pgasync.callback.TransactionCompletedHandler;
 
 /**
- * A unit of work. Transactions must be commited or rolled back, otherwise a
+ * A unit of work. Transactions must be committed or rolled back, otherwise a
  * connection left is a stale state.
  * 
  * @author Antti Laisi

src/main/java/com/github/pgasync/callback/ChainedErrorHandler.java

@@ -14,6 +14,11 @@
 
 package com.github.pgasync.callback;
 
+/**
+ * Delegating error handler
+ *
+ * @author Antti Laisi
+ */
 public class ChainedErrorHandler implements ErrorHandler {
 
     final ErrorHandler onError;

src/main/java/com/github/pgasync/callback/ConnectionHandler.java

@@ -16,6 +16,11 @@
 
 import com.github.pgasync.Connection;
 
+/**
+ * Callback for fetching a connection from pool.
+ *
+ * @author Antti Laisi
+ */
 public interface ConnectionHandler {
 
     void onConnection(Connection connection);

src/main/java/com/github/pgasync/callback/ErrorHandler.java

@@ -14,8 +14,17 @@
 
 package com.github.pgasync.callback;
 
+/**
+ * Callback for errors.
+ *
+ * @author Antti Laisi
+ */
 public interface ErrorHandler {
 
+    /**
+     * Executed on exception.
+     * @param t Error
+     */
     void onError(Throwable t);
 
 }

src/main/java/com/github/pgasync/callback/ResultHandler.java

@@ -16,6 +16,11 @@
 
 import com.github.pgasync.ResultSet;
 
+/**
+ * Callback for processing query results.
+ *
+ * @author Antti Laisi
+ */
 public interface ResultHandler {
 
     void onResult(ResultSet result);

src/main/java/com/github/pgasync/callback/TransactionHandler.java

@@ -17,8 +17,19 @@
 import com.github.pgasync.Connection;
 import com.github.pgasync.Transaction;
 
+/**
+ * Callback for a started transaction.
+ *
+ * @author Antti Laisi
+ */
 public interface TransactionHandler {
 
+    /**
+     * Called when the transaction is started.
+     *
+     * @param txconn Transactional connection, queries are executed in the same transaction
+     * @param transaction Transaction, must be committed or rolled back
+     */
     void onBegin(Connection txconn, Transaction transaction);
 
 }

src/main/java/com/github/pgasync/impl/PgConnection.java

@@ -41,7 +41,7 @@
 import com.github.pgasync.impl.message.Query;
 import com.github.pgasync.impl.message.ReadyForQuery;
 import com.github.pgasync.impl.message.RowDescription;
-import com.github.pgasync.impl.message.Startup;
+import com.github.pgasync.impl.message.StartupMessage;
 
 /**
  * A connection to PostgreSQL backed. The postmaster forks a backend process for
@@ -75,7 +75,7 @@ public void connect(String username, String password, String database,
         this.password = password;
         this.connectedHandler = onConnected;
         this.errorHandler = onError;
-        stream.connect(new Startup(username, database), this);
+        stream.connect(new StartupMessage(username, database), this);
     }
 
     public boolean isConnected() {

src/main/java/com/github/pgasync/impl/PgProtocolStream.java

@@ -15,7 +15,7 @@
 package com.github.pgasync.impl;
 
 import com.github.pgasync.impl.message.Message;
-import com.github.pgasync.impl.message.Startup;
+import com.github.pgasync.impl.message.StartupMessage;
 
 /**
  * Stream of messages from/to backend server.
@@ -24,7 +24,7 @@
  */
 public interface PgProtocolStream {
 
-    void connect(Startup startup, PgProtocolCallbacks callbacks);
+    void connect(StartupMessage startup, PgProtocolCallbacks callbacks);
 
     void send(Message... messages);
 

src/main/java/com/github/pgasync/impl/io/AuthenticationDecoder.java

@@ -18,6 +18,31 @@
 
 import com.github.pgasync.impl.message.Authentication;
 
+/**
+ * See <a href="www.postgresql.org/docs/9.3/static/protocol-message-formats.html">PostgreSQL message formats</a>
+ * 
+ * <pre>
+ * AuthenticationOk (B)
+ *  Byte1('R')
+ *      Identifies the message as an authentication request.
+ *  Int32(8)
+ *      Length of message contents in bytes, including self.
+ *  Int32(0)
+ *      Specifies that the authentication was successful.
+ *       
+ * AuthenticationMD5Password (B)
+ *  Byte1('R')
+ *      Identifies the message as an authentication request.
+ *  Int32(12)
+ *      Length of message contents in bytes, including self.
+ *  Int32(5)
+ *      Specifies that an MD5-encrypted password is required.
+ *  Byte4
+ *      The salt to use when encrypting the password.
+ * </pre>
+ * 
+ * @author Antti Laisi
+ */
 public class AuthenticationDecoder implements Decoder<Authentication> {
 
     static final int OK = 0;

src/main/java/com/github/pgasync/impl/io/BindEncoder.java

@@ -18,6 +18,39 @@
 
 import com.github.pgasync.impl.message.Bind;
 
+/**
+ * See <a href="www.postgresql.org/docs/9.3/static/protocol-message-formats.html">PostgreSQL message formats</a>
+ *  
+ * <pre>
+ * Bind (F)
+ *   Byte1('B')
+ *       Identifies the message as a Bind command.
+ *   Int32
+ *       Length of message contents in bytes, including self.
+ *   String
+ *       The name of the destination portal (an empty string selects the unnamed portal).
+ *   String
+ *       The name of the source prepared statement (an empty string selects the unnamed prepared statement).
+ *   Int16
+ *       The number of parameter format codes that follow (denoted C below). This can be zero to indicate that there are no parameters or that the parameters all use the default format (text); or one, in which case the specified format code is applied to all parameters; or it can equal the actual number of parameters.
+ *   Int16[C]
+ *       The parameter format codes. Each must presently be zero (text) or one (binary).
+ *   Int16
+ *       The number of parameter values that follow (possibly zero). This must match the number of parameters needed by the query.
+ *   Next, the following pair of fields appear for each parameter:
+ *   Int32
+ *       The length of the parameter value, in bytes (this count does not include itself). Can be zero. As a special case, -1 indicates a NULL parameter value. No value bytes follow in the NULL case.
+ *   Byten
+ *       The value of the parameter, in the format indicated by the associated format code. n is the above length.
+ *   After the last parameter, the following fields appear:
+ *   Int16
+ *       The number of result-column format codes that follow (denoted R below). This can be zero to indicate that there are no result columns or that the result columns should all use the default format (text); or one, in which case the specified format code is applied to all result columns (if any); or it can equal the actual number of result columns of the query.
+ *   Int16[R]
+ *       The result-column format codes. Each must presently be zero (text) or one (binary).
+ *</pre>
+ *
+ * @author Antti Laisi
+ */
 public class BindEncoder implements Encoder<Bind> {
 
     @Override

src/main/java/com/github/pgasync/impl/io/CommandCompleteDecoder.java

@@ -20,6 +20,28 @@
 
 import com.github.pgasync.impl.message.CommandComplete;
 
+/**
+ * See <a href="www.postgresql.org/docs/9.3/static/protocol-message-formats.html">PostgreSQL message formats</a>
+ *
+ * <pre>
+ * CommandComplete (B)
+ *  Byte1('C')
+ *      Identifies the message as a command-completed response.
+ *  Int32
+ *      Length of message contents in bytes, including self.
+ *  String
+ *      The command tag. This is usually a single word that identifies which SQL command was completed.
+ *      For an INSERT command, the tag is INSERT oid rows, where rows is the number of rows inserted. oid is the object ID of the inserted row if rows is 1 and the target table has OIDs; otherwise oid is 0.
+ *      For a DELETE command, the tag is DELETE rows where rows is the number of rows deleted.
+ *      For an UPDATE command, the tag is UPDATE rows where rows is the number of rows updated.
+ *      For a SELECT or CREATE TABLE AS command, the tag is SELECT rows where rows is the number of rows retrieved.
+ *      For a MOVE command, the tag is MOVE rows where rows is the number of rows the cursor's position has been changed by.
+ *      For a FETCH command, the tag is FETCH rows where rows is the number of rows that have been retrieved from the cursor.
+ *      For a COPY command, the tag is COPY rows where rows is the number of rows copied. (Note: the row count appears only in PostgreSQL 8.2 and later.)
+ * </pre>
+ *
+ * @author Antti Laisi
+ */
 public class CommandCompleteDecoder implements Decoder<CommandComplete> {
 
     @Override

src/main/java/com/github/pgasync/impl/io/DataRowDecoder.java

@@ -18,6 +18,26 @@
 
 import com.github.pgasync.impl.message.DataRow;
 
+/**
+ * See <a href="www.postgresql.org/docs/9.3/static/protocol-message-formats.html">PostgreSQL message formats</a>
+ *
+ * <pre>
+ * DataRow (B)
+ *  Byte1('D')
+ *      Identifies the message as a data row.
+ *  Int32
+ *      Length of message contents in bytes, including self.
+ *  Int16
+ *      The number of column values that follow (possibly zero).
+ *  Next, the following pair of fields appear for each column:
+ *  Int32
+ *      The length of the column value, in bytes (this count does not include itself). Can be zero. As a special case, -1 indicates a NULL column value. No value bytes follow in the NULL case.
+ *  Byten
+ *      The value of the column, in the format indicated by the associated format code. n is the above length.
+ * </pre>
+ *
+ * @author Antti Laisi
+ */
 public class DataRowDecoder implements Decoder<DataRow> {
 
     @Override

src/main/java/com/github/pgasync/impl/io/Decoder.java

@@ -18,10 +18,21 @@
 
 import com.github.pgasync.impl.message.Message;
 
+/**
+ * Decoder reads messages from byte buffer.
+ *
+ * @author Antti Laisi
+ */
 public interface Decoder<T extends Message> {
 
+    /**
+     * @return Protocol message id
+     */
     byte getMessageId();
 
+    /**
+     * @return Decoded message
+     */
     T read(ByteBuffer buffer);
 
 }