001: /*-------------------------------------------------------------------------
002: *
003: * Copyright (c) 2004-2005, PostgreSQL Global Development Group
004: * Copyright (c) 2004, Open Cloud Limited.
005: *
006: * IDENTIFICATION
007: * $PostgreSQL: pgjdbc/org/postgresql/core/ProtocolConnection.java,v 1.7 2006/12/01 08:53:45 jurka Exp $
008: *
009: *-------------------------------------------------------------------------
010: */
011: package org.postgresql.core;
012:
013: import org.postgresql.PGNotification;
014: import java.sql.*;
015:
016: /**
017: * Provides access to protocol-level connection operations.
018: *
019: * @author Oliver Jowett (oliver@opencloud.com)
020: */
021: public interface ProtocolConnection {
022: /**
023: * Constant returned by {@link #getTransactionState} indicating that no
024: * transaction is currently open.
025: */
026: static final int TRANSACTION_IDLE = 0;
027:
028: /**
029: * Constant returned by {@link #getTransactionState} indicating that a
030: * transaction is currently open.
031: */
032: static final int TRANSACTION_OPEN = 1;
033:
034: /**
035: * Constant returned by {@link #getTransactionState} indicating that a
036: * transaction is currently open, but it has seen errors and will
037: * refuse subsequent queries until a ROLLBACK.
038: */
039: static final int TRANSACTION_FAILED = 2;
040:
041: /**
042: * @return the hostname this connection is connected to.
043: */
044: String getHost();
045:
046: /**
047: * @return the port number this connection is connected to.
048: */
049: int getPort();
050:
051: /**
052: * @return the user this connection authenticated as.
053: */
054: String getUser();
055:
056: /**
057: * @return the database this connection is connected to.
058: */
059: String getDatabase();
060:
061: /**
062: * @return the server version of the connected server, formatted as X.Y.Z.
063: */
064: String getServerVersion();
065:
066: /**
067: * @return the current encoding in use by this connection
068: */
069: Encoding getEncoding();
070:
071: /**
072: * Returns whether the server treats string-literals according to the SQL
073: * standard or if it uses traditional PostgreSQL escaping rules. Versions
074: * up to 8.1 always treated backslashes as escape characters in
075: * string-literals. Since 8.2, this depends on the value of the
076: * <tt>standard_conforming_strings<tt> server variable.
077: *
078: * @return true if the server treats string literals according to the SQL
079: * standard
080: */
081: boolean getStandardConformingStrings();
082:
083: /**
084: * Get the current transaction state of this connection.
085: *
086: * @return a ProtocolConnection.TRANSACTION_* constant.
087: */
088: int getTransactionState();
089:
090: /**
091: * Retrieve and clear the set of asynchronous notifications pending on this
092: * connection.
093: *
094: * @return an array of notifications; if there are no notifications, an empty
095: * array is returned.
096: */
097: PGNotification[] getNotifications() throws SQLException;
098:
099: /**
100: * Retrieve and clear the chain of warnings accumulated on this connection.
101: *
102: * @return the first SQLWarning in the chain; subsequent warnings can be
103: * found via SQLWarning.getNextWarning().
104: */
105: SQLWarning getWarnings();
106:
107: /**
108: * @return the QueryExecutor instance for this connection.
109: */
110: QueryExecutor getQueryExecutor();
111:
112: /**
113: * Sends a query cancellation for this connection.
114: * @throws SQLException if something goes wrong.
115: */
116: void sendQueryCancel() throws SQLException;
117:
118: /**
119: * Close this connection cleanly.
120: */
121: void close();
122:
123: /**
124: * Check if this connection is closed.
125: *
126: * @return true iff the connection is closed.
127: */
128: boolean isClosed();
129:
130: /**
131: *
132: * @return the version of the implementation
133: */
134: public int getProtocolVersion();
135: }
|