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/ParameterList.java,v 1.9 2006/05/22 09:52:36 jurka Exp $
008: *
009: *-------------------------------------------------------------------------
010: */
011: package org.postgresql.core;
012:
013: import java.sql.SQLException;
014: import java.io.InputStream;
015:
016: /**
017: * Abstraction of a list of parameters to be substituted into a Query.
018: * The protocol-specific details of how to efficiently store and stream
019: * the parameters is hidden behind implementations of this interface.
020: *<p>
021: * In general, instances of ParameterList are associated with a particular
022: * Query object (the one that created them) and shouldn't be used against
023: * another Query.
024: *<p>
025: * Parameter indexes are 1-based to match JDBC's PreparedStatement, i.e.
026: * the first parameter has index 1.
027: *
028: * @author Oliver Jowett (oliver@opencloud.com)
029: */
030: public interface ParameterList {
031:
032: void registerOutParameter(int index, int sqlType)
033: throws SQLException;
034:
035: /**
036: * Get the number of parameters in this list. This value never changes
037: * for a particular instance, and might be zero.
038: *
039: * @return the number of parameters in this list.
040: */
041: int getParameterCount();
042:
043: /**
044: * Get the number of IN parameters in this list.
045: *
046: * @return the number of IN parameters in this list
047: */
048: int getInParameterCount();
049:
050: /**
051: * Get the number of OUT parameters in this list.
052: *
053: * @return the number of OUT parameters in this list
054: */
055: int getOutParameterCount();
056:
057: /**
058: * Return the oids of the parameters in this list. May be null for
059: * a ParameterList that does not support typing of parameters.
060: */
061: public int[] getTypeOIDs();
062:
063: /**
064: * Binds an integer value to a parameter. The type of the parameter is
065: * implicitly 'int4'.
066: *
067: * @param index the 1-based parameter index to bind.
068: * @param value the integer value to use.
069: * @throws SQLException on error or if <code>index</code> is out of range
070: */
071: void setIntParameter(int index, int value) throws SQLException;
072:
073: /**
074: * Binds a String value that is an unquoted literal to the
075: * server's query parser (for example, a bare integer) to a parameter.
076: * Associated with the parameter is a typename for the parameter that
077: * should correspond to an entry in pg_types.
078: *
079: * @param index the 1-based parameter index to bind.
080: * @param value the unquoted literal string to use.
081: * @param oid the type OID of the parameter, or <code>0</code>
082: * to infer the type.
083: * @throws SQLException on error or if <code>index</code> is out of range
084: */
085: void setLiteralParameter(int index, String value, int oid)
086: throws SQLException;
087:
088: /**
089: * Binds a String value that needs to be quoted for the server's parser
090: * to understand (for example, a timestamp) to a parameter.
091: * Associated with the parameter is a typename for the parameter that
092: * should correspond to an entry in pg_types.
093: *
094: * @param index the 1-based parameter index to bind.
095: * @param value the quoted string to use.
096: * @param oid the type OID of the parameter, or <code>0</code>
097: * to infer the type.
098: * @throws SQLException on error or if <code>index</code> is out of range
099: */
100: void setStringParameter(int index, String value, int oid)
101: throws SQLException;
102:
103: /**
104: * Binds a binary bytea value stored as a bytearray to a parameter. The
105: * parameter's type is implicitly set to 'bytea'. The bytearray's
106: * contains should remain unchanged until query execution has completed.
107: *
108: * @param index the 1-based parameter index to bind.
109: * @param data an array containing the raw data value
110: * @param offset the offset within <code>data</code> of the start of the parameter data.
111: * @param length the number of bytes of parameter data within <code>data</code> to use.
112: * @throws SQLException on error or if <code>index</code> is out of range
113: */
114: void setBytea(int index, byte[] data, int offset, int length)
115: throws SQLException;
116:
117: /**
118: * Binds a binary bytea value stored as an InputStream. The
119: * parameter's type is implicitly set to 'bytea'. The stream should
120: * remain valid until query execution has completed.
121: *
122: * @param index the 1-based parameter index to bind.
123: * @param stream a stream containing the parameter data.
124: * @param length the number of bytes of parameter data to read from <code>stream</code>.
125: * @throws SQLException on error or if <code>index</code> is out of range
126: */
127: void setBytea(int index, InputStream stream, int length)
128: throws SQLException;
129:
130: /**
131: * Binds a SQL NULL value to a parameter.
132: * Associated with the parameter is a typename for the parameter that
133: * should correspond to an entry in pg_types.
134: *
135: * @param index the 1-based parameter index to bind.
136: * @param oid the type OID of the parameter, or <code>0</code>
137: * to infer the type.
138: * @throws SQLException on error or if <code>index</code> is out of range
139: */
140: void setNull(int index, int oid) throws SQLException;
141:
142: /**
143: * Perform a shallow copy of this ParameterList, returning a new instance
144: * (still suitable for passing to the owning Query). If this ParameterList
145: * is immutable, copy() may return the same immutable object.
146: *
147: * @return a new ParameterList instance
148: */
149: ParameterList copy();
150:
151: /**
152: * Unbind all parameter values bound in this list.
153: */
154: void clear();
155:
156: /**
157: * Return a human-readable representation of a particular parameter in
158: * this ParameterList. If the parameter is not bound, returns "?".
159: *
160: * @param index the 1-based parameter index to bind.
161: * @return a string representation of the parameter.
162: */
163: String toString(int index);
164: }
|