PATCH: Update LISTEN/NOTIFY documentation, PGConnection JavaDoc

Hi folks

It seems the JDBC driver no longer requires a query to be issued before
it will notice new notify messages and be able to process them via
getNotifications() . The JDBC driver documentation doesn't reflect this.

I've attached a patch that updates the documentation. It includes one
thing I'm not 100% sure of, though:

- It states that the need for a dummy query was removed in the 8.1
driver, but I'm not sure that it was in fact 8.1 (and have no idea what
the build number was). Before I went CVS-history-diving I thought I'd
ask and see if anybody knew when the change was.

In addition to correcting the confusion, I've added @see links to the Pg
 LISTEN/NOTIFY docs, added a note about older versions requiring a dummy
select, noted that calling getNotifications() doesn't create network
traffic, and fixed an unrelated place where "8.1" should've read "8.1 or
later".

--
Craig Ringer
Index: doc/pgjdbc.xml
===================================================================
RCS file: /cvsroot/jdbc/pgjdbc/doc/pgjdbc.xml,v
retrieving revision 1.39
diff -u -r1.39 pgjdbc.xml
--- doc/pgjdbc.xml    20 Jun 2009 15:19:40 -0000    1.39
+++ doc/pgjdbc.xml    11 Dec 2009 15:36:53 -0000
@@ -2294,11 +2294,16 @@
    </para>

    <note>
-    <para>
-     A key limitation of the <acronym>JDBC</acronym> driver is that it
-     cannot receive asynchronous notifications and must poll the
-     backend to check if any notifications were issued.
-    </para>
+     <para>
+       In <productname>PgJDBC</productname> drivers earlier than 8.1,
+       notifications were not processed until a statement was next executed.
+       Dummy statements like <literal>SELECT 1;</literal> were used to force
+       the driver to check for notifications. If your application must be compatible with
+       such old versions, you will need to check
+       <function>org.postgresql.Driver.getVersion()</function> and
+       issue dummy statements before <function>getNotifications()</function>
+       calls if necessary.
+     </para>
    </note>

    <example id="listen-notify-example">
@@ -2346,13 +2351,8 @@
     public void run() {
         while (true) {
             try {
-                // issue a dummy query to contact the backend
-                // and receive any pending notifications.
-                Statement stmt = conn.createStatement();
-                ResultSet rs = stmt.executeQuery("SELECT 1");
-                rs.close();
-                stmt.close();
-
+                // Check the connection's read buffer for any unprocessed
+                // notifications and return them.
                 org.postgresql.PGNotification notifications[] = pgconn.getNotifications();
                 if (notifications != null) {
                     for (int i=0; i<notifications.length; i++) {
@@ -2425,7 +2425,7 @@
      avoid these changes in query results, but the V3 protocol is only
      available beginning with server version 7.4.  Enabling server-prepared
      statements will have no affect when connected to a 7.3 server or when
-     explicitly using the V2 protocol to connect to a 7.4 server.
+     explicitly using the V2 protocol to connect to a 7.4 or later server.
     </para>
    </note>

Index: org/postgresql/PGConnection.java
===================================================================
RCS file: /cvsroot/jdbc/pgjdbc/org/postgresql/PGConnection.java,v
retrieving revision 1.17
diff -u -r1.17 PGConnection.java
--- org/postgresql/PGConnection.java    1 Jul 2009 05:00:39 -0000    1.17
+++ org/postgresql/PGConnection.java    11 Dec 2009 15:36:53 -0000
@@ -22,10 +22,21 @@
 public interface PGConnection
 {
     /**
-     * This method returns any notifications that have been received
-     * since the last call to this method.
-     * Returns null if there have been no notifications.
+     * <p>This method returns any notifications that have been received
+     * since the last call to this method.</p>
+     *
+     * <p><code>getNotifications()</code> does not cause any network
+     * communication with the server. It only checks a local receive
+     * buffer for notifications, and is a fairly cheap operation.</p>
+     *
+     * <p><b>Version Compatibility Note:</b> In driver versions older
+     * than 8.1 it was necessary to execute an SQL query via the JDBC
+     * driver before the driver would notice waiting notifications.</p>
+     *
+     * @see <a href="http://www.postgresql.org/docs/current/static/sql-notify.html">PostgreSQL documentation for the
LISTENand NOTIFY commands</a> 
      * @since 7.3
+     *
+     * @return Array of notifications or null if there have been no notifications
      */
     public PGNotification[] getNotifications() throws SQLException;

Index: org/postgresql/PGNotification.java
===================================================================
RCS file: /cvsroot/jdbc/pgjdbc/org/postgresql/PGNotification.java,v
retrieving revision 1.12
diff -u -r1.12 PGNotification.java
--- org/postgresql/PGNotification.java    8 Jan 2008 06:56:26 -0000    1.12
+++ org/postgresql/PGNotification.java    11 Dec 2009 15:36:53 -0000
@@ -10,7 +10,9 @@
 package org.postgresql;

 /**
- *    This interface defines the public PostgreSQL extension for Notifications
+ *    This interface defines the public PostgreSQL extension for Notifications.
+ *    @see PGConnection#getNotifications()
+ *    @see <a href="http://www.postgresql.org/docs/current/static/sql-notify.html">PostgreSQL documentation for the
LISTENand NOTIFY commands</a> 
  */
 public interface PGNotification
 {