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&lt;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 LISTEN and 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 LISTEN and NOTIFY commands</a>
  */
 public interface PGNotification
 {
