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
{