1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
/*-------------------------------------------------------------------------
*
* Copyright (c) 2004-2008, PostgreSQL Global Development Group
* Copyright (c) 2004, Open Cloud Limited.
*
* IDENTIFICATION
* $PostgreSQL: pgjdbc/org/postgresql/core/ParameterList.java,v 1.10 2008/01/08 06:56:27 jurka Exp $
*
*-------------------------------------------------------------------------
*/
package org.postgresql.core;
import java.sql.SQLException;
import java.io.InputStream;
/**
* Abstraction of a list of parameters to be substituted into a Query.
* The protocol-specific details of how to efficiently store and stream
* the parameters is hidden behind implementations of this interface.
*<p>
* In general, instances of ParameterList are associated with a particular
* Query object (the one that created them) and shouldn't be used against
* another Query.
*<p>
* Parameter indexes are 1-based to match JDBC's PreparedStatement, i.e.
* the first parameter has index 1.
*
* @author Oliver Jowett (oliver@opencloud.com)
*/
public interface ParameterList {
void registerOutParameter( int index, int sqlType ) throws SQLException;
/**
* Get the number of parameters in this list. This value never changes
* for a particular instance, and might be zero.
*
* @return the number of parameters in this list.
*/
int getParameterCount();
/**
* Get the number of IN parameters in this list.
*
* @return the number of IN parameters in this list
*/
int getInParameterCount();
/**
* Get the number of OUT parameters in this list.
*
* @return the number of OUT parameters in this list
*/
int getOutParameterCount();
/**
* Return the oids of the parameters in this list. May be null for
* a ParameterList that does not support typing of parameters.
*/
public int[] getTypeOIDs();
/**
* Binds an integer value to a parameter. The type of the parameter is
* implicitly 'int4'.
*
* @param index the 1-based parameter index to bind.
* @param value the integer value to use.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setIntParameter(int index, int value) throws SQLException;
/**
* Binds a String value that is an unquoted literal to the
* server's query parser (for example, a bare integer) to a parameter.
* Associated with the parameter is a typename for the parameter that
* should correspond to an entry in pg_types.
*
* @param index the 1-based parameter index to bind.
* @param value the unquoted literal string to use.
* @param oid the type OID of the parameter, or <code>0</code>
* to infer the type.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setLiteralParameter(int index, String value, int oid) throws SQLException;
/**
* Binds a String value that needs to be quoted for the server's parser
* to understand (for example, a timestamp) to a parameter.
* Associated with the parameter is a typename for the parameter that
* should correspond to an entry in pg_types.
*
* @param index the 1-based parameter index to bind.
* @param value the quoted string to use.
* @param oid the type OID of the parameter, or <code>0</code>
* to infer the type.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setStringParameter(int index, String value, int oid) throws SQLException;
/**
* Binds a binary bytea value stored as a bytearray to a parameter. The
* parameter's type is implicitly set to 'bytea'. The bytearray's
* contains should remain unchanged until query execution has completed.
*
* @param index the 1-based parameter index to bind.
* @param data an array containing the raw data value
* @param offset the offset within <code>data</code> of the start of the parameter data.
* @param length the number of bytes of parameter data within <code>data</code> to use.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setBytea(int index, byte[] data, int offset, int length) throws SQLException;
/**
* Binds a binary bytea value stored as an InputStream. The
* parameter's type is implicitly set to 'bytea'. The stream should
* remain valid until query execution has completed.
*
* @param index the 1-based parameter index to bind.
* @param stream a stream containing the parameter data.
* @param length the number of bytes of parameter data to read from <code>stream</code>.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setBytea(int index, InputStream stream, int length) throws SQLException;
/**
* Binds a SQL NULL value to a parameter.
* Associated with the parameter is a typename for the parameter that
* should correspond to an entry in pg_types.
*
* @param index the 1-based parameter index to bind.
* @param oid the type OID of the parameter, or <code>0</code>
* to infer the type.
* @throws SQLException on error or if <code>index</code> is out of range
*/
void setNull(int index, int oid) throws SQLException;
/**
* Perform a shallow copy of this ParameterList, returning a new instance
* (still suitable for passing to the owning Query). If this ParameterList
* is immutable, copy() may return the same immutable object.
*
* @return a new ParameterList instance
*/
ParameterList copy();
/**
* Unbind all parameter values bound in this list.
*/
void clear();
/**
* Return a human-readable representation of a particular parameter in
* this ParameterList. If the parameter is not bound, returns "?".
*
* @param index the 1-based parameter index to bind.
* @return a string representation of the parameter.
*/
String toString(int index);
}
|
