0001: /*
0002: * Licensed to the Apache Software Foundation (ASF) under one or more
0003: * contributor license agreements. See the NOTICE file distributed with
0004: * this work for additional information regarding copyright ownership.
0005: * The ASF licenses this file to You under the Apache License, Version 2.0
0006: * (the "License"); you may not use this file except in compliance with
0007: * the License. You may obtain a copy of the License at
0008: *
0009: * http://www.apache.org/licenses/LICENSE-2.0
0010: *
0011: * Unless required by applicable law or agreed to in writing, software
0012: * distributed under the License is distributed on an "AS IS" BASIS,
0013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014: * See the License for the specific language governing permissions and
0015: * limitations under the License.
0016: */
0017:
0018: package java.sql;
0019:
0020: import java.math.BigDecimal;
0021: import java.util.Calendar;
0022: import java.util.Map;
0023: import java.net.URL;
0024: import java.io.InputStream;
0025: import java.io.Reader;
0026:
0027: /**
0028: * An interface used to call Stored Procedures.
0029: * <p>
0030: * The JDBC API provides an SQL escape syntax allowing Stored Procedures to be
0031: * called in a standard way for all databases. The JDBC escape syntax has two
0032: * forms. One form includes a result parameter. The second form does not include
0033: * a result parameter. Where the result parameter is used, it must be declared
0034: * as an OUT parameter. Other parameters can be declared as IN, OUT or INOUT.
0035: * Parameters are referenced either by name or by a numerical index, with the
0036: * first parameter being 1, the second 1 and so on. Here are examples of the two
0037: * forms of the escape syntax: <code>
0038: *
0039: * { ?= call <.procedurename>.[([parameter1,parameter2,...])]}
0040: *
0041: * {call <.procedurename>.[([parameter1,parameter2,...])]}
0042: * </code>
0043: * <p>
0044: * IN parameters are set before calling the procedure, using the setter methods
0045: * which are inherited from <code>PreparedStatement</code>. For OUT
0046: * parameters, their Type must be registered before executing the stored
0047: * procedure, and the value is retrieved using the getter methods defined in the
0048: * CallableStatement interface.
0049: * <p>
0050: * CallableStatements can return one or more ResultSets. Where multiple
0051: * ResultSets are returned they are accessed using the methods inherited from
0052: * the <code>Statement</code> interface.
0053: */
0054: public interface CallableStatement extends PreparedStatement {
0055:
0056: /**
0057: * Gets the value of a specified JDBC <code>ARRAY</code> parameter as a
0058: * java.sql.Array.
0059: *
0060: * @param parameterIndex
0061: * the parameter number index, where the first parameter has
0062: * index 1
0063: * @return a java.sql.Array containing the parameter value
0064: * @throws SQLException
0065: * if a database error happens
0066: */
0067: public Array getArray(int parameterIndex) throws SQLException;
0068:
0069: /**
0070: * Gets the value of a specified JDBC ARRAY parameter as a java.sql.Array.
0071: *
0072: * @param parameterName
0073: * the parameter of interest's name
0074: * @return a <code>java.sql.Array</code> containing the parameter value
0075: * @throws SQLException
0076: * if there is a problem accessing the database
0077: */
0078: public Array getArray(String parameterName) throws SQLException;
0079:
0080: /**
0081: * Returns a new {@link BigDecimal} representation of the JDBC
0082: * <code>NUMERIC</code> parameter specified by the input index.
0083: *
0084: * @param parameterIndex
0085: * the parameter number index (starts from 1)
0086: * @return a <code>java.math.BigDecimal</code> with the value of the
0087: * specified parameter. The value <code>null</code> is returned if
0088: * the parameter in question is an SQL <code>NULL</code>
0089: * @throws SQLException
0090: * if there is a problem accessing the database
0091: */
0092: public BigDecimal getBigDecimal(int parameterIndex)
0093: throws SQLException;
0094:
0095: /**
0096: * Returns a new {@link BigDecimal} representation of the JDBC
0097: * <code>NUMERIC</code> parameter specified by the input index. The number
0098: * of digits after the decimal point is specified by <code>scale</code>.
0099: *
0100: * @param parameterIndex
0101: * the parameter number index, where the first parameter has
0102: * index 1
0103: * @param scale
0104: * the number of digits after the decimal point to get
0105: * @return a <code>java.math.BigDecimal</code> with the value of the
0106: * specified parameter. The value <code>null</code> is returned if
0107: * the parameter in question is an SQL <code>NULL</code>
0108: * @throws SQLException
0109: * if there is a problem accessing the database
0110: * @deprecated Use getBigDecimal(int parameterIndex) or getBigDecimal(String
0111: * parameterName)
0112: */
0113: @Deprecated
0114: public BigDecimal getBigDecimal(int parameterIndex, int scale)
0115: throws SQLException;
0116:
0117: /**
0118: * Returns a new {@link BigDecimal} representation of the JDBC
0119: * <code>NUMERIC</code> parameter specified by the input name.
0120: *
0121: * @param parameterName
0122: * the name of the parameter
0123: * @return a java.math.BigDecimal with the value of the specified parameter.
0124: * null if the value is SQL NULL.
0125: * @throws SQLException
0126: * if a database error happens
0127: */
0128: public BigDecimal getBigDecimal(String parameterName)
0129: throws SQLException;
0130:
0131: /**
0132: * Gets the value of a specified JDBC BLOB parameter as a java.sql.Blob
0133: *
0134: * @param parameterIndex
0135: * the parameter number index, where the first parameter has
0136: * index 1
0137: * @return a java.sql.Blob with the value. null if the value is SQL NULL.
0138: * @throws SQLException
0139: * if a database error happens
0140: */
0141: public Blob getBlob(int parameterIndex) throws SQLException;
0142:
0143: /**
0144: * Gets the value of a specified JDBC BLOB parameter as a java.sql.Blob
0145: *
0146: * @param parameterName
0147: * the name of the parameter
0148: * @return a java.sql.Blob with the value. null if the value is SQL NULL.
0149: * @throws SQLException
0150: * if a database error happens
0151: */
0152: public Blob getBlob(String parameterName) throws SQLException;
0153:
0154: /**
0155: * Gets the value of a specified JDBC BIT parameter as a boolean
0156: *
0157: * @param parameterIndex
0158: * the parameter number index, where the first parameter has
0159: * index 1
0160: * @return a boolean representing the parameter value. false if the value is
0161: * SQL NULL
0162: * @throws SQLException
0163: * if a database error happens
0164: */
0165: public boolean getBoolean(int parameterIndex) throws SQLException;
0166:
0167: /**
0168: * Gets the value of a specified JDBC <code>BIT</code> parameter as a
0169: * boolean
0170: *
0171: * @param parameterName
0172: * the parameter of interest's name
0173: * @return a <code>boolean</code> representation of the value of the
0174: * parameter. <code>false</code> is returned if the SQL value is
0175: * <code>NULL</code>.
0176: * @throws SQLException
0177: * if there is a problem accessing the database
0178: */
0179: public boolean getBoolean(String parameterName) throws SQLException;
0180:
0181: /**
0182: * Gets the value of a specified JDBC TINYINT parameter as a byte
0183: *
0184: * @param parameterIndex
0185: * the parameter number index, where the first parameter has
0186: * index 1
0187: * @return a byte with the value of the parameter. 0 if the value is SQL
0188: * NULL.
0189: * @throws SQLException
0190: * if a database error happens
0191: */
0192: public byte getByte(int parameterIndex) throws SQLException;
0193:
0194: /**
0195: * Gets the value of a specified JDBC <code>TINYINT</code> parameter as a
0196: * Java <code>byte</code>.
0197: *
0198: * @param parameterName
0199: * the parameter of interest's name
0200: * @return a <code>byte</code> representation of the value of the
0201: * parameter. <code>0</code> is returned if the SQL value is
0202: * <code>NULL</code>.
0203: * @throws SQLException
0204: * if there is a problem accessing the database
0205: */
0206: public byte getByte(String parameterName) throws SQLException;
0207:
0208: /**
0209: * Returns a byte array representation of the indexed JDBC
0210: * <code>BINARY</code> or <code>VARBINARY</code> parameter.
0211: *
0212: * @param parameterIndex
0213: * the parameter number index, where the first parameter has
0214: * index 1
0215: * @return an array of bytes with the value of the parameter. null if the
0216: * value is SQL NULL.
0217: * @throws SQLException
0218: * if there is a problem accessing the database
0219: */
0220: public byte[] getBytes(int parameterIndex) throws SQLException;
0221:
0222: /**
0223: * Returns a byte array representation of the named JDBC <code>BINARY</code>
0224: * or <code>VARBINARY</code> parameter.
0225: *
0226: * @param parameterName
0227: * the name of the parameter
0228: * @return an array of bytes with the value of the parameter. null if the
0229: * value is SQL NULL.
0230: * @throws SQLException
0231: * if there is a problem accessing the database
0232: */
0233: public byte[] getBytes(String parameterName) throws SQLException;
0234:
0235: /**
0236: * Gets the value of a specified JDBC CLOB parameter as a java.sql.Clob
0237: *
0238: * @param parameterIndex
0239: * the parameter number index, where the first parameter has
0240: * index 1
0241: * @return a java.sql.Clob with the value of the parameter. null if the
0242: * value is SQL NULL.
0243: * @throws SQLException
0244: * if a database error happens
0245: */
0246: public Clob getClob(int parameterIndex) throws SQLException;
0247:
0248: /**
0249: * Gets the value of a specified JDBC CLOB parameter as a java.sql.Clob
0250: *
0251: * @param parameterName
0252: * the name of the parameter
0253: * @return a java.sql.Clob with the value of the parameter. null if the
0254: * value is SQL NULL.
0255: * @throws SQLException
0256: * if a database error happens
0257: */
0258: public Clob getClob(String parameterName) throws SQLException;
0259:
0260: /**
0261: * Gets the value of a specified JDBC DATE parameter as a java.sql.Date.
0262: *
0263: * @param parameterIndex
0264: * the parameter number index, where the first parameter has
0265: * index 1
0266: * @return the java.sql.Date with the parameter value. null if the value is
0267: * SQL NULL.
0268: * @throws SQLException
0269: * if a database error happens
0270: */
0271: public Date getDate(int parameterIndex) throws SQLException;
0272:
0273: /**
0274: * Gets the value of a specified JDBC DATE parameter as a java.sql.Date.,
0275: * using a specified Calendar to construct the date.
0276: * <p>
0277: * The JDBC driver uses the Calendar to create the Date using a particular
0278: * timezone and locale. Default behaviour of the driver is to use the Java
0279: * virtual machine default settings.
0280: *
0281: * @param parameterIndex
0282: * the parameter number index, where the first parameter has
0283: * index 1
0284: * @param cal
0285: * the Calendar to use to construct the Date
0286: * @return the java.sql.Date with the parameter value. null if the value is
0287: * SQL NULL.
0288: * @throws SQLException
0289: * if a database error happens
0290: */
0291: public Date getDate(int parameterIndex, Calendar cal)
0292: throws SQLException;
0293:
0294: /**
0295: * Gets the value of a specified JDBC DATE parameter as a java.sql.Date.
0296: *
0297: * @param parameterName
0298: * the name of the parameter
0299: * @return the java.sql.Date with the parameter value. null if the value is
0300: * SQL NULL.
0301: * @throws SQLException
0302: * if a database error happens
0303: */
0304: public Date getDate(String parameterName) throws SQLException;
0305:
0306: /**
0307: * Gets the value of a specified JDBC DATE parameter as a java.sql.Date.,
0308: * using a specified Calendar to construct the date.
0309: * <p>
0310: * The JDBC driver uses the Calendar to create the Date using a particular
0311: * timezone and locale. Default behaviour of the driver is to use the Java
0312: * virtual machine default settings.
0313: *
0314: * @param parameterName
0315: * the parameter name
0316: * @param cal
0317: * used for creating the returned <code>Date</code>
0318: * @return the java.sql.Date with the parameter value. null if the value is
0319: * SQL NULL.
0320: * @throws SQLException
0321: * if a database error happens
0322: */
0323: public Date getDate(String parameterName, Calendar cal)
0324: throws SQLException;
0325:
0326: /**
0327: * Gets the value of a specified JDBC DOUBLE parameter as a double
0328: *
0329: * @param parameterIndex
0330: * the parameter number index, where the first parameter has
0331: * index 1
0332: * @return the double with the parameter value. 0.0 if the value is SQL
0333: * NULL.
0334: * @throws SQLException
0335: * if a database error happens
0336: */
0337: public double getDouble(int parameterIndex) throws SQLException;
0338:
0339: /**
0340: * Gets the value of a specified JDBC DOUBLE parameter as a double
0341: *
0342: * @param parameterName
0343: * the parameter name
0344: * @return the parameter value as represented in a Java <code>double</code>.
0345: * An SQL value of <code>NULL</code> gets represented as
0346: * <code>0</code> (zero).
0347: * @throws SQLException
0348: * if there is a problem accessing the database
0349: */
0350: public double getDouble(String parameterName) throws SQLException;
0351:
0352: /**
0353: * Gets the value of a specified JDBC FLOAT parameter as a float
0354: *
0355: * @param parameterIndex
0356: * the parameter number index, where the first parameter has
0357: * index 1
0358: * @return the float with the parameter value. 0.0 if the value is SQL NULL.
0359: * @throws SQLException
0360: * if a database error happens
0361: */
0362: public float getFloat(int parameterIndex) throws SQLException;
0363:
0364: /**
0365: * Gets the value of a specified JDBC <code>FLOAT</code> parameter as a
0366: * Java <code>float</code>.
0367: *
0368: * @param parameterName
0369: * the parameter name
0370: * @return the parameter value as represented in a Java <code>float</code>.
0371: * An SQL value of <code>NULL</code> gets represented as
0372: * <code>0</code> (zero).
0373: * @throws SQLException
0374: * if there is a problem accessing the database
0375: */
0376: public float getFloat(String parameterName) throws SQLException;
0377:
0378: /**
0379: * Gets the value of a specified JDBC INTEGER parameter as an int
0380: *
0381: * @param parameterIndex
0382: * the parameter number index, where the first parameter has
0383: * index 1
0384: * @return the int with the parameter value. 0 if the value is SQL NULL.
0385: * @throws SQLException
0386: * if a database error happens
0387: */
0388: public int getInt(int parameterIndex) throws SQLException;
0389:
0390: /**
0391: * Gets the value of a specified JDBC INTEGER parameter as an int
0392: *
0393: * @param parameterName
0394: * the name of the parameter
0395: * @return the int with the parameter value. 0 if the value is SQL NULL.
0396: * @throws SQLException
0397: * if a database error happens
0398: */
0399: public int getInt(String parameterName) throws SQLException;
0400:
0401: /**
0402: * Gets the value of a specified JDBC BIGINT parameter as a long
0403: *
0404: * @param parameterIndex
0405: * the parameter number index, where the first parameter has
0406: * index 1
0407: * @return the long with the parameter value. 0 if the value is SQL NULL.
0408: * @throws SQLException
0409: * if a database error happens
0410: */
0411: public long getLong(int parameterIndex) throws SQLException;
0412:
0413: /**
0414: * Gets the value of a specified JDBC BIGINT parameter as a long
0415: *
0416: * @param parameterName
0417: * the name of the parameter
0418: * @return the long with the parameter value. 0 if the value is SQL NULL.
0419: * @throws SQLException
0420: * if a database error happens
0421: */
0422: public long getLong(String parameterName) throws SQLException;
0423:
0424: /**
0425: * Gets the value of a specified parameter as a Java <code>Object</code>.
0426: * <p>
0427: * The object type returned is the JDBC type registered for the parameter
0428: * with a <code>registerOutParameter</code> call. If a parameter was
0429: * registered as a <code>java.sql.Types.OTHER</code> then it may hold
0430: * abstract types that are particular to the connected database.
0431: *
0432: * @param parameterIndex
0433: * the parameter number index, where the first parameter has
0434: * index 1
0435: * @return an Object holding the value of the parameter.
0436: * @throws SQLException
0437: * if there is a problem accessing the database
0438: */
0439: public Object getObject(int parameterIndex) throws SQLException;
0440:
0441: /**
0442: * Gets the value of a specified parameter as an Object. A Map is supplied
0443: * to provide custom mapping of the parameter value.
0444: *
0445: * @param parameterIndex
0446: * the parameter number index, where the first parameter has
0447: * index 1
0448: * @param map
0449: * the Map holing the mapping from SQL types to Java classes
0450: * @return an Object holding the value of the parameter.
0451: * @throws SQLException
0452: * if a database error happens
0453: */
0454: public Object getObject(int parameterIndex,
0455: Map<String, Class<?>> map) throws SQLException;
0456:
0457: /**
0458: * Gets the value of a specified parameter as an Object.
0459: * <p>
0460: * The object type returned is the JDBC type registered for the parameter
0461: * with a <code>registerOutParameter</code> call. If a parameter was
0462: * registered as a <code>java.sql.Types.OTHER</code> then it may hold
0463: * abstract types that are particular to the connected database.
0464: *
0465: * @param parameterName
0466: * the parameter name
0467: * @return the Java <code>Object</code> representation of the value of the
0468: * parameter.
0469: * @throws SQLException
0470: * if there is a problem accessing the database
0471: */
0472: public Object getObject(String parameterName) throws SQLException;
0473:
0474: /**
0475: * Gets the value of a specified parameter as an Object. A Map is supplied
0476: * to provide custom mapping of the parameter value.
0477: *
0478: * @param parameterName
0479: * the parameter name
0480: * @param map
0481: * the <code>Map</code> of SQL types to their Java counterparts
0482: * @return an <code>Object</code> holding the value of the parameter.
0483: * @throws SQLException
0484: * if there is a problem accessing the database
0485: */
0486: public Object getObject(String parameterName,
0487: Map<String, Class<?>> map) throws SQLException;
0488:
0489: /**
0490: * Gets the value of a specified JDBC REF(<structured type>) parameter as a
0491: * java.sql.Ref
0492: *
0493: * @param parameterIndex
0494: * the parameter number index, where the first parameter has
0495: * index 1
0496: * @return a java.sql.Ref with the parameter value. null if the value is SQL
0497: * NULL.
0498: * @throws SQLException
0499: * if a database error happens
0500: */
0501: public Ref getRef(int parameterIndex) throws SQLException;
0502:
0503: /**
0504: * Gets the value of a specified JDBC REF(<structured type>) parameter as a
0505: * java.sql.Ref
0506: *
0507: * @param parameterName
0508: * the parameter name
0509: * @return the target parameter's value in the form of a
0510: * <code>java.sql.Ref</code>. A <code>null</code> reference is
0511: * returned for a parameter value of SQL <code>NULL</code>.
0512: * @throws SQLException
0513: * if there is a problem accessing the database
0514: */
0515: public Ref getRef(String parameterName) throws SQLException;
0516:
0517: /**
0518: * Gets the value of a specified JDBC SMALLINT parameter as a short
0519: *
0520: * @param parameterIndex
0521: * the parameter number index, where the first parameter has
0522: * index 1
0523: * @return a short with the parameter value. 0 if the value is SQL NULL.
0524: * @throws SQLException
0525: * if a database error happens
0526: */
0527: public short getShort(int parameterIndex) throws SQLException;
0528:
0529: /**
0530: * Gets the value of a specified JDBC <code>SMALLINT</code> parameter as a
0531: * short
0532: *
0533: * @param parameterName
0534: * the parameter name
0535: * @return the value of the target parameter as a Java <code>short</code>.
0536: * If the value is an SQL <code>NULL</code> then <code>0</code>
0537: * (zero) is returned.
0538: * @throws SQLException
0539: * if there is a problem accessing the database
0540: */
0541: public short getShort(String parameterName) throws SQLException;
0542:
0543: /**
0544: * Returns the indexed parameter's value as a string. The parameter value
0545: * must be one of the JDBC types <code>CHAR</code>, <code>VARCHAR</code>
0546: * or <code>LONGVARCHAR</code>.
0547: * <p>
0548: * The string corresponding to a <code>CHAR</code> of fixed length will be
0549: * of identical length to the value in the database inclusive of padding
0550: * characters.
0551: *
0552: * @param parameterIndex
0553: * the parameter number index, where the first parameter has
0554: * index 1
0555: * @return a String with the parameter value. null if the value is SQL NULL.
0556: * @throws SQLException
0557: * if there is a problem accessing the database
0558: */
0559: public String getString(int parameterIndex) throws SQLException;
0560:
0561: /**
0562: * Returns the named parameter's value as a string. The parameter value must
0563: * be one of the JDBC types <code>CHAR</code>, <code>VARCHAR</code> or
0564: * <code>LONGVARCHAR</code>.
0565: * <p>
0566: * The string corresponding to a <code>CHAR</code> of fixed length will be
0567: * of identical length to the value in the database inclusive of padding
0568: * characters.
0569: *
0570: * @param parameterName
0571: * the parameter name
0572: * @return a String with the parameter value. null if the value is SQL NULL.
0573: * @throws SQLException
0574: * if there is a problem accessing the database
0575: */
0576: public String getString(String parameterName) throws SQLException;
0577:
0578: /**
0579: * Gets the value of a specified JDBC TIME parameter as a java.sql.Time.
0580: *
0581: * @param parameterIndex
0582: * the parameter number index, where the first parameter has
0583: * index 1
0584: * @return a java.sql.Time with the parameter value. null if the value is
0585: * SQL NULL.
0586: * @throws SQLException
0587: * if a database error happens
0588: */
0589: public Time getTime(int parameterIndex) throws SQLException;
0590:
0591: /**
0592: * Gets the value of a specified JDBC TIME parameter as a java.sql.Time,
0593: * using the supplied Calendar to construct the time. The JDBC driver uses
0594: * the Calendar to handle specific timezones and locales when creating the
0595: * Time.
0596: *
0597: * @param parameterIndex
0598: * the parameter number index, where the first parameter has
0599: * index 1
0600: * @param cal
0601: * the Calendar to use in constructing the Time.
0602: * @return a java.sql.Time with the parameter value. null if the value is
0603: * SQL NULL.
0604: * @throws SQLException
0605: * if a database error happens
0606: */
0607: public Time getTime(int parameterIndex, Calendar cal)
0608: throws SQLException;
0609:
0610: /**
0611: * Gets the value of a specified JDBC <code>TIME</code> parameter as a
0612: * <codejava.sql.Time</code>
0613: *
0614: * @param parameterName
0615: * the parameter name
0616: * @return a new <code>java.sql.Time</code> with the parameter value. A
0617: * <code>null</code> reference is returned for an SQL value of
0618: * <code>NULL</code>
0619: * @throws SQLException
0620: * if a database error happens
0621: */
0622: public Time getTime(String parameterName) throws SQLException;
0623:
0624: /**
0625: * Gets the value of a specified JDBC TIME parameter as a java.sql.Time,
0626: * using the supplied Calendar to construct the time. The JDBC driver uses
0627: * the Calendar to handle specific timezones and locales when creating the
0628: * Time.
0629: *
0630: * @param parameterName
0631: * the parameter name
0632: * @param cal
0633: * used for creating the returned <code>Time</code>
0634: * @return a <code>java.sql.Time</code> with the parameter value. A
0635: * <code>null</code> reference is returned for an SQL value of
0636: * <code>NULL</code>
0637: * @throws SQLException
0638: * if a database error happens
0639: */
0640: public Time getTime(String parameterName, Calendar cal)
0641: throws SQLException;
0642:
0643: /**
0644: * Returns the indexed parameter's <code>TIMESTAMP</code> value as a
0645: * <code>java.sql.Timestamp</code>.
0646: *
0647: * @param parameterIndex
0648: * the parameter number index, where the first parameter has
0649: * index 1
0650: * @return a new <code>java.sql.Timestamp</code> with the parameter value.
0651: * A <code>null</code> reference is returned for an SQL value of
0652: * <code>NULL</code>
0653: * @throws SQLException
0654: * if a database error happens
0655: */
0656: public Timestamp getTimestamp(int parameterIndex)
0657: throws SQLException;
0658:
0659: /**
0660: * Returns the indexed parameter's <code>TIMESTAMP</code> value as a
0661: * <code>java.sql.Timestamp</code>. The JDBC driver uses the supplied
0662: * <code>Calendar</code> to handle specific timezones and locales when
0663: * creating the result.
0664: *
0665: * @param parameterIndex
0666: * the parameter number index, where the first parameter has
0667: * index 1
0668: * @param cal
0669: * used for creating the returned <code>Timestamp</code>
0670: * @return a new <code>java.sql.Timestamp</code> with the parameter value.
0671: * A <code>null</code> reference is returned for an SQL value of
0672: * <code>NULL</code>
0673: * @throws SQLException
0674: * if a database error happens
0675: */
0676: public Timestamp getTimestamp(int parameterIndex, Calendar cal)
0677: throws SQLException;
0678:
0679: /**
0680: * Returns the named parameter's <code>TIMESTAMP</code> value as a
0681: * <code>java.sql.Timestamp</code>.
0682: *
0683: * @param parameterName
0684: * the parameter name
0685: * @return a new <code>java.sql.Timestamp</code> with the parameter value.
0686: * A <code>null</code> reference is returned for an SQL value of
0687: * <code>NULL</code>
0688: * @throws SQLException
0689: * if a database error happens
0690: */
0691: public Timestamp getTimestamp(String parameterName)
0692: throws SQLException;
0693:
0694: /**
0695: * Returns the indexed parameter's <code>TIMESTAMP</code> value as a
0696: * <code>java.sql.Timestamp</code>. The JDBC driver uses the supplied
0697: * <code>Calendar</code> to handle specific timezones and locales when
0698: * creating the result.
0699: *
0700: * @param parameterName
0701: * the parameter name
0702: * @param cal
0703: * used for creating the returned <code>Timestamp</code>
0704: * @return a new <code>java.sql.Timestamp</code> with the parameter value.
0705: * A <code>null</code> reference is returned for an SQL value of
0706: * <code>NULL</code>
0707: * @throws SQLException
0708: * if a database error happens
0709: */
0710: public Timestamp getTimestamp(String parameterName, Calendar cal)
0711: throws SQLException;
0712:
0713: /**
0714: * Gets the value of a specified JDBC DATALINK parameter as a java.net.URL.
0715: *
0716: * @param parameterIndex
0717: * the parameter number index, where the first parameter has
0718: * index 1
0719: * @return a java.sql.Datalink with the parameter value. null if the value
0720: * is SQL NULL.
0721: * @throws SQLException
0722: * if a database error happens
0723: */
0724: public URL getURL(int parameterIndex) throws SQLException;
0725:
0726: /**
0727: * Returns the named parameter's JDBC <code>DATALINK</code> value in a new
0728: * Java <code>java.net.URL</code>.
0729: *
0730: * @param parameterName
0731: * the parameter name
0732: * @return a new <code>java.net.URL</code> encapsulating the parameter
0733: * value. A <code>null</code> reference is returned for an SQL
0734: * value of <code>NULL</code>
0735: * @throws SQLException
0736: * if a database error happens
0737: */
0738: public URL getURL(String parameterName) throws SQLException;
0739:
0740: /**
0741: * Defines the Type of a specified OUT parameter. All OUT parameters must
0742: * have their Type defined before a stored procedure is executed.
0743: * <p>
0744: * The Type defined by this method fixes the Java type that must be
0745: * retrieved using the getter methods of CallableStatement. If a database
0746: * specific type is expected for a parameter, the Type java.sql.Types.OTHER
0747: * should be used. Note that there is another variant of this method for
0748: * User Defined Types or a REF type.
0749: *
0750: * @param parameterIndex
0751: * the parameter number index, where the first parameter has
0752: * index 1
0753: * @param sqlType
0754: * the JDBC type as defined by java.sql.Types. The JDBC types
0755: * NUMERIC and DECIMAL should be defined using the version of
0756: * <code>registerOutParameter</code> that takes a
0757: * <code>scale</code> parameter.
0758: * @throws SQLException
0759: * if a database error happens
0760: */
0761: public void registerOutParameter(int parameterIndex, int sqlType)
0762: throws SQLException;
0763:
0764: /**
0765: * Defines the Type of a specified OUT parameter. All OUT parameters must
0766: * have their Type defined before a stored procedure is executed. This
0767: * version of the registerOutParameter method, which has a scale parameter,
0768: * should be used for the JDBC types NUMERIC and DECIMAL, where there is a
0769: * need to specify the number of digits expected after the decimal point.
0770: * <p>
0771: * The Type defined by this method fixes the Java type that must be
0772: * retrieved using the getter methods of CallableStatement.
0773: *
0774: * @param parameterIndex
0775: * the parameter number index, where the first parameter has
0776: * index 1
0777: * @param sqlType
0778: * the JDBC type as defined by java.sql.Types.
0779: * @param scale
0780: * the number of digits after the decimal point. Must be greater
0781: * than or equal to 0.
0782: * @throws SQLException
0783: * if a database error happens
0784: */
0785: public void registerOutParameter(int parameterIndex, int sqlType,
0786: int scale) throws SQLException;
0787:
0788: /**
0789: * Defines the Type of a specified OUT parameter. This variant of the method
0790: * is designed for use with parameters that are User Defined Types (UDT) or
0791: * a REF type, although it can be used for any type.
0792: *
0793: * @param paramIndex
0794: * the parameter number index, where the first parameter has
0795: * index 1
0796: * @param sqlType
0797: * a JDBC type expressed as a constant from {@link Types}
0798: * @param typeName
0799: * an SQL type name. For a REF type, this name should be the
0800: * fully qualified name of the referenced type.
0801: * @throws SQLException
0802: * if a database error happens
0803: */
0804: public void registerOutParameter(int paramIndex, int sqlType,
0805: String typeName) throws SQLException;
0806:
0807: /**
0808: * Defines the Type of a specified OUT parameter. All OUT parameters must
0809: * have their Type defined before a stored procedure is executed.
0810: * <p>
0811: * The Type defined by this method fixes the Java type that must be
0812: * retrieved using the getter methods of CallableStatement. If a database
0813: * specific type is expected for a parameter, the Type java.sql.Types.OTHER
0814: * should be used. Note that there is another variant of this method for
0815: * User Defined Types or a REF type.
0816: *
0817: * @param parameterName
0818: * the parameter name
0819: * @param sqlType
0820: * a JDBC type expressed as a constant from {@link Types}. Types
0821: * NUMERIC and DECIMAL should be defined using the variant of
0822: * this method that takes a <code>scale</code> parameter.
0823: * @throws SQLException
0824: * if a database error happens
0825: */
0826: public void registerOutParameter(String parameterName, int sqlType)
0827: throws SQLException;
0828:
0829: /**
0830: * Defines the Type of a specified OUT parameter. All OUT parameters must
0831: * have their Type defined before a stored procedure is executed. This
0832: * version of the registerOutParameter method, which has a scale parameter,
0833: * should be used for the JDBC types NUMERIC and DECIMAL, where there is a
0834: * need to specify the number of digits expected after the decimal point.
0835: * <p>
0836: * The Type defined by this method fixes the Java type that must be
0837: * retrieved using the getter methods of CallableStatement.
0838: *
0839: * @param parameterName
0840: * the parameter name
0841: * @param sqlType
0842: * a JDBC type expressed as a constant from {@link Types}
0843: * @param scale
0844: * the number of digits after the decimal point. Must be greater
0845: * than or equal to 0.
0846: * @throws SQLException
0847: * if a database error happens
0848: */
0849: public void registerOutParameter(String parameterName, int sqlType,
0850: int scale) throws SQLException;
0851:
0852: /**
0853: * Defines the Type of a specified OUT parameter. This variant of the method
0854: * is designed for use with parameters that are User Defined Types (UDT) or
0855: * a REF type, although it can be used for any type.Registers the designated
0856: * output parameter.
0857: *
0858: * @param parameterName
0859: * the parameter name
0860: * @param sqlType
0861: * a JDBC type expressed as a constant from {@link Types}
0862: * @param typeName
0863: * the fully qualified name of an SQL structured type. For a REF
0864: * type, this name should be the fully qualified name of the
0865: * referenced type.
0866: * @throws SQLException
0867: * if a database error happens
0868: */
0869: public void registerOutParameter(String parameterName, int sqlType,
0870: String typeName) throws SQLException;
0871:
0872: /**
0873: * Sets the value of a specified parameter to the content of a supplied
0874: * InputStream, which has a specified number of bytes.
0875: * <p>
0876: * This is a good method for setting an SQL LONVARCHAR parameter where the
0877: * length of the data is large. Data is read from the InputStream until
0878: * end-of-file is reached or the specified number of bytes is copied.
0879: *
0880: * @param parameterName
0881: * the parameter name
0882: * @param theInputStream
0883: * the ASCII InputStream carrying the data to update the
0884: * parameter with
0885: * @param length
0886: * the number of bytes in the InputStream to copy to the
0887: * parameter
0888: * @throws SQLException
0889: * if a database error happens
0890: */
0891: public void setAsciiStream(String parameterName,
0892: InputStream theInputStream, int length) throws SQLException;
0893:
0894: /**
0895: * Sets the value of a specified parameter to a supplied
0896: * java.math.BigDecimal value.
0897: *
0898: * @param parameterName
0899: * the name of the parameter
0900: * @param theBigDecimal
0901: * the java.math.BigInteger value to set
0902: * @throws SQLException
0903: * if a database error happens
0904: */
0905: public void setBigDecimal(String parameterName,
0906: BigDecimal theBigDecimal) throws SQLException;
0907:
0908: /**
0909: * Sets the value of a specified parameter to the content of a supplied
0910: * binary InputStream, which has a specified number of bytes.
0911: * <p>
0912: * Use this method when a large amount of data needs to be set into a
0913: * LONGVARBINARY parameter.
0914: *
0915: * @param parameterName
0916: * the name of the parameter
0917: * @param theInputStream
0918: * the binary InputStream carrying the data to update the
0919: * parameter
0920: * @param length
0921: * the number of bytes in the InputStream to copy to the
0922: * parameter
0923: * @throws SQLException
0924: * if a database error happens
0925: */
0926: public void setBinaryStream(String parameterName,
0927: InputStream theInputStream, int length) throws SQLException;
0928:
0929: /**
0930: * Sets the value of a specified parameter to a supplied boolean value.
0931: *
0932: * @param parameterName
0933: * the parameter name
0934: * @param theBoolean
0935: * the new value with which to update the parameter
0936: * @throws SQLException
0937: * if a database error happens
0938: */
0939: public void setBoolean(String parameterName, boolean theBoolean)
0940: throws SQLException;
0941:
0942: /**
0943: * Sets the value of a specified parameter to a supplied byte value.
0944: *
0945: * @param parameterName
0946: * the parameter name
0947: * @param theByte
0948: * the new value with which to update the parameter
0949: * @throws SQLException
0950: * if a database error happens
0951: */
0952: public void setByte(String parameterName, byte theByte)
0953: throws SQLException;
0954:
0955: /**
0956: * Sets the value of a specified parameter to a supplied array of bytes. The
0957: * array is mapped to <code>VARBINARY</code> or else
0958: * <code>LONGVARBINARY</code> in the connected database.
0959: *
0960: * @param parameterName
0961: * the parameter name
0962: * @param theBytes
0963: * the new value with which to update the parameter
0964: * @throws SQLException
0965: * if a database error happens
0966: */
0967: public void setBytes(String parameterName, byte[] theBytes)
0968: throws SQLException;
0969:
0970: /**
0971: * Sets the value of a specified parameter to the character content of a
0972: * Reader object, with the specified length of character data.
0973: *
0974: * @param parameterName
0975: * the parameter name
0976: * @param reader
0977: * the new value with which to update the parameter
0978: * @param length
0979: * a count of the characters contained in <code>reader</code>
0980: * @throws SQLException
0981: * if a database error happens
0982: */
0983: public void setCharacterStream(String parameterName, Reader reader,
0984: int length) throws SQLException;
0985:
0986: /**
0987: * Sets the value of a specified parameter to a supplied java.sql.Date
0988: * value.
0989: *
0990: * @param parameterName
0991: * the parameter name
0992: * @param theDate
0993: * the new value with which to update the parameter
0994: * @throws SQLException
0995: * if a database error happens
0996: */
0997: public void setDate(String parameterName, Date theDate)
0998: throws SQLException;
0999:
1000: /**
1001: * Sets the value of a specified parameter to a supplied java.sql.Date
1002: * value, using a supplied Calendar to map the Date. The Calendar allows the
1003: * application to control the timezone used to compute the SQL DATE in the
1004: * database - without the supplied Calendar, the driver uses the default
1005: * timezone of the Java virtual machine.
1006: *
1007: * @param parameterName
1008: * the parameter name
1009: * @param theDate
1010: * the new value with which to update the parameter
1011: * @param cal
1012: * a Calendar to use to construct the SQL DATE value
1013: * @throws SQLException
1014: * if a database error happens
1015: */
1016: public void setDate(String parameterName, Date theDate, Calendar cal)
1017: throws SQLException;
1018:
1019: /**
1020: * Sets the value of a specified parameter to a supplied double value.
1021: *
1022: * @param parameterName
1023: * the parameter name
1024: * @param theDouble
1025: * the new value with which to update the parameter
1026: * @throws SQLException
1027: * if a database error happens
1028: */
1029: public void setDouble(String parameterName, double theDouble)
1030: throws SQLException;
1031:
1032: /**
1033: * Sets the value of a specified parameter to to a supplied float value.
1034: *
1035: * @param parameterName
1036: * the parameter name
1037: * @param theFloat
1038: * the new value with which to update the parameter
1039: * @throws SQLException
1040: * if a database error happens
1041: */
1042: public void setFloat(String parameterName, float theFloat)
1043: throws SQLException;
1044:
1045: /**
1046: * Sets the value of a specified parameter to a supplied int value.
1047: *
1048: * @param parameterName
1049: * the parameter name
1050: * @param theInt
1051: * the new value with which to update the parameter
1052: * @throws SQLException
1053: * if a database error happens
1054: */
1055: public void setInt(String parameterName, int theInt)
1056: throws SQLException;
1057:
1058: /**
1059: * Sets the value of a specified parameter to a supplied long value.
1060: *
1061: * @param parameterName
1062: * the parameter name
1063: * @param theLong
1064: * the new value with which to update the parameter
1065: * @throws SQLException
1066: * if a database error happens
1067: */
1068: public void setLong(String parameterName, long theLong)
1069: throws SQLException;
1070:
1071: /**
1072: * Sets the value of a specified parameter to SQL NULL. Don't use this
1073: * version of setNull for User Defined Types or for REF type parameters.
1074: *
1075: * @param parameterName
1076: * the parameter name
1077: * @param sqlType
1078: * a JDBC type expressed as a constant from {@link Types}
1079: * @throws SQLException
1080: * if a database error happens
1081: */
1082: public void setNull(String parameterName, int sqlType)
1083: throws SQLException;
1084:
1085: /**
1086: * Sets the value of a specified parameter to be SQL NULL where the
1087: * parameter type is either <code>REF</code> or user defined (e.g.
1088: * <code>STRUCT</code>, <code>JAVA_OBJECT</code> etc).
1089: * <p>
1090: * For reasons of portability, the caller is expected to supply both the SQL
1091: * Type code and Type name (which is just the parameter name if the type is
1092: * user defined, or the name of the type being referenced if a REF).
1093: *
1094: * @param parameterName
1095: * the parameter name
1096: * @param sqlType
1097: * a JDBC type expressed as a constant from {@link Types}
1098: * @param typeName
1099: * if the target parameter is a user defined type then this
1100: * should contain the full type name
1101: *
1102: * the fully qualified name of a UDT or REF type - ignored if the parameter
1103: * is not a UDT.
1104: * @throws SQLException
1105: * if a database error happens
1106: */
1107: public void setNull(String parameterName, int sqlType,
1108: String typeName) throws SQLException;
1109:
1110: /**
1111: * Sets the value of a specified parameter using a supplied object. Prior to
1112: * issuing this request to the connected database <code>theObject</code>
1113: * is transformed to the corresponding SQL type according to the normal Java
1114: * to SQL mapping rules.
1115: * <p>
1116: * If the object's class implements the interface SQLData, the JDBC driver
1117: * calls <code>SQLData.writeSQL</code> to write it to the SQL data stream.
1118: * If <code>theObject</code> implements any of the following interfaces
1119: * then it is the role of the driver to flow the value to the connected
1120: * database using the appropriate SQL type :
1121: * <ul>
1122: * <li>{@link Ref}
1123: * <li>{@link Struct}
1124: * <li>{@link Array}
1125: * <li>{@link Clob}
1126: * <li>{@link Blob}
1127: * </ul>
1128: *
1129: * @param parameterName
1130: * the parameter name
1131: * @param theObject
1132: * the new value with which to update the parameter
1133: * @throws SQLException
1134: * if a database error happens
1135: */
1136: public void setObject(String parameterName, Object theObject)
1137: throws SQLException;
1138:
1139: /**
1140: * Sets the value of a specified parameter using a supplied object.
1141: * <p>
1142: * The Object is converted to the given targetSqlType before it is sent to
1143: * the database. If the object has a custom mapping (its class implements
1144: * the interface SQLData), the JDBC driver will call the method
1145: * SQLData.writeSQL to write it to the SQL data stream. If
1146: * <code>theObject</code> implements any of the following interfaces then
1147: * it is the role of the driver to flow the value to the connected database
1148: * using the appropriate SQL type :
1149: * <ul>
1150: * <li>{@link Ref}
1151: * <li>{@link Struct}
1152: * <li>{@link Array}
1153: * <li>{@link Clob}
1154: * <li>{@link Blob}
1155: * </ul>
1156: *
1157: * @param parameterName
1158: * the parameter name
1159: * @param theObject
1160: * the new value with which to update the parameter
1161: * @param targetSqlType
1162: * a JDBC type expressed as a constant from {@link Types}
1163: * @throws SQLException
1164: * if a database error happens
1165: */
1166: public void setObject(String parameterName, Object theObject,
1167: int targetSqlType) throws SQLException;
1168:
1169: /**
1170: * Sets the value of a specified parameter using a supplied object.
1171: * <p>
1172: * The Object is converted to the given targetSqlType before it is sent to
1173: * the database. If the object has a custom mapping (its class implements
1174: * the interface SQLData), the JDBC driver will call the method
1175: * SQLData.writeSQL to write it to the SQL data stream. If
1176: * <code>theObject</code> implements any of the following interfaces then
1177: * it is the role of the driver to flow the value to the connected database
1178: * using the appropriate SQL type :
1179: * <ul>
1180: * <li>{@link Ref}
1181: * <li>{@link Struct}
1182: * <li>{@link Array}
1183: * <li>{@link Clob}
1184: * <li>{@link Blob}
1185: * </ul>
1186: *
1187: * @param parameterName
1188: * the parameter name
1189: * @param theObject
1190: * the new value with which to update the parameter
1191: * @param targetSqlType
1192: * a JDBC type expressed as a constant from {@link Types}
1193: * @param scale
1194: * where applicable, the number of digits after the decimal
1195: * point.
1196: * @throws SQLException
1197: * if a database error happens
1198: */
1199: public void setObject(String parameterName, Object theObject,
1200: int targetSqlType, int scale) throws SQLException;
1201:
1202: /**
1203: * Sets the value of a specified parameter to a supplied short value.
1204: *
1205: * @param parameterName
1206: * the name of the parameter
1207: * @param theShort
1208: * a short value to update the parameter
1209: * @throws SQLException
1210: * if a database error happens
1211: */
1212: public void setShort(String parameterName, short theShort)
1213: throws SQLException;
1214:
1215: /**
1216: * Sets the value of a specified parameter to a supplied String.
1217: *
1218: * @param parameterName
1219: * the name of the parameter
1220: * @param theString
1221: * a String value to update the parameter
1222: * @throws SQLException
1223: * if a database error happens
1224: */
1225: public void setString(String parameterName, String theString)
1226: throws SQLException;
1227:
1228: /**
1229: * Sets the value of the parameter named <code>parameterName</code> to the
1230: * value of the supplied <code>java.sql.Time</code>.
1231: *
1232: * @param parameterName
1233: * the parameter name
1234: * @param theTime
1235: * the new value with which to update the parameter
1236: * @throws SQLException
1237: * if a database error happens
1238: */
1239: public void setTime(String parameterName, Time theTime)
1240: throws SQLException;
1241:
1242: /**
1243: * Sets the value of the parameter named <code>parameterName</code> to the
1244: * value of the supplied <code>java.sql.Time</code> using the supplied
1245: * Calendar.
1246: * <p>
1247: * The driver uses the supplied Calendar to create the SQL TIME value, which
1248: * allows it to use a custom timezone - otherwise the driver uses the
1249: * default timezone of the Java virtual machine.
1250: *
1251: * @param parameterName
1252: * the parameter name
1253: * @param theTime
1254: * the new value with which to update the parameter
1255: * @param cal
1256: * used for creating the new SQL <code>TIME</code> value
1257: * @throws SQLException
1258: * if a database error happens
1259: */
1260: public void setTime(String parameterName, Time theTime, Calendar cal)
1261: throws SQLException;
1262:
1263: /**
1264: * Sets the value of a specified parameter to a supplied java.sql.Timestamp
1265: * value.
1266: *
1267: * @param parameterName
1268: * the parameter name
1269: * @param theTimestamp
1270: * the new value with which to update the parameter
1271: * @throws SQLException
1272: * if a database error happens
1273: */
1274: public void setTimestamp(String parameterName,
1275: Timestamp theTimestamp) throws SQLException;
1276:
1277: /**
1278: * Sets the value of a specified parameter to a supplied java.sql.Timestamp
1279: * value, using the supplied Calendar.
1280: * <p>
1281: * The driver uses the supplied Calendar to create the SQL TIMESTAMP value,
1282: * which allows it to use a custom timezone - otherwise the driver uses the
1283: * default timezone of the Java virtual machine.
1284: *
1285: * @param parameterName
1286: * the parameter name
1287: * @param theTimestamp
1288: * the new value with which to update the parameter
1289: * @param cal
1290: * used for creating the new SQL <code>TIME</code> value
1291: * @throws SQLException
1292: * if a database error happens
1293: */
1294: public void setTimestamp(String parameterName,
1295: Timestamp theTimestamp, Calendar cal) throws SQLException;
1296:
1297: /**
1298: * Sets the value of a specified parameter to the supplied java.net.URL.
1299: *
1300: * @param parameterName
1301: * the parameter name
1302: * @param theURL
1303: * the new value with which to update the parameter
1304: * @throws SQLException
1305: * if a database error happens
1306: */
1307: public void setURL(String parameterName, URL theURL)
1308: throws SQLException;
1309:
1310: /**
1311: * Gets whether the value of the last OUT parameter read was SQL NULL.
1312: *
1313: * @return true if the last parameter was SQL NULL, false otherwise.
1314: * @throws SQLException
1315: * if a database error happens
1316: */
1317: public boolean wasNull() throws SQLException;
1318: }
|