History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/javax/sql (112 of 18352 files). Show all

Unified · Split

112 files
  1. java/pkg/javax/sql/CommonDataSource.class +0 −0
  2. java/pkg/javax/sql/CommonDataSource.java +129 −0
  3. java/pkg/javax/sql/ConnectionEvent.class +0 −0
  4. java/pkg/javax/sql/ConnectionEvent.java +95 −0
  5. java/pkg/javax/sql/ConnectionEventListener.class +0 −0
  6. java/pkg/javax/sql/ConnectionEventListener.java +76 −0
  7. java/pkg/javax/sql/ConnectionPoolDataSource.class +0 −0
  8. java/pkg/javax/sql/ConnectionPoolDataSource.java +73 −0
  9. java/pkg/javax/sql/DataSource.class +0 −0
  10. java/pkg/javax/sql/DataSource.java +99 −0
  11. java/pkg/javax/sql/PooledConnection.class +0 −0
  12. java/pkg/javax/sql/PooledConnection.java +178 −0
  13. java/pkg/javax/sql/RowSet.class +0 −0
  14. java/pkg/javax/sql/RowSet.java +2186 −0
  15. java/pkg/javax/sql/RowSetEvent.class +0 −0
  16. java/pkg/javax/sql/RowSetEvent.java +62 −0
  17. java/pkg/javax/sql/RowSetInternal.class +0 −0
  18. java/pkg/javax/sql/RowSetInternal.java +103 −0
  19. java/pkg/javax/sql/RowSetListener.class +0 −0
  20. java/pkg/javax/sql/RowSetListener.java +77 −0
  21. java/pkg/javax/sql/RowSetMetaData.class +0 −0
  22. java/pkg/javax/sql/RowSetMetaData.java +235 −0
  23. java/pkg/javax/sql/RowSetReader.class +0 −0
  24. java/pkg/javax/sql/RowSetReader.java +73 −0
  25. java/pkg/javax/sql/RowSetWriter.class +0 −0
  26. java/pkg/javax/sql/RowSetWriter.java +64 −0
  27. java/pkg/javax/sql/StatementEvent.class +0 −0
  28. java/pkg/javax/sql/StatementEvent.java +117 −0
  29. java/pkg/javax/sql/StatementEventListener.class +0 −0
  30. java/pkg/javax/sql/StatementEventListener.java +86 −0
  31. java/pkg/javax/sql/XAConnection.class +0 −0
  32. java/pkg/javax/sql/XAConnection.java +61 −0
  33. java/pkg/javax/sql/XADataSource.class +0 −0
  34. java/pkg/javax/sql/XADataSource.java +73 −0
  35. java/pkg/javax/sql/mkfile +28 −0
  36. java/pkg/javax/sql/package.html +316 −0
  37. java/pkg/javax/sql/rowset/BaseRowSet.class +0 −0
  38. java/pkg/javax/sql/rowset/BaseRowSet.java +4512 −0
  39. java/pkg/javax/sql/rowset/CachedRowSet.class +0 −0
  40. java/pkg/javax/sql/rowset/CachedRowSet.java +1625 −0
  41. java/pkg/javax/sql/rowset/FilteredRowSet.class +0 −0
  42. java/pkg/javax/sql/rowset/FilteredRowSet.java +160 −0
  43. java/pkg/javax/sql/rowset/JdbcRowSet.class +0 −0
  44. java/pkg/javax/sql/rowset/JdbcRowSet.java +287 −0
  45. java/pkg/javax/sql/rowset/JoinRowSet.class +0 −0
  46. java/pkg/javax/sql/rowset/JoinRowSet.java +537 −0
  47. java/pkg/javax/sql/rowset/Joinable.class +0 −0
  48. java/pkg/javax/sql/rowset/Joinable.java +291 −0
  49. java/pkg/javax/sql/rowset/Predicate.class +0 −0
  50. java/pkg/javax/sql/rowset/Predicate.java +164 −0
  51. java/pkg/javax/sql/rowset/RowSetFactory.class +0 −0
  52. java/pkg/javax/sql/rowset/RowSetFactory.java +99 −0
  53. java/pkg/javax/sql/rowset/RowSetMetaDataImpl$1.class +0 −0
  54. java/pkg/javax/sql/rowset/RowSetMetaDataImpl$ColInfo.class +0 −0
  55. java/pkg/javax/sql/rowset/RowSetMetaDataImpl.class +0 −0
  56. java/pkg/javax/sql/rowset/RowSetMetaDataImpl.java +1095 −0
  57. java/pkg/javax/sql/rowset/RowSetProvider$1.class +0 −0
  58. java/pkg/javax/sql/rowset/RowSetProvider$2.class +0 −0
  59. java/pkg/javax/sql/rowset/RowSetProvider.class +0 −0
  60. java/pkg/javax/sql/rowset/RowSetProvider.java +311 −0
  61. java/pkg/javax/sql/rowset/RowSetWarning.class +0 −0
  62. java/pkg/javax/sql/rowset/RowSetWarning.java +146 −0
  63. java/pkg/javax/sql/rowset/WebRowSet.class +0 −0
  64. java/pkg/javax/sql/rowset/WebRowSet.java +499 −0
  65. java/pkg/javax/sql/rowset/mkfile +24 −0
  66. java/pkg/javax/sql/rowset/package.html +309 −0
  67. java/pkg/javax/sql/rowset/rowset.properties +12 −0
  68. java/pkg/javax/sql/rowset/serial/SQLInputImpl.class +0 −0
  69. java/pkg/javax/sql/rowset/serial/SQLInputImpl.java +830 −0
  70. java/pkg/javax/sql/rowset/serial/SQLOutputImpl.class +0 −0
  71. java/pkg/javax/sql/rowset/serial/SQLOutputImpl.java +618 −0
  72. java/pkg/javax/sql/rowset/serial/SerialArray.class +0 −0
  73. java/pkg/javax/sql/rowset/serial/SerialArray.java +535 −0
  74. java/pkg/javax/sql/rowset/serial/SerialBlob.class +0 −0
  75. java/pkg/javax/sql/rowset/serial/SerialBlob.java +457 −0
  76. java/pkg/javax/sql/rowset/serial/SerialClob.class +0 −0
  77. java/pkg/javax/sql/rowset/serial/SerialClob.java +522 −0
  78. java/pkg/javax/sql/rowset/serial/SerialDatalink.class +0 −0
  79. java/pkg/javax/sql/rowset/serial/SerialDatalink.java +109 −0
  80. java/pkg/javax/sql/rowset/serial/SerialException.class +0 −0
  81. java/pkg/javax/sql/rowset/serial/SerialException.java +56 −0
  82. java/pkg/javax/sql/rowset/serial/SerialJavaObject.class +0 −0
  83. java/pkg/javax/sql/rowset/serial/SerialJavaObject.java +156 −0
  84. java/pkg/javax/sql/rowset/serial/SerialRef.class +0 −0
  85. java/pkg/javax/sql/rowset/serial/SerialRef.java +172 −0
  86. java/pkg/javax/sql/rowset/serial/SerialStruct.class +0 −0
  87. java/pkg/javax/sql/rowset/serial/SerialStruct.java +254 −0
  88. java/pkg/javax/sql/rowset/serial/mkfile +17 −0
  89. java/pkg/javax/sql/rowset/serial/package.html +239 −0
  90. java/pkg/javax/sql/rowset/spi/ProviderImpl.class +0 −0
  91. java/pkg/javax/sql/rowset/spi/SyncFactory$1.class +0 −0
  92. java/pkg/javax/sql/rowset/spi/SyncFactory$SyncFactoryHolder.class +0 −0
  93. java/pkg/javax/sql/rowset/spi/SyncFactory.class +0 −0
  94. java/pkg/javax/sql/rowset/spi/SyncFactory.java +934 −0
  95. java/pkg/javax/sql/rowset/spi/SyncFactoryException.class +0 −0
  96. java/pkg/javax/sql/rowset/spi/SyncFactoryException.java +58 −0
  97. java/pkg/javax/sql/rowset/spi/SyncProvider.class +0 −0
  98. java/pkg/javax/sql/rowset/spi/SyncProvider.java +430 −0
  99. java/pkg/javax/sql/rowset/spi/SyncProviderException.class +0 −0
  100. java/pkg/javax/sql/rowset/spi/SyncProviderException.java +164 −0
  101. java/pkg/javax/sql/rowset/spi/SyncResolver.class +0 −0
  102. java/pkg/javax/sql/rowset/spi/SyncResolver.java +372 −0
  103. java/pkg/javax/sql/rowset/spi/TransactionalWriter.class +0 −0
  104. java/pkg/javax/sql/rowset/spi/TransactionalWriter.java +83 −0
  105. java/pkg/javax/sql/rowset/spi/XmlReader.class +0 −0
  106. java/pkg/javax/sql/rowset/spi/XmlReader.java +74 −0
  107. java/pkg/javax/sql/rowset/spi/XmlWriter.class +0 −0
  108. java/pkg/javax/sql/rowset/spi/XmlWriter.java +74 −0
  109. java/pkg/javax/sql/rowset/spi/mkfile +15 −0
  110. java/pkg/javax/sql/rowset/spi/package.html +510 −0
  111. java/pkg/javax/sql/rowset/sqlxml.xsd +162 −0
  112. java/pkg/javax/sql/rowset/webrowset.xsd +160 −0
java/pkg/javax/sql/CommonDataSource.class+0−0

Binary file not shown.

java/pkg/javax/sql/CommonDataSource.java+129−0
@@ -0,0 +1,129 @@
1+/*
2+ * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.SQLException;
29+import java.io.PrintWriter;
30+import java.sql.SQLFeatureNotSupportedException;
31+import java.util.logging.Logger;
32+
33+/**
34+ * Interface that defines the methods which are common between <code>DataSource</code>,
35+ * <code>XADataSource</code> and <code>ConnectionPoolDataSource</code>.
36+ *<p>
37+ */
38+public interface CommonDataSource {
39+
40+ /**
41+ * <p>Retrieves the log writer for this <code>DataSource</code>
42+ * object.
43+ *
44+ * <p>The log writer is a character output stream to which all logging
45+ * and tracing messages for this data source will be
46+ * printed. This includes messages printed by the methods of this
47+ * object, messages printed by methods of other objects manufactured
48+ * by this object, and so on. Messages printed to a data source
49+ * specific log writer are not printed to the log writer associated
50+ * with the <code>java.sql.DriverManager</code> class. When a
51+ * <code>DataSource</code> object is
52+ * created, the log writer is initially null; in other words, the
53+ * default is for logging to be disabled.
54+ *
55+ * @return the log writer for this data source or null if
56+ * logging is disabled
57+ * @exception java.sql.SQLException if a database access error occurs
58+ * @see #setLogWriter
59+ * @since 1.4
60+ */
61+ java.io.PrintWriter getLogWriter() throws SQLException;
62+
63+ /**
64+ * <p>Sets the log writer for this <code>DataSource</code>
65+ * object to the given <code>java.io.PrintWriter</code> object.
66+ *
67+ * <p>The log writer is a character output stream to which all logging
68+ * and tracing messages for this data source will be
69+ * printed. This includes messages printed by the methods of this
70+ * object, messages printed by methods of other objects manufactured
71+ * by this object, and so on. Messages printed to a data source-
72+ * specific log writer are not printed to the log writer associated
73+ * with the <code>java.sql.DriverManager</code> class. When a
74+ * <code>DataSource</code> object is created the log writer is
75+ * initially null; in other words, the default is for logging to be
76+ * disabled.
77+ *
78+ * @param out the new log writer; to disable logging, set to null
79+ * @exception SQLException if a database access error occurs
80+ * @see #getLogWriter
81+ * @since 1.4
82+ */
83+ void setLogWriter(java.io.PrintWriter out) throws SQLException;
84+
85+ /**
86+ * <p>Sets the maximum time in seconds that this data source will wait
87+ * while attempting to connect to a database. A value of zero
88+ * specifies that the timeout is the default system timeout
89+ * if there is one; otherwise, it specifies that there is no timeout.
90+ * When a <code>DataSource</code> object is created, the login timeout is
91+ * initially zero.
92+ *
93+ * @param seconds the data source login time limit
94+ * @exception SQLException if a database access error occurs.
95+ * @see #getLoginTimeout
96+ * @since 1.4
97+ */
98+ void setLoginTimeout(int seconds) throws SQLException;
99+
100+ /**
101+ * Gets the maximum time in seconds that this data source can wait
102+ * while attempting to connect to a database. A value of zero
103+ * means that the timeout is the default system timeout
104+ * if there is one; otherwise, it means that there is no timeout.
105+ * When a <code>DataSource</code> object is created, the login timeout is
106+ * initially zero.
107+ *
108+ * @return the data source login time limit
109+ * @exception SQLException if a database access error occurs.
110+ * @see #setLoginTimeout
111+ * @since 1.4
112+ */
113+ int getLoginTimeout() throws SQLException;
114+
115+ //------------------------- JDBC 4.1 -----------------------------------
116+
117+ /**
118+ * Return the parent Logger of all the Loggers used by this data source. This
119+ * should be the Logger farthest from the root Logger that is
120+ * still an ancestor of all of the Loggers used by this data source. Configuring
121+ * this Logger will affect all of the log messages generated by the data source.
122+ * In the worst case, this may be the root Logger.
123+ *
124+ * @return the parent Logger for this data source
125+ * @throws SQLFeatureNotSupportedException if the data source does not use <code>java.util.logging<code>.
126+ * @since 1.7
127+ */
128+ public Logger getParentLogger() throws SQLFeatureNotSupportedException;
129+}
java/pkg/javax/sql/ConnectionEvent.class+0−0

Binary file not shown.

java/pkg/javax/sql/ConnectionEvent.java+95−0
@@ -0,0 +1,95 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.SQLException;
29+
30+/**
31+ * <P>An <code>Event</code> object that provides information about the
32+ * source of a connection-related event. <code>ConnectionEvent</code>
33+ * objects are generated when an application closes a pooled connection
34+ * and when an error occurs. The <code>ConnectionEvent</code> object
35+ * contains two kinds of information:
36+ * <UL>
37+ * <LI>The pooled connection closed by the application
38+ * <LI>In the case of an error event, the <code>SQLException</code>
39+ * about to be thrown to the application
40+ * </UL>
41+ *
42+ * @since 1.4
43+ */
44+
45+public class ConnectionEvent extends java.util.EventObject {
46+
47+ /**
48+ * <P>Constructs a <code>ConnectionEvent</code> object initialized with
49+ * the given <code>PooledConnection</code> object. <code>SQLException</code>
50+ * defaults to <code>null</code>.
51+ *
52+ * @param con the pooled connection that is the source of the event
53+ * @throws IllegalArgumentException if <code>con</code> is null.
54+ */
55+ public ConnectionEvent(PooledConnection con) {
56+ super(con);
57+ }
58+
59+ /**
60+ * <P>Constructs a <code>ConnectionEvent</code> object initialized with
61+ * the given <code>PooledConnection</code> object and
62+ * <code>SQLException</code> object.
63+ *
64+ * @param con the pooled connection that is the source of the event
65+ * @param ex the SQLException about to be thrown to the application
66+ * @throws IllegalArgumentException if <code>con</code> is null.
67+ */
68+ public ConnectionEvent(PooledConnection con, SQLException ex) {
69+ super(con);
70+ this.ex = ex;
71+ }
72+
73+ /**
74+ * <P>Retrieves the <code>SQLException</code> for this
75+ * <code>ConnectionEvent</code> object. May be <code>null</code>.
76+ *
77+ * @return the SQLException about to be thrown or <code>null</code>
78+ */
79+ public SQLException getSQLException() { return ex; }
80+
81+ /**
82+ * The <code>SQLException</code> that the driver will throw to the
83+ * application when an error occurs and the pooled connection is no
84+ * longer usable.
85+ * @serial
86+ */
87+ private SQLException ex = null;
88+
89+ /**
90+ * Private serial version unique ID to ensure serialization
91+ * compatibility.
92+ */
93+ static final long serialVersionUID = -4843217645290030002L;
94+
95+ }
java/pkg/javax/sql/ConnectionEventListener.class+0−0

Binary file not shown.

java/pkg/javax/sql/ConnectionEventListener.java+76−0
@@ -0,0 +1,76 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+/**
29+ * <P>
30+ * An object that registers to be notified of events generated by a
31+ * <code>PooledConnection</code> object.
32+ * <P>
33+ * The <code>ConnectionEventListener</code> interface is implemented by a
34+ * connection pooling component. A connection pooling component will
35+ * usually be provided by a JDBC driver vendor or another system software
36+ * vendor. A JDBC driver notifies a <code>ConnectionEventListener</code>
37+ * object when an application is finished using a pooled connection with
38+ * which the listener has registered. The notification
39+ * occurs after the application calls the method <code>close</code> on
40+ * its representation of a <code>PooledConnection</code> object. A
41+ * <code>ConnectionEventListener</code> is also notified when a
42+ * connection error occurs due to the fact that the <code>PooledConnection</code>
43+ * is unfit for future use---the server has crashed, for example.
44+ * The listener is notified by the JDBC driver just before the driver throws an
45+ * <code>SQLException</code> to the application using the
46+ * <code>PooledConnection</code> object.
47+ *
48+ * @since 1.4
49+ */
50+
51+public interface ConnectionEventListener extends java.util.EventListener {
52+
53+ /**
54+ * Notifies this <code>ConnectionEventListener</code> that
55+ * the application has called the method <code>close</code> on its
56+ * representation of a pooled connection.
57+ *
58+ * @param event an event object describing the source of
59+ * the event
60+ */
61+ void connectionClosed(ConnectionEvent event);
62+
63+ /**
64+ * Notifies this <code>ConnectionEventListener</code> that
65+ * a fatal error has occurred and the pooled connection can
66+ * no longer be used. The driver makes this notification just
67+ * before it throws the application the <code>SQLException</code>
68+ * contained in the given <code>ConnectionEvent</code> object.
69+ *
70+ * @param event an event object describing the source of
71+ * the event and containing the <code>SQLException</code> that the
72+ * driver is about to throw
73+ */
74+ void connectionErrorOccurred(ConnectionEvent event);
75+
76+ }
java/pkg/javax/sql/ConnectionPoolDataSource.class+0−0

Binary file not shown.

java/pkg/javax/sql/ConnectionPoolDataSource.java+73−0
@@ -0,0 +1,73 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.SQLException;
29+
30+
31+/**
32+ * A factory for <code>PooledConnection</code>
33+ * objects. An object that implements this interface will typically be
34+ * registered with a naming service that is based on the
35+ * Java<sup><font size=-2>TM</font></sup> Naming and Directory Interface
36+ * (JNDI).
37+ *
38+ * @since 1.4
39+ */
40+
41+public interface ConnectionPoolDataSource extends CommonDataSource {
42+
43+ /**
44+ * Attempts to establish a physical database connection that can
45+ * be used as a pooled connection.
46+ *
47+ * @return a <code>PooledConnection</code> object that is a physical
48+ * connection to the database that this
49+ * <code>ConnectionPoolDataSource</code> object represents
50+ * @exception SQLException if a database access error occurs
51+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
52+ * this method
53+ * @since 1.4
54+ */
55+ PooledConnection getPooledConnection() throws SQLException;
56+
57+ /**
58+ * Attempts to establish a physical database connection that can
59+ * be used as a pooled connection.
60+ *
61+ * @param user the database user on whose behalf the connection is being made
62+ * @param password the user's password
63+ * @return a <code>PooledConnection</code> object that is a physical
64+ * connection to the database that this
65+ * <code>ConnectionPoolDataSource</code> object represents
66+ * @exception SQLException if a database access error occurs
67+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
68+ * this method
69+ * @since 1.4
70+ */
71+ PooledConnection getPooledConnection(String user, String password)
72+ throws SQLException;
73+ }
java/pkg/javax/sql/DataSource.class+0−0

Binary file not shown.

java/pkg/javax/sql/DataSource.java+99−0
@@ -0,0 +1,99 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.Connection;
29+import java.sql.SQLException;
30+import java.sql.Wrapper;
31+
32+/**
33+ * <p>A factory for connections to the physical data source that this
34+ * <code>DataSource</code> object represents. An alternative to the
35+ * <code>DriverManager</code> facility, a <code>DataSource</code> object
36+ * is the preferred means of getting a connection. An object that implements
37+ * the <code>DataSource</code> interface will typically be
38+ * registered with a naming service based on the
39+ * Java<sup><font size=-2>TM</font></sup> Naming and Directory (JNDI) API.
40+ * <P>
41+ * The <code>DataSource</code> interface is implemented by a driver vendor.
42+ * There are three types of implementations:
43+ * <OL>
44+ * <LI>Basic implementation -- produces a standard <code>Connection</code>
45+ * object
46+ * <LI>Connection pooling implementation -- produces a <code>Connection</code>
47+ * object that will automatically participate in connection pooling. This
48+ * implementation works with a middle-tier connection pooling manager.
49+ * <LI>Distributed transaction implementation -- produces a
50+ * <code>Connection</code> object that may be used for distributed
51+ * transactions and almost always participates in connection pooling.
52+ * This implementation works with a middle-tier
53+ * transaction manager and almost always with a connection
54+ * pooling manager.
55+ * </OL>
56+ * <P>
57+ * A <code>DataSource</code> object has properties that can be modified
58+ * when necessary. For example, if the data source is moved to a different
59+ * server, the property for the server can be changed. The benefit is that
60+ * because the data source's properties can be changed, any code accessing
61+ * that data source does not need to be changed.
62+ * <P>
63+ * A driver that is accessed via a <code>DataSource</code> object does not
64+ * register itself with the <code>DriverManager</code>. Rather, a
65+ * <code>DataSource</code> object is retrieved though a lookup operation
66+ * and then used to create a <code>Connection</code> object. With a basic
67+ * implementation, the connection obtained through a <code>DataSource</code>
68+ * object is identical to a connection obtained through the
69+ * <code>DriverManager</code> facility.
70+ *
71+ * @since 1.4
72+ */
73+
74+public interface DataSource extends CommonDataSource,Wrapper {
75+
76+ /**
77+ * <p>Attempts to establish a connection with the data source that
78+ * this <code>DataSource</code> object represents.
79+ *
80+ * @return a connection to the data source
81+ * @exception SQLException if a database access error occurs
82+ */
83+ Connection getConnection() throws SQLException;
84+
85+ /**
86+ * <p>Attempts to establish a connection with the data source that
87+ * this <code>DataSource</code> object represents.
88+ *
89+ * @param username the database user on whose behalf the connection is
90+ * being made
91+ * @param password the user's password
92+ * @return a connection to the data source
93+ * @exception SQLException if a database access error occurs
94+ * @since 1.4
95+ */
96+ Connection getConnection(String username, String password)
97+ throws SQLException;
98+
99+}
java/pkg/javax/sql/PooledConnection.class+0−0

Binary file not shown.

java/pkg/javax/sql/PooledConnection.java+178−0
@@ -0,0 +1,178 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.Connection;
29+import java.sql.SQLException;
30+
31+/**
32+ * An object that provides hooks for connection pool management.
33+ * A <code>PooledConnection</code> object
34+ * represents a physical connection to a data source. The connection
35+ * can be recycled rather than being closed when an application is
36+ * finished with it, thus reducing the number of connections that
37+ * need to be made.
38+ * <P>
39+ * An application programmer does not use the <code>PooledConnection</code>
40+ * interface directly; rather, it is used by a middle tier infrastructure
41+ * that manages the pooling of connections.
42+ * <P>
43+ * When an application calls the method <code>DataSource.getConnection</code>,
44+ * it gets back a <code>Connection</code> object. If connection pooling is
45+ * being done, that <code>Connection</code> object is actually a handle to
46+ * a <code>PooledConnection</code> object, which is a physical connection.
47+ * <P>
48+ * The connection pool manager, typically the application server, maintains
49+ * a pool of <code>PooledConnection</code> objects. If there is a
50+ * <code>PooledConnection</code> object available in the pool, the
51+ * connection pool manager returns a <code>Connection</code> object that
52+ * is a handle to that physical connection.
53+ * If no <code>PooledConnection</code> object is available, the
54+ * connection pool manager calls the <code>ConnectionPoolDataSource</code>
55+ * method <code>getPoolConnection</code> to create a new physical connection. The
56+ * JDBC driver implementing <code>ConnectionPoolDataSource</code> creates a
57+ * new <code>PooledConnection</code> object and returns a handle to it.
58+ * <P>
59+ * When an application closes a connection, it calls the <code>Connection</code>
60+ * method <code>close</code>. When connection pooling is being done,
61+ * the connection pool manager is notified because it has registered itself as
62+ * a <code>ConnectionEventListener</code> object using the
63+ * <code>ConnectionPool</code> method <code>addConnectionEventListener</code>.
64+ * The connection pool manager deactivates the handle to
65+ * the <code>PooledConnection</code> object and returns the
66+ * <code>PooledConnection</code> object to the pool of connections so that
67+ * it can be used again. Thus, when an application closes its connection,
68+ * the underlying physical connection is recycled rather than being closed.
69+ * <P>
70+ * The physical connection is not closed until the connection pool manager
71+ * calls the <code>PooledConnection</code> method <code>close</code>.
72+ * This method is generally called to have an orderly shutdown of the server or
73+ * if a fatal error has made the connection unusable.
74+ *
75+ * <p>
76+ * A connection pool manager is often also a statement pool manager, maintining
77+ * a pool of <code>PreparedStatement</code> objects.
78+ * When an application closes a prepared statement, it calls the
79+ * <code>PreparedStatement</code>
80+ * method <code>close</code>. When <code>Statement</code> pooling is being done,
81+ * the pool manager is notified because it has registered itself as
82+ * a <code>StatementEventListener</code> object using the
83+ * <code>ConnectionPool</code> method <code>addStatementEventListener</code>.
84+ * Thus, when an application closes its <code>PreparedStatement</code>,
85+ * the underlying prepared statement is recycled rather than being closed.
86+ * <P>
87+ *
88+ * @since 1.4
89+ */
90+
91+public interface PooledConnection {
92+
93+ /**
94+ * Creates and returns a <code>Connection</code> object that is a handle
95+ * for the physical connection that
96+ * this <code>PooledConnection</code> object represents.
97+ * The connection pool manager calls this method when an application has
98+ * called the method <code>DataSource.getConnection</code> and there are
99+ * no <code>PooledConnection</code> objects available. See the
100+ * {@link PooledConnection interface description} for more information.
101+ *
102+ * @return a <code>Connection</code> object that is a handle to
103+ * this <code>PooledConnection</code> object
104+ * @exception SQLException if a database access error occurs
105+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
106+ * this method
107+ * @since 1.4
108+ */
109+ Connection getConnection() throws SQLException;
110+
111+ /**
112+ * Closes the physical connection that this <code>PooledConnection</code>
113+ * object represents. An application never calls this method directly;
114+ * it is called by the connection pool module, or manager.
115+ * <P>
116+ * See the {@link PooledConnection interface description} for more
117+ * information.
118+ *
119+ * @exception SQLException if a database access error occurs
120+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
121+ * this method
122+ * @since 1.4
123+ */
124+ void close() throws SQLException;
125+
126+ /**
127+ * Registers the given event listener so that it will be notified
128+ * when an event occurs on this <code>PooledConnection</code> object.
129+ *
130+ * @param listener a component, usually the connection pool manager,
131+ * that has implemented the
132+ * <code>ConnectionEventListener</code> interface and wants to be
133+ * notified when the connection is closed or has an error
134+ * @see #removeConnectionEventListener
135+ */
136+ void addConnectionEventListener(ConnectionEventListener listener);
137+
138+ /**
139+ * Removes the given event listener from the list of components that
140+ * will be notified when an event occurs on this
141+ * <code>PooledConnection</code> object.
142+ *
143+ * @param listener a component, usually the connection pool manager,
144+ * that has implemented the
145+ * <code>ConnectionEventListener</code> interface and
146+ * been registered with this <code>PooledConnection</code> object as
147+ * a listener
148+ * @see #addConnectionEventListener
149+ */
150+ void removeConnectionEventListener(ConnectionEventListener listener);
151+
152+ /**
153+ * Registers a <code>StatementEventListener</code> with this <code>PooledConnection</code> object. Components that
154+ * wish to be notified when <code>PreparedStatement</code>s created by the
155+ * connection are closed or are detected to be invalid may use this method
156+ * to register a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.
157+ * <p>
158+ * @param listener an component which implements the <code>StatementEventListener</code>
159+ * interface that is to be registered with this <code>PooledConnection</code> object
160+ * <p>
161+ * @since 1.6
162+ */
163+ public void addStatementEventListener(StatementEventListener listener);
164+
165+ /**
166+ * Removes the specified <code>StatementEventListener</code> from the list of
167+ * components that will be notified when the driver detects that a
168+ * <code>PreparedStatement</code> has been closed or is invalid.
169+ * <p>
170+ * @param listener the component which implements the
171+ * <code>StatementEventListener</code> interface that was previously
172+ * registered with this <code>PooledConnection</code> object
173+ * <p>
174+ * @since 1.6
175+ */
176+ public void removeStatementEventListener(StatementEventListener listener);
177+
178+ }
java/pkg/javax/sql/RowSet.class+0−0

Binary file not shown.

java/pkg/javax/sql/RowSet.java+2186−0
@@ -0,0 +1,2186 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.*;
29+import java.io.*;
30+import java.math.*;
31+import java.util.*;
32+
33+/**
34+ * The interface that adds support to the JDBC API for the
35+ * JavaBeans<sup><font size=-2>TM</font></sup> component model.
36+ * A rowset, which can be used as a JavaBeans component in
37+ * a visual Bean development environment, can be created and
38+ * configured at design time and executed at run time.
39+ * <P>
40+ * The <code>RowSet</code>
41+ * interface provides a set of JavaBeans properties that allow a <code>RowSet</code>
42+ * instance to be configured to connect to a JDBC data source and read
43+ * some data from the data source. A group of setter methods (<code>setInt</code>,
44+ * <code>setBytes</code>, <code>setString</code>, and so on)
45+ * provide a way to pass input parameters to a rowset's command property.
46+ * This command is the SQL query the rowset uses when it gets its data from
47+ * a relational database, which is generally the case.
48+ * <P>
49+ * The <code>RowSet</code>
50+ * interface supports JavaBeans events, allowing other components in an
51+ * application to be notified when an event occurs on a rowset,
52+ * such as a change in its value.
53+ *
54+ * <P>The <code>RowSet</code> interface is unique in that it is intended to be
55+ * implemented using the rest of the JDBC API. In other words, a
56+ * <code>RowSet</code> implementation is a layer of software that executes "on top"
57+ * of a JDBC driver. Implementations of the <code>RowSet</code> interface can
58+ * be provided by anyone, including JDBC driver vendors who want to
59+ * provide a <code>RowSet</code> implementation as part of their JDBC products.
60+ * <P>
61+ * A <code>RowSet</code> object may make a connection with a data source and
62+ * maintain that connection throughout its life cycle, in which case it is
63+ * called a <i>connected</i> rowset. A rowset may also make a connection with
64+ * a data source, get data from it, and then close the connection. Such a rowset
65+ * is called a <i>disconnected</i> rowset. A disconnected rowset may make
66+ * changes to its data while it is disconnected and then send the changes back
67+ * to the original source of the data, but it must reestablish a connection to do so.
68+ * <P>
69+ * A disconnected rowset may have a reader (a <code>RowSetReader</code> object)
70+ * and a writer (a <code>RowSetWriter</code> object) associated with it.
71+ * The reader may be implemented in many different ways to populate a rowset
72+ * with data, including getting data from a non-relational data source. The
73+ * writer can also be implemented in many different ways to propagate changes
74+ * made to the rowset's data back to the underlying data source.
75+ * <P>
76+ * Rowsets are easy to use. The <code>RowSet</code> interface extends the standard
77+ * <code>java.sql.ResultSet</code> interface. The <code>RowSetMetaData</code>
78+ * interface extends the <code>java.sql.ResultSetMetaData</code> interface.
79+ * Thus, developers familiar
80+ * with the JDBC API will have to learn a minimal number of new APIs to
81+ * use rowsets. In addition, third-party software tools that work with
82+ * JDBC <code>ResultSet</code> objects will also easily be made to work with rowsets.
83+ *
84+ * @since 1.4
85+ */
86+
87+public interface RowSet extends ResultSet {
88+
89+ //-----------------------------------------------------------------------
90+ // Properties
91+ //-----------------------------------------------------------------------
92+
93+ //-----------------------------------------------------------------------
94+ // The following properties may be used to create a Connection.
95+ //-----------------------------------------------------------------------
96+
97+ /**
98+ * Retrieves the url property this <code>RowSet</code> object will use to
99+ * create a connection if it uses the <code>DriverManager</code>
100+ * instead of a <code>DataSource</code> object to establish the connection.
101+ * The default value is <code>null</code>.
102+ *
103+ * @return a string url
104+ * @exception SQLException if a database access error occurs
105+ * @see #setUrl
106+ */
107+ String getUrl() throws SQLException;
108+
109+ /**
110+ * Sets the URL this <code>RowSet</code> object will use when it uses the
111+ * <code>DriverManager</code> to create a connection.
112+ *
113+ * Setting this property is optional. If a URL is used, a JDBC driver
114+ * that accepts the URL must be loaded before the
115+ * rowset is used to connect to a database. The rowset will use the URL
116+ * internally to create a database connection when reading or writing
117+ * data. Either a URL or a data source name is used to create a
118+ * connection, whichever was set to non null value most recently.
119+ *
120+ * @param url a string value; may be <code>null</code>
121+ * @exception SQLException if a database access error occurs
122+ * @see #getUrl
123+ */
124+ void setUrl(String url) throws SQLException;
125+
126+ /**
127+ * Retrieves the logical name that identifies the data source for this
128+ * <code>RowSet</code> object.
129+ *
130+ * @return a data source name
131+ * @see #setDataSourceName
132+ * @see #setUrl
133+ */
134+ String getDataSourceName();
135+
136+ /**
137+ * Sets the data source name property for this <code>RowSet</code> object to the
138+ * given <code>String</code>.
139+ * <P>
140+ * The value of the data source name property can be used to do a lookup of
141+ * a <code>DataSource</code> object that has been registered with a naming
142+ * service. After being retrieved, the <code>DataSource</code> object can be
143+ * used to create a connection to the data source that it represents.
144+ *
145+ * @param name the logical name of the data source for this <code>RowSet</code>
146+ * object; may be <code>null</code>
147+ * @exception SQLException if a database access error occurs
148+ * @see #getDataSourceName
149+ */
150+ void setDataSourceName(String name) throws SQLException;
151+
152+ /**
153+ * Retrieves the username used to create a database connection for this
154+ * <code>RowSet</code> object.
155+ * The username property is set at run time before calling the method
156+ * <code>execute</code>. It is
157+ * not usually part of the serialized state of a <code>RowSet</code> object.
158+ *
159+ * @return the username property
160+ * @see #setUsername
161+ */
162+ String getUsername();
163+
164+ /**
165+ * Sets the username property for this <code>RowSet</code> object to the
166+ * given <code>String</code>.
167+ *
168+ * @param name a user name
169+ * @exception SQLException if a database access error occurs
170+ * @see #getUsername
171+ */
172+ void setUsername(String name) throws SQLException;
173+
174+ /**
175+ * Retrieves the password used to create a database connection.
176+ * The password property is set at run time before calling the method
177+ * <code>execute</code>. It is not usually part of the serialized state
178+ * of a <code>RowSet</code> object.
179+ *
180+ * @return the password for making a database connection
181+ * @see #setPassword
182+ */
183+ String getPassword();
184+
185+ /**
186+ * Sets the database password for this <code>RowSet</code> object to
187+ * the given <code>String</code>.
188+ *
189+ * @param password the password string
190+ * @exception SQLException if a database access error occurs
191+ * @see #getPassword
192+ */
193+ void setPassword(String password) throws SQLException;
194+
195+ /**
196+ * Retrieves the transaction isolation level set for this
197+ * <code>RowSet</code> object.
198+ *
199+ * @return the transaction isolation level; one of
200+ * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
201+ * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
202+ * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
203+ * <code>Connection.TRANSACTION_SERIALIZABLE</code>
204+ * @see #setTransactionIsolation
205+ */
206+ int getTransactionIsolation();
207+
208+ /**
209+ * Sets the transaction isolation level for this <code>RowSet</code> obejct.
210+ *
211+ * @param level the transaction isolation level; one of
212+ * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
213+ * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
214+ * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
215+ * <code>Connection.TRANSACTION_SERIALIZABLE</code>
216+ * @exception SQLException if a database access error occurs
217+ * @see #getTransactionIsolation
218+ */
219+ void setTransactionIsolation(int level) throws SQLException;
220+
221+ /**
222+ * Retrieves the <code>Map</code> object associated with this
223+ * <code>RowSet</code> object, which specifies the custom mapping
224+ * of SQL user-defined types, if any. The default is for the
225+ * type map to be empty.
226+ *
227+ * @return a <code>java.util.Map</code> object containing the names of
228+ * SQL user-defined types and the Java classes to which they are
229+ * to be mapped
230+ *
231+ * @exception SQLException if a database access error occurs
232+ * @see #setTypeMap
233+ */
234+ java.util.Map<String,Class<?>> getTypeMap() throws SQLException;
235+
236+ /**
237+ * Installs the given <code>java.util.Map</code> object as the default
238+ * type map for this <code>RowSet</code> object. This type map will be
239+ * used unless another type map is supplied as a method parameter.
240+ *
241+ * @param map a <code>java.util.Map</code> object containing the names of
242+ * SQL user-defined types and the Java classes to which they are
243+ * to be mapped
244+ * @exception SQLException if a database access error occurs
245+ * @see #getTypeMap
246+ */
247+ void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException;
248+
249+ //-----------------------------------------------------------------------
250+ // The following properties may be used to create a Statement.
251+ //-----------------------------------------------------------------------
252+
253+ /**
254+ * Retrieves this <code>RowSet</code> object's command property.
255+ *
256+ * The command property contains a command string, which must be an SQL
257+ * query, that can be executed to fill the rowset with data.
258+ * The default value is <code>null</code>.
259+ *
260+ * @return the command string; may be <code>null</code>
261+ * @see #setCommand
262+ */
263+ String getCommand();
264+
265+ /**
266+ * Sets this <code>RowSet</code> object's command property to the given
267+ * SQL query.
268+ *
269+ * This property is optional
270+ * when a rowset gets its data from a data source that does not support
271+ * commands, such as a spreadsheet.
272+ *
273+ * @param cmd the SQL query that will be used to get the data for this
274+ * <code>RowSet</code> object; may be <code>null</code>
275+ * @exception SQLException if a database access error occurs
276+ * @see #getCommand
277+ */
278+ void setCommand(String cmd) throws SQLException;
279+
280+ /**
281+ * Retrieves whether this <code>RowSet</code> object is read-only.
282+ * If updates are possible, the default is for a rowset to be
283+ * updatable.
284+ * <P>
285+ * Attempts to update a read-only rowset will result in an
286+ * <code>SQLException</code> being thrown.
287+ *
288+ * @return <code>true</code> if this <code>RowSet</code> object is
289+ * read-only; <code>false</code> if it is updatable
290+ * @see #setReadOnly
291+ */
292+ boolean isReadOnly();
293+
294+ /**
295+ * Sets whether this <code>RowSet</code> object is read-only to the
296+ * given <code>boolean</code>.
297+ *
298+ * @param value <code>true</code> if read-only; <code>false</code> if
299+ * updatable
300+ * @exception SQLException if a database access error occurs
301+ * @see #isReadOnly
302+ */
303+ void setReadOnly(boolean value) throws SQLException;
304+
305+ /**
306+ * Retrieves the maximum number of bytes that may be returned
307+ * for certain column values.
308+ * This limit applies only to <code>BINARY</code>,
309+ * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
310+ * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>
311+ * and <code>NVARCHAR</code> columns.
312+ * If the limit is exceeded, the excess data is silently discarded.
313+ *
314+ * @return the current maximum column size limit; zero means that there
315+ * is no limit
316+ * @exception SQLException if a database access error occurs
317+ * @see #setMaxFieldSize
318+ */
319+ int getMaxFieldSize() throws SQLException;
320+
321+ /**
322+ * Sets the maximum number of bytes that can be returned for a column
323+ * value to the given number of bytes.
324+ * This limit applies only to <code>BINARY</code>,
325+ * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
326+ * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>
327+ * and <code>NVARCHAR</code> columns.
328+ * If the limit is exceeded, the excess data is silently discarded.
329+ * For maximum portability, use values greater than 256.
330+ *
331+ * @param max the new max column size limit in bytes; zero means unlimited
332+ * @exception SQLException if a database access error occurs
333+ * @see #getMaxFieldSize
334+ */
335+ void setMaxFieldSize(int max) throws SQLException;
336+
337+ /**
338+ * Retrieves the maximum number of rows that this <code>RowSet</code>
339+ * object can contain.
340+ * If the limit is exceeded, the excess rows are silently dropped.
341+ *
342+ * @return the current maximum number of rows that this <code>RowSet</code>
343+ * object can contain; zero means unlimited
344+ * @exception SQLException if a database access error occurs
345+ * @see #setMaxRows
346+ */
347+ int getMaxRows() throws SQLException;
348+
349+ /**
350+ * Sets the maximum number of rows that this <code>RowSet</code>
351+ * object can contain to the specified number.
352+ * If the limit is exceeded, the excess rows are silently dropped.
353+ *
354+ * @param max the new maximum number of rows; zero means unlimited
355+ * @exception SQLException if a database access error occurs
356+ * @see #getMaxRows
357+ */
358+ void setMaxRows(int max) throws SQLException;
359+
360+ /**
361+ * Retrieves whether escape processing is enabled for this
362+ * <code>RowSet</code> object.
363+ * If escape scanning is enabled, which is the default, the driver will do
364+ * escape substitution before sending an SQL statement to the database.
365+ *
366+ * @return <code>true</code> if escape processing is enabled;
367+ * <code>false</code> if it is disabled
368+ * @exception SQLException if a database access error occurs
369+ * @see #setEscapeProcessing
370+ */
371+ boolean getEscapeProcessing() throws SQLException;
372+
373+ /**
374+ * Sets escape processing for this <code>RowSet</code> object on or
375+ * off. If escape scanning is on (the default), the driver will do
376+ * escape substitution before sending an SQL statement to the database.
377+ *
378+ * @param enable <code>true</code> to enable escape processing;
379+ * <code>false</code> to disable it
380+ * @exception SQLException if a database access error occurs
381+ * @see #getEscapeProcessing
382+ */
383+ void setEscapeProcessing(boolean enable) throws SQLException;
384+
385+ /**
386+ * Retrieves the maximum number of seconds the driver will wait for
387+ * a statement to execute.
388+ * If this limit is exceeded, an <code>SQLException</code> is thrown.
389+ *
390+ * @return the current query timeout limit in seconds; zero means
391+ * unlimited
392+ * @exception SQLException if a database access error occurs
393+ * @see #setQueryTimeout
394+ */
395+ int getQueryTimeout() throws SQLException;
396+
397+ /**
398+ * Sets the maximum time the driver will wait for
399+ * a statement to execute to the given number of seconds.
400+ * If this limit is exceeded, an <code>SQLException</code> is thrown.
401+ *
402+ * @param seconds the new query timeout limit in seconds; zero means
403+ * that there is no limit
404+ * @exception SQLException if a database access error occurs
405+ * @see #getQueryTimeout
406+ */
407+ void setQueryTimeout(int seconds) throws SQLException;
408+
409+ /**
410+ * Sets the type of this <code>RowSet</code> object to the given type.
411+ * This method is used to change the type of a rowset, which is by
412+ * default read-only and non-scrollable.
413+ *
414+ * @param type one of the <code>ResultSet</code> constants specifying a type:
415+ * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
416+ * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
417+ * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
418+ * @exception SQLException if a database access error occurs
419+ * @see java.sql.ResultSet#getType
420+ */
421+ void setType(int type) throws SQLException;
422+
423+ /**
424+ * Sets the concurrency of this <code>RowSet</code> object to the given
425+ * concurrency level. This method is used to change the concurrency level
426+ * of a rowset, which is by default <code>ResultSet.CONCUR_READ_ONLY</code>
427+ *
428+ * @param concurrency one of the <code>ResultSet</code> constants specifying a
429+ * concurrency level: <code>ResultSet.CONCUR_READ_ONLY</code> or
430+ * <code>ResultSet.CONCUR_UPDATABLE</code>
431+ * @exception SQLException if a database access error occurs
432+ * @see ResultSet#getConcurrency
433+ */
434+ void setConcurrency(int concurrency) throws SQLException;
435+
436+ //-----------------------------------------------------------------------
437+ // Parameters
438+ //-----------------------------------------------------------------------
439+
440+ /**
441+ * The <code>RowSet</code> setter methods are used to set any input parameters
442+ * needed by the <code>RowSet</code> object's command.
443+ * Parameters are set at run time, as opposed to design time.
444+ */
445+
446+ /**
447+ * Sets the designated parameter in this <code>RowSet</code> object's SQL
448+ * command to SQL <code>NULL</code>.
449+ *
450+ * <P><B>Note:</B> You must specify the parameter's SQL type.
451+ *
452+ * @param parameterIndex the first parameter is 1, the second is 2, ...
453+ * @param sqlType a SQL type code defined by <code>java.sql.Types</code>
454+ * @exception SQLException if a database access error occurs
455+ */
456+ void setNull(int parameterIndex, int sqlType) throws SQLException;
457+
458+ /**
459+ * Sets the designated parameter to SQL <code>NULL</code>.
460+ *
461+ * <P><B>Note:</B> You must specify the parameter's SQL type.
462+ *
463+ * @param parameterName the name of the parameter
464+ * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
465+ * @exception SQLException if a database access error occurs or
466+ * this method is called on a closed <code>CallableStatement</code>
467+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
468+ * this method
469+ * @since 1.4
470+ */
471+ void setNull(String parameterName, int sqlType) throws SQLException;
472+
473+ /**
474+ * Sets the designated parameter in this <code>RowSet</code> object's SQL
475+ * command to SQL <code>NULL</code>. This version of the method <code>setNull</code>
476+ * should be used for SQL user-defined types (UDTs) and <code>REF</code> type
477+ * parameters. Examples of UDTs include: <code>STRUCT</code>, <code>DISTINCT</code>,
478+ * <code>JAVA_OBJECT</code>, and named array types.
479+ *
480+ * <P><B>Note:</B> To be portable, applications must give the
481+ * SQL type code and the fully qualified SQL type name when specifying
482+ * a NULL UDT or <code>REF</code> parameter. In the case of a UDT,
483+ * the name is the type name of the parameter itself. For a <code>REF</code>
484+ * parameter, the name is the type name of the referenced type. If
485+ * a JDBC driver does not need the type code or type name information,
486+ * it may ignore it.
487+ *
488+ * Although it is intended for UDT and <code>REF</code> parameters,
489+ * this method may be used to set a null parameter of any JDBC type.
490+ * If the parameter does not have a user-defined or <code>REF</code> type,
491+ * the typeName parameter is ignored.
492+ *
493+ *
494+ * @param paramIndex the first parameter is 1, the second is 2, ...
495+ * @param sqlType a value from <code>java.sql.Types</code>
496+ * @param typeName the fully qualified name of an SQL UDT or the type
497+ * name of the SQL structured type being referenced by a <code>REF</code>
498+ * type; ignored if the parameter is not a UDT or <code>REF</code> type
499+ * @exception SQLException if a database access error occurs
500+ */
501+ void setNull (int paramIndex, int sqlType, String typeName)
502+ throws SQLException;
503+
504+ /**
505+ * Sets the designated parameter to SQL <code>NULL</code>.
506+ * This version of the method <code>setNull</code> should
507+ * be used for user-defined types and REF type parameters. Examples
508+ * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
509+ * named array types.
510+ *
511+ * <P><B>Note:</B> To be portable, applications must give the
512+ * SQL type code and the fully-qualified SQL type name when specifying
513+ * a NULL user-defined or REF parameter. In the case of a user-defined type
514+ * the name is the type name of the parameter itself. For a REF
515+ * parameter, the name is the type name of the referenced type. If
516+ * a JDBC driver does not need the type code or type name information,
517+ * it may ignore it.
518+ *
519+ * Although it is intended for user-defined and Ref parameters,
520+ * this method may be used to set a null parameter of any JDBC type.
521+ * If the parameter does not have a user-defined or REF type, the given
522+ * typeName is ignored.
523+ *
524+ *
525+ * @param parameterName the name of the parameter
526+ * @param sqlType a value from <code>java.sql.Types</code>
527+ * @param typeName the fully-qualified name of an SQL user-defined type;
528+ * ignored if the parameter is not a user-defined type or
529+ * SQL <code>REF</code> value
530+ * @exception SQLException if a database access error occurs or
531+ * this method is called on a closed <code>CallableStatement</code>
532+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
533+ * this method
534+ * @since 1.4
535+ */
536+ void setNull (String parameterName, int sqlType, String typeName)
537+ throws SQLException;
538+
539+ /**
540+ * Sets the designated parameter in this <code>RowSet</code> object's command
541+ * to the given Java <code>boolean</code> value. The driver converts this to
542+ * an SQL <code>BIT</code> value before sending it to the database.
543+ *
544+ * @param parameterIndex the first parameter is 1, the second is 2, ...
545+ * @param x the parameter value
546+ * @exception SQLException if a database access error occurs
547+ */
548+ void setBoolean(int parameterIndex, boolean x) throws SQLException;
549+
550+ /**
551+ * Sets the designated parameter to the given Java <code>boolean</code> value.
552+ * The driver converts this
553+ * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
554+ *
555+ * @param parameterName the name of the parameter
556+ * @param x the parameter value
557+ * @exception SQLException if a database access error occurs or
558+ * this method is called on a closed <code>CallableStatement</code>
559+ * @see #getBoolean
560+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
561+ * this method
562+ * @since 1.4
563+ */
564+ void setBoolean(String parameterName, boolean x) throws SQLException;
565+
566+ /**
567+ * Sets the designated parameter in this <code>RowSet</code> object's command
568+ * to the given Java <code>byte</code> value. The driver converts this to
569+ * an SQL <code>TINYINT</code> value before sending it to the database.
570+ *
571+ * @param parameterIndex the first parameter is 1, the second is 2, ...
572+ * @param x the parameter value
573+ * @exception SQLException if a database access error occurs
574+ */
575+ void setByte(int parameterIndex, byte x) throws SQLException;
576+
577+ /**
578+ * Sets the designated parameter to the given Java <code>byte</code> value.
579+ * The driver converts this
580+ * to an SQL <code>TINYINT</code> value when it sends it to the database.
581+ *
582+ * @param parameterName the name of the parameter
583+ * @param x the parameter value
584+ * @exception SQLException if a database access error occurs or
585+ * this method is called on a closed <code>CallableStatement</code>
586+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
587+ * this method
588+ * @see #getByte
589+ * @since 1.4
590+ */
591+ void setByte(String parameterName, byte x) throws SQLException;
592+
593+ /**
594+ * Sets the designated parameter in this <code>RowSet</code> object's command
595+ * to the given Java <code>short</code> value. The driver converts this to
596+ * an SQL <code>SMALLINT</code> value before sending it to the database.
597+ *
598+ * @param parameterIndex the first parameter is 1, the second is 2, ...
599+ * @param x the parameter value
600+ * @exception SQLException if a database access error occurs
601+ */
602+ void setShort(int parameterIndex, short x) throws SQLException;
603+
604+ /**
605+ * Sets the designated parameter to the given Java <code>short</code> value.
606+ * The driver converts this
607+ * to an SQL <code>SMALLINT</code> value when it sends it to the database.
608+ *
609+ * @param parameterName the name of the parameter
610+ * @param x the parameter value
611+ * @exception SQLException if a database access error occurs or
612+ * this method is called on a closed <code>CallableStatement</code>
613+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
614+ * this method
615+ * @see #getShort
616+ * @since 1.4
617+ */
618+ void setShort(String parameterName, short x) throws SQLException;
619+
620+ /**
621+ * Sets the designated parameter in this <code>RowSet</code> object's command
622+ * to the given Java <code>int</code> value. The driver converts this to
623+ * an SQL <code>INTEGER</code> value before sending it to the database.
624+ *
625+ * @param parameterIndex the first parameter is 1, the second is 2, ...
626+ * @param x the parameter value
627+ * @exception SQLException if a database access error occurs
628+ */
629+ void setInt(int parameterIndex, int x) throws SQLException;
630+
631+ /**
632+ * Sets the designated parameter to the given Java <code>int</code> value.
633+ * The driver converts this
634+ * to an SQL <code>INTEGER</code> value when it sends it to the database.
635+ *
636+ * @param parameterName the name of the parameter
637+ * @param x the parameter value
638+ * @exception SQLException if a database access error occurs or
639+ * this method is called on a closed <code>CallableStatement</code>
640+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
641+ * this method
642+ * @see #getInt
643+ * @since 1.4
644+ */
645+ void setInt(String parameterName, int x) throws SQLException;
646+
647+ /**
648+ * Sets the designated parameter in this <code>RowSet</code> object's command
649+ * to the given Java <code>long</code> value. The driver converts this to
650+ * an SQL <code>BIGINT</code> value before sending it to the database.
651+ *
652+ * @param parameterIndex the first parameter is 1, the second is 2, ...
653+ * @param x the parameter value
654+ * @exception SQLException if a database access error occurs
655+ */
656+ void setLong(int parameterIndex, long x) throws SQLException;
657+
658+ /**
659+ * Sets the designated parameter to the given Java <code>long</code> value.
660+ * The driver converts this
661+ * to an SQL <code>BIGINT</code> value when it sends it to the database.
662+ *
663+ * @param parameterName the name of the parameter
664+ * @param x the parameter value
665+ * @exception SQLException if a database access error occurs or
666+ * this method is called on a closed <code>CallableStatement</code>
667+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
668+ * this method
669+ * @see #getLong
670+ * @since 1.4
671+ */
672+ void setLong(String parameterName, long x) throws SQLException;
673+
674+ /**
675+ * Sets the designated parameter in this <code>RowSet</code> object's command
676+ * to the given Java <code>float</code> value. The driver converts this to
677+ * an SQL <code>REAL</code> value before sending it to the database.
678+ *
679+ * @param parameterIndex the first parameter is 1, the second is 2, ...
680+ * @param x the parameter value
681+ * @exception SQLException if a database access error occurs
682+ */
683+ void setFloat(int parameterIndex, float x) throws SQLException;
684+
685+ /**
686+ * Sets the designated parameter to the given Java <code>float</code> value.
687+ * The driver converts this
688+ * to an SQL <code>FLOAT</code> value when it sends it to the database.
689+ *
690+ * @param parameterName the name of the parameter
691+ * @param x the parameter value
692+ * @exception SQLException if a database access error occurs or
693+ * this method is called on a closed <code>CallableStatement</code>
694+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
695+ * this method
696+ * @see #getFloat
697+ * @since 1.4
698+ */
699+ void setFloat(String parameterName, float x) throws SQLException;
700+
701+ /**
702+ * Sets the designated parameter in this <code>RowSet</code> object's command
703+ * to the given Java <code>double</code> value. The driver converts this to
704+ * an SQL <code>DOUBLE</code> value before sending it to the database.
705+ *
706+ * @param parameterIndex the first parameter is 1, the second is 2, ...
707+ * @param x the parameter value
708+ * @exception SQLException if a database access error occurs
709+ */
710+ void setDouble(int parameterIndex, double x) throws SQLException;
711+
712+ /**
713+ * Sets the designated parameter to the given Java <code>double</code> value.
714+ * The driver converts this
715+ * to an SQL <code>DOUBLE</code> value when it sends it to the database.
716+ *
717+ * @param parameterName the name of the parameter
718+ * @param x the parameter value
719+ * @exception SQLException if a database access error occurs or
720+ * this method is called on a closed <code>CallableStatement</code>
721+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
722+ * this method
723+ * @see #getDouble
724+ * @since 1.4
725+ */
726+ void setDouble(String parameterName, double x) throws SQLException;
727+
728+ /**
729+ * Sets the designated parameter in this <code>RowSet</code> object's command
730+ * to the given <code>java.math.BigDeciaml</code> value.
731+ * The driver converts this to
732+ * an SQL <code>NUMERIC</code> value before sending it to the database.
733+ *
734+ * @param parameterIndex the first parameter is 1, the second is 2, ...
735+ * @param x the parameter value
736+ * @exception SQLException if a database access error occurs
737+ */
738+ void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException;
739+
740+ /**
741+ * Sets the designated parameter to the given
742+ * <code>java.math.BigDecimal</code> value.
743+ * The driver converts this to an SQL <code>NUMERIC</code> value when
744+ * it sends it to the database.
745+ *
746+ * @param parameterName the name of the parameter
747+ * @param x the parameter value
748+ * @exception SQLException if a database access error occurs or
749+ * this method is called on a closed <code>CallableStatement</code>
750+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
751+ * this method
752+ * @see #getBigDecimal
753+ * @since 1.4
754+ */
755+ void setBigDecimal(String parameterName, BigDecimal x) throws SQLException;
756+
757+ /**
758+ * Sets the designated parameter in this <code>RowSet</code> object's command
759+ * to the given Java <code>String</code> value. Before sending it to the
760+ * database, the driver converts this to an SQL <code>VARCHAR</code> or
761+ * <code>LONGVARCHAR</code> value, depending on the argument's size relative
762+ * to the driver's limits on <code>VARCHAR</code> values.
763+ *
764+ * @param parameterIndex the first parameter is 1, the second is 2, ...
765+ * @param x the parameter value
766+ * @exception SQLException if a database access error occurs
767+ */
768+ void setString(int parameterIndex, String x) throws SQLException;
769+
770+ /**
771+ * Sets the designated parameter to the given Java <code>String</code> value.
772+ * The driver converts this
773+ * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
774+ * (depending on the argument's
775+ * size relative to the driver's limits on <code>VARCHAR</code> values)
776+ * when it sends it to the database.
777+ *
778+ * @param parameterName the name of the parameter
779+ * @param x the parameter value
780+ * @exception SQLException if a database access error occurs or
781+ * this method is called on a closed <code>CallableStatement</code>
782+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
783+ * this method
784+ * @see #getString
785+ * @since 1.4
786+ */
787+ void setString(String parameterName, String x) throws SQLException;
788+
789+ /**
790+ * Sets the designated parameter in this <code>RowSet</code> object's command
791+ * to the given Java array of <code>byte</code> values. Before sending it to the
792+ * database, the driver converts this to an SQL <code>VARBINARY</code> or
793+ * <code>LONGVARBINARY</code> value, depending on the argument's size relative
794+ * to the driver's limits on <code>VARBINARY</code> values.
795+ *
796+ * @param parameterIndex the first parameter is 1, the second is 2, ...
797+ * @param x the parameter value
798+ * @exception SQLException if a database access error occurs
799+ */
800+ void setBytes(int parameterIndex, byte x[]) throws SQLException;
801+
802+ /**
803+ * Sets the designated parameter to the given Java array of bytes.
804+ * The driver converts this to an SQL <code>VARBINARY</code> or
805+ * <code>LONGVARBINARY</code> (depending on the argument's size relative
806+ * to the driver's limits on <code>VARBINARY</code> values) when it sends
807+ * it to the database.
808+ *
809+ * @param parameterName the name of the parameter
810+ * @param x the parameter value
811+ * @exception SQLException if a database access error occurs or
812+ * this method is called on a closed <code>CallableStatement</code>
813+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
814+ * this method
815+ * @see #getBytes
816+ * @since 1.4
817+ */
818+ void setBytes(String parameterName, byte x[]) throws SQLException;
819+
820+ /**
821+ * Sets the designated parameter in this <code>RowSet</code> object's command
822+ * to the given <code>java.sql.Date</code> value. The driver converts this to
823+ * an SQL <code>DATE</code> value before sending it to the database, using the
824+ * default <code>java.util.Calendar</code> to calculate the date.
825+ *
826+ * @param parameterIndex the first parameter is 1, the second is 2, ...
827+ * @param x the parameter value
828+ * @exception SQLException if a database access error occurs
829+ */
830+ void setDate(int parameterIndex, java.sql.Date x) throws SQLException;
831+
832+ /**
833+ * Sets the designated parameter in this <code>RowSet</code> object's command
834+ * to the given <code>java.sql.Time</code> value. The driver converts this to
835+ * an SQL <code>TIME</code> value before sending it to the database, using the
836+ * default <code>java.util.Calendar</code> to calculate it.
837+ *
838+ * @param parameterIndex the first parameter is 1, the second is 2, ...
839+ * @param x the parameter value
840+ * @exception SQLException if a database access error occurs
841+ */
842+ void setTime(int parameterIndex, java.sql.Time x) throws SQLException;
843+
844+ /**
845+ * Sets the designated parameter in this <code>RowSet</code> object's command
846+ * to the given <code>java.sql.Timestamp</code> value. The driver converts this to
847+ * an SQL <code>TIMESTAMP</code> value before sending it to the database, using the
848+ * default <code>java.util.Calendar</code> to calculate it.
849+ *
850+ * @param parameterIndex the first parameter is 1, the second is 2, ...
851+ * @param x the parameter value
852+ * @exception SQLException if a database access error occurs
853+ */
854+ void setTimestamp(int parameterIndex, java.sql.Timestamp x)
855+ throws SQLException;
856+
857+ /**
858+ * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
859+ * The driver
860+ * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
861+ * database.
862+ *
863+ * @param parameterName the name of the parameter
864+ * @param x the parameter value
865+ * @exception SQLException if a database access error occurs or
866+ * this method is called on a closed <code>CallableStatement</code>
867+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
868+ * this method
869+ * @see #getTimestamp
870+ * @since 1.4
871+ */
872+ void setTimestamp(String parameterName, java.sql.Timestamp x)
873+ throws SQLException;
874+
875+ /**
876+ * Sets the designated parameter in this <code>RowSet</code> object's command
877+ * to the given <code>java.io.InputStream</code> value.
878+ * It may be more practical to send a very large ASCII value via a
879+ * <code>java.io.InputStream</code> rather than as a <code>LONGVARCHAR</code>
880+ * parameter. The driver will read the data from the stream
881+ * as needed until it reaches end-of-file.
882+ *
883+ * <P><B>Note:</B> This stream object can either be a standard
884+ * Java stream object or your own subclass that implements the
885+ * standard interface.
886+ *
887+ * @param parameterIndex the first parameter is 1, the second is 2, ...
888+ * @param x the Java input stream that contains the ASCII parameter value
889+ * @param length the number of bytes in the stream
890+ * @exception SQLException if a database access error occurs
891+ */
892+ void setAsciiStream(int parameterIndex, java.io.InputStream x, int length)
893+ throws SQLException;
894+
895+ /**
896+ * Sets the designated parameter to the given input stream, which will have
897+ * the specified number of bytes.
898+ * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
899+ * parameter, it may be more practical to send it via a
900+ * <code>java.io.InputStream</code>. Data will be read from the stream
901+ * as needed until end-of-file is reached. The JDBC driver will
902+ * do any necessary conversion from ASCII to the database char format.
903+ *
904+ * <P><B>Note:</B> This stream object can either be a standard
905+ * Java stream object or your own subclass that implements the
906+ * standard interface.
907+ *
908+ * @param parameterName the name of the parameter
909+ * @param x the Java input stream that contains the ASCII parameter value
910+ * @param length the number of bytes in the stream
911+ * @exception SQLException if a database access error occurs or
912+ * this method is called on a closed <code>CallableStatement</code>
913+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
914+ * this method
915+ * @since 1.4
916+ */
917+ void setAsciiStream(String parameterName, java.io.InputStream x, int length)
918+ throws SQLException;
919+
920+ /**
921+ * Sets the designated parameter in this <code>RowSet</code> object's command
922+ * to the given <code>java.io.InputStream</code> value.
923+ * It may be more practical to send a very large binary value via a
924+ * <code>java.io.InputStream</code> rather than as a <code>LONGVARBINARY</code>
925+ * parameter. The driver will read the data from the stream
926+ * as needed until it reaches end-of-file.
927+ *
928+ * <P><B>Note:</B> This stream object can either be a standard
929+ * Java stream object or your own subclass that implements the
930+ * standard interface.
931+ *
932+ * @param parameterIndex the first parameter is 1, the second is 2, ...
933+ * @param x the java input stream which contains the binary parameter value
934+ * @param length the number of bytes in the stream
935+ * @exception SQLException if a database access error occurs
936+ */
937+ void setBinaryStream(int parameterIndex, java.io.InputStream x,
938+ int length) throws SQLException;
939+
940+ /**
941+ * Sets the designated parameter to the given input stream, which will have
942+ * the specified number of bytes.
943+ * When a very large binary value is input to a <code>LONGVARBINARY</code>
944+ * parameter, it may be more practical to send it via a
945+ * <code>java.io.InputStream</code> object. The data will be read from the stream
946+ * as needed until end-of-file is reached.
947+ *
948+ * <P><B>Note:</B> This stream object can either be a standard
949+ * Java stream object or your own subclass that implements the
950+ * standard interface.
951+ *
952+ * @param parameterName the name of the parameter
953+ * @param x the java input stream which contains the binary parameter value
954+ * @param length the number of bytes in the stream
955+ * @exception SQLException if a database access error occurs or
956+ * this method is called on a closed <code>CallableStatement</code>
957+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
958+ * this method
959+ * @since 1.4
960+ */
961+ void setBinaryStream(String parameterName, java.io.InputStream x,
962+ int length) throws SQLException;
963+
964+ /**
965+ * Sets the designated parameter in this <code>RowSet</code> object's command
966+ * to the given <code>java.io.Reader</code> value.
967+ * It may be more practical to send a very large UNICODE value via a
968+ * <code>java.io.Reader</code> rather than as a <code>LONGVARCHAR</code>
969+ * parameter. The driver will read the data from the stream
970+ * as needed until it reaches end-of-file.
971+ *
972+ * <P><B>Note:</B> This stream object can either be a standard
973+ * Java stream object or your own subclass that implements the
974+ * standard interface.
975+ *
976+ * @param parameterIndex the first parameter is 1, the second is 2, ...
977+ * @param reader the <code>Reader</code> object that contains the UNICODE data
978+ * to be set
979+ * @param length the number of characters in the stream
980+ * @exception SQLException if a database access error occurs
981+ */
982+ void setCharacterStream(int parameterIndex,
983+ Reader reader,
984+ int length) throws SQLException;
985+
986+ /**
987+ * Sets the designated parameter to the given <code>Reader</code>
988+ * object, which is the given number of characters long.
989+ * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
990+ * parameter, it may be more practical to send it via a
991+ * <code>java.io.Reader</code> object. The data will be read from the stream
992+ * as needed until end-of-file is reached. The JDBC driver will
993+ * do any necessary conversion from UNICODE to the database char format.
994+ *
995+ * <P><B>Note:</B> This stream object can either be a standard
996+ * Java stream object or your own subclass that implements the
997+ * standard interface.
998+ *
999+ * @param parameterName the name of the parameter
1000+ * @param reader the <code>java.io.Reader</code> object that
1001+ * contains the UNICODE data used as the designated parameter
1002+ * @param length the number of characters in the stream
1003+ * @exception SQLException if a database access error occurs or
1004+ * this method is called on a closed <code>CallableStatement</code>
1005+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1006+ * this method
1007+ * @since 1.4
1008+ */
1009+ void setCharacterStream(String parameterName,
1010+ java.io.Reader reader,
1011+ int length) throws SQLException;
1012+
1013+ /**
1014+ * Sets the designated parameter in this <code>RowSet</code> object's command
1015+ * to the given input stream.
1016+ * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1017+ * parameter, it may be more practical to send it via a
1018+ * <code>java.io.InputStream</code>. Data will be read from the stream
1019+ * as needed until end-of-file is reached. The JDBC driver will
1020+ * do any necessary conversion from ASCII to the database char format.
1021+ *
1022+ * <P><B>Note:</B> This stream object can either be a standard
1023+ * Java stream object or your own subclass that implements the
1024+ * standard interface.
1025+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1026+ * it might be more efficient to use a version of
1027+ * <code>setAsciiStream</code> which takes a length parameter.
1028+ *
1029+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1030+ * @param x the Java input stream that contains the ASCII parameter value
1031+ * @exception SQLException if a database access error occurs or
1032+ * this method is called on a closed <code>PreparedStatement</code>
1033+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1034+ * @since 1.6
1035+ */
1036+ void setAsciiStream(int parameterIndex, java.io.InputStream x)
1037+ throws SQLException;
1038+
1039+ /**
1040+ * Sets the designated parameter to the given input stream.
1041+ * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1042+ * parameter, it may be more practical to send it via a
1043+ * <code>java.io.InputStream</code>. Data will be read from the stream
1044+ * as needed until end-of-file is reached. The JDBC driver will
1045+ * do any necessary conversion from ASCII to the database char format.
1046+ *
1047+ * <P><B>Note:</B> This stream object can either be a standard
1048+ * Java stream object or your own subclass that implements the
1049+ * standard interface.
1050+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1051+ * it might be more efficient to use a version of
1052+ * <code>setAsciiStream</code> which takes a length parameter.
1053+ *
1054+ * @param parameterName the name of the parameter
1055+ * @param x the Java input stream that contains the ASCII parameter value
1056+ * @exception SQLException if a database access error occurs or
1057+ * this method is called on a closed <code>CallableStatement</code>
1058+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1059+ * @since 1.6
1060+ */
1061+ void setAsciiStream(String parameterName, java.io.InputStream x)
1062+ throws SQLException;
1063+
1064+ /**
1065+ * Sets the designated parameter in this <code>RowSet</code> object's command
1066+ * to the given input stream.
1067+ * When a very large binary value is input to a <code>LONGVARBINARY</code>
1068+ * parameter, it may be more practical to send it via a
1069+ * <code>java.io.InputStream</code> object. The data will be read from the
1070+ * stream as needed until end-of-file is reached.
1071+ *
1072+ * <P><B>Note:</B> This stream object can either be a standard
1073+ * Java stream object or your own subclass that implements the
1074+ * standard interface.
1075+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1076+ * it might be more efficient to use a version of
1077+ * <code>setBinaryStream</code> which takes a length parameter.
1078+ *
1079+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1080+ * @param x the java input stream which contains the binary parameter value
1081+ * @exception SQLException if a database access error occurs or
1082+ * this method is called on a closed <code>PreparedStatement</code>
1083+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1084+ * @since 1.6
1085+ */
1086+ void setBinaryStream(int parameterIndex, java.io.InputStream x)
1087+ throws SQLException;
1088+
1089+ /**
1090+ * Sets the designated parameter to the given input stream.
1091+ * When a very large binary value is input to a <code>LONGVARBINARY</code>
1092+ * parameter, it may be more practical to send it via a
1093+ * <code>java.io.InputStream</code> object. The data will be read from the
1094+ * stream as needed until end-of-file is reached.
1095+ *
1096+ * <P><B>Note:</B> This stream object can either be a standard
1097+ * Java stream object or your own subclass that implements the
1098+ * standard interface.
1099+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1100+ * it might be more efficient to use a version of
1101+ * <code>setBinaryStream</code> which takes a length parameter.
1102+ *
1103+ * @param parameterName the name of the parameter
1104+ * @param x the java input stream which contains the binary parameter value
1105+ * @exception SQLException if a database access error occurs or
1106+ * this method is called on a closed <code>CallableStatement</code>
1107+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1108+ * @since 1.6
1109+ */
1110+ void setBinaryStream(String parameterName, java.io.InputStream x)
1111+ throws SQLException;
1112+
1113+ /**
1114+ * Sets the designated parameter in this <code>RowSet</code> object's command
1115+ * to the given <code>Reader</code>
1116+ * object.
1117+ * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1118+ * parameter, it may be more practical to send it via a
1119+ * <code>java.io.Reader</code> object. The data will be read from the stream
1120+ * as needed until end-of-file is reached. The JDBC driver will
1121+ * do any necessary conversion from UNICODE to the database char format.
1122+ *
1123+ * <P><B>Note:</B> This stream object can either be a standard
1124+ * Java stream object or your own subclass that implements the
1125+ * standard interface.
1126+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1127+ * it might be more efficient to use a version of
1128+ * <code>setCharacterStream</code> which takes a length parameter.
1129+ *
1130+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1131+ * @param reader the <code>java.io.Reader</code> object that contains the
1132+ * Unicode data
1133+ * @exception SQLException if a database access error occurs or
1134+ * this method is called on a closed <code>PreparedStatement</code>
1135+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1136+ * @since 1.6
1137+ */
1138+ void setCharacterStream(int parameterIndex,
1139+ java.io.Reader reader) throws SQLException;
1140+
1141+ /**
1142+ * Sets the designated parameter to the given <code>Reader</code>
1143+ * object.
1144+ * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1145+ * parameter, it may be more practical to send it via a
1146+ * <code>java.io.Reader</code> object. The data will be read from the stream
1147+ * as needed until end-of-file is reached. The JDBC driver will
1148+ * do any necessary conversion from UNICODE to the database char format.
1149+ *
1150+ * <P><B>Note:</B> This stream object can either be a standard
1151+ * Java stream object or your own subclass that implements the
1152+ * standard interface.
1153+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1154+ * it might be more efficient to use a version of
1155+ * <code>setCharacterStream</code> which takes a length parameter.
1156+ *
1157+ * @param parameterName the name of the parameter
1158+ * @param reader the <code>java.io.Reader</code> object that contains the
1159+ * Unicode data
1160+ * @exception SQLException if a database access error occurs or
1161+ * this method is called on a closed <code>CallableStatement</code>
1162+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1163+ * @since 1.6
1164+ */
1165+ void setCharacterStream(String parameterName,
1166+ java.io.Reader reader) throws SQLException;
1167+
1168+ /**
1169+ * Sets the designated parameter in this <code>RowSet</code> object's command
1170+ * to a <code>Reader</code> object. The
1171+ * <code>Reader</code> reads the data till end-of-file is reached. The
1172+ * driver does the necessary conversion from Java character format to
1173+ * the national character set in the database.
1174+
1175+ * <P><B>Note:</B> This stream object can either be a standard
1176+ * Java stream object or your own subclass that implements the
1177+ * standard interface.
1178+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1179+ * it might be more efficient to use a version of
1180+ * <code>setNCharacterStream</code> which takes a length parameter.
1181+ *
1182+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
1183+ * @param value the parameter value
1184+ * @throws SQLException if the driver does not support national
1185+ * character sets; if the driver can detect that a data conversion
1186+ * error could occur ; if a database access error occurs; or
1187+ * this method is called on a closed <code>PreparedStatement</code>
1188+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1189+ * @since 1.6
1190+ */
1191+ void setNCharacterStream(int parameterIndex, Reader value) throws SQLException;
1192+
1193+
1194+
1195+ /**
1196+ * Sets the designated parameter in this <code>RowSet</code> object's command
1197+ * with the given Java <code>Object</code>. For integral values, the
1198+ * <code>java.lang</code> equivalent objects should be used (for example,
1199+ * an instance of the class <code>Integer</code> for an <code>int</code>).
1200+ *
1201+ * If the second argument is an <code>InputStream</code> then the stream must contain
1202+ * the number of bytes specified by scaleOrLength. If the second argument is a
1203+ * <code>Reader</code> then the reader must contain the number of characters specified * by scaleOrLength. If these conditions are not true the driver will generate a
1204+ * <code>SQLException</code> when the prepared statement is executed.
1205+ *
1206+ * <p>The given Java object will be converted to the targetSqlType
1207+ * before being sent to the database.
1208+ * <P>
1209+ * If the object is of a class implementing <code>SQLData</code>,
1210+ * the rowset should call the method <code>SQLData.writeSQL</code>
1211+ * to write the object to an <code>SQLOutput</code> data stream.
1212+ * If, on the other hand, the object is of a class implementing
1213+ * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1214+ * <code>Struct</code>, <code>java.net.URL</code>,
1215+ * or <code>Array</code>, the driver should pass it to the database as a
1216+ * value of the corresponding SQL type.
1217+ * <P>
1218+ *
1219+ * <p>Note that this method may be used to pass datatabase-specific
1220+ * abstract data types.
1221+ *
1222+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1223+ * @param x the object containing the input parameter value
1224+ * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1225+ * to be sent to the database. The scale argument may further qualify this
1226+ * type.
1227+ * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code>
1228+ * or <code>java.sql.Types.NUMERIC types</code>,
1229+ * this is the number of digits after the decimal point. For
1230+ * Java Object types <code>InputStream</code> and <code>Reader</code>,
1231+ * this is the length
1232+ * of the data in the stream or reader. For all other types,
1233+ * this value will be ignored.
1234+ * @exception SQLException if a database access error occurs
1235+ * @see java.sql.Types
1236+ */
1237+ void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength)
1238+ throws SQLException;
1239+
1240+ /**
1241+ * Sets the value of the designated parameter with the given object. The second
1242+ * argument must be an object type; for integral values, the
1243+ * <code>java.lang</code> equivalent objects should be used.
1244+ *
1245+ * <p>The given Java object will be converted to the given targetSqlType
1246+ * before being sent to the database.
1247+ *
1248+ * If the object has a custom mapping (is of a class implementing the
1249+ * interface <code>SQLData</code>),
1250+ * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1251+ * to the SQL data stream.
1252+ * If, on the other hand, the object is of a class implementing
1253+ * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1254+ * <code>Struct</code>, <code>java.net.URL</code>,
1255+ * or <code>Array</code>, the driver should pass it to the database as a
1256+ * value of the corresponding SQL type.
1257+ * <P>
1258+ * Note that this method may be used to pass datatabase-
1259+ * specific abstract data types.
1260+ *
1261+ * @param parameterName the name of the parameter
1262+ * @param x the object containing the input parameter value
1263+ * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1264+ * sent to the database. The scale argument may further qualify this type.
1265+ * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1266+ * this is the number of digits after the decimal point. For all other
1267+ * types, this value will be ignored.
1268+ * @exception SQLException if a database access error occurs or
1269+ * this method is called on a closed <code>CallableStatement</code>
1270+ * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1271+ * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1272+ * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1273+ * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1274+ * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1275+ * or <code>STRUCT</code> data type and the JDBC driver does not support
1276+ * this data type
1277+ * @see Types
1278+ * @see #getObject
1279+ * @since 1.4
1280+ */
1281+ void setObject(String parameterName, Object x, int targetSqlType, int scale)
1282+ throws SQLException;
1283+
1284+ /**
1285+ * Sets the designated parameter in this <code>RowSet</code> object's command
1286+ * with a Java <code>Object</code>. For integral values, the
1287+ * <code>java.lang</code> equivalent objects should be used.
1288+ * This method is like <code>setObject</code> above, but the scale used is the scale
1289+ * of the second parameter. Scalar values have a scale of zero. Literal
1290+ * values have the scale present in the literal.
1291+ * <P>
1292+ * Even though it is supported, it is not recommended that this method
1293+ * be called with floating point input values.
1294+ *
1295+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1296+ * @param x the object containing the input parameter value
1297+ * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1298+ * to be sent to the database
1299+ * @exception SQLException if a database access error occurs
1300+ */
1301+ void setObject(int parameterIndex, Object x,
1302+ int targetSqlType) throws SQLException;
1303+
1304+ /**
1305+ * Sets the value of the designated parameter with the given object.
1306+ * This method is like the method <code>setObject</code>
1307+ * above, except that it assumes a scale of zero.
1308+ *
1309+ * @param parameterName the name of the parameter
1310+ * @param x the object containing the input parameter value
1311+ * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1312+ * sent to the database
1313+ * @exception SQLException if a database access error occurs or
1314+ * this method is called on a closed <code>CallableStatement</code>
1315+ * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1316+ * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1317+ * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1318+ * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1319+ * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1320+ * or <code>STRUCT</code> data type and the JDBC driver does not support
1321+ * this data type
1322+ * @see #getObject
1323+ * @since 1.4
1324+ */
1325+ void setObject(String parameterName, Object x, int targetSqlType)
1326+ throws SQLException;
1327+
1328+ /**
1329+ * Sets the value of the designated parameter with the given object.
1330+ * The second parameter must be of type <code>Object</code>; therefore, the
1331+ * <code>java.lang</code> equivalent objects should be used for built-in types.
1332+ *
1333+ * <p>The JDBC specification specifies a standard mapping from
1334+ * Java <code>Object</code> types to SQL types. The given argument
1335+ * will be converted to the corresponding SQL type before being
1336+ * sent to the database.
1337+ *
1338+ * <p>Note that this method may be used to pass datatabase-
1339+ * specific abstract data types, by using a driver-specific Java
1340+ * type.
1341+ *
1342+ * If the object is of a class implementing the interface <code>SQLData</code>,
1343+ * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1344+ * to write it to the SQL data stream.
1345+ * If, on the other hand, the object is of a class implementing
1346+ * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1347+ * <code>Struct</code>, <code>java.net.URL</code>,
1348+ * or <code>Array</code>, the driver should pass it to the database as a
1349+ * value of the corresponding SQL type.
1350+ * <P>
1351+ * This method throws an exception if there is an ambiguity, for example, if the
1352+ * object is of a class implementing more than one of the interfaces named above.
1353+ *
1354+ * @param parameterName the name of the parameter
1355+ * @param x the object containing the input parameter value
1356+ * @exception SQLException if a database access error occurs,
1357+ * this method is called on a closed <code>CallableStatement</code> or if the given
1358+ * <code>Object</code> parameter is ambiguous
1359+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1360+ * this method
1361+ * @see #getObject
1362+ * @since 1.4
1363+ */
1364+ void setObject(String parameterName, Object x) throws SQLException;
1365+
1366+ /**
1367+ * Sets the designated parameter in this <code>RowSet</code> object's command
1368+ * with a Java <code>Object</code>. For integral values, the
1369+ * <code>java.lang</code> equivalent objects should be used.
1370+ *
1371+ * <p>The JDBC specification provides a standard mapping from
1372+ * Java Object types to SQL types. The driver will convert the
1373+ * given Java object to its standard SQL mapping before sending it
1374+ * to the database.
1375+ *
1376+ * <p>Note that this method may be used to pass datatabase-specific
1377+ * abstract data types by using a driver-specific Java type.
1378+ *
1379+ * If the object is of a class implementing <code>SQLData</code>,
1380+ * the rowset should call the method <code>SQLData.writeSQL</code>
1381+ * to write the object to an <code>SQLOutput</code> data stream.
1382+ * If, on the other hand, the object is of a class implementing
1383+ * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1384+ * <code>Struct</code>, <code>java.net.URL</code>,
1385+ * or <code>Array</code>, the driver should pass it to the database as a
1386+ * value of the corresponding SQL type.
1387+ * <P>
1388+ * <P>
1389+ * An exception is thrown if there is an ambiguity, for example, if the
1390+ * object is of a class implementing more than one of these interfaces.
1391+ *
1392+ * @param parameterIndex The first parameter is 1, the second is 2, ...
1393+ * @param x The object containing the input parameter value
1394+ * @exception SQLException if a database access error occurs
1395+ */
1396+ void setObject(int parameterIndex, Object x) throws SQLException;
1397+
1398+
1399+ /**
1400+ * Sets the designated parameter in this <code>RowSet</code> object's command
1401+ * with the given <code>Ref</code> value. The driver will convert this
1402+ * to the appropriate <code>REF(&lt;structured-type&gt;)</code> value.
1403+ *
1404+ * @param i the first parameter is 1, the second is 2, ...
1405+ * @param x an object representing data of an SQL <code>REF</code> type
1406+ * @exception SQLException if a database access error occurs
1407+ */
1408+ void setRef (int i, Ref x) throws SQLException;
1409+
1410+ /**
1411+ * Sets the designated parameter in this <code>RowSet</code> object's command
1412+ * with the given <code>Blob</code> value. The driver will convert this
1413+ * to the <code>BLOB</code> value that the <code>Blob</code> object
1414+ * represents before sending it to the database.
1415+ *
1416+ * @param i the first parameter is 1, the second is 2, ...
1417+ * @param x an object representing a BLOB
1418+ * @exception SQLException if a database access error occurs
1419+ */
1420+ void setBlob (int i, Blob x) throws SQLException;
1421+
1422+ /**
1423+ * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number
1424+ * of characters specified by length otherwise a <code>SQLException</code> will be
1425+ * generated when the <code>PreparedStatement</code> is executed.
1426+ * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1427+ * method because it informs the driver that the parameter value should be
1428+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1429+ * the driver may have to do extra work to determine whether the parameter
1430+ * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1431+ * @param parameterIndex index of the first parameter is 1,
1432+ * the second is 2, ...
1433+ * @param inputStream An object that contains the data to set the parameter
1434+ * value to.
1435+ * @param length the number of bytes in the parameter data.
1436+ * @throws SQLException if a database access error occurs,
1437+ * this method is called on a closed <code>PreparedStatement</code>,
1438+ * if parameterIndex does not correspond
1439+ * to a parameter marker in the SQL statement, if the length specified
1440+ * is less than zero or if the number of bytes in the inputstream does not match
1441+ * the specfied length.
1442+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1443+ *
1444+ * @since 1.6
1445+ */
1446+ void setBlob(int parameterIndex, InputStream inputStream, long length)
1447+ throws SQLException;
1448+
1449+ /**
1450+ * Sets the designated parameter to a <code>InputStream</code> object.
1451+ * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1452+ * method because it informs the driver that the parameter value should be
1453+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1454+ * the driver may have to do extra work to determine whether the parameter
1455+ * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1456+ *
1457+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1458+ * it might be more efficient to use a version of
1459+ * <code>setBlob</code> which takes a length parameter.
1460+ *
1461+ * @param parameterIndex index of the first parameter is 1,
1462+ * the second is 2, ...
1463+ * @param inputStream An object that contains the data to set the parameter
1464+ * value to.
1465+ * @throws SQLException if a database access error occurs,
1466+ * this method is called on a closed <code>PreparedStatement</code> or
1467+ * if parameterIndex does not correspond
1468+ * to a parameter marker in the SQL statement,
1469+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1470+ *
1471+ * @since 1.6
1472+ */
1473+ void setBlob(int parameterIndex, InputStream inputStream)
1474+ throws SQLException;
1475+
1476+ /**
1477+ * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number
1478+ * of characters specified by length, otherwise a <code>SQLException</code> will be
1479+ * generated when the <code>CallableStatement</code> is executed.
1480+ * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1481+ * method because it informs the driver that the parameter value should be
1482+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1483+ * the driver may have to do extra work to determine whether the parameter
1484+ * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1485+ *
1486+ * @param parameterName the name of the parameter to be set
1487+ * the second is 2, ...
1488+ *
1489+ * @param inputStream An object that contains the data to set the parameter
1490+ * value to.
1491+ * @param length the number of bytes in the parameter data.
1492+ * @throws SQLException if parameterIndex does not correspond
1493+ * to a parameter marker in the SQL statement, or if the length specified
1494+ * is less than zero; if the number of bytes in the inputstream does not match
1495+ * the specfied length; if a database access error occurs or
1496+ * this method is called on a closed <code>CallableStatement</code>
1497+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1498+ * this method
1499+ *
1500+ * @since 1.6
1501+ */
1502+ void setBlob(String parameterName, InputStream inputStream, long length)
1503+ throws SQLException;
1504+
1505+ /**
1506+ * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
1507+ * The driver converts this to an SQL <code>BLOB</code> value when it
1508+ * sends it to the database.
1509+ *
1510+ * @param parameterName the name of the parameter
1511+ * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
1512+ * @exception SQLException if a database access error occurs or
1513+ * this method is called on a closed <code>CallableStatement</code>
1514+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1515+ * this method
1516+ * @since 1.6
1517+ */
1518+ void setBlob (String parameterName, Blob x) throws SQLException;
1519+
1520+ /**
1521+ * Sets the designated parameter to a <code>InputStream</code> object.
1522+ * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1523+ * method because it informs the driver that the parameter value should be
1524+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1525+ * the driver may have to do extra work to determine whether the parameter
1526+ * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1527+ *
1528+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1529+ * it might be more efficient to use a version of
1530+ * <code>setBlob</code> which takes a length parameter.
1531+ *
1532+ * @param parameterName the name of the parameter
1533+ * @param inputStream An object that contains the data to set the parameter
1534+ * value to.
1535+ * @throws SQLException if a database access error occurs or
1536+ * this method is called on a closed <code>CallableStatement</code>
1537+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1538+ *
1539+ * @since 1.6
1540+ */
1541+ void setBlob(String parameterName, InputStream inputStream)
1542+ throws SQLException;
1543+
1544+ /**
1545+ * Sets the designated parameter in this <code>RowSet</code> object's command
1546+ * with the given <code>Clob</code> value. The driver will convert this
1547+ * to the <code>CLOB</code> value that the <code>Clob</code> object
1548+ * represents before sending it to the database.
1549+ *
1550+ * @param i the first parameter is 1, the second is 2, ...
1551+ * @param x an object representing a CLOB
1552+ * @exception SQLException if a database access error occurs
1553+ */
1554+ void setClob (int i, Clob x) throws SQLException;
1555+
1556+ /**
1557+ * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
1558+ * of characters specified by length otherwise a <code>SQLException</code> will be
1559+ * generated when the <code>PreparedStatement</code> is executed.
1560+ *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1561+ * because it informs the driver that the parameter value should be sent to
1562+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1563+ * driver may have to do extra work to determine whether the parameter
1564+ * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1565+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1566+ * @param reader An object that contains the data to set the parameter value to.
1567+ * @param length the number of characters in the parameter data.
1568+ * @throws SQLException if a database access error occurs, this method is called on
1569+ * a closed <code>PreparedStatement</code>, if parameterIndex does not correspond to a parameter
1570+ * marker in the SQL statement, or if the length specified is less than zero.
1571+ *
1572+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1573+ * @since 1.6
1574+ */
1575+ void setClob(int parameterIndex, Reader reader, long length)
1576+ throws SQLException;
1577+
1578+ /**
1579+ * Sets the designated parameter to a <code>Reader</code> object.
1580+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1581+ * because it informs the driver that the parameter value should be sent to
1582+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1583+ * driver may have to do extra work to determine whether the parameter
1584+ * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1585+ *
1586+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1587+ * it might be more efficient to use a version of
1588+ * <code>setClob</code> which takes a length parameter.
1589+ *
1590+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1591+ * @param reader An object that contains the data to set the parameter value to.
1592+ * @throws SQLException if a database access error occurs, this method is called on
1593+ * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter
1594+ * marker in the SQL statement
1595+ *
1596+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1597+ * @since 1.6
1598+ */
1599+ void setClob(int parameterIndex, Reader reader)
1600+ throws SQLException;
1601+
1602+ /**
1603+ * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1604+ * of characters specified by length otherwise a <code>SQLException</code> will be
1605+ * generated when the <code>CallableStatement</code> is executed.
1606+ * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1607+ * because it informs the driver that the parameter value should be sent to
1608+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1609+ * driver may have to do extra work to determine whether the parameter
1610+ * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1611+ * @param parameterName the name of the parameter to be set
1612+ * @param reader An object that contains the data to set the parameter value to.
1613+ * @param length the number of characters in the parameter data.
1614+ * @throws SQLException if parameterIndex does not correspond to a parameter
1615+ * marker in the SQL statement; if the length specified is less than zero;
1616+ * a database access error occurs or
1617+ * this method is called on a closed <code>CallableStatement</code>
1618+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1619+ * this method
1620+ *
1621+ * @since 1.6
1622+ */
1623+ void setClob(String parameterName, Reader reader, long length)
1624+ throws SQLException;
1625+
1626+ /**
1627+ * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
1628+ * The driver converts this to an SQL <code>CLOB</code> value when it
1629+ * sends it to the database.
1630+ *
1631+ * @param parameterName the name of the parameter
1632+ * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
1633+ * @exception SQLException if a database access error occurs or
1634+ * this method is called on a closed <code>CallableStatement</code>
1635+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1636+ * this method
1637+ * @since 1.6
1638+ */
1639+ void setClob (String parameterName, Clob x) throws SQLException;
1640+
1641+ /**
1642+ * Sets the designated parameter to a <code>Reader</code> object.
1643+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1644+ * because it informs the driver that the parameter value should be sent to
1645+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1646+ * driver may have to do extra work to determine whether the parameter
1647+ * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1648+ *
1649+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1650+ * it might be more efficient to use a version of
1651+ * <code>setClob</code> which takes a length parameter.
1652+ *
1653+ * @param parameterName the name of the parameter
1654+ * @param reader An object that contains the data to set the parameter value to.
1655+ * @throws SQLException if a database access error occurs or this method is called on
1656+ * a closed <code>CallableStatement</code>
1657+ *
1658+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1659+ * @since 1.6
1660+ */
1661+ void setClob(String parameterName, Reader reader)
1662+ throws SQLException;
1663+
1664+ /**
1665+ * Sets the designated parameter in this <code>RowSet</code> object's command
1666+ * with the given <code>Array</code> value. The driver will convert this
1667+ * to the <code>ARRAY</code> value that the <code>Array</code> object
1668+ * represents before sending it to the database.
1669+ *
1670+ * @param i the first parameter is 1, the second is 2, ...
1671+ * @param x an object representing an SQL array
1672+ * @exception SQLException if a database access error occurs
1673+ */
1674+ void setArray (int i, Array x) throws SQLException;
1675+
1676+ /**
1677+ * Sets the designated parameter in this <code>RowSet</code> object's command
1678+ * with the given <code>java.sql.Date</code> value. The driver will convert this
1679+ * to an SQL <code>DATE</code> value, using the given <code>java.util.Calendar</code>
1680+ * object to calculate the date.
1681+ *
1682+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1683+ * @param x the parameter value
1684+ * @param cal the <code>java.util.Calendar</code> object to use for calculating the date
1685+ * @exception SQLException if a database access error occurs
1686+ */
1687+ void setDate(int parameterIndex, java.sql.Date x, Calendar cal)
1688+ throws SQLException;
1689+
1690+ /**
1691+ * Sets the designated parameter to the given <code>java.sql.Date</code> value
1692+ * using the default time zone of the virtual machine that is running
1693+ * the application.
1694+ * The driver converts this
1695+ * to an SQL <code>DATE</code> value when it sends it to the database.
1696+ *
1697+ * @param parameterName the name of the parameter
1698+ * @param x the parameter value
1699+ * @exception SQLException if a database access error occurs or
1700+ * this method is called on a closed <code>CallableStatement</code>
1701+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1702+ * this method
1703+ * @see #getDate
1704+ * @since 1.4
1705+ */
1706+ void setDate(String parameterName, java.sql.Date x)
1707+ throws SQLException;
1708+
1709+ /**
1710+ * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1711+ * using the given <code>Calendar</code> object. The driver uses
1712+ * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1713+ * which the driver then sends to the database. With a
1714+ * a <code>Calendar</code> object, the driver can calculate the date
1715+ * taking into account a custom timezone. If no
1716+ * <code>Calendar</code> object is specified, the driver uses the default
1717+ * timezone, which is that of the virtual machine running the application.
1718+ *
1719+ * @param parameterName the name of the parameter
1720+ * @param x the parameter value
1721+ * @param cal the <code>Calendar</code> object the driver will use
1722+ * to construct the date
1723+ * @exception SQLException if a database access error occurs or
1724+ * this method is called on a closed <code>CallableStatement</code>
1725+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1726+ * this method
1727+ * @see #getDate
1728+ * @since 1.4
1729+ */
1730+ void setDate(String parameterName, java.sql.Date x, Calendar cal)
1731+ throws SQLException;
1732+
1733+ /**
1734+ * Sets the designated parameter in this <code>RowSet</code> object's command
1735+ * with the given <code>java.sql.Time</code> value. The driver will convert this
1736+ * to an SQL <code>TIME</code> value, using the given <code>java.util.Calendar</code>
1737+ * object to calculate it, before sending it to the database.
1738+ *
1739+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1740+ * @param x the parameter value
1741+ * @param cal the <code>java.util.Calendar</code> object to use for calculating the time
1742+ * @exception SQLException if a database access error occurs
1743+ */
1744+ void setTime(int parameterIndex, java.sql.Time x, Calendar cal)
1745+ throws SQLException;
1746+
1747+ /**
1748+ * Sets the designated parameter to the given <code>java.sql.Time</code> value.
1749+ * The driver converts this
1750+ * to an SQL <code>TIME</code> value when it sends it to the database.
1751+ *
1752+ * @param parameterName the name of the parameter
1753+ * @param x the parameter value
1754+ * @exception SQLException if a database access error occurs or
1755+ * this method is called on a closed <code>CallableStatement</code>
1756+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1757+ * this method
1758+ * @see #getTime
1759+ * @since 1.4
1760+ */
1761+ void setTime(String parameterName, java.sql.Time x)
1762+ throws SQLException;
1763+
1764+ /**
1765+ * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1766+ * using the given <code>Calendar</code> object. The driver uses
1767+ * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1768+ * which the driver then sends to the database. With a
1769+ * a <code>Calendar</code> object, the driver can calculate the time
1770+ * taking into account a custom timezone. If no
1771+ * <code>Calendar</code> object is specified, the driver uses the default
1772+ * timezone, which is that of the virtual machine running the application.
1773+ *
1774+ * @param parameterName the name of the parameter
1775+ * @param x the parameter value
1776+ * @param cal the <code>Calendar</code> object the driver will use
1777+ * to construct the time
1778+ * @exception SQLException if a database access error occurs or
1779+ * this method is called on a closed <code>CallableStatement</code>
1780+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1781+ * this method
1782+ * @see #getTime
1783+ * @since 1.4
1784+ */
1785+ void setTime(String parameterName, java.sql.Time x, Calendar cal)
1786+ throws SQLException;
1787+
1788+ /**
1789+ * Sets the designated parameter in this <code>RowSet</code> object's command
1790+ * with the given <code>java.sql.Timestamp</code> value. The driver will
1791+ * convert this to an SQL <code>TIMESTAMP</code> value, using the given
1792+ * <code>java.util.Calendar</code> object to calculate it, before sending it to the
1793+ * database.
1794+ *
1795+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1796+ * @param x the parameter value
1797+ * @param cal the <code>java.util.Calendar</code> object to use for calculating the
1798+ * timestamp
1799+ * @exception SQLException if a database access error occurs
1800+ */
1801+ void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal)
1802+ throws SQLException;
1803+
1804+ /**
1805+ * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1806+ * using the given <code>Calendar</code> object. The driver uses
1807+ * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1808+ * which the driver then sends to the database. With a
1809+ * a <code>Calendar</code> object, the driver can calculate the timestamp
1810+ * taking into account a custom timezone. If no
1811+ * <code>Calendar</code> object is specified, the driver uses the default
1812+ * timezone, which is that of the virtual machine running the application.
1813+ *
1814+ * @param parameterName the name of the parameter
1815+ * @param x the parameter value
1816+ * @param cal the <code>Calendar</code> object the driver will use
1817+ * to construct the timestamp
1818+ * @exception SQLException if a database access error occurs or
1819+ * this method is called on a closed <code>CallableStatement</code>
1820+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1821+ * this method
1822+ * @see #getTimestamp
1823+ * @since 1.4
1824+ */
1825+ void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
1826+ throws SQLException;
1827+
1828+ /**
1829+ * Clears the parameters set for this <code>RowSet</code> object's command.
1830+ * <P>In general, parameter values remain in force for repeated use of a
1831+ * <code>RowSet</code> object. Setting a parameter value automatically clears its
1832+ * previous value. However, in some cases it is useful to immediately
1833+ * release the resources used by the current parameter values, which can
1834+ * be done by calling the method <code>clearParameters</code>.
1835+ *
1836+ * @exception SQLException if a database access error occurs
1837+ */
1838+ void clearParameters() throws SQLException;
1839+
1840+ //---------------------------------------------------------------------
1841+ // Reading and writing data
1842+ //---------------------------------------------------------------------
1843+
1844+ /**
1845+ * Fills this <code>RowSet</code> object with data.
1846+ * <P>
1847+ * The <code>execute</code> method may use the following properties
1848+ * to create a connection for reading data: url, data source name,
1849+ * user name, password, transaction isolation, and type map.
1850+ *
1851+ * The <code>execute</code> method may use the following properties
1852+ * to create a statement to execute a command:
1853+ * command, read only, maximum field size,
1854+ * maximum rows, escape processing, and query timeout.
1855+ * <P>
1856+ * If the required properties have not been set, an exception is
1857+ * thrown. If this method is successful, the current contents of the rowset are
1858+ * discarded and the rowset's metadata is also (re)set. If there are
1859+ * outstanding updates, they are ignored.
1860+ * <P>
1861+ * If this <code>RowSet</code> object does not maintain a continuous connection
1862+ * with its source of data, it may use a reader (a <code>RowSetReader</code>
1863+ * object) to fill itself with data. In this case, a reader will have been
1864+ * registered with this <code>RowSet</code> object, and the method
1865+ * <code>execute</code> will call on the reader's <code>readData</code>
1866+ * method as part of its implementation.
1867+ *
1868+ * @exception SQLException if a database access error occurs or any of the
1869+ * properties necessary for making a connection and creating
1870+ * a statement have not been set
1871+ */
1872+ void execute() throws SQLException;
1873+
1874+ //--------------------------------------------------------------------
1875+ // Events
1876+ //--------------------------------------------------------------------
1877+
1878+ /**
1879+ * Registers the given listener so that it will be notified of events
1880+ * that occur on this <code>RowSet</code> object.
1881+ *
1882+ * @param listener a component that has implemented the <code>RowSetListener</code>
1883+ * interface and wants to be notified when events occur on this
1884+ * <code>RowSet</code> object
1885+ * @see #removeRowSetListener
1886+ */
1887+ void addRowSetListener(RowSetListener listener);
1888+
1889+ /**
1890+ * Removes the specified listener from the list of components that will be
1891+ * notified when an event occurs on this <code>RowSet</code> object.
1892+ *
1893+ * @param listener a component that has been registered as a listener for this
1894+ * <code>RowSet</code> object
1895+ * @see #addRowSetListener
1896+ */
1897+ void removeRowSetListener(RowSetListener listener);
1898+
1899+ /**
1900+ * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1901+ * SQL <code>XML</code> value when it sends it to the database.
1902+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1903+ * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value
1904+ * @throws SQLException if a database access error occurs, this method
1905+ * is called on a closed result set,
1906+ * the <code>java.xml.transform.Result</code>,
1907+ * <code>Writer</code> or <code>OutputStream</code> has not been closed
1908+ * for the <code>SQLXML</code> object or
1909+ * if there is an error processing the XML value. The <code>getCause</code> method
1910+ * of the exception may provide a more detailed exception, for example, if the
1911+ * stream does not contain valid XML.
1912+ * @since 1.6
1913+ */
1914+ void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException;
1915+
1916+ /**
1917+ * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1918+ * <code>SQL XML</code> value when it sends it to the database.
1919+ * @param parameterName the name of the parameter
1920+ * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
1921+ * @throws SQLException if a database access error occurs, this method
1922+ * is called on a closed result set,
1923+ * the <code>java.xml.transform.Result</code>,
1924+ * <code>Writer</code> or <code>OutputStream</code> has not been closed
1925+ * for the <code>SQLXML</code> object or
1926+ * if there is an error processing the XML value. The <code>getCause</code> method
1927+ * of the exception may provide a more detailed exception, for example, if the
1928+ * stream does not contain valid XML.
1929+ * @since 1.6
1930+ */
1931+ void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException;
1932+
1933+ /**
1934+ * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1935+ * driver converts this to a SQL <code>ROWID</code> value when it sends it
1936+ * to the database
1937+ *
1938+ * @param parameterIndex the first parameter is 1, the second is 2, ...
1939+ * @param x the parameter value
1940+ * @throws SQLException if a database access error occurs
1941+ *
1942+ * @since 1.6
1943+ */
1944+ void setRowId(int parameterIndex, RowId x) throws SQLException;
1945+
1946+ /**
1947+ * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1948+ * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1949+ * database.
1950+ *
1951+ * @param parameterName the name of the parameter
1952+ * @param x the parameter value
1953+ * @throws SQLException if a database access error occurs
1954+ * @since 1.6
1955+ */
1956+ void setRowId(String parameterName, RowId x) throws SQLException;
1957+
1958+ /**
1959+ * Sets the designated paramter to the given <code>String</code> object.
1960+ * The driver converts this to a SQL <code>NCHAR</code> or
1961+ * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
1962+ * (depending on the argument's
1963+ * size relative to the driver's limits on <code>NVARCHAR</code> values)
1964+ * when it sends it to the database.
1965+ *
1966+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
1967+ * @param value the parameter value
1968+ * @throws SQLException if the driver does not support national
1969+ * character sets; if the driver can detect that a data conversion
1970+ * error could occur ; or if a database access error occurs
1971+ * @since 1.6
1972+ */
1973+ void setNString(int parameterIndex, String value) throws SQLException;
1974+
1975+ /**
1976+ * Sets the designated paramter to the given <code>String</code> object.
1977+ * The driver converts this to a SQL <code>NCHAR</code> or
1978+ * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1979+ * @param parameterName the name of the column to be set
1980+ * @param value the parameter value
1981+ * @throws SQLException if the driver does not support national
1982+ * character sets; if the driver can detect that a data conversion
1983+ * error could occur; or if a database access error occurs
1984+ * @since 1.6
1985+ */
1986+ public void setNString(String parameterName, String value)
1987+ throws SQLException;
1988+
1989+ /**
1990+ * Sets the designated parameter to a <code>Reader</code> object. The
1991+ * <code>Reader</code> reads the data till end-of-file is reached. The
1992+ * driver does the necessary conversion from Java character format to
1993+ * the national character set in the database.
1994+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
1995+ * @param value the parameter value
1996+ * @param length the number of characters in the parameter data.
1997+ * @throws SQLException if the driver does not support national
1998+ * character sets; if the driver can detect that a data conversion
1999+ * error could occur ; or if a database access error occurs
2000+ * @since 1.6
2001+ */
2002+ void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException;
2003+
2004+ /**
2005+ * Sets the designated parameter to a <code>Reader</code> object. The
2006+ * <code>Reader</code> reads the data till end-of-file is reached. The
2007+ * driver does the necessary conversion from Java character format to
2008+ * the national character set in the database.
2009+ * @param parameterName the name of the column to be set
2010+ * @param value the parameter value
2011+ * @param length the number of characters in the parameter data.
2012+ * @throws SQLException if the driver does not support national
2013+ * character sets; if the driver can detect that a data conversion
2014+ * error could occur; or if a database access error occurs
2015+ * @since 1.6
2016+ */
2017+ public void setNCharacterStream(String parameterName, Reader value, long length)
2018+ throws SQLException;
2019+
2020+ /**
2021+ * Sets the designated parameter to a <code>Reader</code> object. The
2022+ * <code>Reader</code> reads the data till end-of-file is reached. The
2023+ * driver does the necessary conversion from Java character format to
2024+ * the national character set in the database.
2025+
2026+ * <P><B>Note:</B> This stream object can either be a standard
2027+ * Java stream object or your own subclass that implements the
2028+ * standard interface.
2029+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2030+ * it might be more efficient to use a version of
2031+ * <code>setNCharacterStream</code> which takes a length parameter.
2032+ *
2033+ * @param parameterName the name of the parameter
2034+ * @param value the parameter value
2035+ * @throws SQLException if the driver does not support national
2036+ * character sets; if the driver can detect that a data conversion
2037+ * error could occur ; if a database access error occurs; or
2038+ * this method is called on a closed <code>CallableStatement</code>
2039+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2040+ * @since 1.6
2041+ */
2042+ void setNCharacterStream(String parameterName, Reader value) throws SQLException;
2043+
2044+ /**
2045+ * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
2046+ * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
2047+ * object maps to a SQL <code>NCLOB</code>.
2048+ * @param parameterName the name of the column to be set
2049+ * @param value the parameter value
2050+ * @throws SQLException if the driver does not support national
2051+ * character sets; if the driver can detect that a data conversion
2052+ * error could occur; or if a database access error occurs
2053+ * @since 1.6
2054+ */
2055+ void setNClob(String parameterName, NClob value) throws SQLException;
2056+
2057+ /**
2058+ * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
2059+ * of characters specified by length otherwise a <code>SQLException</code> will be
2060+ * generated when the <code>CallableStatement</code> is executed.
2061+ * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2062+ * because it informs the driver that the parameter value should be sent to
2063+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2064+ * driver may have to do extra work to determine whether the parameter
2065+ * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2066+ *
2067+ * @param parameterName the name of the parameter to be set
2068+ * @param reader An object that contains the data to set the parameter value to.
2069+ * @param length the number of characters in the parameter data.
2070+ * @throws SQLException if parameterIndex does not correspond to a parameter
2071+ * marker in the SQL statement; if the length specified is less than zero;
2072+ * if the driver does not support national
2073+ * character sets; if the driver can detect that a data conversion
2074+ * error could occur; if a database access error occurs or
2075+ * this method is called on a closed <code>CallableStatement</code>
2076+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2077+ * this method
2078+ * @since 1.6
2079+ */
2080+ void setNClob(String parameterName, Reader reader, long length)
2081+ throws SQLException;
2082+
2083+ /**
2084+ * Sets the designated parameter to a <code>Reader</code> object.
2085+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2086+ * because it informs the driver that the parameter value should be sent to
2087+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2088+ * driver may have to do extra work to determine whether the parameter
2089+ * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2090+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2091+ * it might be more efficient to use a version of
2092+ * <code>setNClob</code> which takes a length parameter.
2093+ *
2094+ * @param parameterName the name of the parameter
2095+ * @param reader An object that contains the data to set the parameter value to.
2096+ * @throws SQLException if the driver does not support national character sets;
2097+ * if the driver can detect that a data conversion
2098+ * error could occur; if a database access error occurs or
2099+ * this method is called on a closed <code>CallableStatement</code>
2100+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2101+ *
2102+ * @since 1.6
2103+ */
2104+ void setNClob(String parameterName, Reader reader)
2105+ throws SQLException;
2106+
2107+ /**
2108+ * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
2109+ * of characters specified by length otherwise a <code>SQLException</code> will be
2110+ * generated when the <code>PreparedStatement</code> is executed.
2111+ * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2112+ * because it informs the driver that the parameter value should be sent to
2113+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2114+ * driver may have to do extra work to determine whether the parameter
2115+ * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2116+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2117+ * @param reader An object that contains the data to set the parameter value to.
2118+ * @param length the number of characters in the parameter data.
2119+ * @throws SQLException if parameterIndex does not correspond to a parameter
2120+ * marker in the SQL statement; if the length specified is less than zero;
2121+ * if the driver does not support national character sets;
2122+ * if the driver can detect that a data conversion
2123+ * error could occur; if a database access error occurs or
2124+ * this method is called on a closed <code>PreparedStatement</code>
2125+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2126+ *
2127+ * @since 1.6
2128+ */
2129+ void setNClob(int parameterIndex, Reader reader, long length)
2130+ throws SQLException;
2131+
2132+ /**
2133+ * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a
2134+ * SQL <code>NCLOB</code> value when it sends it to the database.
2135+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
2136+ * @param value the parameter value
2137+ * @throws SQLException if the driver does not support national
2138+ * character sets; if the driver can detect that a data conversion
2139+ * error could occur ; or if a database access error occurs
2140+ * @since 1.6
2141+ */
2142+ void setNClob(int parameterIndex, NClob value) throws SQLException;
2143+
2144+ /**
2145+ * Sets the designated parameter to a <code>Reader</code> object.
2146+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2147+ * because it informs the driver that the parameter value should be sent to
2148+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2149+ * driver may have to do extra work to determine whether the parameter
2150+ * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2151+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2152+ * it might be more efficient to use a version of
2153+ * <code>setNClob</code> which takes a length parameter.
2154+ *
2155+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2156+ * @param reader An object that contains the data to set the parameter value to.
2157+ * @throws SQLException if parameterIndex does not correspond to a parameter
2158+ * marker in the SQL statement;
2159+ * if the driver does not support national character sets;
2160+ * if the driver can detect that a data conversion
2161+ * error could occur; if a database access error occurs or
2162+ * this method is called on a closed <code>PreparedStatement</code>
2163+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2164+ *
2165+ * @since 1.6
2166+ */
2167+ void setNClob(int parameterIndex, Reader reader)
2168+ throws SQLException;
2169+
2170+ /**
2171+ * Sets the designated parameter to the given <code>java.net.URL</code> value.
2172+ * The driver converts this to an SQL <code>DATALINK</code> value
2173+ * when it sends it to the database.
2174+ *
2175+ * @param parameterIndex the first parameter is 1, the second is 2, ...
2176+ * @param x the <code>java.net.URL</code> object to be set
2177+ * @exception SQLException if a database access error occurs or
2178+ * this method is called on a closed <code>PreparedStatement</code>
2179+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2180+ * @since 1.4
2181+ */
2182+ void setURL(int parameterIndex, java.net.URL x) throws SQLException;
2183+
2184+
2185+
2186+}
java/pkg/javax/sql/RowSetEvent.class+0−0

Binary file not shown.

java/pkg/javax/sql/RowSetEvent.java+62−0
@@ -0,0 +1,62 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+/**
29+ * An <code>Event</code> object generated when an event occurs to a
30+ * <code>RowSet</code> object. A <code>RowSetEvent</code> object is
31+ * generated when a single row in a rowset is changed, the whole rowset
32+ * is changed, or the rowset cursor moves.
33+ * <P>
34+ * When an event occurs on a <code>RowSet</code> object, one of the
35+ * <code>RowSetListener</code> methods will be sent to all registered
36+ * listeners to notify them of the event. An <code>Event</code> object
37+ * is supplied to the <code>RowSetListener</code> method so that the
38+ * listener can use it to find out which <code>RowSet</code> object is
39+ * the source of the event.
40+ *
41+ * @since 1.4
42+ */
43+
44+public class RowSetEvent extends java.util.EventObject {
45+
46+ /**
47+ * Constructs a <code>RowSetEvent</code> object initialized with the
48+ * given <code>RowSet</code> object.
49+ *
50+ * @param source the <code>RowSet</code> object whose data has changed or
51+ * whose cursor has moved
52+ * @throws IllegalArgumentException if <code>source</code> is null.
53+ */
54+ public RowSetEvent(RowSet source)
55+ { super(source); }
56+
57+ /**
58+ * Private serial version unique ID to ensure serialization
59+ * compatibility.
60+ */
61+ static final long serialVersionUID = -1875450876546332005L;
62+}
java/pkg/javax/sql/RowSetInternal.class+0−0

Binary file not shown.

java/pkg/javax/sql/RowSetInternal.java+103−0
@@ -0,0 +1,103 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.*;
29+
30+/**
31+ * The interface that a <code>RowSet</code> object implements in order to
32+ * present itself to a <code>RowSetReader</code> or <code>RowSetWriter</code>
33+ * object. The <code>RowSetInternal</code> interface contains
34+ * methods that let the reader or writer access and modify the internal
35+ * state of the rowset.
36+ *
37+ * @since 1.4
38+ */
39+
40+public interface RowSetInternal {
41+
42+ /**
43+ * Retrieves the parameters that have been set for this
44+ * <code>RowSet</code> object's command.
45+ *
46+ * @return an array of the current parameter values for this <code>RowSet</code>
47+ * object's command
48+ * @exception SQLException if a database access error occurs
49+ */
50+ Object[] getParams() throws SQLException;
51+
52+ /**
53+ * Retrieves the <code>Connection</code> object that was passed to this
54+ * <code>RowSet</code> object.
55+ *
56+ * @return the <code>Connection</code> object passed to the rowset
57+ * or <code>null</code> if none was passed
58+ * @exception SQLException if a database access error occurs
59+ */
60+ Connection getConnection() throws SQLException;
61+
62+ /**
63+ * Sets the given <code>RowSetMetaData</code> object as the
64+ * <code>RowSetMetaData</code> object for this <code>RowSet</code>
65+ * object. The <code>RowSetReader</code> object associated with the rowset
66+ * will use <code>RowSetMetaData</code> methods to set the values giving
67+ * information about the rowset's columns.
68+ *
69+ * @param md the <code>RowSetMetaData</code> object that will be set with
70+ * information about the rowset's columns
71+ *
72+ * @exception SQLException if a database access error occurs
73+ */
74+ void setMetaData(RowSetMetaData md) throws SQLException;
75+
76+ /**
77+ * Retrieves a <code>ResultSet</code> object containing the original
78+ * value of this <code>RowSet</code> object.
79+ * <P>
80+ * The cursor is positioned before the first row in the result set.
81+ * Only rows contained in the result set returned by the method
82+ * <code>getOriginal</code> are said to have an original value.
83+ *
84+ * @return the original value of the rowset
85+ * @exception SQLException if a database access error occurs
86+ */
87+ public ResultSet getOriginal() throws SQLException;
88+
89+ /**
90+ * Retrieves a <code>ResultSet</code> object containing the original value
91+ * of the current row only. If the current row has no original value,
92+ * an empty result set is returned. If there is no current row,
93+ * an exception is thrown.
94+ *
95+ * @return the original value of the current row as a <code>ResultSet</code>
96+ * object
97+ * @exception SQLException if a database access error occurs or this method
98+ * is called while the cursor is on the insert row, before the
99+ * first row, or after the last row
100+ */
101+ public ResultSet getOriginalRow() throws SQLException;
102+
103+}
java/pkg/javax/sql/RowSetListener.class+0−0

Binary file not shown.

java/pkg/javax/sql/RowSetListener.java+77−0
@@ -0,0 +1,77 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+/**
29+ * An interface that must be implemented by a
30+ * component that wants to be notified when a significant
31+ * event happens in the life of a <code>RowSet</code> object.
32+ * A component becomes a listener by being registered with a
33+ * <code>RowSet</code> object via the method <code>RowSet.addRowSetListener</code>.
34+ * How a registered component implements this interface determines what it does
35+ * when it is notified of an event.
36+ *
37+ * @since 1.4
38+ */
39+
40+public interface RowSetListener extends java.util.EventListener {
41+
42+ /**
43+ * Notifies registered listeners that a <code>RowSet</code> object
44+ * in the given <code>RowSetEvent</code> object has changed its entire contents.
45+ * <P>
46+ * The source of the event can be retrieved with the method
47+ * <code>event.getSource</code>.
48+ *
49+ * @param event a <code>RowSetEvent</code> object that contains
50+ * the <code>RowSet</code> object that is the source of the event
51+ */
52+ void rowSetChanged(RowSetEvent event);
53+
54+ /**
55+ * Notifies registered listeners that a <code>RowSet</code> object
56+ * has had a change in one of its rows.
57+ * <P>
58+ * The source of the event can be retrieved with the method
59+ * <code>event.getSource</code>.
60+ *
61+ * @param event a <code>RowSetEvent</code> object that contains
62+ * the <code>RowSet</code> object that is the source of the event
63+ */
64+ void rowChanged(RowSetEvent event);
65+
66+ /**
67+ * Notifies registered listeners that a <code>RowSet</code> object's
68+ * cursor has moved.
69+ * <P>
70+ * The source of the event can be retrieved with the method
71+ * <code>event.getSource</code>.
72+ *
73+ * @param event a <code>RowSetEvent</code> object that contains
74+ * the <code>RowSet</code> object that is the source of the event
75+ */
76+ void cursorMoved(RowSetEvent event);
77+}
java/pkg/javax/sql/RowSetMetaData.class+0−0

Binary file not shown.

java/pkg/javax/sql/RowSetMetaData.java+235−0
@@ -0,0 +1,235 @@
1+/*
2+ * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.*;
29+
30+/**
31+ * An object that contains information about the columns in a
32+ * <code>RowSet</code> object. This interface is
33+ * an extension of the <code>ResultSetMetaData</code> interface with
34+ * methods for setting the values in a <code>RowSetMetaData</code> object.
35+ * When a <code>RowSetReader</code> object reads data into a <code>RowSet</code>
36+ * object, it creates a <code>RowSetMetaData</code> object and initializes it
37+ * using the methods in the <code>RowSetMetaData</code> interface. Then the
38+ * reader passes the <code>RowSetMetaData</code> object to the rowset.
39+ * <P>
40+ * The methods in this interface are invoked internally when an application
41+ * calls the method <code>RowSet.execute</code>; an application
42+ * programmer would not use them directly.
43+ *
44+ * @since 1.4
45+ */
46+
47+public interface RowSetMetaData extends ResultSetMetaData {
48+
49+ /**
50+ * Sets the number of columns in the <code>RowSet</code> object to
51+ * the given number.
52+ *
53+ * @param columnCount the number of columns in the <code>RowSet</code> object
54+ * @exception SQLException if a database access error occurs
55+ */
56+ void setColumnCount(int columnCount) throws SQLException;
57+
58+ /**
59+ * Sets whether the designated column is automatically numbered,
60+ * The default is for a <code>RowSet</code> object's
61+ * columns not to be automatically numbered.
62+ *
63+ * @param columnIndex the first column is 1, the second is 2, ...
64+ * @param property <code>true</code> if the column is automatically
65+ * numbered; <code>false</code> if it is not
66+ *
67+ * @exception SQLException if a database access error occurs
68+ */
69+ void setAutoIncrement(int columnIndex, boolean property) throws SQLException;
70+
71+ /**
72+ * Sets whether the designated column is case sensitive.
73+ * The default is <code>false</code>.
74+ *
75+ * @param columnIndex the first column is 1, the second is 2, ...
76+ * @param property <code>true</code> if the column is case sensitive;
77+ * <code>false</code> if it is not
78+ *
79+ * @exception SQLException if a database access error occurs
80+ */
81+ void setCaseSensitive(int columnIndex, boolean property) throws SQLException;
82+
83+ /**
84+ * Sets whether the designated column can be used in a where clause.
85+ * The default is <code>false</code>.
86+ *
87+ * @param columnIndex the first column is 1, the second is 2, ...
88+ * @param property <code>true</code> if the column can be used in a
89+ * <code>WHERE</code> clause; <code>false</code> if it cannot
90+ *
91+ * @exception SQLException if a database access error occurs
92+ */
93+ void setSearchable(int columnIndex, boolean property) throws SQLException;
94+
95+ /**
96+ * Sets whether the designated column is a cash value.
97+ * The default is <code>false</code>.
98+ *
99+ * @param columnIndex the first column is 1, the second is 2, ...
100+ * @param property <code>true</code> if the column is a cash value;
101+ * <code>false</code> if it is not
102+ *
103+ * @exception SQLException if a database access error occurs
104+ */
105+ void setCurrency(int columnIndex, boolean property) throws SQLException;
106+
107+ /**
108+ * Sets whether the designated column's value can be set to
109+ * <code>NULL</code>.
110+ * The default is <code>ResultSetMetaData.columnNullableUnknown</code>
111+ *
112+ * @param columnIndex the first column is 1, the second is 2, ...
113+ * @param property one of the following constants:
114+ * <code>ResultSetMetaData.columnNoNulls</code>,
115+ * <code>ResultSetMetaData.columnNullable</code>, or
116+ * <code>ResultSetMetaData.columnNullableUnknown</code>
117+ *
118+ * @exception SQLException if a database access error occurs
119+ */
120+ void setNullable(int columnIndex, int property) throws SQLException;
121+
122+ /**
123+ * Sets whether the designated column is a signed number.
124+ * The default is <code>false</code>.
125+ *
126+ * @param columnIndex the first column is 1, the second is 2, ...
127+ * @param property <code>true</code> if the column is a signed number;
128+ * <code>false</code> if it is not
129+ *
130+ * @exception SQLException if a database access error occurs
131+ */
132+ void setSigned(int columnIndex, boolean property) throws SQLException;
133+
134+ /**
135+ * Sets the designated column's normal maximum width in chars to the
136+ * given <code>int</code>.
137+ *
138+ * @param columnIndex the first column is 1, the second is 2, ...
139+ * @param size the normal maximum number of characters for
140+ * the designated column
141+ *
142+ * @exception SQLException if a database access error occurs
143+ */
144+ void setColumnDisplaySize(int columnIndex, int size) throws SQLException;
145+
146+ /**
147+ * Sets the suggested column title for use in printouts and
148+ * displays, if any, to the given <code>String</code>.
149+ *
150+ * @param columnIndex the first column is 1, the second is 2, ...
151+ * @param label the column title
152+ * @exception SQLException if a database access error occurs
153+ */
154+ void setColumnLabel(int columnIndex, String label) throws SQLException;
155+
156+ /**
157+ * Sets the name of the designated column to the given <code>String</code>.
158+ *
159+ * @param columnIndex the first column is 1, the second is 2, ...
160+ * @param columnName the designated column's name
161+ * @exception SQLException if a database access error occurs
162+ */
163+ void setColumnName(int columnIndex, String columnName) throws SQLException;
164+
165+ /**
166+ * Sets the name of the designated column's table's schema, if any, to
167+ * the given <code>String</code>.
168+ *
169+ * @param columnIndex the first column is 1, the second is 2, ...
170+ * @param schemaName the schema name
171+ * @exception SQLException if a database access error occurs
172+ */
173+ void setSchemaName(int columnIndex, String schemaName) throws SQLException;
174+
175+ /**
176+ * Sets the designated column's number of decimal digits to the
177+ * given <code>int</code>.
178+ *
179+ * @param columnIndex the first column is 1, the second is 2, ...
180+ * @param precision the total number of decimal digits
181+ * @exception SQLException if a database access error occurs
182+ */
183+ void setPrecision(int columnIndex, int precision) throws SQLException;
184+
185+ /**
186+ * Sets the designated column's number of digits to the
187+ * right of the decimal point to the given <code>int</code>.
188+ *
189+ * @param columnIndex the first column is 1, the second is 2, ...
190+ * @param scale the number of digits to right of decimal point
191+ * @exception SQLException if a database access error occurs
192+ */
193+ void setScale(int columnIndex, int scale) throws SQLException;
194+
195+ /**
196+ * Sets the designated column's table name, if any, to the given
197+ * <code>String</code>.
198+ *
199+ * @param columnIndex the first column is 1, the second is 2, ...
200+ * @param tableName the column's table name
201+ * @exception SQLException if a database access error occurs
202+ */
203+ void setTableName(int columnIndex, String tableName) throws SQLException;
204+
205+ /**
206+ * Sets the designated column's table's catalog name, if any, to the given
207+ * <code>String</code>.
208+ *
209+ * @param columnIndex the first column is 1, the second is 2, ...
210+ * @param catalogName the column's catalog name
211+ * @exception SQLException if a database access error occurs
212+ */
213+ void setCatalogName(int columnIndex, String catalogName) throws SQLException;
214+
215+ /**
216+ * Sets the designated column's SQL type to the one given.
217+ *
218+ * @param columnIndex the first column is 1, the second is 2, ...
219+ * @param SQLType the column's SQL type
220+ * @exception SQLException if a database access error occurs
221+ * @see Types
222+ */
223+ void setColumnType(int columnIndex, int SQLType) throws SQLException;
224+
225+ /**
226+ * Sets the designated column's type name that is specific to the
227+ * data source, if any, to the given <code>String</code>.
228+ *
229+ * @param columnIndex the first column is 1, the second is 2, ...
230+ * @param typeName data source specific type name.
231+ * @exception SQLException if a database access error occurs
232+ */
233+ void setColumnTypeName(int columnIndex, String typeName) throws SQLException;
234+
235+}
java/pkg/javax/sql/RowSetReader.class+0−0

Binary file not shown.

java/pkg/javax/sql/RowSetReader.java+73−0
@@ -0,0 +1,73 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.*;
29+
30+/**
31+ * The facility that a disconnected <code>RowSet</code> object calls on
32+ * to populate itself with rows of data. A reader (an object implementing the
33+ * <code>RowSetReader</code> interface) may be registered with
34+ * a <code>RowSet</code> object that supports the reader/writer paradigm.
35+ * When the <code>RowSet</code> object's <code>execute</code> method is
36+ * called, it in turn calls the reader's <code>readData</code> method.
37+ *
38+ * @since 1.4
39+ */
40+
41+public interface RowSetReader {
42+
43+ /**
44+ * Reads the new contents of the calling <code>RowSet</code> object.
45+ * In order to call this method, a <code>RowSet</code>
46+ * object must have implemented the <code>RowSetInternal</code> interface
47+ * and registered this <code>RowSetReader</code> object as its reader.
48+ * The <code>readData</code> method is invoked internally
49+ * by the <code>RowSet.execute</code> method for rowsets that support the
50+ * reader/writer paradigm.
51+ *
52+ * <P>The <code>readData</code> method adds rows to the caller.
53+ * It can be implemented in a wide variety of ways and can even
54+ * populate the caller with rows from a nonrelational data source.
55+ * In general, a reader may invoke any of the rowset's methods,
56+ * with one exception. Calling the method <code>execute</code> will
57+ * cause an <code>SQLException</code> to be thrown
58+ * because <code>execute</code> may not be called recursively. Also,
59+ * when a reader invokes <code>RowSet</code> methods, no listeners
60+ * are notified; that is, no <code>RowSetEvent</code> objects are
61+ * generated and no <code>RowSetListener</code> methods are invoked.
62+ * This is true because listeners are already being notified by the method
63+ * <code>execute</code>.
64+ *
65+ * @param caller the <code>RowSet</code> object (1) that has implemented the
66+ * <code>RowSetInternal</code> interface, (2) with which this reader is
67+ * registered, and (3) whose <code>execute</code> method called this reader
68+ * @exception SQLException if a database access error occurs or this method
69+ * invokes the <code>RowSet.execute</code> method
70+ */
71+ void readData(RowSetInternal caller) throws SQLException;
72+
73+}
java/pkg/javax/sql/RowSetWriter.class+0−0

Binary file not shown.

java/pkg/javax/sql/RowSetWriter.java+64−0
@@ -0,0 +1,64 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.*;
29+
30+/**
31+ * An object that implements the <code>RowSetWriter</code> interface,
32+ * called a <i>writer</i>. A writer may be registered with a <code>RowSet</code>
33+ * object that supports the reader/writer paradigm.
34+ * <P>
35+ * If a disconnected <code>RowSet</code> object modifies some of its data,
36+ * and it has a writer associated with it, it may be implemented so that it
37+ * calls on the writer's <code>writeData</code> method internally
38+ * to write the updates back to the data source. In order to do this, the writer
39+ * must first establish a connection with the rowset's data source.
40+ * <P>
41+ * If the data to be updated has already been changed in the data source, there
42+ * is a conflict, in which case the writer will not write
43+ * the changes to the data source. The algorithm the writer uses for preventing
44+ * or limiting conflicts depends entirely on its implementation.
45+ *
46+ * @since 1.4
47+ */
48+
49+public interface RowSetWriter {
50+
51+ /**
52+ * Writes the changes in this <code>RowSetWriter</code> object's
53+ * rowset back to the data source from which it got its data.
54+ *
55+ * @param caller the <code>RowSet</code> object (1) that has implemented the
56+ * <code>RowSetInternal</code> interface, (2) with which this writer is
57+ * registered, and (3) that called this method internally
58+ * @return <code>true</code> if the modified data was written; <code>false</code>
59+ * if not, which will be the case if there is a conflict
60+ * @exception SQLException if a database access error occurs
61+ */
62+ boolean writeData(RowSetInternal caller) throws SQLException;
63+
64+}
java/pkg/javax/sql/StatementEvent.class+0−0

Binary file not shown.

java/pkg/javax/sql/StatementEvent.java+117−0
@@ -0,0 +1,117 @@
1+/*
2+ * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+/*
27+ * Created on Apr 28, 2005
28+ */
29+package javax.sql;
30+
31+import java.sql.PreparedStatement;
32+import java.sql.SQLException;
33+import java.util.EventObject;
34+
35+/**
36+ * A <code>StatementEvent</code> is sent to all <code>StatementEventListener</code>s which were
37+ * registered with a <code>PooledConnection</code>. This occurs when the driver determines that a
38+ * <code>PreparedStatement</code> that is associated with the <code>PooledConnection</code> has been closed or the driver determines
39+ * is invalid.
40+ * <p>
41+ * @since 1.6
42+ */
43+public class StatementEvent extends EventObject {
44+
45+ private SQLException exception;
46+ private PreparedStatement statement;
47+
48+ /**
49+ * Constructs a <code>StatementEvent</code> with the specified <code>PooledConnection</code> and
50+ * <code>PreparedStatement</code>. The <code>SQLException</code> contained in the event defaults to
51+ * null.
52+ * <p>
53+ * @param con The <code>PooledConnection</code> that the closed or invalid
54+ * <code>PreparedStatement</code>is associated with.
55+ * @param statement The <code>PreparedStatement</code> that is bieng closed or is invalid
56+ * <p>
57+ * @throws IllegalArgumentException if <code>con</code> is null.
58+ *
59+ * @since 1.6
60+ */
61+ public StatementEvent(PooledConnection con,
62+ PreparedStatement statement) {
63+
64+ super(con);
65+
66+ this.statement = statement;
67+ this.exception = null;
68+ }
69+
70+ /**
71+ * Constructs a <code>StatementEvent</code> with the specified <code>PooledConnection</code>,
72+ * <code>PreparedStatement</code> and <code>SQLException</code>
73+ * <p>
74+ * @param con The <code>PooledConnection</code> that the closed or invalid <code>PreparedStatement</code>
75+ * is associated with.
76+ * @param statement The <code>PreparedStatement</code> that is being closed or is invalid
77+ * @param exception The <code>SQLException </code>the driver is about to throw to
78+ * the application
79+ *
80+ * @throws IllegalArgumentException if <code>con</code> is null.
81+ * <p>
82+ * @since 1.6
83+ */
84+ public StatementEvent(PooledConnection con,
85+ PreparedStatement statement,
86+ SQLException exception) {
87+
88+ super(con);
89+
90+ this.statement = statement;
91+ this.exception = exception;
92+ }
93+
94+ /**
95+ * Returns the <code>PreparedStatement</code> that is being closed or is invalid
96+ * <p>
97+ * @return The <code>PreparedStatement</code> that is being closed or is invalid
98+ * <p>
99+ * @since 1.6
100+ */
101+ public PreparedStatement getStatement() {
102+
103+ return this.statement;
104+ }
105+
106+ /**
107+ * Returns the <code>SQLException</code> the driver is about to throw
108+ * <p>
109+ * @return The <code>SQLException</code> the driver is about to throw
110+ * <p>
111+ * @since 1.6
112+ */
113+ public SQLException getSQLException() {
114+
115+ return this.exception;
116+ }
117+}
java/pkg/javax/sql/StatementEventListener.class+0−0

Binary file not shown.

java/pkg/javax/sql/StatementEventListener.java+86−0
@@ -0,0 +1,86 @@
1+/*
2+ * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+/*
27+ * Created on Apr 28, 2005
28+ */
29+package javax.sql;
30+
31+/**
32+ * An object that registers to be notified of events that occur on PreparedStatements
33+ * that are in the Statement pool.
34+ * <p>
35+ * The JDBC 3.0 specification added the maxStatements
36+ * <code>ConnectionPooledDataSource</code> property to provide a standard mechanism for
37+ * enabling the pooling of <code>PreparedStatements</code>
38+ * and to specify the size of the statement
39+ * pool. However, there was no way for a driver to notify an external
40+ * statement pool when a <code>PreparedStatement</code> becomes invalid. For some databases, a
41+ * statement becomes invalid if a DDL operation is performed that affects the
42+ * table. For example an application may create a temporary table to do some work
43+ * on the table and then destroy it. It may later recreate the same table when
44+ * it is needed again. Some databases will invalidate any prepared statements
45+ * that reference the temporary table when the table is dropped.
46+ * <p>
47+ * Similar to the methods defined in the <code>ConnectionEventListener</code> interface,
48+ * the driver will call the <code>StatementEventListener.statementErrorOccurred</code>
49+ * method prior to throwing any exceptions when it detects a statement is invalid.
50+ * The driver will also call the <code>StatementEventListener.statementClosed</code>
51+ * method when a <code>PreparedStatement</code> is closed.
52+ * <p>
53+ * Methods which allow a component to register a StatementEventListener with a
54+ * <code>PooledConnection</code> have been added to the <code>PooledConnection</code> interface.
55+ * <p>
56+ * @since 1.6
57+ */
58+public interface StatementEventListener extends java.util.EventListener{
59+ /**
60+ * The driver calls this method on all <code>StatementEventListener</code>s registered on the connection when it detects that a
61+ * <code>PreparedStatement</code> is closed.
62+ *
63+ * @param event an event object describing the source of
64+ * the event and that the <code>PreparedStatement</code> was closed.
65+ * @since 1.6
66+ */
67+ void statementClosed(StatementEvent event);
68+
69+ /**
70+ * The driver calls this method on all <code>StatementEventListener</code>s
71+ * registered on the connection when it detects that a
72+ * <code>PreparedStatement</code> is invalid. The driver calls this method
73+ * just before it throws the <code>SQLException</code>,
74+ * contained in the given event, to the application.
75+ * <p>
76+ * @param event an event object describing the source of the event,
77+ * the statement that is invalid and the exception the
78+ * driver is about to throw. The source of the event is
79+ * the <code>PooledConnection</code> which the invalid <code>PreparedStatement</code>
80+ * is associated with.
81+ * <p>
82+ * @since 1.6
83+ */
84+ void statementErrorOccurred(StatementEvent event);
85+
86+}
java/pkg/javax/sql/XAConnection.class+0−0

Binary file not shown.

java/pkg/javax/sql/XAConnection.java+61−0
@@ -0,0 +1,61 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.*;
29+
30+
31+/**
32+ * An object that provides support for distributed
33+ * transactions. An <code>XAConnection</code> object may be enlisted
34+ * in a distributed transaction by means of an <code>XAResource</code> object.
35+ * A transaction manager, usually part of a middle tier server, manages an
36+ * <code>XAConnection</code> object through the <code>XAResource</code> object.
37+ * <P>
38+ * An application programmer does not use this interface directly; rather,
39+ * it is used by a transaction manager working in the middle tier server.
40+ *
41+ * @since 1.4
42+ */
43+
44+public interface XAConnection extends PooledConnection {
45+
46+
47+ /**
48+ * Retrieves an <code>XAResource</code> object that
49+ * the transaction manager will use
50+ * to manage this <code>XAConnection</code> object's participation in a
51+ * distributed transaction.
52+ *
53+ * @return the <code>XAResource</code> object
54+ * @exception SQLException if a database access error occurs
55+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
56+ * this method
57+ * @since 1.4
58+ */
59+ javax.transaction.xa.XAResource getXAResource() throws SQLException;
60+
61+ }
java/pkg/javax/sql/XADataSource.class+0−0

Binary file not shown.

java/pkg/javax/sql/XADataSource.java+73−0
@@ -0,0 +1,73 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql;
27+
28+import java.sql.*;
29+
30+/**
31+ * A factory for <code>XAConnection</code> objects that is used internally.
32+ * An object that implements the <code>XADataSource</code> interface is
33+ * typically registered with a naming service that uses the
34+ * Java Naming and Directory Interface<sup><font size=-3>TM</font></sup>
35+ * (JNDI).
36+ *
37+ * @since 1.4
38+ */
39+
40+public interface XADataSource extends CommonDataSource {
41+
42+ /**
43+ * Attempts to establish a physical database connection that can be
44+ * used in a distributed transaction.
45+ *
46+ * @return an <code>XAConnection</code> object, which represents a
47+ * physical connection to a data source, that can be used in
48+ * a distributed transaction
49+ * @exception SQLException if a database access error occurs
50+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
51+ * this method
52+ * @since 1.4
53+ */
54+ XAConnection getXAConnection() throws SQLException;
55+
56+ /**
57+ * Attempts to establish a physical database connection, using the given
58+ * user name and password. The connection that is returned is one that
59+ * can be used in a distributed transaction.
60+ *
61+ * @param user the database user on whose behalf the connection is being made
62+ * @param password the user's password
63+ * @return an <code>XAConnection</code> object, which represents a
64+ * physical connection to a data source, that can be used in
65+ * a distributed transaction
66+ * @exception SQLException if a database access error occurs
67+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
68+ * this method
69+ * @since 1.4
70+ */
71+ XAConnection getXAConnection(String user, String password)
72+ throws SQLException;
73+ }
java/pkg/javax/sql/mkfile+28−0
@@ -0,0 +1,28 @@
1+<../../../../mkconfig
2+
3+DIRS=\
4+ rowset\
5+
6+TARG=\
7+ CommonDataSource.dis\
8+ ConnectionEvent.dis\
9+ ConnectionEventListener.dis\
10+ ConnectionPoolDataSource.dis\
11+ DataSource.dis\
12+ PooledConnection.dis\
13+ RowSet.dis\
14+ RowSetEvent.dis\
15+ RowSetInternal.dis\
16+ RowSetListener.dis\
17+ RowSetMetaData.dis\
18+ RowSetReader.dis\
19+ RowSetWriter.dis\
20+ StatementEvent.dis\
21+ StatementEventListener.dis\
22+ XAConnection.dis\
23+ XADataSource.dis\
24+
25+DISBIN=$ROOT/java/dis/java/java/javax/sql
26+
27+<$ROOT/mkfiles/mkjava
28+<$ROOT/mkfiles/mksubdirs
java/pkg/javax/sql/package.html+316−0
@@ -0,0 +1,316 @@
1+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2+<html>
3+<head>
4+<!--
5+Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
6+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
7+
8+This code is free software; you can redistribute it and/or modify it
9+under the terms of the GNU General Public License version 2 only, as
10+published by the Free Software Foundation. Oracle designates this
11+particular file as subject to the "Classpath" exception as provided
12+by Oracle in the LICENSE file that accompanied this code.
13+
14+This code is distributed in the hope that it will be useful, but WITHOUT
15+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17+version 2 for more details (a copy is included in the LICENSE file that
18+accompanied this code).
19+
20+You should have received a copy of the GNU General Public License version
21+2 along with this work; if not, write to the Free Software Foundation,
22+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
23+
24+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
25+or visit www.oracle.com if you need additional information or have any
26+questions.
27+-->
28+
29+</head>
30+
31+
32+
33+<body bgcolor="white">
34+
35+Provides the API for server side data source access and processing from
36+the Java<sup><font size=-2>TM</font></sup> programming language.
37+This package supplements the <code>java.sql</code>
38+package and, as of the version 1.4 release, is included in the
39+Java Platform, Standard Edition
40+(Java SE<sup><font size=-2>TM</sup></font>).
41+It remains an essential part of the Java Platform, Enterprise Edition
42+(Java EE<sup><font size=-2>TM</sup></font>).
43+<P>
44+The <code>javax.sql</code> package provides for the following:
45+<OL>
46+ <LI>The <code>DataSource</code> interface as an alternative to the
47+ <code>DriverManager</code> for establishing a
48+ connection with a data source
49+ <LI>Connection pooling and Statement pooling
50+ <LI>Distributed transactions
51+ <LI>Rowsets
52+</OL>
53+<P>
54+Applications use the <code>DataSource</code> and <code>RowSet</code>
55+APIs directly, but the connection pooling and distributed transaction
56+APIs are used internally by the middle-tier infrastructure.
57+
58+<H2>Using a <code>DataSource</code> Object to Make a Connection</H2>
59+
60+The <code>javax.sql</code> package provides the preferred
61+way to make a connection with a data source. The <code>DriverManager</code>
62+class, the original mechanism, is still valid, and code using it will
63+continue to run. However, the newer <code>DataSource</code> mechanism
64+is preferred because it offers many advantages over the
65+<code>DriverManager</code> mechanism.
66+<P>
67+These are the main advantages of using a <code>DataSource</code> object to
68+make a connection:
69+<UL>
70+
71+ <LI>Changes can be made to a data source's properties, which means
72+ that it is not necessary to make changes in application code when
73+ something about the data source or driver changes.
74+ <LI>Connection and Statement pooling and distributed transactions are available
75+ through a <code>DataSource</code> object that is
76+ implemented to work with the middle-tier infrastructure.
77+ Connections made through the <code>DriverManager</code>
78+ do not have connection and statement pooling or distributed transaction
79+ capabilities.
80+</UL>
81+<P>
82+Driver vendors provide <code>DataSource</code> implementations. A
83+particular <code>DataSource</code> object represents a particular
84+physical data source, and each connection the <code>DataSource</code> object
85+creates is a connection to that physical data source.
86+<P>
87+A logical name for the data source is registered with a naming service that
88+uses the Java Naming and Directory Interface<sup><font size=-2>TM</font></sup>
89+(JNDI) API, usually by a system administrator or someone performing the
90+duties of a system administrator. An application can retrieve the
91+<code>DataSource</code> object it wants by doing a lookup on the logical
92+name that has been registered for it. The application can then use the
93+<code>DataSource</code> object to create a connection to the physical data
94+source it represents.
95+<P>
96+A <code>DataSource</code> object can be implemented to work with the
97+middle tier infrastructure so that the connections it produces will be
98+pooled for reuse. An application that uses such a <code>DataSource</code>
99+implementation will automatically get a connection that participates in
100+connection pooling.
101+A <code>DataSource</code> object can also be implemented to work with the
102+middle tier infrastructure so that the connections it produces can be
103+used for distributed transactions without any special coding.
104+
105+<H2>Connection Pooling and Statement Pooling</H2>
106+
107+Connections made via a <code>DataSource</code>
108+object that is implemented to work with a middle tier connection pool manager
109+will participate in connection pooling. This can improve performance
110+dramatically because creating new connections is very expensive.
111+Connection pooling allows a connection to be used and reused,
112+thus cutting down substantially on the number of new connections
113+that need to be created.
114+<P>
115+Connection pooling is totally transparent. It is done automatically
116+in the middle tier of a Java EE configuration, so from an application's
117+viewpoint, no change in code is required. An application simply uses
118+the <code>DataSource.getConnection</code> method to get the pooled
119+connection and uses it the same way it uses any <code>Connection</code>
120+object.
121+<P>
122+The classes and interfaces used for connection pooling are:
123+<UL>
124+ <LI><code>ConnectionPoolDataSource</code>
125+ <LI><code>PooledConnection</code>
126+ <LI><code>ConnectionEvent</code>
127+ <LI><code>ConnectionEventListener</code>
128+ <LI><code>StatementEvent</code>
129+ <LI><code>StatementEventListener</code>
130+</UL>
131+The connection pool manager, a facility in the middle tier of
132+a three-tier architecture, uses these classes and interfaces
133+behind the scenes. When a <code>ConnectionPoolDataSource</code> object
134+is called on to create a <code>PooledConnection</code> object, the
135+connection pool manager will register as a <code>ConnectionEventListener</code>
136+object with the new <code>PooledConnection</code> object. When the connection
137+is closed or there is an error, the connection pool manager (being a listener)
138+gets a notification that includes a <code>ConnectionEvent</code> object.
139+<p>
140+If the connection pool manager supports <code>Statement</code> pooling, for
141+<code>PreparedStatements</code>, which can be determined by invoking the method
142+<code>DatabaseMetaData.supportsStatementPooling</code>, the
143+connection pool manager will register as a <code>StatementEventListener</code>
144+object with the new <code>PooledConnection</code> object. When the
145+<code>PreparedStatement</code> is closed or there is an error, the connection
146+pool manager (being a listener)
147+gets a notification that includes a <code>StatementEvent</code> object.
148+<p>
149+
150+<H2>Distributed Transactions</H2>
151+
152+As with pooled connections, connections made via a <code>DataSource</code>
153+object that is implemented to work with the middle tier infrastructure
154+may participate in distributed transactions. This gives an application
155+the ability to involve data sources on multiple servers in a single
156+transaction.
157+<P>
158+The classes and interfaces used for distributed transactions are:
159+<UL>
160+ <LI><code>XADataSource</code>
161+ <LI><code>XAConnection</code>
162+</UL>
163+These interfaces are used by the transaction manager; an application does
164+not use them directly.
165+<P>
166+The <code>XAConnection</code> interface is derived from the
167+<code>PooledConnection</code> interface, so what applies to a pooled connection
168+also applies to a connection that is part of a distributed transaction.
169+A transaction manager in the middle tier handles everything transparently.
170+The only change in application code is that an application cannot do anything
171+that would interfere with the transaction manager's handling of the transaction.
172+Specifically, an application cannot call the methods <code>Connection.commit</code>
173+or <code>Connection.rollback</code>, and it cannot set the connection to be in
174+auto-commit mode (that is, it cannot call
175+<code>Connection.setAutoCommit(true)</code>).
176+<P>
177+An application does not need to do anything special to participate in a
178+distributed transaction.
179+It simply creates connections to the data sources it wants to use via
180+the <code>DataSource.getConnection</code> method, just as it normally does.
181+The transaction manager manages the transaction behind the scenes. The
182+<code>XADataSource</code> interface creates <code>XAConnection</code> objects, and
183+each <code>XAConnection</code> object creates an <code>XAResource</code> object
184+that the transaction manager uses to manage the connection.
185+
186+
187+<H2>Rowsets</H2>
188+The <code>RowSet</code> interface works with various other classes and
189+interfaces behind the scenes. These can be grouped into three categories.
190+<OL>
191+<LI>Event Notification
192+<UL>
193+ <LI><code>RowSetListener</code><br>
194+A <code>RowSet</code> object is a JavaBeans<sup><font size=-2>TM</font></sup>
195+component because it has properties and participates in the JavaBeans
196+event notification mechanism. The <code>RowSetListener</code> interface
197+is implemented by a component that wants to be notified about events that
198+occur to a particular <code>RowSet</code> object. Such a component registers
199+itself as a listener with a rowset via the <code>RowSet.addRowSetListener</code>
200+method.
201+<P>
202+When the <code>RowSet</code> object changes one of its rows, changes all of
203+it rows, or moves its cursor, it also notifies each listener that is registered
204+with it. The listener reacts by carrying out its implementation of the
205+notification method called on it.
206+<P>
207+ <LI><code>RowSetEvent</code><br>
208+As part of its internal notification process, a <code>RowSet</code> object
209+creates an instance of <code>RowSetEvent</code> and passes it to the listener.
210+The listener can use this <code>RowSetEvent</code> object to find out which rowset
211+had the event.
212+</UL>
213+<P>
214+<LI>Metadata
215+<UL>
216+ <LI><code>RowSetMetaData</code><br>
217+This interface, derived from the
218+<code>ResultSetMetaData</code> interface, provides information about
219+the columns in a <code>RowSet</code> object. An application can use
220+<code>RowSetMetaData</code> methods to find out how many columns the
221+rowset contains and what kind of data each column can contain.
222+<P>
223+The <code>RowSetMetaData</code> interface provides methods for
224+setting the information about columns, but an application would not
225+normally use these methods. When an application calls the <code>RowSet</code>
226+method <code>execute</code>, the <code>RowSet</code> object will contain
227+a new set of rows, and its <code>RowSetMetaData</code> object will have been
228+internally updated to contain information about the new columns.
229+<P>
230+</UL>
231+<LI>The Reader/Writer Facility<br>
232+A <code>RowSet</code> object that implements the <code>RowSetInternal</code>
233+interface can call on the <code>RowSetReader</code> object associated with it
234+to populate itself with data. It can also call on the <code>RowSetWriter</code>
235+object associated with it to write any changes to its rows back to the
236+data source from which it originally got the rows.
237+A rowset that remains connected to its data source does not need to use a
238+reader and writer because it can simply operate on the data source directly.
239+
240+<UL>
241+ <LI><code>RowSetInternal</code><br>
242+By implementing the <code>RowSetInternal</code> interface, a
243+<code>RowSet</code> object gets access to
244+its internal state and is able to call on its reader and writer. A rowset
245+keeps track of the values in its current rows and of the values that immediately
246+preceded the current ones, referred to as the <i>original</i> values. A rowset
247+also keeps track of (1) the parameters that have been set for its command and
248+(2) the connection that was passed to it, if any. A rowset uses the
249+<code>RowSetInternal</code> methods behind the scenes to get access to
250+this information. An application does not normally invoke these methods directly.
251+<P>
252+ <LI><code>RowSetReader</code><br>
253+A disconnected <code>RowSet</code> object that has implemented the
254+<code>RowSetInternal</code> interface can call on its reader (the
255+<code>RowSetReader</code> object associated with it) to populate it with
256+data. When an application calls the <code>RowSet.execute</code> method,
257+that method calls on the rowset's reader to do much of the work. Implementations
258+can vary widely, but generally a reader makes a connection to the data source,
259+reads data from the data source and populates the rowset with it, and closes
260+the connection. A reader may also update the <code>RowSetMetaData</code> object
261+for its rowset. The rowset's internal state is also updated, either by the
262+reader or directly by the method <code>RowSet.execute</code>.
263+
264+
265+ <LI><code>RowSetWriter</code><br>
266+A disconnected <code>RowSet</code> object that has implemented the
267+<code>RowSetInternal</code> interface can call on its writer (the
268+<code>RowSetWriter</code> object associated with it) to write changes
269+back to the underlying data source. Implementations may vary widely, but
270+generally, a writer will do the following:
271+
272+<P>
273+<UL>
274+ <LI>Make a connection to the data source
275+ <LI>Check to see whether there is a conflict, that is, whether
276+ a value that has been changed in the rowset has also been changed
277+ in the data source
278+ <LI>Write the new values to the data source if there is no conflict
279+ <LI>Close the connection
280+</UL>
281+
282+
283+</UL>
284+</OL>
285+<P>
286+The <code>RowSet</code> interface may be implemented in any number of
287+ways, and anyone may write an implementation. Developers are encouraged
288+to use their imaginations in coming up with new ways to use rowsets.
289+<P>
290+<B>IMPORTANT NOTE:</B> Code that uses API marked "Since 1.6" must be run using a
291+JDBC technology driver that implements the JDBC 4.0 API.
292+You must check your driver documentation to be sure that it implements
293+the particular features you want to use.
294+<P>
295+
296+<h2>Package Specification</h2>
297+
298+<ul>
299+ <li><a href="http://java.sun.com/products/jdbc/download.html">Specification of the
300+ JDBC 4.0 API</a>
301+</ul>
302+
303+<h2>Related Documentation</h2>
304+
305+The Java Series book published by Addison-Wesley Longman provides detailed
306+information about the classes and interfaces in the <code>javax.sql</code>
307+package:
308+
309+<ul>
310+ <li><a href="http://java.sun.com/docs/books/jdbc"><i>JDBC<sup><font size=-2>TM</font></sup>
311+ API Tutorial and Reference, Third Edition:</i></a>
312+</ul>
313+<P>
314+@since 1.4
315+</body>
316+</html>
java/pkg/javax/sql/rowset/BaseRowSet.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/BaseRowSet.java+4512−0
@@ -0,0 +1,4512 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import java.util.*;
31+import java.io.*;
32+import java.math.*;
33+import java.io.Serializable;
34+
35+import javax.sql.rowset.serial.*;
36+
37+/**
38+ * An abstract class providing a <code>RowSet</code> object with its basic functionality.
39+ * The basic functions include having properties and sending event notifications,
40+ * which all JavaBeans<sup><font size=-2>TM</font></sup> components must implement.
41+ * <P>
42+ * <h3>1.0 Overview</h3>
43+ * The <code>BaseRowSet</code> class provides the core functionality
44+ * for all <code>RowSet</code> implementations,
45+ * and all standard implementations <b>may</b> use this class in combination with
46+ * one or more <code>RowSet</code> interfaces in order to provide a standard
47+ * vendor-specific implementation. To clarify, all implementations must implement
48+ * at least one of the <code>RowSet</code> interfaces (<code>JdbcRowSet</code>,
49+ * <code>CachedRowSet</code>, <code>JoinRowSet</code>, <code>FilteredRowSet</code>,
50+ * or <code>WebRowSet</code>). This means that any implementation that extends
51+ * the <code>BaseRowSet</code> class must also implement one of the <code>RowSet</code>
52+ * interfaces.
53+ * <p>
54+ * The <code>BaseRowSet</code> class provides the following:
55+ * <p>
56+ * <UL>
57+ * <LI><b>Properties</b>
58+ * <ul>
59+ * <li>Fields for storing current properties
60+ * <li>Methods for getting and setting properties
61+ * </ul>
62+ * <p>
63+ * <LI><b>Event notification</b>
64+ * <P>
65+ * <LI><b>A complete set of setter methods</b> for setting the parameters in a
66+ * <code>RowSet</code> object's command
67+ * <p>
68+ * <LI> <b>Streams</b>
69+ * <ul>
70+ * <li>Fields for storing stream instances
71+ * <li>Constants for indicating the type of a stream
72+ * </ul>
73+ * <p>
74+ * </UL>
75+ *
76+ * <h3>2.0 Setting Properties</h3>
77+ * All rowsets maintain a set of properties, which will usually be set using
78+ * a tool. The number and kinds of properties a rowset has will vary,
79+ * depending on what the <code>RowSet</code> implementation does and how it gets
80+ * its data. For example,
81+ * rowsets that get their data from a <code>ResultSet</code> object need to
82+ * set the properties that are required for making a database connection.
83+ * If a <code>RowSet</code> object uses the <code>DriverManager</code> facility to make a
84+ * connection, it needs to set a property for the JDBC URL that identifies the
85+ * appropriate driver, and it needs to set the properties that give the
86+ * user name and password.
87+ * If, on the other hand, the rowset uses a <code>DataSource</code> object
88+ * to make the connection, which is the preferred method, it does not need to
89+ * set the property for the JDBC URL. Instead, it needs to set the property
90+ * for the logical name of the data source along with the properties for
91+ * the user name and password.
92+ * <P>
93+ * NOTE: In order to use a <code>DataSource</code> object for making a
94+ * connection, the <code>DataSource</code> object must have been registered
95+ * with a naming service that uses the Java Naming and Directory
96+ * Interface<sup><font size=-2>TM</font></sup> (JNDI) API. This registration
97+ * is usually done by a person acting in the capacity of a system administrator.
98+ * <P>
99+ * <h3>3.0 Setting the Command and Its Parameters</h3>
100+ * When a rowset gets its data from a relational database, it executes a command (a query)
101+ * that produces a <code>ResultSet</code> object. This query is the command that is set
102+ * for the <code>RowSet</code> object's command property. The rowset populates itself with data by reading the
103+ * data from the <code>ResultSet</code> object into itself. If the query
104+ * contains placeholders for values to be set, the <code>BaseRowSet</code> setter methods
105+ * are used to set these values. All setter methods allow these values to be set
106+ * to <code>null</code> if required.
107+ * <P>
108+ * The following code fragment illustrates how the
109+ * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
110+ * object <code>crs</code> might have its command property set. Note that if a
111+ * tool is used to set properties, this is the code that the tool would use.
112+ * <PRE>
113+ * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
114+ * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
115+ * </PRE>
116+ * <P>
117+ * In this example, the values for <code>CREDIT_LIMIT</code> and
118+ * <code>REGION</code> are placeholder parameters, which are indicated with a
119+ * question mark (?). The first question mark is placeholder parameter number
120+ * <code>1</code>, the second question mark is placeholder parameter number
121+ * <code>2</code>, and so on. Any placeholder parameters must be set with
122+ * values before the query can be executed. To set these
123+ * placeholder parameters, the <code>BaseRowSet</code> class provides a set of setter
124+ * methods, similar to those provided by the <code>PreparedStatement</code>
125+ * interface, for setting values of each data type. A <code>RowSet</code> object stores the
126+ * parameter values internally, and its <code>execute</code> method uses them internally
127+ * to set values for the placeholder parameters
128+ * before it sends the command to the DBMS to be executed.
129+ * <P>
130+ * The following code fragment demonstrates
131+ * setting the two parameters in the query from the previous example.
132+ * <PRE>
133+ * crs.setInt(1, 5000);
134+ * crs.setString(2, "West");
135+ * </PRE>
136+ * If the <code>execute</code> method is called at this point, the query
137+ * sent to the DBMS will be:
138+ * <PRE>
139+ * "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
140+ * "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"
141+ * </PRE>
142+ * NOTE: Setting <code>Array</code>, <code>Clob</code>, <code>Blob</code> and
143+ * <code>Ref</code> objects as a command parameter, stores these values as
144+ * <code>SerialArray</code>, <code>SerialClob</code>, <code>SerialBlob</code>
145+ * and <code>SerialRef</code> objects respectively.
146+ *
147+ * <h3>4.0 Handling of Parameters Behind the Scenes</h3>
148+ *
149+ * NOTE: The <code>BaseRowSet</code> class provides two kinds of setter methods,
150+ * those that set properties and those that set placeholder parameters. The setter
151+ * methods discussed in this section are those that set placeholder parameters.
152+ * <P>
153+ * The placeholder parameters set with the <code>BaseRowSet</code> setter methods
154+ * are stored as objects in an internal <code>Hashtable</code> object.
155+ * Primitives are stored as their <code>Object</code> type. For example, <code>byte</code>
156+ * is stored as <code>Byte</code> object, and <code>int</code> is stored as
157+ * an <code>Integer</code> object.
158+ * When the method <code>execute</code> is called, the values in the
159+ * <code>Hashtable</code> object are substituted for the appropriate placeholder
160+ * parameters in the command.
161+ * <P)>
162+ * A call to the method <code>getParams</code> returns the values stored in the
163+ * <code>Hashtable</code> object as an array of <code>Object</code> instances.
164+ * An element in this array may be a simple <code>Object</code> instance or an
165+ * array (which is a type of <code>Object</code>). The particular setter method used
166+ * determines whether an element in this array is an <code>Object</code> or an array.
167+ * <P>
168+ * The majority of methods for setting placeholder parameters take two parameters,
169+ * with the first parameter
170+ * indicating which placeholder parameter is to be set, and the second parameter
171+ * giving the value to be set. Methods such as <code>setInt</code>,
172+ * <code>setString</code>, <code>setBoolean</code>, and <code>setLong</code> fall into
173+ * this category. After these methods have been called, a call to the method
174+ * <code>getParams</code> will return an array with the values that have been set. Each
175+ * element in the array is an <code>Object</code> instance representing the
176+ * values that have been set. The order of these values in the array is determined by the
177+ * <code>int</code> (the first parameter) passed to the setter method. The values in the
178+ * array are the values (the second parameter) passed to the setter method.
179+ * In other words, the first element in the array is the value
180+ * to be set for the first placeholder parameter in the <code>RowSet</code> object's
181+ * command. The second element is the value to
182+ * be set for the second placeholder parameter, and so on.
183+ * <P>
184+ * Several setter methods send the driver and DBMS information beyond the value to be set.
185+ * When the method <code>getParams</code> is called after one of these setter methods has
186+ * been used, the elements in the array will themselves be arrays to accommodate the
187+ * additional information. In this category, the method <code>setNull</code> is a special case
188+ * because one version takes only
189+ * two parameters (<code>setNull(int parameterIndex, int SqlType)</code>). Nevertheless,
190+ * it requires
191+ * an array to contain the information that will be passed to the driver and DBMS. The first
192+ * element in this array is the value to be set, which is <code>null</code>, and the
193+ * second element is the <code>int</code> supplied for <i>sqlType</i>, which
194+ * indicates the type of SQL value that is being set to <code>null</code>. This information
195+ * is needed by some DBMSs and is therefore required in order to ensure that applications
196+ * are portable.
197+ * The other version is intended to be used when the value to be set to <code>null</code>
198+ * is a user-defined type. It takes three parameters
199+ * (<code>setNull(int parameterIndex, int sqlType, String typeName)</code>) and also
200+ * requires an array to contain the information to be passed to the driver and DBMS.
201+ * The first two elements in this array are the same as for the first version of
202+ * <code>setNull</code>. The third element, <i>typeName</i>, gives the SQL name of
203+ * the user-defined type. As is true with the other setter methods, the number of the
204+ * placeholder parameter to be set is indicated by an element's position in the array
205+ * returned by <code>getParams</code>. So, for example, if the parameter
206+ * supplied to <code>setNull</code> is <code>2</code>, the second element in the array
207+ * returned by <code>getParams</code> will be an array of two or three elements.
208+ * <P>
209+ * Some methods, such as <code>setObject</code> and <code>setDate</code> have versions
210+ * that take more than two parameters, with the extra parameters giving information
211+ * to the driver or the DBMS. For example, the methods <code>setDate</code>,
212+ * <code>setTime</code>, and <code>setTimestamp</code> can take a <code>Calendar</code>
213+ * object as their third parameter. If the DBMS does not store time zone information,
214+ * the drivern uses the <code>Calendar</code> object to construct the <code>Date</code>,
215+ * <code>Time</code>, or <code>Timestamp</code> object being set. As is true with other
216+ * methods that provide additional information, the element in the array returned
217+ * by <code>getParams</code> is an array instead of a simple <code>Object</code> instance.
218+ * <P>
219+ * The methods <code>setAsciiStream</code>, <code>setBinaryStream</code>,
220+ * <code>setCharacterStream</code>, and <code>setUnicodeStream</code> (which is
221+ * deprecated, so applications should use <code>getCharacterStream</code> instead)
222+ * take three parameters, so for them, the element in the array returned by
223+ * <code>getParams</code> is also an array. What is different about these setter
224+ * methods is that in addition to the information provided by parameters, the array contains
225+ * one of the <code>BaseRowSet</code> constants indicating the type of stream being set.
226+* <p>
227+* NOTE: The method <code>getParams</code> is called internally by
228+* <code>RowSet</code> implementations extending this class; it is not normally called by an
229+* application programmer directly.
230+*
231+* <h3>5.0 Event Notification</h3>
232+* The <code>BaseRowSet</code> class provides the event notification
233+* mechanism for rowsets. It contains the field
234+* <code>listeners</code>, methods for adding and removing listeners, and
235+* methods for notifying listeners of changes.
236+* <P>
237+* A listener is an object that has implemented the <code>RowSetListener</code> interface.
238+* If it has been added to a <code>RowSet</code> object's list of listeners, it will be notified
239+* when an event occurs on that <code>RowSet</code> object. Each listener's
240+* implementation of the <code>RowSetListener</code> methods defines what that object
241+* will do when it is notified that an event has occurred.
242+* <P>
243+* There are three possible events for a <code>RowSet</code> object:
244+* <OL>
245+* <LI>the cursor moves
246+* <LI>an individual row is changed (updated, deleted, or inserted)
247+* <LI>the contents of the entire <code>RowSet</code> object are changed
248+* </OL>
249+* <P>
250+* The <code>BaseRowSet</code> method used for the notification indicates the
251+* type of event that has occurred. For example, the method
252+* <code>notifyRowChanged</code> indicates that a row has been updated,
253+* deleted, or inserted. Each of the notification methods creates a
254+* <code>RowSetEvent</code> object, which is supplied to the listener in order to
255+* identify the <code>RowSet</code> object on which the event occurred.
256+* What the listener does with this information, which may be nothing, depends on how it was
257+* implemented.
258+* <p>
259+* <h3>6.0 Default Behavior</h3>
260+* A default <code>BaseRowSet</code> object is initialized with many starting values.
261+*
262+* The following is true of a default <code>RowSet</code> instance that extends
263+* the <code>BaseRowSet</code> class:
264+* <UL>
265+* <LI>Has a scrollable cursor and does not show changes
266+* made by others.
267+* <LI>Is updatable.
268+* <LI>Does not show rows that have been deleted.
269+* <LI>Has no time limit for how long a driver may take to
270+* execute the <code>RowSet</code> object's command.
271+* <LI>Has no limit for the number of rows it may contain.
272+* <LI>Has no limit for the number of bytes a column may contain. NOTE: This
273+* limit applies only to columns that hold values of the
274+* following types: <code>BINARY</code>, <code>VARBINARY</code>,
275+* <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
276+* and <code>LONGVARCHAR</code>.
277+* <LI>Will not see uncommitted data (make "dirty" reads).
278+* <LI>Has escape processing turned on.
279+* <LI>Has its connection's type map set to <code>null</code>.
280+* <LI>Has an empty <code>Vector</code> object for storing the values set
281+* for the placeholder parameters in the <code>RowSet</code> object's command.
282+* </UL>
283+* <p>
284+* If other values are desired, an application must set the property values
285+* explicitly. For example, the following line of code sets the maximum number
286+* of rows for the <code>CachedRowSet</code> object <i>crs</i> to 500.
287+* <PRE>
288+* crs.setMaxRows(500);
289+* </PRE>
290+* Methods implemented in extensions of this <code>BaseRowSet</code> class <b>must</b> throw an
291+* <code>SQLException</code> object for any violation of the defined assertions. Also, if the
292+* extending class overrides and reimplements any <code>BaseRowSet</code> method and encounters
293+* connectivity or underlying data source issues, that method <b>may</b> in addition throw an
294+* <code>SQLException</code> object for that reason.
295+*/
296+
297+public abstract class BaseRowSet implements Serializable, Cloneable {
298+
299+ /**
300+ * A constant indicating to a <code>RowSetReaderImpl</code> object
301+ * that a given parameter is a Unicode stream. This
302+ * <code>RowSetReaderImpl</code> object is provided as an extension of the
303+ * <code>SyncProvider</code> abstract class defined in the
304+ * <code>SyncFactory</code> static factory SPI mechanism.
305+ */
306+ public static final int UNICODE_STREAM_PARAM = 0;
307+
308+ /**
309+ * A constant indicating to a <code>RowSetReaderImpl</code> object
310+ * that a given parameter is a binary stream. A
311+ * <code>RowSetReaderImpl</code> object is provided as an extension of the
312+ * <code>SyncProvider</code> abstract class defined in the
313+ * <code>SyncFactory</code> static factory SPI mechanism.
314+ */
315+ public static final int BINARY_STREAM_PARAM = 1;
316+
317+ /**
318+ * A constant indicating to a <code>RowSetReaderImpl</code> object
319+ * that a given parameter is an ASCII stream. A
320+ * <code>RowSetReaderImpl</code> object is provided as an extension of the
321+ * <code>SyncProvider</code> abstract class defined in the
322+ * <code>SyncFactory</code> static factory SPI mechanism.
323+ */
324+ public static final int ASCII_STREAM_PARAM = 2;
325+
326+ /**
327+ * The <code>InputStream</code> object that will be
328+ * returned by the method <code>getBinaryStream</code>, which is
329+ * specified in the <code>ResultSet</code> interface.
330+ * @serial
331+ */
332+ protected java.io.InputStream binaryStream;
333+
334+ /**
335+ * The <code>InputStream</code> object that will be
336+ * returned by the method <code>getUnicodeStream</code>,
337+ * which is specified in the <code>ResultSet</code> interface.
338+ * @serial
339+ */
340+ protected java.io.InputStream unicodeStream;
341+
342+ /**
343+ * The <code>InputStream</code> object that will be
344+ * returned by the method <code>getAsciiStream</code>,
345+ * which is specified in the <code>ResultSet</code> interface.
346+ * @serial
347+ */
348+ protected java.io.InputStream asciiStream;
349+
350+ /**
351+ * The <code>Reader</code> object that will be
352+ * returned by the method <code>getCharacterStream</code>,
353+ * which is specified in the <code>ResultSet</code> interface.
354+ * @serial
355+ */
356+ protected java.io.Reader charStream;
357+
358+ /**
359+ * The query that will be sent to the DBMS for execution when the
360+ * method <code>execute</code> is called.
361+ * @serial
362+ */
363+ private String command;
364+
365+ /**
366+ * The JDBC URL the reader, writer, or both supply to the method
367+ * <code>DriverManager.getConnection</code> when the
368+ * <code>DriverManager</code> is used to get a connection.
369+ * <P>
370+ * The JDBC URL identifies the driver to be used to make the conndection.
371+ * This URL can be found in the documentation supplied by the driver
372+ * vendor.
373+ * @serial
374+ */
375+ private String URL;
376+
377+ /**
378+ * The logical name of the data source that the reader/writer should use
379+ * in order to retrieve a <code>DataSource</code> object from a Java
380+ * Directory and Naming Interface (JNDI) naming service.
381+ * @serial
382+ */
383+ private String dataSource;
384+
385+ /**
386+ * The user name the reader, writer, or both supply to the method
387+ * <code>DriverManager.getConnection</code> when the
388+ * <code>DriverManager</code> is used to get a connection.
389+ * @serial
390+ */
391+ private transient String username;
392+
393+ /**
394+ * The password the reader, writer, or both supply to the method
395+ * <code>DriverManager.getConnection</code> when the
396+ * <code>DriverManager</code> is used to get a connection.
397+ * @serial
398+ */
399+ private transient String password;
400+
401+ /**
402+ * A constant indicating the type of this JDBC <code>RowSet</code>
403+ * object. It must be one of the following <code>ResultSet</code>
404+ * constants: <code>TYPE_FORWARD_ONLY</code>,
405+ * <code>TYPE_SCROLL_INSENSITIVE</code>, or
406+ * <code>TYPE_SCROLL_SENSITIVE</code>.
407+ * @serial
408+ */
409+ private int rowSetType = ResultSet.TYPE_SCROLL_INSENSITIVE;
410+
411+ /**
412+ * A <code>boolean</code> indicating whether deleted rows are visible in this
413+ * JDBC <code>RowSet</code> object .
414+ * @serial
415+ */
416+ private boolean showDeleted = false; // default is false
417+
418+ /**
419+ * The maximum number of seconds the driver
420+ * will wait for a command to execute. This limit applies while
421+ * this JDBC <code>RowSet</code> object is connected to its data
422+ * source, that is, while it is populating itself with
423+ * data and while it is writing data back to the data source.
424+ * @serial
425+ */
426+ private int queryTimeout = 0; // default is no timeout
427+
428+ /**
429+ * The maximum number of rows the reader should read.
430+ * @serial
431+ */
432+ private int maxRows = 0; // default is no limit
433+
434+ /**
435+ * The maximum field size the reader should read.
436+ * @serial
437+ */
438+ private int maxFieldSize = 0; // default is no limit
439+
440+ /**
441+ * A constant indicating the concurrency of this JDBC <code>RowSet</code>
442+ * object. It must be one of the following <code>ResultSet</code>
443+ * constants: <code>CONCUR_READ_ONLY</code> or
444+ * <code>CONCUR_UPDATABLE</code>.
445+ * @serial
446+ */
447+ private int concurrency = ResultSet.CONCUR_UPDATABLE;
448+
449+ /**
450+ * A <code>boolean</code> indicating whether this JDBC <code>RowSet</code>
451+ * object is read-only. <code>true</code> indicates that it is read-only;
452+ * <code>false</code> that it is writable.
453+ * @serial
454+ */
455+ private boolean readOnly;
456+
457+ /**
458+ * A <code>boolean</code> indicating whether the reader for this
459+ * JDBC <code>RowSet</code> object should perform escape processing.
460+ * <code>true</code> means that escape processing is turned on;
461+ * <code>false</code> that it is not. The default is <code>true</code>.
462+ * @serial
463+ */
464+ private boolean escapeProcessing;
465+
466+ /**
467+ * A constant indicating the isolation level of the connection
468+ * for this JDBC <code>RowSet</code> object . It must be one of
469+ * the following <code>Connection</code> constants:
470+ * <code>TRANSACTION_NONE</code>,
471+ * <code>TRANSACTION_READ_UNCOMMITTED</code>,
472+ * <code>TRANSACTION_READ_COMMITTED</code>,
473+ * <code>TRANSACTION_REPEATABLE_READ</code> or
474+ * <code>TRANSACTION_SERIALIZABLE</code>.
475+ * @serial
476+ */
477+ private int isolation;
478+
479+ /**
480+ * A constant used as a hint to the driver that indicates the direction in
481+ * which data from this JDBC <code>RowSet</code> object is going
482+ * to be fetched. The following <code>ResultSet</code> constants are
483+ * possible values:
484+ * <code>FETCH_FORWARD</code>,
485+ * <code>FETCH_REVERSE</code>,
486+ * <code>FETCH_UNKNOWN</code>.
487+ * <P>
488+ * Unused at this time.
489+ * @serial
490+ */
491+ private int fetchDir = ResultSet.FETCH_FORWARD; // default fetch direction
492+
493+ /**
494+ * A hint to the driver that indicates the expected number of rows
495+ * in this JDBC <code>RowSet</code> object .
496+ * <P>
497+ * Unused at this time.
498+ * @serial
499+ */
500+ private int fetchSize = 0; // default fetchSize
501+
502+ /**
503+ * The <code>java.util.Map</code> object that contains entries mapping
504+ * SQL type names to classes in the Java programming language for the
505+ * custom mapping of user-defined types.
506+ * @serial
507+ */
508+ private Map<String, Class<?>> map;
509+
510+ /**
511+ * A <code>Vector</code> object that holds the list of listeners
512+ * that have registered with this <code>RowSet</code> object.
513+ * @serial
514+ */
515+ private Vector<RowSetListener> listeners;
516+
517+ /**
518+ * A <code>Vector</code> object that holds the parameters set
519+ * for this <code>RowSet</code> object's current command.
520+ * @serial
521+ */
522+ private Hashtable<Integer, Object> params; // could be transient?
523+
524+ /**
525+ * Constructs a new <code>BaseRowSet</code> object initialized with
526+ * a default <code>Vector</code> object for its <code>listeners</code>
527+ * field. The other default values with which it is initialized are listed
528+ * in Section 6.0 of the class comment for this class.
529+ */
530+ public BaseRowSet() {
531+ // allocate the listeners collection
532+ listeners = new Vector<RowSetListener>();
533+ }
534+
535+ /**
536+ * Performs the necessary internal configurations and initializations
537+ * to allow any JDBC <code>RowSet</code> implementation to start using
538+ * the standard facilities provided by a <code>BaseRowSet</code>
539+ * instance. This method <b>should</b> be called after the <code>RowSet</code> object
540+ * has been instantiated to correctly initialize all parameters. This method
541+ * <b>should</b> never be called by an application, but is called from with
542+ * a <code>RowSet</code> implementation extending this class.
543+ */
544+ protected void initParams() {
545+ params = new Hashtable<Integer, Object>();
546+ }
547+
548+ //--------------------------------------------------------------------
549+ // Events
550+ //--------------------------------------------------------------------
551+
552+ /**
553+ * The listener will be notified whenever an event occurs on this <code>RowSet</code>
554+ * object.
555+ * <P>
556+ * A listener might, for example, be a table or graph that needs to
557+ * be updated in order to accurately reflect the current state of
558+ * the <code>RowSet</code> object.
559+ * <p>
560+ * <b>Note</b>: if the <code>RowSetListener</code> object is
561+ * <code>null</code>, this method silently discards the <code>null</code>
562+ * value and does not add a null reference to the set of listeners.
563+ * <p>
564+ * <b>Note</b>: if the listener is already set, and the new <code>RowSetListerner</code>
565+ * instance is added to the set of listeners already registered to receive
566+ * event notifications from this <code>RowSet</code>.
567+ *
568+ * @param listener an object that has implemented the
569+ * <code>javax.sql.RowSetListener</code> interface and wants to be notified
570+ * of any events that occur on this <code>RowSet</code> object; May be
571+ * null.
572+ * @see #removeRowSetListener
573+ */
574+ public void addRowSetListener(RowSetListener listener) {
575+ listeners.add(listener);
576+ }
577+
578+ /**
579+ * Removes the designated object from this <code>RowSet</code> object's list of listeners.
580+ * If the given argument is not a registered listener, this method
581+ * does nothing.
582+ *
583+ * <b>Note</b>: if the <code>RowSetListener</code> object is
584+ * <code>null</code>, this method silently discards the <code>null</code>
585+ * value.
586+ *
587+ * @param listener a <code>RowSetListener</code> object that is on the list
588+ * of listeners for this <code>RowSet</code> object
589+ * @see #addRowSetListener
590+ */
591+ public void removeRowSetListener(RowSetListener listener) {
592+ listeners.remove(listener);
593+ }
594+
595+ /**
596+ * Determine if instance of this class extends the RowSet interface.
597+ */
598+ private void checkforRowSetInterface() throws SQLException {
599+ if ((this instanceof javax.sql.RowSet) == false) {
600+ throw new SQLException("The class extending abstract class BaseRowSet " +
601+ "must implement javax.sql.RowSet or one of it's sub-interfaces.");
602+ }
603+ }
604+
605+ /**
606+ * Notifies all of the listeners registered with this
607+ * <code>RowSet</code> object that its cursor has moved.
608+ * <P>
609+ * When an application calls a method to move the cursor,
610+ * that method moves the cursor and then calls this method
611+ * internally. An application <b>should</b> never invoke
612+ * this method directly.
613+ *
614+ * @throws SQLException if the class extending the <code>BaseRowSet</code>
615+ * abstract class does not implement the <code>RowSet</code> interface or
616+ * one of it's sub-interfaces.
617+ */
618+ protected void notifyCursorMoved() throws SQLException {
619+ checkforRowSetInterface();
620+ if (listeners.isEmpty() == false) {
621+ RowSetEvent event = new RowSetEvent((RowSet)this);
622+ for (Iterator i = listeners.iterator(); i.hasNext(); ) {
623+ ((RowSetListener)i.next()).cursorMoved(event);
624+ }
625+ }
626+ }
627+
628+ /**
629+ * Notifies all of the listeners registered with this <code>RowSet</code> object that
630+ * one of its rows has changed.
631+ * <P>
632+ * When an application calls a method that changes a row, such as
633+ * the <code>CachedRowSet</code> methods <code>insertRow</code>,
634+ * <code>updateRow</code>, or <code>deleteRow</code>,
635+ * that method calls <code>notifyRowChanged</code>
636+ * internally. An application <b>should</b> never invoke
637+ * this method directly.
638+ *
639+ * @throws SQLException if the class extending the <code>BaseRowSet</code>
640+ * abstract class does not implement the <code>RowSet</code> interface or
641+ * one of it's sub-interfaces.
642+ */
643+ protected void notifyRowChanged() throws SQLException {
644+ checkforRowSetInterface();
645+ if (listeners.isEmpty() == false) {
646+ RowSetEvent event = new RowSetEvent((RowSet)this);
647+ for (Iterator i = listeners.iterator(); i.hasNext(); ) {
648+ ((RowSetListener)i.next()).rowChanged(event);
649+ }
650+ }
651+ }
652+
653+ /**
654+ * Notifies all of the listeners registered with this <code>RowSet</code>
655+ * object that its entire contents have changed.
656+ * <P>
657+ * When an application calls methods that change the entire contents
658+ * of the <code>RowSet</code> object, such as the <code>CachedRowSet</code> methods
659+ * <code>execute</code>, <code>populate</code>, <code>restoreOriginal</code>,
660+ * or <code>release</code>, that method calls <code>notifyRowSetChanged</code>
661+ * internally (either directly or indirectly). An application <b>should</b>
662+ * never invoke this method directly.
663+ *
664+ * @throws SQLException if the class extending the <code>BaseRowSet</code>
665+ * abstract class does not implement the <code>RowSet</code> interface or
666+ * one of it's sub-interfaces.
667+ */
668+ protected void notifyRowSetChanged() throws SQLException {
669+ checkforRowSetInterface();
670+ if (listeners.isEmpty() == false) {
671+ RowSetEvent event = new RowSetEvent((RowSet)this);
672+ for (Iterator i = listeners.iterator(); i.hasNext(); ) {
673+ ((RowSetListener)i.next()).rowSetChanged(event);
674+ }
675+ }
676+}
677+
678+ /**
679+ * Retrieves the SQL query that is the command for this
680+ * <code>RowSet</code> object. The command property contains the query that
681+ * will be executed to populate this <code>RowSet</code> object.
682+ * <P>
683+ * The SQL query returned by this method is used by <code>RowSet</code> methods
684+ * such as <code>execute</code> and <code>populate</code>, which may be implemented
685+ * by any class that extends the <code>BaseRowSet</code> abstract class and
686+ * implements one or more of the standard JSR-114 <code>RowSet</code>
687+ * interfaces.
688+ * <P>
689+ * The command is used by the <code>RowSet</code> object's
690+ * reader to obtain a <code>ResultSet</code> object. The reader then
691+ * reads the data from the <code>ResultSet</code> object and uses it to
692+ * to populate this <code>RowSet</code> object.
693+ * <P>
694+ * The default value for the <code>command</code> property is <code>null</code>.
695+ *
696+ * @return the <code>String</code> that is the value for this
697+ * <code>RowSet</code> object's <code>command</code> property;
698+ * may be <code>null</code>
699+ * @see #setCommand
700+ */
701+ public String getCommand() {
702+ return command;
703+ }
704+
705+ /**
706+ * Sets this <code>RowSet</code> object's <code>command</code> property to
707+ * the given <code>String</code> object and clears the parameters, if any,
708+ * that were set for the previous command.
709+ * <P>
710+ * The <code>command</code> property may not be needed if the <code>RowSet</code>
711+ * object gets its data from a source that does not support commands,
712+ * such as a spreadsheet or other tabular file.
713+ * Thus, this property is optional and may be <code>null</code>.
714+ *
715+ * @param cmd a <code>String</code> object containing an SQL query
716+ * that will be set as this <code>RowSet</code> object's command
717+ * property; may be <code>null</code> but may not be an empty string
718+ * @throws SQLException if an empty string is provided as the command value
719+ * @see #getCommand
720+ */
721+ public void setCommand(String cmd) throws SQLException {
722+ // cmd equal to null or
723+ // cmd with length 0 (implies url =="")
724+ // are not independent events.
725+
726+ if(cmd == null) {
727+ command = null;
728+ } else if (cmd.length() == 0) {
729+ throw new SQLException("Invalid command string detected. " +
730+ "Cannot be of length less than 0");
731+ } else {
732+ // "unbind" any parameters from any previous command.
733+ if(params == null){
734+ throw new SQLException("Set initParams() before setCommand");
735+ }
736+ params.clear();
737+ command = cmd;
738+ }
739+
740+ }
741+
742+ /**
743+ * Retrieves the JDBC URL that this <code>RowSet</code> object's
744+ * <code>javax.sql.Reader</code> object uses to make a connection
745+ * with a relational database using a JDBC technology-enabled driver.
746+ *<P>
747+ * The <code>Url</code> property will be <code>null</code> if the underlying data
748+ * source is a non-SQL data source, such as a spreadsheet or an XML
749+ * data source.
750+ *
751+ * @return a <code>String</code> object that contains the JDBC URL
752+ * used to establish the connection for this <code>RowSet</code>
753+ * object; may be <code>null</code> (default value) if not set
754+ * @throws SQLException if an error occurs retrieving the URL value
755+ * @see #setUrl
756+ */
757+ public String getUrl() throws SQLException {
758+ return URL;
759+ }
760+
761+ /**
762+ * Sets the Url property for this <code>RowSet</code> object
763+ * to the given <code>String</code> object and sets the dataSource name
764+ * property to <code>null</code>. The Url property is a
765+ * JDBC URL that is used when
766+ * the connection is created using a JDBC technology-enabled driver
767+ * ("JDBC driver") and the <code>DriverManager</code>.
768+ * The correct JDBC URL for the specific driver to be used can be found
769+ * in the driver documentation. Although there are guidelines for for how
770+ * a JDBC URL is formed,
771+ * a driver vendor can specify any <code>String</code> object except
772+ * one with a length of <code>0</code> (an empty string).
773+ * <P>
774+ * Setting the Url property is optional if connections are established using
775+ * a <code>DataSource</code> object instead of the <code>DriverManager</code>.
776+ * The driver will use either the URL property or the
777+ * dataSourceName property to create a connection, whichever was
778+ * specified most recently. If an application uses a JDBC URL, it
779+ * must load a JDBC driver that accepts the JDBC URL before it uses the
780+ * <code>RowSet</code> object to connect to a database. The <code>RowSet</code>
781+ * object will use the URL internally to create a database connection in order
782+ * to read or write data.
783+ *
784+ * @param url a <code>String</code> object that contains the JDBC URL
785+ * that will be used to establish the connection to a database for this
786+ * <code>RowSet</code> object; may be <code>null</code> but must not
787+ * be an empty string
788+ * @throws SQLException if an error occurs setting the Url property or the
789+ * parameter supplied is a string with a length of <code>0</code> (an
790+ * empty string)
791+ * @see #getUrl
792+ */
793+ public void setUrl(String url) throws SQLException {
794+ if(url == null) {
795+ url = null;
796+ } else if (url.length() < 1) {
797+ throw new SQLException("Invalid url string detected. " +
798+ "Cannot be of length less than 1");
799+ } else {
800+ URL = url;
801+ }
802+
803+ dataSource = null;
804+
805+ }
806+
807+ /**
808+ * Returns the logical name that when supplied to a naming service
809+ * that uses the Java Naming and Directory Interface (JNDI) API, will
810+ * retrieve a <code>javax.sql.DataSource</code> object. This
811+ * <code>DataSource</code> object can be used to establish a connection
812+ * to the data source that it represents.
813+ * <P>
814+ * Users should set either the url or the data source name property.
815+ * The driver will use the property set most recently to establish a
816+ * connection.
817+ *
818+ * @return a <code>String</code> object that identifies the
819+ * <code>DataSource</code> object to be used for making a
820+ * connection; if no logical name has been set, <code>null</code>
821+ * is returned.
822+ * @see #setDataSourceName
823+ */
824+ public String getDataSourceName() {
825+ return dataSource;
826+ }
827+
828+
829+ /**
830+ * Sets the <code>DataSource</code> name property for this <code>RowSet</code>
831+ * object to the given logical name and sets this <code>RowSet</code> object's
832+ * Url property to <code>null</code>. The name must have been bound to a
833+ * <code>DataSource</code> object in a JNDI naming service so that an
834+ * application can do a lookup using that name to retrieve the
835+ * <code>DataSource</code> object bound to it. The <code>DataSource</code>
836+ * object can then be used to establish a connection to the data source it
837+ * represents.
838+ * <P>
839+ * Users should set either the Url property or the dataSourceName property.
840+ * If both properties are set, the driver will use the property set most recently.
841+ *
842+ * @param name a <code>String</code> object with the name that can be supplied
843+ * to a naming service based on JNDI technology to retrieve the
844+ * <code>DataSource</code> object that can be used to get a connection;
845+ * may be <code>null</code> but must not be an empty string
846+ * @throws SQLException if an empty string is provided as the <code>DataSource</code>
847+ * name
848+ * @see #getDataSourceName
849+ */
850+ public void setDataSourceName(String name) throws SQLException {
851+
852+ if (name == null) {
853+ dataSource = null;
854+ } else if (name.equals("")) {
855+ throw new SQLException("DataSource name cannot be empty string");
856+ } else {
857+ dataSource = name;
858+ }
859+
860+ URL = null;
861+ }
862+
863+ /**
864+ * Returns the user name used to create a database connection. Because it
865+ * is not serialized, the username property is set at runtime before
866+ * calling the method <code>execute</code>.
867+ *
868+ * @return the <code>String</code> object containing the user name that
869+ * is supplied to the data source to create a connection; may be
870+ * <code>null</code> (default value) if not set
871+ * @see #setUsername
872+ */
873+ public String getUsername() {
874+ return username;
875+ }
876+
877+ /**
878+ * Sets the username property for this <code>RowSet</code> object
879+ * to the given user name. Because it
880+ * is not serialized, the username property is set at run time before
881+ * calling the method <code>execute</code>.
882+ *
883+ * @param name the <code>String</code> object containing the user name that
884+ * is supplied to the data source to create a connection. It may be null.
885+ * @see #getUsername
886+ */
887+ public void setUsername(String name) {
888+ if(name == null)
889+ {
890+ username = null;
891+ } else {
892+ username = name;
893+ }
894+ }
895+
896+ /**
897+ * Returns the password used to create a database connection for this
898+ * <code>RowSet</code> object. Because the password property is not
899+ * serialized, it is set at run time before calling the method
900+ * <code>execute</code>. The default value is <code>null</code>
901+ *
902+ * @return the <code>String</code> object that represents the password
903+ * that must be supplied to the database to create a connection
904+ * @see #setPassword
905+ */
906+ public String getPassword() {
907+ return password;
908+ }
909+
910+ /**
911+ * Sets the password used to create a database connection for this
912+ * <code>RowSet</code> object to the given <code>String</code>
913+ * object. Because the password property is not
914+ * serialized, it is set at run time before calling the method
915+ * <code>execute</code>.
916+ *
917+ * @param pass the <code>String</code> object that represents the password
918+ * that is supplied to the database to create a connection. It may be
919+ * null.
920+ * @see #getPassword
921+ */
922+ public void setPassword(String pass) {
923+ if(pass == null)
924+ {
925+ password = null;
926+ } else {
927+ password = pass;
928+ }
929+ }
930+
931+ /**
932+ * Sets the type for this <code>RowSet</code> object to the specified type.
933+ * The default type is <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>.
934+ *
935+ * @param type one of the following constants:
936+ * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
937+ * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
938+ * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
939+ * @throws SQLException if the parameter supplied is not one of the
940+ * following constants:
941+ * <code>ResultSet.TYPE_FORWARD_ONLY</code> or
942+ * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>
943+ * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
944+ * @see #getConcurrency
945+ * @see #getType
946+ */
947+ public void setType(int type) throws SQLException {
948+
949+ if ((type != ResultSet.TYPE_FORWARD_ONLY) &&
950+ (type != ResultSet.TYPE_SCROLL_INSENSITIVE) &&
951+ (type != ResultSet.TYPE_SCROLL_SENSITIVE)) {
952+ throw new SQLException("Invalid type of RowSet set. Must be either " +
953+ "ResultSet.TYPE_FORWARD_ONLY or ResultSet.TYPE_SCROLL_INSENSITIVE " +
954+ "or ResultSet.TYPE_SCROLL_SENSITIVE.");
955+ }
956+ this.rowSetType = type;
957+ }
958+
959+ /**
960+ * Returns the type of this <code>RowSet</code> object. The type is initially
961+ * determined by the statement that created the <code>RowSet</code> object.
962+ * The <code>RowSet</code> object can call the method
963+ * <code>setType</code> at any time to change its
964+ * type. The default is <code>TYPE_SCROLL_INSENSITIVE</code>.
965+ *
966+ * @return the type of this JDBC <code>RowSet</code>
967+ * object, which must be one of the following:
968+ * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
969+ * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
970+ * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
971+ * @throws SQLException if an error occurs getting the type of
972+ * of this <code>RowSet</code> object
973+ * @see #setType
974+ */
975+ public int getType() throws SQLException {
976+ return rowSetType;
977+ }
978+
979+ /**
980+ * Sets the concurrency for this <code>RowSet</code> object to
981+ * the specified concurrency. The default concurrency for any <code>RowSet</code>
982+ * object (connected or disconnected) is <code>ResultSet.CONCUR_UPDATABLE</code>,
983+ * but this method may be called at any time to change the concurrency.
984+ * <P>
985+ * @param concurrency one of the following constants:
986+ * <code>ResultSet.CONCUR_READ_ONLY</code> or
987+ * <code>ResultSet.CONCUR_UPDATABLE</code>
988+ * @throws SQLException if the parameter supplied is not one of the
989+ * following constants:
990+ * <code>ResultSet.CONCUR_UPDATABLE</code> or
991+ * <code>ResultSet.CONCUR_READ_ONLY</code>
992+ * @see #getConcurrency
993+ * @see #isReadOnly
994+ */
995+ public void setConcurrency(int concurrency) throws SQLException {
996+
997+ if((concurrency != ResultSet.CONCUR_READ_ONLY) &&
998+ (concurrency != ResultSet.CONCUR_UPDATABLE)) {
999+ throw new SQLException("Invalid concurrency set. Must be either " +
1000+ "ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE.");
1001+ }
1002+ this.concurrency = concurrency;
1003+ }
1004+
1005+ /**
1006+ * Returns a <code>boolean</code> indicating whether this
1007+ * <code>RowSet</code> object is read-only.
1008+ * Any attempts to update a read-only <code>RowSet</code> object will result in an
1009+ * <code>SQLException</code> being thrown. By default,
1010+ * rowsets are updatable if updates are possible.
1011+ *
1012+ * @return <code>true</code> if this <code>RowSet</code> object
1013+ * cannot be updated; <code>false</code> otherwise
1014+ * @see #setConcurrency
1015+ * @see #setReadOnly
1016+ */
1017+ public boolean isReadOnly() {
1018+ return readOnly;
1019+ };
1020+
1021+ /**
1022+ * Sets this <code>RowSet</code> object's readOnly property to the given <code>boolean</code>.
1023+ *
1024+ * @param value <code>true</code> to indicate that this
1025+ * <code>RowSet</code> object is read-only;
1026+ * <code>false</code> to indicate that it is updatable
1027+ */
1028+ public void setReadOnly(boolean value) {
1029+ readOnly = value;
1030+ }
1031+
1032+ /**
1033+ * Returns the transaction isolation property for this
1034+ * <code>RowSet</code> object's connection. This property represents
1035+ * the transaction isolation level requested for use in transactions.
1036+ * <P>
1037+ * For <code>RowSet</code> implementations such as
1038+ * the <code>CachedRowSet</code> that operate in a disconnected environment,
1039+ * the <code>SyncProvider</code> object
1040+ * offers complementary locking and data integrity options. The
1041+ * options described below are pertinent only to connected <code>RowSet</code>
1042+ * objects (<code>JdbcRowSet</code> objects).
1043+ *
1044+ * @return one of the following constants:
1045+ * <code>Connection.TRANSACTION_NONE</code>,
1046+ * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
1047+ * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
1048+ * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
1049+ * <code>Connection.TRANSACTION_SERIALIZABLE</code>
1050+ * @see javax.sql.rowset.spi.SyncFactory
1051+ * @see javax.sql.rowset.spi.SyncProvider
1052+ * @see #setTransactionIsolation
1053+
1054+ */
1055+ public int getTransactionIsolation() {
1056+ return isolation;
1057+ };
1058+
1059+ /**
1060+ * Sets the transaction isolation property for this JDBC <code>RowSet</code> object to the given
1061+ * constant. The DBMS will use this transaction isolation level for
1062+ * transactions if it can.
1063+ * <p>
1064+ * For <code>RowSet</code> implementations such as
1065+ * the <code>CachedRowSet</code> that operate in a disconnected environment,
1066+ * the <code>SyncProvider</code> object being used
1067+ * offers complementary locking and data integrity options. The
1068+ * options described below are pertinent only to connected <code>RowSet</code>
1069+ * objects (<code>JdbcRowSet</code> objects).
1070+ *
1071+ * @param level one of the following constants, listed in ascending order:
1072+ * <code>Connection.TRANSACTION_NONE</code>,
1073+ * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
1074+ * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
1075+ * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
1076+ * <code>Connection.TRANSACTION_SERIALIZABLE</code>
1077+ * @throws SQLException if the given parameter is not one of the Connection
1078+ * constants
1079+ * @see javax.sql.rowset.spi.SyncFactory
1080+ * @see javax.sql.rowset.spi.SyncProvider
1081+ * @see #getTransactionIsolation
1082+ */
1083+ public void setTransactionIsolation(int level) throws SQLException {
1084+ if ((level != Connection.TRANSACTION_NONE) &&
1085+ (level != Connection.TRANSACTION_READ_COMMITTED) &&
1086+ (level != Connection.TRANSACTION_READ_UNCOMMITTED) &&
1087+ (level != Connection.TRANSACTION_REPEATABLE_READ) &&
1088+ (level != Connection.TRANSACTION_SERIALIZABLE))
1089+ {
1090+ throw new SQLException("Invalid transaction isolation set. Must " +
1091+ "be either " +
1092+ "Connection.TRANSACTION_NONE or " +
1093+ "Connection.TRANSACTION_READ_UNCOMMITTED or " +
1094+ "Connection.TRANSACTION_READ_COMMITTED or " +
1095+ "Connection.RRANSACTION_REPEATABLE_READ or " +
1096+ "Connection.TRANSACTION_SERIALIZABLE");
1097+ }
1098+ this.isolation = level;
1099+ }
1100+
1101+ /**
1102+ * Retrieves the type map associated with the <code>Connection</code>
1103+ * object for this <code>RowSet</code> object.
1104+ * <P>
1105+ * Drivers that support the JDBC 3.0 API will create
1106+ * <code>Connection</code> objects with an associated type map.
1107+ * This type map, which is initially empty, can contain one or more
1108+ * fully-qualified SQL names and <code>Class</code> objects indicating
1109+ * the class to which the named SQL value will be mapped. The type mapping
1110+ * specified in the connection's type map is used for custom type mapping
1111+ * when no other type map supersedes it.
1112+ * <p>
1113+ * If a type map is explicitly supplied to a method that can perform
1114+ * custom mapping, that type map supersedes the connection's type map.
1115+ *
1116+ * @return the <code>java.util.Map</code> object that is the type map
1117+ * for this <code>RowSet</code> object's connection
1118+ */
1119+ public java.util.Map<String,Class<?>> getTypeMap() {
1120+ return map;
1121+ }
1122+
1123+ /**
1124+ * Installs the given <code>java.util.Map</code> object as the type map
1125+ * associated with the <code>Connection</code> object for this
1126+ * <code>RowSet</code> object. The custom mapping indicated in
1127+ * this type map will be used unless a different type map is explicitly
1128+ * supplied to a method, in which case the type map supplied will be used.
1129+ *
1130+ * @param map a <code>java.util.Map</code> object that contains the
1131+ * mapping from SQL type names for user defined types (UDT) to classes in
1132+ * the Java programming language. Each entry in the <code>Map</code>
1133+ * object consists of the fully qualified SQL name of a UDT and the
1134+ * <code>Class</code> object for the <code>SQLData</code> implementation
1135+ * of that UDT. May be <code>null</code>.
1136+ */
1137+ public void setTypeMap(java.util.Map<String,Class<?>> map) {
1138+ this.map = map;
1139+ }
1140+
1141+ /**
1142+ * Retrieves the maximum number of bytes that can be used for a column
1143+ * value in this <code>RowSet</code> object.
1144+ * This limit applies only to columns that hold values of the
1145+ * following types: <code>BINARY</code>, <code>VARBINARY</code>,
1146+ * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
1147+ * and <code>LONGVARCHAR</code>. If the limit is exceeded, the excess
1148+ * data is silently discarded.
1149+ *
1150+ * @return an <code>int</code> indicating the current maximum column size
1151+ * limit; zero means that there is no limit
1152+ * @throws SQLException if an error occurs internally determining the
1153+ * maximum limit of the column size
1154+ */
1155+ public int getMaxFieldSize() throws SQLException {
1156+ return maxFieldSize;
1157+ }
1158+
1159+ /**
1160+ * Sets the maximum number of bytes that can be used for a column
1161+ * value in this <code>RowSet</code> object to the given number.
1162+ * This limit applies only to columns that hold values of the
1163+ * following types: <code>BINARY</code>, <code>VARBINARY</code>,
1164+ * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
1165+ * and <code>LONGVARCHAR</code>. If the limit is exceeded, the excess
1166+ * data is silently discarded. For maximum portability, it is advisable to
1167+ * use values greater than 256.
1168+ *
1169+ * @param max an <code>int</code> indicating the new maximum column size
1170+ * limit; zero means that there is no limit
1171+ * @throws SQLException if (1) an error occurs internally setting the
1172+ * maximum limit of the column size or (2) a size of less than 0 is set
1173+ */
1174+ public void setMaxFieldSize(int max) throws SQLException {
1175+ if (max < 0) {
1176+ throw new SQLException("Invalid max field size set. Cannot be of " +
1177+ "value: " + max);
1178+ }
1179+ maxFieldSize = max;
1180+ }
1181+
1182+ /**
1183+ * Retrieves the maximum number of rows that this <code>RowSet</code> object may contain. If
1184+ * this limit is exceeded, the excess rows are silently dropped.
1185+ *
1186+ * @return an <code>int</code> indicating the current maximum number of
1187+ * rows; zero means that there is no limit
1188+ * @throws SQLException if an error occurs internally determining the
1189+ * maximum limit of rows that a <code>Rowset</code> object can contain
1190+ */
1191+ public int getMaxRows() throws SQLException {
1192+ return maxRows;
1193+ }
1194+
1195+ /**
1196+ * Sets the maximum number of rows that this <code>RowSet</code> object may contain to
1197+ * the given number. If this limit is exceeded, the excess rows are
1198+ * silently dropped.
1199+ *
1200+ * @param max an <code>int</code> indicating the current maximum number
1201+ * of rows; zero means that there is no limit
1202+ * @throws SQLException if an error occurs internally setting the
1203+ * maximum limit on the number of rows that a JDBC <code>RowSet</code> object
1204+ * can contain; or if <i>max</i> is less than <code>0</code>; or
1205+ * if <i>max</i> is less than the <code>fetchSize</code> of the
1206+ * <code>RowSet</code>
1207+ */
1208+ public void setMaxRows(int max) throws SQLException {
1209+ if (max < 0) {
1210+ throw new SQLException("Invalid max row size set. Cannot be of " +
1211+ "value: " + max);
1212+ } else if (max < this.getFetchSize()) {
1213+ throw new SQLException("Invalid max row size set. Cannot be less " +
1214+ "than the fetchSize.");
1215+ }
1216+ this.maxRows = max;
1217+ }
1218+
1219+ /**
1220+ * Sets to the given <code>boolean</code> whether or not the driver will
1221+ * scan for escape syntax and do escape substitution before sending SQL
1222+ * statements to the database. The default is for the driver to do escape
1223+ * processing.
1224+ * <P>
1225+ * Note: Since <code>PreparedStatement</code> objects have usually been
1226+ * parsed prior to making this call, disabling escape processing for
1227+ * prepared statements will likely have no effect.
1228+ *
1229+ * @param enable <code>true</code> to enable escape processing;
1230+ * <code>false</code> to disable it
1231+ * @throws SQLException if an error occurs setting the underlying JDBC
1232+ * technology-enabled driver to process the escape syntax
1233+ */
1234+ public void setEscapeProcessing(boolean enable) throws SQLException {
1235+ escapeProcessing = enable;
1236+ }
1237+
1238+ /**
1239+ * Retrieves the maximum number of seconds the driver will wait for a
1240+ * query to execute. If the limit is exceeded, an <code>SQLException</code>
1241+ * is thrown.
1242+ *
1243+ * @return the current query timeout limit in seconds; zero means that
1244+ * there is no limit
1245+ * @throws SQLException if an error occurs in determining the query
1246+ * time-out value
1247+ */
1248+ public int getQueryTimeout() throws SQLException {
1249+ return queryTimeout;
1250+ }
1251+
1252+ /**
1253+ * Sets to the given number the maximum number of seconds the driver will
1254+ * wait for a query to execute. If the limit is exceeded, an
1255+ * <code>SQLException</code> is thrown.
1256+ *
1257+ * @param seconds the new query time-out limit in seconds; zero means that
1258+ * there is no limit; must not be less than zero
1259+ * @throws SQLException if an error occurs setting the query
1260+ * time-out or if the query time-out value is less than 0
1261+ */
1262+ public void setQueryTimeout(int seconds) throws SQLException {
1263+ if (seconds < 0) {
1264+ throw new SQLException("Invalid query timeout value set. Cannot be " +
1265+ "of value: " + seconds);
1266+ }
1267+ this.queryTimeout = seconds;
1268+ }
1269+
1270+ /**
1271+ * Retrieves a <code>boolean</code> indicating whether rows marked
1272+ * for deletion appear in the set of current rows.
1273+ * The default value is <code>false</code>.
1274+ * <P>
1275+ * Note: Allowing deleted rows to remain visible complicates the behavior
1276+ * of some of the methods. However, most <code>RowSet</code> object users
1277+ * can simply ignore this extra detail because only sophisticated
1278+ * applications will likely want to take advantage of this feature.
1279+ *
1280+ * @return <code>true</code> if deleted rows are visible;
1281+ * <code>false</code> otherwise
1282+ * @throws SQLException if an error occurs determining if deleted rows
1283+ * are visible or not
1284+ * @see #setShowDeleted
1285+ */
1286+ public boolean getShowDeleted() throws SQLException {
1287+ return showDeleted;
1288+ }
1289+
1290+ /**
1291+ * Sets the property <code>showDeleted</code> to the given
1292+ * <code>boolean</code> value, which determines whether
1293+ * rows marked for deletion appear in the set of current rows.
1294+ *
1295+ * @param value <code>true</code> if deleted rows should be shown;
1296+ * <code>false</code> otherwise
1297+ * @throws SQLException if an error occurs setting whether deleted
1298+ * rows are visible or not
1299+ * @see #getShowDeleted
1300+ */
1301+ public void setShowDeleted(boolean value) throws SQLException {
1302+ showDeleted = value;
1303+ }
1304+
1305+ /**
1306+ * Ascertains whether escape processing is enabled for this
1307+ * <code>RowSet</code> object.
1308+ *
1309+ * @return <code>true</code> if escape processing is turned on;
1310+ * <code>false</code> otherwise
1311+ * @throws SQLException if an error occurs determining if escape
1312+ * processing is enabled or not or if the internal escape
1313+ * processing trigger has not been enabled
1314+ */
1315+ public boolean getEscapeProcessing() throws SQLException {
1316+ return escapeProcessing;
1317+ }
1318+
1319+ /**
1320+ * Gives the driver a performance hint as to the direction in
1321+ * which the rows in this <code>RowSet</code> object will be
1322+ * processed. The driver may ignore this hint.
1323+ * <P>
1324+ * A <code>RowSet</code> object inherits the default properties of the
1325+ * <code>ResultSet</code> object from which it got its data. That
1326+ * <code>ResultSet</code> object's default fetch direction is set by
1327+ * the <code>Statement</code> object that created it.
1328+ * <P>
1329+ * This method applies to a <code>RowSet</code> object only while it is
1330+ * connected to a database using a JDBC driver.
1331+ * <p>
1332+ * A <code>RowSet</code> object may use this method at any time to change
1333+ * its setting for the fetch direction.
1334+ *
1335+ * @param direction one of <code>ResultSet.FETCH_FORWARD</code>,
1336+ * <code>ResultSet.FETCH_REVERSE</code>, or
1337+ * <code>ResultSet.FETCH_UNKNOWN</code>
1338+ * @throws SQLException if (1) the <code>RowSet</code> type is
1339+ * <code>TYPE_FORWARD_ONLY</code> and the given fetch direction is not
1340+ * <code>FETCH_FORWARD</code> or (2) the given fetch direction is not
1341+ * one of the following:
1342+ * ResultSet.FETCH_FORWARD,
1343+ * ResultSet.FETCH_REVERSE, or
1344+ * ResultSet.FETCH_UNKNOWN
1345+ * @see #getFetchDirection
1346+ */
1347+ public void setFetchDirection(int direction) throws SQLException {
1348+ // Changed the condition checking to the below as there were two
1349+ // conditions that had to be checked
1350+ // 1. RowSet is TYPE_FORWARD_ONLY and direction is not FETCH_FORWARD
1351+ // 2. Direction is not one of the valid values
1352+
1353+ if (((getType() == ResultSet.TYPE_FORWARD_ONLY) && (direction != ResultSet.FETCH_FORWARD)) ||
1354+ ((direction != ResultSet.FETCH_FORWARD) &&
1355+ (direction != ResultSet.FETCH_REVERSE) &&
1356+ (direction != ResultSet.FETCH_UNKNOWN))) {
1357+ throw new SQLException("Invalid Fetch Direction");
1358+ }
1359+ fetchDir = direction;
1360+ }
1361+
1362+ /**
1363+ * Retrieves this <code>RowSet</code> object's current setting for the
1364+ * fetch direction. The default type is <code>ResultSet.FETCH_FORWARD</code>
1365+ *
1366+ * @return one of <code>ResultSet.FETCH_FORWARD</code>,
1367+ * <code>ResultSet.FETCH_REVERSE</code>, or
1368+ * <code>ResultSet.FETCH_UNKNOWN</code>
1369+ * @throws SQLException if an error occurs in determining the
1370+ * current fetch direction for fetching rows
1371+ * @see #setFetchDirection
1372+ */
1373+ public int getFetchDirection() throws SQLException {
1374+
1375+ //Added the following code to throw a
1376+ //SQL Exception if the fetchDir is not
1377+ //set properly.Bug id:4914155
1378+
1379+ // This checking is not necessary!
1380+
1381+ /*
1382+ if((fetchDir != ResultSet.FETCH_FORWARD) &&
1383+ (fetchDir != ResultSet.FETCH_REVERSE) &&
1384+ (fetchDir != ResultSet.FETCH_UNKNOWN)) {
1385+ throw new SQLException("Fetch Direction Invalid");
1386+ }
1387+ */
1388+ return (fetchDir);
1389+ }
1390+
1391+ /**
1392+ * Sets the fetch size for this <code>RowSet</code> object to the given number of
1393+ * rows. The fetch size gives a JDBC technology-enabled driver ("JDBC driver")
1394+ * a hint as to the
1395+ * number of rows that should be fetched from the database when more rows
1396+ * are needed for this <code>RowSet</code> object. If the fetch size specified
1397+ * is zero, the driver ignores the value and is free to make its own best guess
1398+ * as to what the fetch size should be.
1399+ * <P>
1400+ * A <code>RowSet</code> object inherits the default properties of the
1401+ * <code>ResultSet</code> object from which it got its data. That
1402+ * <code>ResultSet</code> object's default fetch size is set by
1403+ * the <code>Statement</code> object that created it.
1404+ * <P>
1405+ * This method applies to a <code>RowSet</code> object only while it is
1406+ * connected to a database using a JDBC driver.
1407+ * For connected <code>RowSet</code> implementations such as
1408+ * <code>JdbcRowSet</code>, this method has a direct and immediate effect
1409+ * on the underlying JDBC driver.
1410+ * <P>
1411+ * A <code>RowSet</code> object may use this method at any time to change
1412+ * its setting for the fetch size.
1413+ * <p>
1414+ * For <code>RowSet</code> implementations such as
1415+ * <code>CachedRowSet</code>, which operate in a disconnected environment,
1416+ * the <code>SyncProvider</code> object being used
1417+ * may leverage the fetch size to poll the data source and
1418+ * retrieve a number of rows that do not exceed the fetch size and that may
1419+ * form a subset of the actual rows returned by the original query. This is
1420+ * an implementation variance determined by the specific <code>SyncProvider</code>
1421+ * object employed by the disconnected <code>RowSet</code> object.
1422+ * <P>
1423+ *
1424+ * @param rows the number of rows to fetch; <code>0</code> to let the
1425+ * driver decide what the best fetch size is; must not be less
1426+ * than <code>0</code> or more than the maximum number of rows
1427+ * allowed for this <code>RowSet</code> object (the number returned
1428+ * by a call to the method {@link #getMaxRows})
1429+ * @throws SQLException if the specified fetch size is less than <code>0</code>
1430+ * or more than the limit for the maximum number of rows
1431+ * @see #getFetchSize
1432+ */
1433+ public void setFetchSize(int rows) throws SQLException {
1434+ //Added this checking as maxRows can be 0 when this function is called
1435+ //maxRows = 0 means rowset can hold any number of rows, os this checking
1436+ // is needed to take care of this condition.
1437+ if (getMaxRows() == 0 && rows >= 0) {
1438+ fetchSize = rows;
1439+ return;
1440+ }
1441+ if ((rows < 0) || (rows > getMaxRows())) {
1442+ throw new SQLException("Invalid fetch size set. Cannot be of " +
1443+ "value: " + rows);
1444+ }
1445+ fetchSize = rows;
1446+ }
1447+
1448+ /**
1449+ * Returns the fetch size for this <code>RowSet</code> object. The default
1450+ * value is zero.
1451+ *
1452+ * @return the number of rows suggested as the fetch size when this <code>RowSet</code> object
1453+ * needs more rows from the database
1454+ * @throws SQLException if an error occurs determining the number of rows in the
1455+ * current fetch size
1456+ * @see #setFetchSize
1457+ */
1458+ public int getFetchSize() throws SQLException {
1459+ return fetchSize;
1460+ }
1461+
1462+ /**
1463+ * Returns the concurrency for this <code>RowSet</code> object.
1464+ * The default is <code>CONCUR_UPDATABLE</code> for both connected and
1465+ * disconnected <code>RowSet</code> objects.
1466+ * <P>
1467+ * An application can call the method <code>setConcurrency</code> at any time
1468+ * to change a <code>RowSet</code> object's concurrency.
1469+ * <p>
1470+ * @return the concurrency type for this <code>RowSet</code>
1471+ * object, which must be one of the following:
1472+ * <code>ResultSet.CONCUR_READ_ONLY</code> or
1473+ * <code>ResultSet.CONCUR_UPDATABLE</code>
1474+ * @throws SQLException if an error occurs getting the concurrency
1475+ * of this <code>RowSet</code> object
1476+ * @see #setConcurrency
1477+ * @see #isReadOnly
1478+ */
1479+ public int getConcurrency() throws SQLException {
1480+ return concurrency;
1481+ }
1482+
1483+ //-----------------------------------------------------------------------
1484+ // Parameters
1485+ //-----------------------------------------------------------------------
1486+
1487+ /**
1488+ * Checks the given index to see whether it is less than <code>1</code> and
1489+ * throws an <code>SQLException</code> object if it is.
1490+ * <P>
1491+ * This method is called by many methods internally; it is never
1492+ * called by an application directly.
1493+ *
1494+ * @param idx an <code>int</code> indicating which parameter is to be
1495+ * checked; the first parameter is <code>1</code>
1496+ * @throws SQLException if the parameter is less than <code>1</code>
1497+ */
1498+ private void checkParamIndex(int idx) throws SQLException {
1499+ if ((idx < 1)) {
1500+ throw new SQLException("Invalid Parameter Index");
1501+ }
1502+ }
1503+
1504+ //---------------------------------------------------------------------
1505+ // setter methods for setting the parameters in a <code>RowSet</code> object's command
1506+ //---------------------------------------------------------------------
1507+
1508+ /**
1509+ * Sets the designated parameter to SQL <code>NULL</code>.
1510+ * Note that the parameter's SQL type must be specified using one of the
1511+ * type codes defined in <code>java.sql.Types</code>. This SQL type is
1512+ * specified in the second parameter.
1513+ * <p>
1514+ * Note that the second parameter tells the DBMS the data type of the value being
1515+ * set to <code>NULL</code>. Some DBMSs require this information, so it is required
1516+ * in order to make code more portable.
1517+ * <P>
1518+ * The parameter value set by this method is stored internally and
1519+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1520+ * object's command when the method <code>execute</code> is called.
1521+ * Methods such as <code>execute</code> and <code>populate</code> must be
1522+ * provided in any class that extends this class and implements one or
1523+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1524+ * <P>
1525+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1526+ * as it is undefined in this class.
1527+ * <P>
1528+ * Calls made to the method <code>getParams</code> after this version of
1529+ * <code>setNull</code>
1530+ * has been called will return an <code>Object</code> array containing the parameter values that
1531+ * have been set. In that array, the element that represents the values
1532+ * set with this method will itself be an array. The first element of that array
1533+ * is <code>null</code>.
1534+ * The second element is the value set for <i>sqlType</i>.
1535+ * The parameter number is indicated by an element's position in the array
1536+ * returned by the method <code>getParams</code>,
1537+ * with the first element being the value for the first placeholder parameter, the
1538+ * second element being the value for the second placeholder parameter, and so on.
1539+ * In other words, if the second placeholder parameter is being set to
1540+ * <code>null</code>, the array containing it will be the second element in
1541+ * the array returned by <code>getParams</code>.
1542+ * <P>
1543+ * Note that because the numbering of elements in an array starts at zero,
1544+ * the array element that corresponds to placeholder parameter number
1545+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
1546+ *
1547+ * @param parameterIndex the ordinal number of the placeholder parameter
1548+ * in this <code>RowSet</code> object's command that is to be set.
1549+ * The first parameter is 1, the second is 2, and so on; must be
1550+ * <code>1</code> or greater
1551+ * @param sqlType an <code>int</code> that is one of the SQL type codes
1552+ * defined in the class {@link java.sql.Types}. If a non-standard
1553+ * <i>sqlType</i> is supplied, this method will not throw a
1554+ * <code>SQLException</code>. This allows implicit support for
1555+ * non-standard SQL types.
1556+ * @throws SQLException if a database access error occurs or the given
1557+ * parameter index is out of bounds
1558+ * @see #getParams
1559+ */
1560+ public void setNull(int parameterIndex, int sqlType) throws SQLException {
1561+ Object nullVal[];
1562+ checkParamIndex(parameterIndex);
1563+
1564+ nullVal = new Object[2];
1565+ nullVal[0] = null;
1566+ nullVal[1] = Integer.valueOf(sqlType);
1567+
1568+ if (params == null){
1569+ throw new SQLException("Set initParams() before setNull");
1570+ }
1571+
1572+ params.put(Integer.valueOf(parameterIndex - 1), nullVal);
1573+ }
1574+
1575+ /**
1576+ * Sets the designated parameter to SQL <code>NULL</code>.
1577+ *
1578+ * Although this version of the method <code>setNull</code> is intended
1579+ * for user-defined
1580+ * and <code>REF</code> parameters, this method may be used to set a null
1581+ * parameter for any JDBC type. The following are user-defined types:
1582+ * <code>STRUCT</code>, <code>DISTINCT</code>, and <code>JAVA_OBJECT</code>,
1583+ * and named array types.
1584+ *
1585+ * <P><B>Note:</B> To be portable, applications must give the
1586+ * SQL type code and the fully qualified SQL type name when specifying
1587+ * a <code>NULL</code> user-defined or <code>REF</code> parameter.
1588+ * In the case of a user-defined type, the name is the type name of
1589+ * the parameter itself. For a <code>REF</code> parameter, the name is
1590+ * the type name of the referenced type. If a JDBC technology-enabled
1591+ * driver does not need the type code or type name information,
1592+ * it may ignore it.
1593+ * <P>
1594+ * If the parameter does not have a user-defined or <code>REF</code> type,
1595+ * the given <code>typeName</code> parameter is ignored.
1596+ * <P>
1597+ * The parameter value set by this method is stored internally and
1598+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1599+ * object's command when the method <code>execute</code> is called.
1600+ * Methods such as <code>execute</code> and <code>populate</code> must be
1601+ * provided in any class that extends this class and implements one or
1602+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1603+ * <P>
1604+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1605+ * as it is undefined in this class.
1606+ * <P>
1607+ * Calls made to the method <code>getParams</code> after this version of
1608+ * <code>setNull</code>
1609+ * has been called will return an <code>Object</code> array containing the parameter values that
1610+ * have been set. In that array, the element that represents the values
1611+ * set with this method will itself be an array. The first element of that array
1612+ * is <code>null</code>.
1613+ * The second element is the value set for <i>sqlType</i>, and the third
1614+ * element is the value set for <i>typeName</i>.
1615+ * The parameter number is indicated by an element's position in the array
1616+ * returned by the method <code>getParams</code>,
1617+ * with the first element being the value for the first placeholder parameter, the
1618+ * second element being the value for the second placeholder parameter, and so on.
1619+ * In other words, if the second placeholder parameter is being set to
1620+ * <code>null</code>, the array containing it will be the second element in
1621+ * the array returned by <code>getParams</code>.
1622+ * <P>
1623+ * Note that because the numbering of elements in an array starts at zero,
1624+ * the array element that corresponds to placeholder parameter number
1625+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
1626+ *
1627+ * @param parameterIndex the ordinal number of the placeholder parameter
1628+ * in this <code>RowSet</code> object's command that is to be set.
1629+ * The first parameter is 1, the second is 2, and so on; must be
1630+ * <code>1</code> or greater
1631+ * @param sqlType a value from <code>java.sql.Types</code>
1632+ * @param typeName the fully qualified name of an SQL user-defined type,
1633+ * which is ignored if the parameter is not a user-defined
1634+ * type or <code>REF</code> value
1635+ * @throws SQLException if an error occurs or the given parameter index
1636+ * is out of bounds
1637+ * @see #getParams
1638+ */
1639+ public void setNull(int parameterIndex, int sqlType, String typeName)
1640+ throws SQLException {
1641+
1642+ Object nullVal[];
1643+ checkParamIndex(parameterIndex);
1644+
1645+ nullVal = new Object[3];
1646+ nullVal[0] = null;
1647+ nullVal[1] = Integer.valueOf(sqlType);
1648+ nullVal[2] = typeName;
1649+
1650+ if(params == null){
1651+ throw new SQLException("Set initParams() before setNull");
1652+ }
1653+
1654+ params.put(Integer.valueOf(parameterIndex - 1), nullVal);
1655+ }
1656+
1657+
1658+ /**
1659+ * Sets the designated parameter to the given <code>boolean</code> in the
1660+ * Java programming language. The driver converts this to an SQL
1661+ * <code>BIT</code> value when it sends it to the database.
1662+ * <P>
1663+ * The parameter value set by this method is stored internally and
1664+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1665+ * object's command when the method <code>execute</code> is called.
1666+ * Methods such as <code>execute</code>, <code>populate</code> must be
1667+ * provided in any class that extends this class and implements one or
1668+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1669+ * <p>
1670+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1671+ * as it is undefined in this class.
1672+ *
1673+ * @param parameterIndex the ordinal number of the placeholder parameter
1674+ * in this <code>RowSet</code> object's command that is to be set.
1675+ * The first parameter is 1, the second is 2, and so on; must be
1676+ * <code>1</code> or greater
1677+ * @param x the parameter value
1678+ * @throws SQLException if an error occurs or the
1679+ * parameter index is out of bounds
1680+ * @see #getParams
1681+ */
1682+ public void setBoolean(int parameterIndex, boolean x) throws SQLException {
1683+ checkParamIndex(parameterIndex);
1684+
1685+ if(params == null){
1686+ throw new SQLException("Set initParams() before setNull");
1687+ }
1688+
1689+ params.put(Integer.valueOf(parameterIndex - 1), Boolean.valueOf(x));
1690+ }
1691+
1692+ /**
1693+ * Sets the designated parameter to the given <code>byte</code> in the Java
1694+ * programming language. The driver converts this to an SQL
1695+ * <code>TINYINT</code> value when it sends it to the database.
1696+ * <P>
1697+ * The parameter value set by this method is stored internally and
1698+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1699+ * object's command when the method <code>execute</code> is called.
1700+ * Methods such as <code>execute</code> and <code>populate</code> must be
1701+ * provided in any class that extends this class and implements one or
1702+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1703+ * <p>
1704+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1705+ * as it is undefined in this class.
1706+ *
1707+ * @param parameterIndex the ordinal number of the placeholder parameter
1708+ * in this <code>RowSet</code> object's command that is to be set.
1709+ * The first parameter is 1, the second is 2, and so on; must be
1710+ * <code>1</code> or greater
1711+ * @param x the parameter value
1712+ * @throws SQLException if an error occurs or the
1713+ * parameter index is out of bounds
1714+ * @see #getParams
1715+ */
1716+ public void setByte(int parameterIndex, byte x) throws SQLException {
1717+ checkParamIndex(parameterIndex);
1718+
1719+ if(params == null){
1720+ throw new SQLException("Set initParams() before setByte");
1721+ }
1722+
1723+ params.put(Integer.valueOf(parameterIndex - 1), Byte.valueOf(x));
1724+ }
1725+
1726+ /**
1727+ * Sets the designated parameter to the given <code>short</code> in the
1728+ * Java programming language. The driver converts this to an SQL
1729+ * <code>SMALLINT</code> value when it sends it to the database.
1730+ * <P>
1731+ * The parameter value set by this method is stored internally and
1732+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1733+ * object's command when the method <code>execute</code> is called.
1734+ * Methods such as <code>execute</code> and <code>populate</code> must be
1735+ * provided in any class that extends this class and implements one or
1736+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1737+ * <p>
1738+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1739+ * as it is undefined in this class.
1740+ * <p>
1741+ * @param parameterIndex the ordinal number of the placeholder parameter
1742+ * in this <code>RowSet</code> object's command that is to be set.
1743+ * The first parameter is 1, the second is 2, and so on; must be
1744+ * <code>1</code> or greater
1745+ * @param x the parameter value
1746+ * @throws SQLException if an error occurs or the
1747+ * parameter index is out of bounds
1748+ * @see #getParams
1749+ */
1750+ public void setShort(int parameterIndex, short x) throws SQLException {
1751+ checkParamIndex(parameterIndex);
1752+
1753+ if(params == null){
1754+ throw new SQLException("Set initParams() before setShort");
1755+ }
1756+
1757+ params.put(Integer.valueOf(parameterIndex - 1), Short.valueOf(x));
1758+ }
1759+
1760+ /**
1761+ * Sets the designated parameter to an <code>int</code> in the Java
1762+ * programming language. The driver converts this to an SQL
1763+ * <code>INTEGER</code> value when it sends it to the database.
1764+ * <P>
1765+ * The parameter value set by this method is stored internally and
1766+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1767+ * object's command when the method <code>execute</code> is called.
1768+ * Methods such as <code>execute</code> and <code>populate</code> must be
1769+ * provided in any class that extends this class and implements one or
1770+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1771+ * <P>
1772+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1773+ * as it is undefined in this class.
1774+ *
1775+ * @param parameterIndex the ordinal number of the placeholder parameter
1776+ * in this <code>RowSet</code> object's command that is to be set.
1777+ * The first parameter is 1, the second is 2, and so on; must be
1778+ * <code>1</code> or greater
1779+ * @param x the parameter value
1780+ * @throws SQLException if an error occurs or the
1781+ * parameter index is out of bounds
1782+ * @see #getParams
1783+ */
1784+ public void setInt(int parameterIndex, int x) throws SQLException {
1785+ checkParamIndex(parameterIndex);
1786+ if(params == null){
1787+ throw new SQLException("Set initParams() before setInt");
1788+ }
1789+ params.put(Integer.valueOf(parameterIndex - 1), Integer.valueOf(x));
1790+ }
1791+
1792+ /**
1793+ * Sets the designated parameter to the given <code>long</code> in the Java
1794+ * programming language. The driver converts this to an SQL
1795+ * <code>BIGINT</code> value when it sends it to the database.
1796+ * <P>
1797+ * The parameter value set by this method is stored internally and
1798+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1799+ * object's command when the method <code>execute</code> is called.
1800+ * Methods such as <code>execute</code> and <code>populate</code> must be
1801+ * provided in any class that extends this class and implements one or
1802+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1803+ * <P>
1804+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1805+ * as it is undefined in this class.
1806+ *
1807+ * @param parameterIndex the ordinal number of the placeholder parameter
1808+ * in this <code>RowSet</code> object's command that is to be set.
1809+ * The first parameter is 1, the second is 2, and so on; must be
1810+ * <code>1</code> or greater
1811+ * @param x the parameter value
1812+ * @throws SQLException if an error occurs or the
1813+ * parameter index is out of bounds
1814+ * @see #getParams
1815+ */
1816+ public void setLong(int parameterIndex, long x) throws SQLException {
1817+ checkParamIndex(parameterIndex);
1818+ if(params == null){
1819+ throw new SQLException("Set initParams() before setLong");
1820+ }
1821+ params.put(Integer.valueOf(parameterIndex - 1), Long.valueOf(x));
1822+ }
1823+
1824+ /**
1825+ * Sets the designated parameter to the given <code>float</code> in the
1826+ * Java programming language. The driver converts this to an SQL
1827+ * <code>FLOAT</code> value when it sends it to the database.
1828+ * <P>
1829+ * The parameter value set by this method is stored internally and
1830+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1831+ * object's command when the method <code>execute</code> is called.
1832+ * Methods such as <code>execute</code> and <code>populate</code> must be
1833+ * provided in any class that extends this class and implements one or
1834+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1835+ * <P>
1836+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1837+ * as it is undefined in this class.
1838+ *
1839+ * @param parameterIndex the ordinal number of the placeholder parameter
1840+ * in this <code>RowSet</code> object's command that is to be set.
1841+ * The first parameter is 1, the second is 2, and so on; must be
1842+ * <code>1</code> or greater
1843+ * @param x the parameter value
1844+ * @throws SQLException if an error occurs or the
1845+ * parameter index is out of bounds
1846+ * @see #getParams
1847+ */
1848+ public void setFloat(int parameterIndex, float x) throws SQLException {
1849+ checkParamIndex(parameterIndex);
1850+ if(params == null){
1851+ throw new SQLException("Set initParams() before setFloat");
1852+ }
1853+ params.put(Integer.valueOf(parameterIndex - 1), new Float(x));
1854+ }
1855+
1856+ /**
1857+ * Sets the designated parameter to the given <code>double</code> in the
1858+ * Java programming language. The driver converts this to an SQL
1859+ * <code>DOUBLE</code> value when it sends it to the database.
1860+ * <P>
1861+ * The parameter value set by this method is stored internally and
1862+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1863+ * object's command when the method <code>execute</code> is called.
1864+ * Methods such as <code>execute</code> and <code>populate</code> must be
1865+ * provided in any class that extends this class and implements one or
1866+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1867+ * <P>
1868+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1869+ * as it is undefined in this class.
1870+ * S
1871+ * @param parameterIndex the ordinal number of the placeholder parameter
1872+ * in this <code>RowSet</code> object's command that is to be set.
1873+ * The first parameter is 1, the second is 2, and so on; must be
1874+ * <code>1</code> or greater
1875+ * @param x the parameter value
1876+ * @throws SQLException if an error occurs or the
1877+ * parameter index is out of bounds
1878+ * @see #getParams
1879+ */
1880+ public void setDouble(int parameterIndex, double x) throws SQLException {
1881+ checkParamIndex(parameterIndex);
1882+ if(params == null){
1883+ throw new SQLException("Set initParams() before setDouble");
1884+ }
1885+ params.put(Integer.valueOf(parameterIndex - 1), new Double(x));
1886+ }
1887+
1888+ /**
1889+ * Sets the designated parameter to the given
1890+ * <code>java.lang.BigDecimal</code> value. The driver converts this to
1891+ * an SQL <code>NUMERIC</code> value when it sends it to the database.
1892+ * <P>
1893+ * The parameter value set by this method is stored internally and
1894+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1895+ * object's command when the method <code>execute</code> is called.
1896+ * Methods such as <code>execute</code> and <code>populate</code> must be
1897+ * provided in any class that extends this class and implements one or
1898+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1899+ * <P>
1900+ * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1901+ * as it is undefined in this class.
1902+ *
1903+ * @param parameterIndex the ordinal number of the placeholder parameter
1904+ * in this <code>RowSet</code> object's command that is to be set.
1905+ * The first parameter is 1, the second is 2, and so on; must be
1906+ * <code>1</code> or greater
1907+ * @param x the parameter value
1908+ * @throws SQLException if an error occurs or the
1909+ * parameter index is out of bounds
1910+ * @see #getParams
1911+ */
1912+ public void setBigDecimal(int parameterIndex, java.math.BigDecimal x) throws SQLException {
1913+ checkParamIndex(parameterIndex);
1914+ if(params == null){
1915+ throw new SQLException("Set initParams() before setBigDecimal");
1916+ }
1917+ params.put(Integer.valueOf(parameterIndex - 1), x);
1918+ }
1919+
1920+ /**
1921+ * Sets the designated parameter to the given <code>String</code>
1922+ * value. The driver converts this to an SQL
1923+ * <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
1924+ * (depending on the argument's size relative to the driver's limits
1925+ * on <code>VARCHAR</code> values) when it sends it to the database.
1926+ * <P>
1927+ * The parameter value set by this method is stored internally and
1928+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1929+ * object's command when the method <code>execute</code> is called.
1930+ * Methods such as <code>execute</code> and <code>populate</code> must be
1931+ * provided in any class that extends this class and implements one or
1932+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1933+ * <p>
1934+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1935+ * as it is undefined in this class.
1936+ * <p>
1937+ * @param parameterIndex the ordinal number of the placeholder parameter
1938+ * in this <code>RowSet</code> object's command that is to be set.
1939+ * The first parameter is 1, the second is 2, and so on; must be
1940+ * <code>1</code> or greater
1941+ * @param x the parameter value
1942+ * @throws SQLException if an error occurs or the
1943+ * parameter index is out of bounds
1944+ * @see #getParams
1945+ */
1946+ public void setString(int parameterIndex, String x) throws SQLException {
1947+ checkParamIndex(parameterIndex);
1948+ if(params == null){
1949+ throw new SQLException("Set initParams() before setString");
1950+ }
1951+ params.put(Integer.valueOf(parameterIndex - 1), x);
1952+ }
1953+
1954+ /**
1955+ * Sets the designated parameter to the given array of bytes.
1956+ * The driver converts this to an SQL
1957+ * <code>VARBINARY</code> or <code>LONGVARBINARY</code> value
1958+ * (depending on the argument's size relative to the driver's limits
1959+ * on <code>VARBINARY</code> values) when it sends it to the database.
1960+ * <P>
1961+ * The parameter value set by this method is stored internally and
1962+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1963+ * object's command when the method <code>execute</code> is called.
1964+ * Methods such as <code>execute</code> and <code>populate</code> must be
1965+ * provided in any class that extends this class and implements one or
1966+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1967+ * <p>
1968+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
1969+ * as it is undefined in this class.
1970+ *
1971+ * @param parameterIndex the ordinal number of the placeholder parameter
1972+ * in this <code>RowSet</code> object's command that is to be set.
1973+ * The first parameter is 1, the second is 2, and so on; must be
1974+ * <code>1</code> or greater
1975+ * @param x the parameter value
1976+ * @throws SQLException if an error occurs or the
1977+ * parameter index is out of bounds
1978+ * @see #getParams
1979+ */
1980+ public void setBytes(int parameterIndex, byte x[]) throws SQLException {
1981+ checkParamIndex(parameterIndex);
1982+ if(params == null){
1983+ throw new SQLException("Set initParams() before setBytes");
1984+ }
1985+ params.put(Integer.valueOf(parameterIndex - 1), x);
1986+ }
1987+
1988+ /**
1989+ * Sets the designated parameter to the given <code>java.sql.Date</code>
1990+ * value. The driver converts this to an SQL
1991+ * <code>DATE</code> value when it sends it to the database.
1992+ * <P>
1993+ * The parameter value set by this method is stored internally and
1994+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
1995+ * object's command when the method <code>execute</code> is called.
1996+ * Methods such as <code>execute</code> and <code>populate</code> must be
1997+ * provided in any class that extends this class and implements one or
1998+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
1999+ * <P>
2000+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2001+ * as it is undefined in this class.
2002+ * <P>
2003+ * Calls made to the method <code>getParams</code> after this version
2004+ * of <code>setDate</code>
2005+ * has been called will return an array with the value to be set for
2006+ * placeholder parameter number <i>parameterIndex</i> being the <code>Date</code>
2007+ * object supplied as the second parameter.
2008+ * Note that because the numbering of elements in an array starts at zero,
2009+ * the array element that corresponds to placeholder parameter number
2010+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2011+ *
2012+ * @param parameterIndex the ordinal number of the placeholder parameter
2013+ * in this <code>RowSet</code> object's command that is to be set.
2014+ * The first parameter is 1, the second is 2, and so on; must be
2015+ * <code>1</code> or greater
2016+ * @param x the parameter value
2017+ * @throws SQLException if an error occurs or the
2018+ * parameter index is out of bounds
2019+ * @see #getParams
2020+ */
2021+ public void setDate(int parameterIndex, java.sql.Date x) throws SQLException {
2022+ checkParamIndex(parameterIndex);
2023+
2024+ if(params == null){
2025+ throw new SQLException("Set initParams() before setDate");
2026+ }
2027+ params.put(Integer.valueOf(parameterIndex - 1), x);
2028+ }
2029+
2030+ /**
2031+ * Sets the designated parameter to the given <code>java.sql.Time</code>
2032+ * value. The driver converts this to an SQL <code>TIME</code> value
2033+ * when it sends it to the database.
2034+ * <P>
2035+ * The parameter value set by this method is stored internally and
2036+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2037+ * object's command when the method <code>execute</code> is called.
2038+ * Methods such as <code>execute</code> and <code>populate</code> must be
2039+ * provided in any class that extends this class and implements one or
2040+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2041+ * <P>
2042+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2043+ * as it is undefined in this class.
2044+ * <P>
2045+ * Calls made to the method <code>getParams</code> after this version
2046+ * of the method <code>setTime</code>
2047+ * has been called will return an array of the parameters that have been set.
2048+ * The parameter to be set for parameter placeholder number <i>parameterIndex</i>
2049+ * will be the <code>Time</code> object that was set as the second parameter
2050+ * to this method.
2051+ * <P>
2052+ * Note that because the numbering of elements in an array starts at zero,
2053+ * the array element that corresponds to placeholder parameter number
2054+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2055+ *
2056+ * @param parameterIndex the ordinal number of the placeholder parameter
2057+ * in this <code>RowSet</code> object's command that is to be set.
2058+ * The first parameter is 1, the second is 2, and so on; must be
2059+ * <code>1</code> or greater
2060+ * @param x a <code>java.sql.Time</code> object, which is to be set as the value
2061+ * for placeholder parameter <i>parameterIndex</i>
2062+ * @throws SQLException if an error occurs or the
2063+ * parameter index is out of bounds
2064+ * @see #getParams
2065+ */
2066+ public void setTime(int parameterIndex, java.sql.Time x) throws SQLException {
2067+ checkParamIndex(parameterIndex);
2068+ if(params == null){
2069+ throw new SQLException("Set initParams() before setTime");
2070+ }
2071+
2072+ params.put(Integer.valueOf(parameterIndex - 1), x);
2073+ }
2074+
2075+ /**
2076+ * Sets the designated parameter to the given
2077+ * <code>java.sql.Timestamp</code> value.
2078+ * The driver converts this to an SQL <code>TIMESTAMP</code> value when it
2079+ * sends it to the database.
2080+ * <P>
2081+ * The parameter value set by this method is stored internally and
2082+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2083+ * object's command when the method <code>execute</code> is called.
2084+ * Methods such as <code>execute</code> and <code>populate</code> must be
2085+ * provided in any class that extends this class and implements one or
2086+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2087+ * <P>
2088+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2089+ * as it is undefined in this class.
2090+ * <P>
2091+ * Calls made to the method <code>getParams</code> after this version of
2092+ * <code>setTimestamp</code>
2093+ * has been called will return an array with the value for parameter placeholder
2094+ * number <i>parameterIndex</i> being the <code>Timestamp</code> object that was
2095+ * supplied as the second parameter to this method.
2096+ * Note that because the numbering of elements in an array starts at zero,
2097+ * the array element that corresponds to placeholder parameter number
2098+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2099+ *
2100+ * @param parameterIndex the ordinal number of the placeholder parameter
2101+ * in this <code>RowSet</code> object's command that is to be set.
2102+ * The first parameter is 1, the second is 2, and so on; must be
2103+ * <code>1</code> or greater
2104+ * @param x a <code>java.sql.Timestamp</code> object
2105+ * @throws SQLException if an error occurs or the
2106+ * parameter index is out of bounds
2107+ * @see #getParams
2108+ */
2109+ public void setTimestamp(int parameterIndex, java.sql.Timestamp x) throws SQLException {
2110+ checkParamIndex(parameterIndex);
2111+ if(params == null){
2112+ throw new SQLException("Set initParams() before setTimestamp");
2113+ }
2114+
2115+ params.put(Integer.valueOf(parameterIndex - 1), x);
2116+ }
2117+
2118+ /**
2119+ * Sets the designated parameter to the given
2120+ * <code>java.io.InputStream</code> object,
2121+ * which will have the specified number of bytes.
2122+ * The contents of the stream will be read and sent to the database.
2123+ * This method throws an <code>SQLException</code> object if the number of bytes
2124+ * read and sent to the database is not equal to <i>length</i>.
2125+ * <P>
2126+ * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2127+ * parameter, it may be more practical to send it via a
2128+ * <code>java.io.InputStream</code> object. A JDBC technology-enabled
2129+ * driver will read the data from the stream as needed until it reaches
2130+ * end-of-file. The driver will do any necessary conversion from ASCII to
2131+ * the database <code>CHAR</code> format.
2132+ *
2133+ * <P><B>Note:</B> This stream object can be either a standard
2134+ * Java stream object or your own subclass that implements the
2135+ * standard interface.
2136+ * <P>
2137+ * The parameter value set by this method is stored internally and
2138+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2139+ * object's command when the method <code>execute</code> is called.
2140+ * Methods such as <code>execute</code> and <code>populate</code> must be
2141+ * provided in any class that extends this class and implements one or
2142+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2143+ * <P>
2144+ * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2145+ * as it is undefined in this class.
2146+ * <P>
2147+ * Calls made to the method <code>getParams</code> after <code>setAsciiStream</code>
2148+ * has been called will return an array containing the parameter values that
2149+ * have been set. The element in the array that represents the values
2150+ * set with this method will itself be an array. The first element of that array
2151+ * is the given <code>java.io.InputStream</code> object.
2152+ * The second element is the value set for <i>length</i>.
2153+ * The third element is an internal <code>BaseRowSet</code> constant
2154+ * specifying that the stream passed to this method is an ASCII stream.
2155+ * The parameter number is indicated by an element's position in the array
2156+ * returned by the method <code>getParams</code>,
2157+ * with the first element being the value for the first placeholder parameter, the
2158+ * second element being the value for the second placeholder parameter, and so on.
2159+ * In other words, if the input stream being set is the value for the second
2160+ * placeholder parameter, the array containing it will be the second element in
2161+ * the array returned by <code>getParams</code>.
2162+ * <P>
2163+ * Note that because the numbering of elements in an array starts at zero,
2164+ * the array element that corresponds to placeholder parameter number
2165+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2166+ *
2167+ * @param parameterIndex the ordinal number of the placeholder parameter
2168+ * in this <code>RowSet</code> object's command that is to be set.
2169+ * The first parameter is 1, the second is 2, and so on; must be
2170+ * <code>1</code> or greater
2171+ * @param x the Java input stream that contains the ASCII parameter value
2172+ * @param length the number of bytes in the stream. This is the number of bytes
2173+ * the driver will send to the DBMS; lengths of 0 or less are
2174+ * are undefined but will cause an invalid length exception to be
2175+ * thrown in the underlying JDBC driver.
2176+ * @throws SQLException if an error occurs, the parameter index is out of bounds,
2177+ * or when connected to a data source, the number of bytes the driver reads
2178+ * and sends to the database is not equal to the number of bytes specified
2179+ * in <i>length</i>
2180+ * @see #getParams
2181+ */
2182+ public void setAsciiStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException {
2183+ Object asciiStream[];
2184+ checkParamIndex(parameterIndex);
2185+
2186+ asciiStream = new Object[3];
2187+ asciiStream[0] = x;
2188+ asciiStream[1] = Integer.valueOf(length);
2189+ asciiStream[2] = Integer.valueOf(ASCII_STREAM_PARAM);
2190+
2191+ if(params == null){
2192+ throw new SQLException("Set initParams() before setAsciiStream");
2193+ }
2194+
2195+ params.put(Integer.valueOf(parameterIndex - 1), asciiStream);
2196+ }
2197+
2198+ /**
2199+ * Sets the designated parameter in this <code>RowSet</code> object's command
2200+ * to the given input stream.
2201+ * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2202+ * parameter, it may be more practical to send it via a
2203+ * <code>java.io.InputStream</code>. Data will be read from the stream
2204+ * as needed until end-of-file is reached. The JDBC driver will
2205+ * do any necessary conversion from ASCII to the database char format.
2206+ *
2207+ * <P><B>Note:</B> This stream object can either be a standard
2208+ * Java stream object or your own subclass that implements the
2209+ * standard interface.
2210+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2211+ * it might be more efficient to use a version of
2212+ * <code>setAsciiStream</code> which takes a length parameter.
2213+ *
2214+ * @param parameterIndex the first parameter is 1, the second is 2, ...
2215+ * @param x the Java input stream that contains the ASCII parameter value
2216+ * @exception SQLException if a database access error occurs or
2217+ * this method is called on a closed <code>PreparedStatement</code>
2218+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2219+ * @since 1.6
2220+ */
2221+ public void setAsciiStream(int parameterIndex, java.io.InputStream x)
2222+ throws SQLException {
2223+ throw new SQLFeatureNotSupportedException("Feature not supported");
2224+ }
2225+
2226+ /**
2227+ * Sets the designated parameter to the given <code>java.io.InputStream</code>
2228+ * object, which will have the specified number of bytes.
2229+ * The contents of the stream will be read and sent to the database.
2230+ * This method throws an <code>SQLException</code> object if the number of bytes
2231+ * read and sent to the database is not equal to <i>length</i>.
2232+ * <P>
2233+ * When a very large binary value is input to a
2234+ * <code>LONGVARBINARY</code> parameter, it may be more practical
2235+ * to send it via a <code>java.io.InputStream</code> object.
2236+ * A JDBC technology-enabled driver will read the data from the
2237+ * stream as needed until it reaches end-of-file.
2238+ *
2239+ * <P><B>Note:</B> This stream object can be either a standard
2240+ * Java stream object or your own subclass that implements the
2241+ * standard interface.
2242+ * <P>
2243+ * The parameter value set by this method is stored internally and
2244+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2245+ * object's command when the method <code>execute</code> is called.
2246+ * Methods such as <code>execute</code> and <code>populate</code> must be
2247+ * provided in any class that extends this class and implements one or
2248+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2249+ *<P>
2250+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2251+ * as it is undefined in this class.
2252+ * <P>
2253+ * Calls made to the method <code>getParams</code> after <code>setBinaryStream</code>
2254+ * has been called will return an array containing the parameter values that
2255+ * have been set. In that array, the element that represents the values
2256+ * set with this method will itself be an array. The first element of that array
2257+ * is the given <code>java.io.InputStream</code> object.
2258+ * The second element is the value set for <i>length</i>.
2259+ * The third element is an internal <code>BaseRowSet</code> constant
2260+ * specifying that the stream passed to this method is a binary stream.
2261+ * The parameter number is indicated by an element's position in the array
2262+ * returned by the method <code>getParams</code>,
2263+ * with the first element being the value for the first placeholder parameter, the
2264+ * second element being the value for the second placeholder parameter, and so on.
2265+ * In other words, if the input stream being set is the value for the second
2266+ * placeholder parameter, the array containing it will be the second element in
2267+ * the array returned by <code>getParams</code>.
2268+ * <P>
2269+ * Note that because the numbering of elements in an array starts at zero,
2270+ * the array element that corresponds to placeholder parameter number
2271+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2272+ *
2273+ * @param parameterIndex the ordinal number of the placeholder parameter
2274+ * in this <code>RowSet</code> object's command that is to be set.
2275+ * The first parameter is 1, the second is 2, and so on; must be
2276+ * <code>1</code> or greater
2277+ * @param x the input stream that contains the binary value to be set
2278+ * @param length the number of bytes in the stream; lengths of 0 or less are
2279+ * are undefined but will cause an invalid length exception to be
2280+ * thrown in the underlying JDBC driver.
2281+ * @throws SQLException if an error occurs, the parameter index is out of bounds,
2282+ * or when connected to a data source, the number of bytes the driver
2283+ * reads and sends to the database is not equal to the number of bytes
2284+ * specified in <i>length</i>
2285+ * @see #getParams
2286+ */
2287+ public void setBinaryStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException {
2288+ Object binaryStream[];
2289+ checkParamIndex(parameterIndex);
2290+
2291+ binaryStream = new Object[3];
2292+ binaryStream[0] = x;
2293+ binaryStream[1] = Integer.valueOf(length);
2294+ binaryStream[2] = Integer.valueOf(BINARY_STREAM_PARAM);
2295+ if(params == null){
2296+ throw new SQLException("Set initParams() before setBinaryStream");
2297+ }
2298+
2299+ params.put(Integer.valueOf(parameterIndex - 1), binaryStream);
2300+ }
2301+
2302+
2303+ /**
2304+ * Sets the designated parameter in this <code>RowSet</code> object's command
2305+ * to the given input stream.
2306+ * When a very large binary value is input to a <code>LONGVARBINARY</code>
2307+ * parameter, it may be more practical to send it via a
2308+ * <code>java.io.InputStream</code> object. The data will be read from the
2309+ * stream as needed until end-of-file is reached.
2310+ *
2311+ * <P><B>Note:</B> This stream object can either be a standard
2312+ * Java stream object or your own subclass that implements the
2313+ * standard interface.
2314+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2315+ * it might be more efficient to use a version of
2316+ * <code>setBinaryStream</code> which takes a length parameter.
2317+ *
2318+ * @param parameterIndex the first parameter is 1, the second is 2, ...
2319+ * @param x the java input stream which contains the binary parameter value
2320+ * @exception SQLException if a database access error occurs or
2321+ * this method is called on a closed <code>PreparedStatement</code>
2322+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2323+ * @since 1.6
2324+ */
2325+ public void setBinaryStream(int parameterIndex, java.io.InputStream x)
2326+ throws SQLException {
2327+ throw new SQLFeatureNotSupportedException("Feature not supported");
2328+ }
2329+
2330+
2331+ /**
2332+ * Sets the designated parameter to the given
2333+ * <code>java.io.InputStream</code> object, which will have the specified
2334+ * number of bytes. The contents of the stream will be read and sent
2335+ * to the database.
2336+ * This method throws an <code>SQLException</code> if the number of bytes
2337+ * read and sent to the database is not equal to <i>length</i>.
2338+ * <P>
2339+ * When a very large Unicode value is input to a
2340+ * <code>LONGVARCHAR</code> parameter, it may be more practical
2341+ * to send it via a <code>java.io.InputStream</code> object.
2342+ * A JDBC technology-enabled driver will read the data from the
2343+ * stream as needed, until it reaches end-of-file.
2344+ * The driver will do any necessary conversion from Unicode to the
2345+ * database <code>CHAR</code> format.
2346+ * The byte format of the Unicode stream must be Java UTF-8, as
2347+ * defined in the Java Virtual Machine Specification.
2348+ *
2349+ * <P><B>Note:</B> This stream object can be either a standard
2350+ * Java stream object or your own subclass that implements the
2351+ * standard interface.
2352+ * <P>
2353+ * This method is deprecated; the method <code>getCharacterStream</code>
2354+ * should be used in its place.
2355+ * <P>
2356+ * The parameter value set by this method is stored internally and
2357+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2358+ * object's command when the method <code>execute</code> is called.
2359+ * Calls made to the method <code>getParams</code> after <code>setUnicodeStream</code>
2360+ * has been called will return an array containing the parameter values that
2361+ * have been set. In that array, the element that represents the values
2362+ * set with this method will itself be an array. The first element of that array
2363+ * is the given <code>java.io.InputStream</code> object.
2364+ * The second element is the value set for <i>length</i>.
2365+ * The third element is an internal <code>BaseRowSet</code> constant
2366+ * specifying that the stream passed to this method is a Unicode stream.
2367+ * The parameter number is indicated by an element's position in the array
2368+ * returned by the method <code>getParams</code>,
2369+ * with the first element being the value for the first placeholder parameter, the
2370+ * second element being the value for the second placeholder parameter, and so on.
2371+ * In other words, if the input stream being set is the value for the second
2372+ * placeholder parameter, the array containing it will be the second element in
2373+ * the array returned by <code>getParams</code>.
2374+ * <P>
2375+ * Note that because the numbering of elements in an array starts at zero,
2376+ * the array element that corresponds to placeholder parameter number
2377+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2378+ *
2379+ * @param parameterIndex the ordinal number of the placeholder parameter
2380+ * in this <code>RowSet</code> object's command that is to be set.
2381+ * The first parameter is 1, the second is 2, and so on; must be
2382+ * <code>1</code> or greater
2383+ * @param x the <code>java.io.InputStream</code> object that contains the
2384+ * UNICODE parameter value
2385+ * @param length the number of bytes in the input stream
2386+ * @throws SQLException if an error occurs, the parameter index is out of bounds,
2387+ * or the number of bytes the driver reads and sends to the database is
2388+ * not equal to the number of bytes specified in <i>length</i>
2389+ * @deprecated getCharacterStream should be used in its place
2390+ * @see #getParams
2391+ */
2392+
2393+ public void setUnicodeStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException {
2394+ Object unicodeStream[];
2395+ checkParamIndex(parameterIndex);
2396+
2397+ unicodeStream = new Object[3];
2398+ unicodeStream[0] = x;
2399+ unicodeStream[1] = Integer.valueOf(length);
2400+ unicodeStream[2] = Integer.valueOf(UNICODE_STREAM_PARAM);
2401+ if(params == null){
2402+ throw new SQLException("Set initParams() before setUnicodeStream");
2403+ }
2404+ params.put(Integer.valueOf(parameterIndex - 1), unicodeStream);
2405+ }
2406+
2407+ /**
2408+ * Sets the designated parameter to the given <code>java.io.Reader</code>
2409+ * object, which will have the specified number of characters. The
2410+ * contents of the reader will be read and sent to the database.
2411+ * This method throws an <code>SQLException</code> if the number of bytes
2412+ * read and sent to the database is not equal to <i>length</i>.
2413+ * <P>
2414+ * When a very large Unicode value is input to a
2415+ * <code>LONGVARCHAR</code> parameter, it may be more practical
2416+ * to send it via a <code>Reader</code> object.
2417+ * A JDBC technology-enabled driver will read the data from the
2418+ * stream as needed until it reaches end-of-file.
2419+ * The driver will do any necessary conversion from Unicode to the
2420+ * database <code>CHAR</code> format.
2421+ * The byte format of the Unicode stream must be Java UTF-8, as
2422+ * defined in the Java Virtual Machine Specification.
2423+ *
2424+ * <P><B>Note:</B> This stream object can be either a standard
2425+ * Java stream object or your own subclass that implements the
2426+ * standard interface.
2427+ * <P>
2428+ * The parameter value set by this method is stored internally and
2429+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2430+ * object's command when the method <code>execute</code> is called.
2431+ * Methods such as <code>execute</code> and <code>populate</code> must be
2432+ * provided in any class that extends this class and implements one or
2433+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2434+ * <P>
2435+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2436+ * as it is undefined in this class.
2437+ * <P>
2438+ * Calls made to the method <code>getParams</code> after
2439+ * <code>setCharacterStream</code>
2440+ * has been called will return an array containing the parameter values that
2441+ * have been set. In that array, the element that represents the values
2442+ * set with this method will itself be an array. The first element of that array
2443+ * is the given <code>java.io.Reader</code> object.
2444+ * The second element is the value set for <i>length</i>.
2445+ * The parameter number is indicated by an element's position in the array
2446+ * returned by the method <code>getParams</code>,
2447+ * with the first element being the value for the first placeholder parameter, the
2448+ * second element being the value for the second placeholder parameter, and so on.
2449+ * In other words, if the reader being set is the value for the second
2450+ * placeholder parameter, the array containing it will be the second element in
2451+ * the array returned by <code>getParams</code>.
2452+ * <P>
2453+ * Note that because the numbering of elements in an array starts at zero,
2454+ * the array element that corresponds to placeholder parameter number
2455+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2456+ *
2457+ * @param parameterIndex the ordinal number of the placeholder parameter
2458+ * in this <code>RowSet</code> object's command that is to be set.
2459+ * The first parameter is 1, the second is 2, and so on; must be
2460+ * <code>1</code> or greater
2461+ * @param reader the <code>Reader</code> object that contains the
2462+ * Unicode data
2463+ * @param length the number of characters in the stream; lengths of 0 or
2464+ * less are undefined but will cause an invalid length exception to
2465+ * be thrown in the underlying JDBC driver.
2466+ * @throws SQLException if an error occurs, the parameter index is out of bounds,
2467+ * or when connected to a data source, the number of bytes the driver
2468+ * reads and sends to the database is not equal to the number of bytes
2469+ * specified in <i>length</i>
2470+ * @see #getParams
2471+ */
2472+ public void setCharacterStream(int parameterIndex, Reader reader, int length) throws SQLException {
2473+ Object charStream[];
2474+ checkParamIndex(parameterIndex);
2475+
2476+ charStream = new Object[2];
2477+ charStream[0] = reader;
2478+ charStream[1] = Integer.valueOf(length);
2479+ if(params == null){
2480+ throw new SQLException("Set initParams() before setCharacterStream");
2481+ }
2482+ params.put(Integer.valueOf(parameterIndex - 1), charStream);
2483+ }
2484+
2485+ /**
2486+ * Sets the designated parameter in this <code>RowSet</code> object's command
2487+ * to the given <code>Reader</code>
2488+ * object.
2489+ * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2490+ * parameter, it may be more practical to send it via a
2491+ * <code>java.io.Reader</code> object. The data will be read from the stream
2492+ * as needed until end-of-file is reached. The JDBC driver will
2493+ * do any necessary conversion from UNICODE to the database char format.
2494+ *
2495+ * <P><B>Note:</B> This stream object can either be a standard
2496+ * Java stream object or your own subclass that implements the
2497+ * standard interface.
2498+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2499+ * it might be more efficient to use a version of
2500+ * <code>setCharacterStream</code> which takes a length parameter.
2501+ *
2502+ * @param parameterIndex the first parameter is 1, the second is 2, ...
2503+ * @param reader the <code>java.io.Reader</code> object that contains the
2504+ * Unicode data
2505+ * @exception SQLException if a database access error occurs or
2506+ * this method is called on a closed <code>PreparedStatement</code>
2507+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2508+ * @since 1.6
2509+ */
2510+ public void setCharacterStream(int parameterIndex,
2511+ java.io.Reader reader) throws SQLException {
2512+ throw new SQLFeatureNotSupportedException("Feature not supported");
2513+ }
2514+
2515+ /**
2516+ * Sets the designated parameter to an <code>Object</code> in the Java
2517+ * programming language. The second parameter must be an
2518+ * <code>Object</code> type. For integral values, the
2519+ * <code>java.lang</code> equivalent
2520+ * objects should be used. For example, use the class <code>Integer</code>
2521+ * for an <code>int</code>.
2522+ * <P>
2523+ * The driver converts this object to the specified
2524+ * target SQL type before sending it to the database.
2525+ * If the object has a custom mapping (is of a class implementing
2526+ * <code>SQLData</code>), the driver should call the method
2527+ * <code>SQLData.writeSQL</code> to write the object to the SQL
2528+ * data stream. If, on the other hand, the object is of a class
2529+ * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
2530+ * <code>Struct</code>, or <code>Array</code>,
2531+ * the driver should pass it to the database as a value of the
2532+ * corresponding SQL type.
2533+ * <P>
2534+ * <p>Note that this method may be used to pass database-
2535+ * specific abstract data types.
2536+ * <P>
2537+ * The parameter value set by this method is stored internally and
2538+ * will be supplied as the appropriate parameter in this <code>RowSet</code
2539+ * object's command when the method <code>execute</code> is called.
2540+ * Methods such as <code>execute</code> and <code>populate</code> must be
2541+ * provided in any class that extends this class and implements one or
2542+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2543+ * <P>
2544+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2545+ * as it is undefined in this class.
2546+ * <P>
2547+ * Calls made to the method <code>getParams</code> after this version of
2548+ * <code>setObject</code>
2549+ * has been called will return an array containing the parameter values that
2550+ * have been set. In that array, the element that represents the values
2551+ * set with this method will itself be an array. The first element of that array
2552+ * is the given <code>Object</code> instance, and the
2553+ * second element is the value set for <i>targetSqlType</i>. The
2554+ * third element is the value set for <i>scale</i>, which the driver will
2555+ * ignore if the type of the object being set is not
2556+ * <code>java.sql.Types.NUMERIC</code> or <code>java.sql.Types.DECIMAL</code>.
2557+ * The parameter number is indicated by an element's position in the array
2558+ * returned by the method <code>getParams</code>,
2559+ * with the first element being the value for the first placeholder parameter, the
2560+ * second element being the value for the second placeholder parameter, and so on.
2561+ * In other words, if the object being set is the value for the second
2562+ * placeholder parameter, the array containing it will be the second element in
2563+ * the array returned by <code>getParams</code>.
2564+ *<P>
2565+ * Note that because the numbering of elements in an array starts at zero,
2566+ * the array element that corresponds to placeholder parameter number
2567+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2568+ *
2569+ *
2570+ * @param parameterIndex the ordinal number of the placeholder parameter
2571+ * in this <code>RowSet</code> object's command that is to be set.
2572+ * The first parameter is 1, the second is 2, and so on; must be
2573+ * <code>1</code> or greater
2574+ * @param x the <code>Object</code> containing the input parameter value;
2575+ * must be an <code>Object</code> type
2576+ * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
2577+ * to be sent to the database. The <code>scale</code> argument may
2578+ * further qualify this type. If a non-standard <i>targetSqlType</i>
2579+ * is supplied, this method will not throw a <code>SQLException</code>.
2580+ * This allows implicit support for non-standard SQL types.
2581+ * @param scale for the types <code>java.sql.Types.DECIMAL</code> and
2582+ * <code>java.sql.Types.NUMERIC</code>, this is the number
2583+ * of digits after the decimal point. For all other types, this
2584+ * value will be ignored.
2585+ * @throws SQLException if an error occurs or the parameter index is out of bounds
2586+ * @see #getParams
2587+ */
2588+ public void setObject(int parameterIndex, Object x, int targetSqlType, int scale) throws SQLException {
2589+ Object obj[];
2590+ checkParamIndex(parameterIndex);
2591+
2592+ obj = new Object[3];
2593+ obj[0] = x;
2594+ obj[1] = Integer.valueOf(targetSqlType);
2595+ obj[2] = Integer.valueOf(scale);
2596+ if(params == null){
2597+ throw new SQLException("Set initParams() before setObject");
2598+ }
2599+ params.put(Integer.valueOf(parameterIndex - 1), obj);
2600+ }
2601+
2602+ /**
2603+ * Sets the value of the designated parameter with the given
2604+ * <code>Object</code> value.
2605+ * This method is like <code>setObject(int parameterIndex, Object x, int
2606+ * targetSqlType, int scale)</code> except that it assumes a scale of zero.
2607+ * <P>
2608+ * The parameter value set by this method is stored internally and
2609+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2610+ * object's command when the method <code>execute</code> is called.
2611+ * Methods such as <code>execute</code> and <code>populate</code> must be
2612+ * provided in any class that extends this class and implements one or
2613+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2614+ * <P>
2615+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2616+ * as it is undefined in this class.
2617+ * <P>
2618+ * Calls made to the method <code>getParams</code> after this version of
2619+ * <code>setObject</code>
2620+ * has been called will return an array containing the parameter values that
2621+ * have been set. In that array, the element that represents the values
2622+ * set with this method will itself be an array. The first element of that array
2623+ * is the given <code>Object</code> instance.
2624+ * The second element is the value set for <i>targetSqlType</i>.
2625+ * The parameter number is indicated by an element's position in the array
2626+ * returned by the method <code>getParams</code>,
2627+ * with the first element being the value for the first placeholder parameter, the
2628+ * second element being the value for the second placeholder parameter, and so on.
2629+ * In other words, if the object being set is the value for the second
2630+ * placeholder parameter, the array containing it will be the second element in
2631+ * the array returned by <code>getParams</code>.
2632+ * <P>
2633+ * Note that because the numbering of elements in an array starts at zero,
2634+ * the array element that corresponds to placeholder parameter number
2635+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2636+ *
2637+ * @param parameterIndex the ordinal number of the placeholder parameter
2638+ * in this <code>RowSet</code> object's command that is to be set.
2639+ * The first parameter is 1, the second is 2, and so on; must be
2640+ * <code>1</code> or greater
2641+ * @param x the <code>Object</code> containing the input parameter value;
2642+ * must be an <code>Object</code> type
2643+ * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
2644+ * to be sent to the database. If a non-standard <i>targetSqlType</i>
2645+ * is supplied, this method will not throw a <code>SQLException</code>.
2646+ * This allows implicit support for non-standard SQL types.
2647+ * @throws SQLException if an error occurs or the parameter index
2648+ * is out of bounds
2649+ * @see #getParams
2650+ */
2651+ public void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException {
2652+ Object obj[];
2653+ checkParamIndex(parameterIndex);
2654+
2655+ obj = new Object[2];
2656+ obj[0] = x;
2657+ obj[1] = Integer.valueOf(targetSqlType);
2658+ if (params == null){
2659+ throw new SQLException("Set initParams() before setObject");
2660+ }
2661+ params.put(Integer.valueOf(parameterIndex - 1), obj);
2662+ }
2663+
2664+ /**
2665+ * Sets the designated parameter to an <code>Object</code> in the Java
2666+ * programming language. The second parameter must be an
2667+ * <code>Object</code>
2668+ * type. For integral values, the <code>java.lang</code> equivalent
2669+ * objects should be used. For example, use the class <code>Integer</code>
2670+ * for an <code>int</code>.
2671+ * <P>
2672+ * The JDBC specification defines a standard mapping from
2673+ * Java <code>Object</code> types to SQL types. The driver will
2674+ * use this standard mapping to convert the given object
2675+ * to its corresponding SQL type before sending it to the database.
2676+ * If the object has a custom mapping (is of a class implementing
2677+ * <code>SQLData</code>), the driver should call the method
2678+ * <code>SQLData.writeSQL</code> to write the object to the SQL
2679+ * data stream.
2680+ * <P>
2681+ * If, on the other hand, the object is of a class
2682+ * implementing <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,
2683+ * <code>Struct</code>, or <code>Array</code>,
2684+ * the driver should pass it to the database as a value of the
2685+ * corresponding SQL type.
2686+ * <P>
2687+ * This method throws an exception if there
2688+ * is an ambiguity, for example, if the object is of a class
2689+ * implementing more than one interface.
2690+ * <P>
2691+ * Note that this method may be used to pass database-specific
2692+ * abstract data types.
2693+ * <P>
2694+ * The parameter value set by this method is stored internally and
2695+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2696+ * object's command when the method <code>execute</code> is called.
2697+ * Methods such as <code>execute</code> and <code>populate</code> must be
2698+ * provided in any class that extends this class and implements one or
2699+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2700+ * <p>
2701+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2702+ * as it is undefined in this class.
2703+ * <P>
2704+ * After this method has been called, a call to the
2705+ * method <code>getParams</code>
2706+ * will return an object array of the current command parameters, which will
2707+ * include the <code>Object</code> set for placeholder parameter number
2708+ * <code>parameterIndex</code>.
2709+ * Note that because the numbering of elements in an array starts at zero,
2710+ * the array element that corresponds to placeholder parameter number
2711+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2712+ *
2713+ * @param parameterIndex the ordinal number of the placeholder parameter
2714+ * in this <code>RowSet</code> object's command that is to be set.
2715+ * The first parameter is 1, the second is 2, and so on; must be
2716+ * <code>1</code> or greater
2717+ * @param x the object containing the input parameter value
2718+ * @throws SQLException if an error occurs the
2719+ * parameter index is out of bounds, or there
2720+ * is ambiguity in the implementation of the
2721+ * object being set
2722+ * @see #getParams
2723+ */
2724+ public void setObject(int parameterIndex, Object x) throws SQLException {
2725+ checkParamIndex(parameterIndex);
2726+ if (params == null) {
2727+ throw new SQLException("Set initParams() before setObject");
2728+ }
2729+ params.put(Integer.valueOf(parameterIndex - 1), x);
2730+ }
2731+
2732+ /**
2733+ * Sets the designated parameter to the given <code>Ref</code> object in
2734+ * the Java programming language. The driver converts this to an SQL
2735+ * <code>REF</code> value when it sends it to the database. Internally, the
2736+ * <code>Ref</code> is represented as a <code>SerialRef</code> to ensure
2737+ * serializability.
2738+ * <P>
2739+ * The parameter value set by this method is stored internally and
2740+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2741+ * object's command when the method <code>execute</code> is called.
2742+ * Methods such as <code>execute</code> and <code>populate</code> must be
2743+ * provided in any class that extends this class and implements one or
2744+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2745+ * <p>
2746+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2747+ * as it is undefined in this class.
2748+ * <p>
2749+ * After this method has been called, a call to the
2750+ * method <code>getParams</code>
2751+ * will return an object array of the current command parameters, which will
2752+ * include the <code>Ref</code> object set for placeholder parameter number
2753+ * <code>parameterIndex</code>.
2754+ * Note that because the numbering of elements in an array starts at zero,
2755+ * the array element that corresponds to placeholder parameter number
2756+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2757+ *
2758+ * @param parameterIndex the ordinal number of the placeholder parameter
2759+ * in this <code>RowSet</code> object's command that is to be set.
2760+ * The first parameter is 1, the second is 2, and so on; must be
2761+ * <code>1</code> or greater
2762+ * @param ref a <code>Ref</code> object representing an SQL <code>REF</code>
2763+ * value; cannot be null
2764+ * @throws SQLException if an error occurs; the parameter index is out of
2765+ * bounds or the <code>Ref</code> object is <code>null</code>; or
2766+ * the <code>Ref</code> object returns a <code>null</code> base type
2767+ * name.
2768+ * @see #getParams
2769+ * @see javax.sql.rowset.serial.SerialRef
2770+ */
2771+ public void setRef (int parameterIndex, Ref ref) throws SQLException {
2772+ checkParamIndex(parameterIndex);
2773+ if (params == null) {
2774+ throw new SQLException("Set initParams() before setRef");
2775+ }
2776+ params.put(Integer.valueOf(parameterIndex - 1), new SerialRef(ref));
2777+ }
2778+
2779+ /**
2780+ * Sets the designated parameter to the given <code>Blob</code> object in
2781+ * the Java programming language. The driver converts this to an SQL
2782+ * <code>BLOB</code> value when it sends it to the database. Internally,
2783+ * the <code>Blob</code> is represented as a <code>SerialBlob</code>
2784+ * to ensure serializability.
2785+ * <P>
2786+ * The parameter value set by this method is stored internally and
2787+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2788+ * object's command when the method <code>execute</code> is called.
2789+ * Methods such as <code>execute</code> and <code>populate</code> must be
2790+ * provided in any class that extends this class and implements one or
2791+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2792+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2793+ * as it is undefined in this class.
2794+ * <p>
2795+ * After this method has been called, a call to the
2796+ * method <code>getParams</code>
2797+ * will return an object array of the current command parameters, which will
2798+ * include the <code>Blob</code> object set for placeholder parameter number
2799+ * <code>parameterIndex</code>.
2800+ * Note that because the numbering of elements in an array starts at zero,
2801+ * the array element that corresponds to placeholder parameter number
2802+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2803+ *
2804+ * @param parameterIndex the ordinal number of the placeholder parameter
2805+ * in this <code>RowSet</code> object's command that is to be set.
2806+ * The first parameter is 1, the second is 2, and so on; must be
2807+ * <code>1</code> or greater
2808+ * @param x a <code>Blob</code> object representing an SQL
2809+ * <code>BLOB</code> value
2810+ * @throws SQLException if an error occurs or the
2811+ * parameter index is out of bounds
2812+ * @see #getParams
2813+ * @see javax.sql.rowset.serial.SerialBlob
2814+ */
2815+ public void setBlob (int parameterIndex, Blob x) throws SQLException {
2816+ checkParamIndex(parameterIndex);
2817+ if(params == null){
2818+ throw new SQLException("Set initParams() before setBlob");
2819+ }
2820+ params.put(Integer.valueOf(parameterIndex - 1), new SerialBlob(x));
2821+ }
2822+
2823+ /**
2824+ * Sets the designated parameter to the given <code>Clob</code> object in
2825+ * the Java programming language. The driver converts this to an SQL
2826+ * <code>CLOB</code> value when it sends it to the database. Internally, the
2827+ * <code>Clob</code> is represented as a <code>SerialClob</code> to ensure
2828+ * serializability.
2829+ * <P>
2830+ * The parameter value set by this method is stored internally and
2831+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2832+ * object's command when the method <code>execute</code> is called.
2833+ * Methods such as <code>execute</code> and <code>populate</code> must be
2834+ * provided in any class that extends this class and implements one or
2835+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2836+ * <p>
2837+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2838+ * as it is undefined in this class.
2839+ * <p>
2840+ * After this method has been called, a call to the
2841+ * method <code>getParams</code>
2842+ * will return an object array of the current command parameters, which will
2843+ * include the <code>Clob</code> object set for placeholder parameter number
2844+ * <code>parameterIndex</code>.
2845+ * Note that because the numbering of elements in an array starts at zero,
2846+ * the array element that corresponds to placeholder parameter number
2847+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2848+ *
2849+ * @param parameterIndex the ordinal number of the placeholder parameter
2850+ * in this <code>RowSet</code> object's command that is to be set.
2851+ * The first parameter is 1, the second is 2, and so on; must be
2852+ * <code>1</code> or greater
2853+ * @param x a <code>Clob</code> object representing an SQL
2854+ * <code>CLOB</code> value; cannot be null
2855+ * @throws SQLException if an error occurs; the parameter index is out of
2856+ * bounds or the <code>Clob</code> is null
2857+ * @see #getParams
2858+ * @see javax.sql.rowset.serial.SerialBlob
2859+ */
2860+ public void setClob (int parameterIndex, Clob x) throws SQLException {
2861+ checkParamIndex(parameterIndex);
2862+ if(params == null){
2863+ throw new SQLException("Set initParams() before setClob");
2864+ }
2865+ params.put(Integer.valueOf(parameterIndex - 1), new SerialClob(x));
2866+ }
2867+
2868+ /**
2869+ * Sets the designated parameter to an <code>Array</code> object in the
2870+ * Java programming language. The driver converts this to an SQL
2871+ * <code>ARRAY</code> value when it sends it to the database. Internally,
2872+ * the <code>Array</code> is represented as a <code>SerialArray</code>
2873+ * to ensure serializability.
2874+ * <P>
2875+ * The parameter value set by this method is stored internally and
2876+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2877+ * object's command when the method <code>execute</code> is called.
2878+ * Methods such as <code>execute</code> and <code>populate</code> must be
2879+ * provided in any class that extends this class and implements one or
2880+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2881+ * <P>
2882+ * Note: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2883+ * as it is undefined in this class.
2884+ * <p>
2885+ * After this method has been called, a call to the
2886+ * method <code>getParams</code>
2887+ * will return an object array of the current command parameters, which will
2888+ * include the <code>Array</code> object set for placeholder parameter number
2889+ * <code>parameterIndex</code>.
2890+ * Note that because the numbering of elements in an array starts at zero,
2891+ * the array element that corresponds to placeholder parameter number
2892+ * <i>parameterIndex</i> is element number <i>parameterIndex</i> -1.
2893+ *
2894+ * @param parameterIndex the ordinal number of the placeholder parameter
2895+ * in this <code>RowSet</code> object's command that is to be set.
2896+ * The first parameter is 1, the second is 2, and so on; must be
2897+ * <code>1</code> or greater
2898+ * @param array an <code>Array</code> object representing an SQL
2899+ * <code>ARRAY</code> value; cannot be null. The <code>Array</code> object
2900+ * passed to this method must return a non-null Object for all
2901+ * <code>getArray()</code> method calls. A null value will cause a
2902+ * <code>SQLException</code> to be thrown.
2903+ * @throws SQLException if an error occurs; the parameter index is out of
2904+ * bounds or the <code>ARRAY</code> is null
2905+ * @see #getParams
2906+ * @see javax.sql.rowset.serial.SerialArray
2907+ */
2908+ public void setArray (int parameterIndex, Array array) throws SQLException {
2909+ checkParamIndex(parameterIndex);
2910+ if (params == null){
2911+ throw new SQLException("Set initParams() before setArray");
2912+ }
2913+ params.put(Integer.valueOf(parameterIndex - 1), new SerialArray(array));
2914+ }
2915+
2916+ /**
2917+ * Sets the designated parameter to the given <code>java.sql.Date</code>
2918+ * object.
2919+ * When the DBMS does not store time zone information, the driver will use
2920+ * the given <code>Calendar</code> object to construct the SQL <code>DATE</code>
2921+ * value to send to the database. With a
2922+ * <code>Calendar</code> object, the driver can calculate the date
2923+ * taking into account a custom time zone. If no <code>Calendar</code>
2924+ * object is specified, the driver uses the time zone of the Virtual Machine
2925+ * that is running the application.
2926+ * <P>
2927+ * The parameter value set by this method is stored internally and
2928+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2929+ * object's command when the method <code>execute</code> is called.
2930+ * Methods such as <code>execute</code> and <code>populate</code> must be
2931+ * provided in any class that extends this class and implements one or
2932+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
2933+ * <P>
2934+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
2935+ * as it is undefined in this class.
2936+ * <P>
2937+ * Calls made to the method <code>getParams</code> after this version of
2938+ * <code>setDate</code>
2939+ * has been called will return an array containing the parameter values that
2940+ * have been set. In that array, the element that represents the values
2941+ * set with this method will itself be an array. The first element of that array
2942+ * is the given <code>java.sql.Date</code> object.
2943+ * The second element is the value set for <i>cal</i>.
2944+ * The parameter number is indicated by an element's position in the array
2945+ * returned by the method <code>getParams</code>,
2946+ * with the first element being the value for the first placeholder parameter, the
2947+ * second element being the value for the second placeholder parameter, and so on.
2948+ * In other words, if the date being set is the value for the second
2949+ * placeholder parameter, the array containing it will be the second element in
2950+ * the array returned by <code>getParams</code>.
2951+ * <P>
2952+ * Note that because the numbering of elements in an array starts at zero,
2953+ * the array element that corresponds to placeholder parameter number
2954+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
2955+ *
2956+ * @param parameterIndex the ordinal number of the placeholder parameter
2957+ * in this <code>RowSet</code> object's command that is to be set.
2958+ * The first parameter is 1, the second is 2, and so on; must be
2959+ * <code>1</code> or greater
2960+ * @param x a <code>java.sql.Date</code> object representing an SQL
2961+ * <code>DATE</code> value
2962+ * @param cal a <code>java.util.Calendar</code> object to use when
2963+ * when constructing the date
2964+ * @throws SQLException if an error occurs or the
2965+ * parameter index is out of bounds
2966+ * @see #getParams
2967+ */
2968+ public void setDate(int parameterIndex, java.sql.Date x, Calendar cal) throws SQLException {
2969+ Object date[];
2970+ checkParamIndex(parameterIndex);
2971+
2972+ date = new Object[2];
2973+ date[0] = x;
2974+ date[1] = cal;
2975+ if(params == null){
2976+ throw new SQLException("Set initParams() before setDate");
2977+ }
2978+ params.put(Integer.valueOf(parameterIndex - 1), date);
2979+ }
2980+
2981+ /**
2982+ * Sets the designated parameter to the given <code>java.sql.Time</code>
2983+ * object. The driver converts this
2984+ * to an SQL <code>TIME</code> value when it sends it to the database.
2985+ * <P>
2986+ * When the DBMS does not store time zone information, the driver will use
2987+ * the given <code>Calendar</code> object to construct the SQL <code>TIME</code>
2988+ * value to send to the database. With a
2989+ * <code>Calendar</code> object, the driver can calculate the date
2990+ * taking into account a custom time zone. If no <code>Calendar</code>
2991+ * object is specified, the driver uses the time zone of the Virtual Machine
2992+ * that is running the application.
2993+ * <P>
2994+ * The parameter value set by this method is stored internally and
2995+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
2996+ * object's command when the method <code>execute</code> is called.
2997+ * Methods such as <code>execute</code> and <code>populate</code> must be
2998+ * provided in any class that extends this class and implements one or
2999+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
3000+ * <P>
3001+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
3002+ * as it is undefined in this class.
3003+ * <P>
3004+ * Calls made to the method <code>getParams</code> after this version of
3005+ * <code>setTime</code>
3006+ * has been called will return an array containing the parameter values that
3007+ * have been set. In that array, the element that represents the values
3008+ * set with this method will itself be an array. The first element of that array
3009+ * is the given <code>java.sql.Time</code> object.
3010+ * The second element is the value set for <i>cal</i>.
3011+ * The parameter number is indicated by an element's position in the array
3012+ * returned by the method <code>getParams</code>,
3013+ * with the first element being the value for the first placeholder parameter, the
3014+ * second element being the value for the second placeholder parameter, and so on.
3015+ * In other words, if the time being set is the value for the second
3016+ * placeholder parameter, the array containing it will be the second element in
3017+ * the array returned by <code>getParams</code>.
3018+ * <P>
3019+ * Note that because the numbering of elements in an array starts at zero,
3020+ * the array element that corresponds to placeholder parameter number
3021+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
3022+ *
3023+ * @param parameterIndex the ordinal number of the placeholder parameter
3024+ * in this <code>RowSet</code> object's command that is to be set.
3025+ * The first parameter is 1, the second is 2, and so on; must be
3026+ * <code>1</code> or greater
3027+ * @param x a <code>java.sql.Time</code> object
3028+ * @param cal the <code>java.util.Calendar</code> object the driver can use to
3029+ * construct the time
3030+ * @throws SQLException if an error occurs or the
3031+ * parameter index is out of bounds
3032+ * @see #getParams
3033+ */
3034+ public void setTime(int parameterIndex, java.sql.Time x, Calendar cal) throws SQLException {
3035+ Object time[];
3036+ checkParamIndex(parameterIndex);
3037+
3038+ time = new Object[2];
3039+ time[0] = x;
3040+ time[1] = cal;
3041+ if(params == null){
3042+ throw new SQLException("Set initParams() before setTime");
3043+ }
3044+ params.put(Integer.valueOf(parameterIndex - 1), time);
3045+ }
3046+
3047+ /**
3048+ * Sets the designated parameter to the given
3049+ * <code>java.sql.Timestamp</code> object. The driver converts this
3050+ * to an SQL <code>TIMESTAMP</code> value when it sends it to the database.
3051+ * <P>
3052+ * When the DBMS does not store time zone information, the driver will use
3053+ * the given <code>Calendar</code> object to construct the SQL <code>TIMESTAMP</code>
3054+ * value to send to the database. With a
3055+ * <code>Calendar</code> object, the driver can calculate the timestamp
3056+ * taking into account a custom time zone. If no <code>Calendar</code>
3057+ * object is specified, the driver uses the time zone of the Virtual Machine
3058+ * that is running the application.
3059+ * <P>
3060+ * The parameter value set by this method is stored internally and
3061+ * will be supplied as the appropriate parameter in this <code>RowSet</code>
3062+ * object's command when the method <code>execute</code> is called.
3063+ * Methods such as <code>execute</code> and <code>populate</code> must be
3064+ * provided in any class that extends this class and implements one or
3065+ * more of the standard JSR-114 <code>RowSet</code> interfaces.
3066+ * <P>
3067+ * NOTE: <code>JdbcRowSet</code> does not require the <code>populate</code> method
3068+ * as it is undefined in this class.
3069+ * <P>
3070+ * Calls made to the method <code>getParams</code> after this version of
3071+ * <code>setTimestamp</code>
3072+ * has been called will return an array containing the parameter values that
3073+ * have been set. In that array, the element that represents the values
3074+ * set with this method will itself be an array. The first element of that array
3075+ * is the given <code>java.sql.Timestamp</code> object.
3076+ * The second element is the value set for <i>cal</i>.
3077+ * The parameter number is indicated by an element's position in the array
3078+ * returned by the method <code>getParams</code>,
3079+ * with the first element being the value for the first placeholder parameter, the
3080+ * second element being the value for the second placeholder parameter, and so on.
3081+ * In other words, if the timestamp being set is the value for the second
3082+ * placeholder parameter, the array containing it will be the second element in
3083+ * the array returned by <code>getParams</code>.
3084+ * <P>
3085+ * Note that because the numbering of elements in an array starts at zero,
3086+ * the array element that corresponds to placeholder parameter number
3087+ * <i>parameterIndex</i> is <i>parameterIndex</i> -1.
3088+ *
3089+ * @param parameterIndex the ordinal number of the placeholder parameter
3090+ * in this <code>RowSet</code> object's command that is to be set.
3091+ * The first parameter is 1, the second is 2, and so on; must be
3092+ * <code>1</code> or greater
3093+ * @param x a <code>java.sql.Timestamp</code> object
3094+ * @param cal the <code>java.util.Calendar</code> object the driver can use to
3095+ * construct the timestamp
3096+ * @throws SQLException if an error occurs or the
3097+ * parameter index is out of bounds
3098+ * @see #getParams
3099+ */
3100+ public void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) throws SQLException {
3101+ Object timestamp[];
3102+ checkParamIndex(parameterIndex);
3103+
3104+ timestamp = new Object[2];
3105+ timestamp[0] = x;
3106+ timestamp[1] = cal;
3107+ if(params == null){
3108+ throw new SQLException("Set initParams() before setTimestamp");
3109+ }
3110+ params.put(Integer.valueOf(parameterIndex - 1), timestamp);
3111+ }
3112+
3113+ /**
3114+ * Clears all of the current parameter values in this <code>RowSet</code>
3115+ * object's internal representation of the parameters to be set in
3116+ * this <code>RowSet</code> object's command when it is executed.
3117+ * <P>
3118+ * In general, parameter values remain in force for repeated use in
3119+ * this <code>RowSet</code> object's command. Setting a parameter value with the
3120+ * setter methods automatically clears the value of the
3121+ * designated parameter and replaces it with the new specified value.
3122+ * <P>
3123+ * This method is called internally by the <code>setCommand</code>
3124+ * method to clear all of the parameters set for the previous command.
3125+ * <P>
3126+ * Furthermore, this method differs from the <code>initParams</code>
3127+ * method in that it maintains the schema of the <code>RowSet</code> object.
3128+ *
3129+ * @throws SQLException if an error occurs clearing the parameters
3130+ */
3131+ public void clearParameters() throws SQLException {
3132+ params.clear();
3133+ }
3134+
3135+ /**
3136+ * Retrieves an array containing the parameter values (both Objects and
3137+ * primitives) that have been set for this
3138+ * <code>RowSet</code> object's command and throws an <code>SQLException</code> object
3139+ * if all parameters have not been set. Before the command is sent to the
3140+ * DBMS to be executed, these parameters will be substituted
3141+ * for placeholder parameters in the <code>PreparedStatement</code> object
3142+ * that is the command for a <code>RowSet</code> implementation extending
3143+ * the <code>BaseRowSet</code> class.
3144+ * <P>
3145+ * Each element in the array that is returned is an <code>Object</code> instance
3146+ * that contains the values of the parameters supplied to a setter method.
3147+ * The order of the elements is determined by the value supplied for
3148+ * <i>parameterIndex</i>. If the setter method takes only the parameter index
3149+ * and the value to be set (possibly null), the array element will contain the value to be set
3150+ * (which will be expressed as an <code>Object</code>). If there are additional
3151+ * parameters, the array element will itself be an array containing the value to be set
3152+ * plus any additional parameter values supplied to the setter method. If the method
3153+ * sets a stream, the array element includes the type of stream being supplied to the
3154+ * method. These additional parameters are for the use of the driver or the DBMS and may or
3155+ * may not be used.
3156+ * <P>
3157+ * NOTE: Stored parameter values of types <code>Array</code>, <code>Blob</code>,
3158+ * <code>Clob</code> and <code>Ref</code> are returned as <code>SerialArray</code>,
3159+ * <code>SerialBlob</code>, <code>SerialClob</code> and <code>SerialRef</code>
3160+ * respectively.
3161+ *
3162+ * @return an array of <code>Object</code> instances that includes the
3163+ * parameter values that may be set in this <code>RowSet</code> object's
3164+ * command; an empty array if no parameters have been set
3165+ * @throws SQLException if an error occurs retrieveing the object array of
3166+ * parameters of this <code>RowSet</code> object or if not all parameters have
3167+ * been set
3168+ */
3169+ public Object[] getParams() throws SQLException {
3170+ if (params == null) {
3171+
3172+ initParams();
3173+ Object [] paramsArray = new Object[params.size()];
3174+ return paramsArray;
3175+
3176+ } else {
3177+ // The parameters may be set in random order
3178+ // but all must be set, check to verify all
3179+ // have been set till the last parameter
3180+ // else throw exception.
3181+
3182+ Object[] paramsArray = new Object[params.size()];
3183+ for (int i = 0; i < params.size(); i++) {
3184+ paramsArray[i] = params.get(Integer.valueOf(i));
3185+ if (paramsArray[i] == null) {
3186+ throw new SQLException("missing parameter: " + (i + 1));
3187+ } //end if
3188+ } //end for
3189+ return paramsArray;
3190+
3191+ } //end if
3192+
3193+ } //end getParams
3194+
3195+
3196+ /**
3197+ * Sets the designated parameter to SQL <code>NULL</code>.
3198+ *
3199+ * <P><B>Note:</B> You must specify the parameter's SQL type.
3200+ *
3201+ * @param parameterName the name of the parameter
3202+ * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
3203+ * @exception SQLException if a database access error occurs or
3204+ * this method is called on a closed <code>CallableStatement</code>
3205+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3206+ * this method
3207+ * @since 1.4
3208+ */
3209+ public void setNull(String parameterName, int sqlType) throws SQLException {
3210+ throw new SQLFeatureNotSupportedException("Feature not supported");
3211+ }
3212+
3213+
3214+ /**
3215+ * Sets the designated parameter to SQL <code>NULL</code>.
3216+ * This version of the method <code>setNull</code> should
3217+ * be used for user-defined types and REF type parameters. Examples
3218+ * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
3219+ * named array types.
3220+ *
3221+ * <P><B>Note:</B> To be portable, applications must give the
3222+ * SQL type code and the fully-qualified SQL type name when specifying
3223+ * a NULL user-defined or REF parameter. In the case of a user-defined type
3224+ * the name is the type name of the parameter itself. For a REF
3225+ * parameter, the name is the type name of the referenced type. If
3226+ * a JDBC driver does not need the type code or type name information,
3227+ * it may ignore it.
3228+ *
3229+ * Although it is intended for user-defined and Ref parameters,
3230+ * this method may be used to set a null parameter of any JDBC type.
3231+ * If the parameter does not have a user-defined or REF type, the given
3232+ * typeName is ignored.
3233+ *
3234+ *
3235+ * @param parameterName the name of the parameter
3236+ * @param sqlType a value from <code>java.sql.Types</code>
3237+ * @param typeName the fully-qualified name of an SQL user-defined type;
3238+ * ignored if the parameter is not a user-defined type or
3239+ * SQL <code>REF</code> value
3240+ * @exception SQLException if a database access error occurs or
3241+ * this method is called on a closed <code>CallableStatement</code>
3242+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3243+ * this method
3244+ * @since 1.4
3245+ */
3246+ public void setNull (String parameterName, int sqlType, String typeName)
3247+ throws SQLException{
3248+ throw new SQLFeatureNotSupportedException("Feature not supported");
3249+ }
3250+
3251+
3252+
3253+ /**
3254+ * Sets the designated parameter to the given Java <code>boolean</code> value.
3255+ * The driver converts this
3256+ * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
3257+ *
3258+ * @param parameterName the name of the parameter
3259+ * @param x the parameter value
3260+ * @exception SQLException if a database access error occurs or
3261+ * this method is called on a closed <code>CallableStatement</code>
3262+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3263+ * this method
3264+ * @see #getParams
3265+ * @since 1.4
3266+ */
3267+ public void setBoolean(String parameterName, boolean x) throws SQLException{
3268+ throw new SQLFeatureNotSupportedException("Feature not supported");
3269+ }
3270+
3271+
3272+
3273+ /**
3274+ * Sets the designated parameter to the given Java <code>byte</code> value.
3275+ * The driver converts this
3276+ * to an SQL <code>TINYINT</code> value when it sends it to the database.
3277+ *
3278+ * @param parameterName the name of the parameter
3279+ * @param x the parameter value
3280+ * @exception SQLException if a database access error occurs or
3281+ * this method is called on a closed <code>CallableStatement</code>
3282+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3283+ * this method
3284+ * @see #getParams
3285+ * @since 1.4
3286+ */
3287+ public void setByte(String parameterName, byte x) throws SQLException{
3288+ throw new SQLFeatureNotSupportedException("Feature not supported");
3289+ }
3290+
3291+
3292+
3293+ /**
3294+ * Sets the designated parameter to the given Java <code>short</code> value.
3295+ * The driver converts this
3296+ * to an SQL <code>SMALLINT</code> value when it sends it to the database.
3297+ *
3298+ * @param parameterName the name of the parameter
3299+ * @param x the parameter value
3300+ * @exception SQLException if a database access error occurs or
3301+ * this method is called on a closed <code>CallableStatement</code>
3302+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3303+ * this method
3304+ * @see #getParams
3305+ * @since 1.4
3306+ */
3307+ public void setShort(String parameterName, short x) throws SQLException{
3308+ throw new SQLFeatureNotSupportedException("Feature not supported");
3309+ }
3310+
3311+
3312+ /**
3313+ * Sets the designated parameter to the given Java <code>int</code> value.
3314+ * The driver converts this
3315+ * to an SQL <code>INTEGER</code> value when it sends it to the database.
3316+ *
3317+ * @param parameterName the name of the parameter
3318+ * @param x the parameter value
3319+ * @exception SQLException if a database access error occurs or
3320+ * this method is called on a closed <code>CallableStatement</code>
3321+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3322+ * this method
3323+ * @see #getParams
3324+ * @since 1.4
3325+ */
3326+ public void setInt(String parameterName, int x) throws SQLException{
3327+ throw new SQLFeatureNotSupportedException("Feature not supported");
3328+ }
3329+
3330+
3331+ /**
3332+ * Sets the designated parameter to the given Java <code>long</code> value.
3333+ * The driver converts this
3334+ * to an SQL <code>BIGINT</code> value when it sends it to the database.
3335+ *
3336+ * @param parameterName the name of the parameter
3337+ * @param x the parameter value
3338+ * @exception SQLException if a database access error occurs or
3339+ * this method is called on a closed <code>CallableStatement</code>
3340+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3341+ * this method
3342+ * @see #getParams
3343+ * @since 1.4
3344+ */
3345+ public void setLong(String parameterName, long x) throws SQLException{
3346+ throw new SQLFeatureNotSupportedException("Feature not supported");
3347+ }
3348+
3349+
3350+ /**
3351+ * Sets the designated parameter to the given Java <code>float</code> value.
3352+ * The driver converts this
3353+ * to an SQL <code>FLOAT</code> value when it sends it to the database.
3354+ *
3355+ * @param parameterName the name of the parameter
3356+ * @param x the parameter value
3357+ * @exception SQLException if a database access error occurs or
3358+ * this method is called on a closed <code>CallableStatement</code>
3359+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3360+ * this method
3361+ * @see #getParams
3362+ * @since 1.4
3363+ */
3364+ public void setFloat(String parameterName, float x) throws SQLException{
3365+ throw new SQLFeatureNotSupportedException("Feature not supported");
3366+ }
3367+
3368+
3369+ /**
3370+ * Sets the designated parameter to the given Java <code>double</code> value.
3371+ * The driver converts this
3372+ * to an SQL <code>DOUBLE</code> value when it sends it to the database.
3373+ *
3374+ * @param parameterName the name of the parameter
3375+ * @param x the parameter value
3376+ * @exception SQLException if a database access error occurs or
3377+ * this method is called on a closed <code>CallableStatement</code>
3378+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3379+ * this method
3380+ * @see #getParams
3381+ * @since 1.4
3382+ */
3383+ public void setDouble(String parameterName, double x) throws SQLException{
3384+ throw new SQLFeatureNotSupportedException("Feature not supported");
3385+ }
3386+
3387+
3388+
3389+ /**
3390+ * Sets the designated parameter to the given
3391+ * <code>java.math.BigDecimal</code> value.
3392+ * The driver converts this to an SQL <code>NUMERIC</code> value when
3393+ * it sends it to the database.
3394+ *
3395+ * @param parameterName the name of the parameter
3396+ * @param x the parameter value
3397+ * @exception SQLException if a database access error occurs or
3398+ * this method is called on a closed <code>CallableStatement</code>
3399+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3400+ * this method
3401+ * @see #getParams
3402+ * @since 1.4
3403+ */
3404+ public void setBigDecimal(String parameterName, BigDecimal x) throws SQLException{
3405+ throw new SQLFeatureNotSupportedException("Feature not supported");
3406+ }
3407+
3408+
3409+
3410+ /**
3411+ * Sets the designated parameter to the given Java <code>String</code> value.
3412+ * The driver converts this
3413+ * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
3414+ * (depending on the argument's
3415+ * size relative to the driver's limits on <code>VARCHAR</code> values)
3416+ * when it sends it to the database.
3417+ *
3418+ * @param parameterName the name of the parameter
3419+ * @param x the parameter value
3420+ * @exception SQLException if a database access error occurs or
3421+ * this method is called on a closed <code>CallableStatement</code>
3422+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3423+ * this method
3424+ * @see #getParams
3425+ * @since 1.4
3426+ */
3427+ public void setString(String parameterName, String x) throws SQLException{
3428+ throw new SQLFeatureNotSupportedException("Feature not supported");
3429+ }
3430+
3431+
3432+
3433+ /**
3434+ * Sets the designated parameter to the given Java array of bytes.
3435+ * The driver converts this to an SQL <code>VARBINARY</code> or
3436+ * <code>LONGVARBINARY</code> (depending on the argument's size relative
3437+ * to the driver's limits on <code>VARBINARY</code> values) when it sends
3438+ * it to the database.
3439+ *
3440+ * @param parameterName the name of the parameter
3441+ * @param x the parameter value
3442+ * @exception SQLException if a database access error occurs or
3443+ * this method is called on a closed <code>CallableStatement</code>
3444+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3445+ * this method
3446+ * @see #getParams
3447+ * @since 1.4
3448+ */
3449+ public void setBytes(String parameterName, byte x[]) throws SQLException{
3450+ throw new SQLFeatureNotSupportedException("Feature not supported");
3451+ }
3452+
3453+
3454+
3455+ /**
3456+ * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
3457+ * The driver
3458+ * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
3459+ * database.
3460+ *
3461+ * @param parameterName the name of the parameter
3462+ * @param x the parameter value
3463+ * @exception SQLException if a database access error occurs or
3464+ * this method is called on a closed <code>CallableStatement</code>
3465+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3466+ * this method
3467+ * @see #getParams
3468+ * @since 1.4
3469+ */
3470+ public void setTimestamp(String parameterName, java.sql.Timestamp x)
3471+ throws SQLException{
3472+ throw new SQLFeatureNotSupportedException("Feature not supported");
3473+ }
3474+
3475+
3476+
3477+ /**
3478+ * Sets the designated parameter to the given input stream, which will have
3479+ * the specified number of bytes.
3480+ * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
3481+ * parameter, it may be more practical to send it via a
3482+ * <code>java.io.InputStream</code>. Data will be read from the stream
3483+ * as needed until end-of-file is reached. The JDBC driver will
3484+ * do any necessary conversion from ASCII to the database char format.
3485+ *
3486+ * <P><B>Note:</B> This stream object can either be a standard
3487+ * Java stream object or your own subclass that implements the
3488+ * standard interface.
3489+ *
3490+ * @param parameterName the name of the parameter
3491+ * @param x the Java input stream that contains the ASCII parameter value
3492+ * @param length the number of bytes in the stream
3493+ * @exception SQLException if a database access error occurs or
3494+ * this method is called on a closed <code>CallableStatement</code>
3495+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3496+ * this method
3497+ * @since 1.4
3498+ */
3499+ public void setAsciiStream(String parameterName, java.io.InputStream x, int length)
3500+ throws SQLException{
3501+ throw new SQLFeatureNotSupportedException("Feature not supported");
3502+ }
3503+
3504+
3505+ /**
3506+ * Sets the designated parameter to the given input stream, which will have
3507+ * the specified number of bytes.
3508+ * When a very large binary value is input to a <code>LONGVARBINARY</code>
3509+ * parameter, it may be more practical to send it via a
3510+ * <code>java.io.InputStream</code> object. The data will be read from the stream
3511+ * as needed until end-of-file is reached.
3512+ *
3513+ * <P><B>Note:</B> This stream object can either be a standard
3514+ * Java stream object or your own subclass that implements the
3515+ * standard interface.
3516+ *
3517+ * @param parameterName the name of the parameter
3518+ * @param x the java input stream which contains the binary parameter value
3519+ * @param length the number of bytes in the stream
3520+ * @exception SQLException if a database access error occurs or
3521+ * this method is called on a closed <code>CallableStatement</code>
3522+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3523+ * this method
3524+ * @since 1.4
3525+ */
3526+ public void setBinaryStream(String parameterName, java.io.InputStream x,
3527+ int length) throws SQLException{
3528+ throw new SQLFeatureNotSupportedException("Feature not supported");
3529+ }
3530+
3531+
3532+ /**
3533+ * Sets the designated parameter to the given <code>Reader</code>
3534+ * object, which is the given number of characters long.
3535+ * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
3536+ * parameter, it may be more practical to send it via a
3537+ * <code>java.io.Reader</code> object. The data will be read from the stream
3538+ * as needed until end-of-file is reached. The JDBC driver will
3539+ * do any necessary conversion from UNICODE to the database char format.
3540+ *
3541+ * <P><B>Note:</B> This stream object can either be a standard
3542+ * Java stream object or your own subclass that implements the
3543+ * standard interface.
3544+ *
3545+ * @param parameterName the name of the parameter
3546+ * @param reader the <code>java.io.Reader</code> object that
3547+ * contains the UNICODE data used as the designated parameter
3548+ * @param length the number of characters in the stream
3549+ * @exception SQLException if a database access error occurs or
3550+ * this method is called on a closed <code>CallableStatement</code>
3551+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3552+ * this method
3553+ * @since 1.4
3554+ */
3555+ public void setCharacterStream(String parameterName,
3556+ java.io.Reader reader,
3557+ int length) throws SQLException{
3558+ throw new SQLFeatureNotSupportedException("Feature not supported");
3559+ }
3560+
3561+
3562+ /**
3563+ * Sets the designated parameter to the given input stream.
3564+ * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
3565+ * parameter, it may be more practical to send it via a
3566+ * <code>java.io.InputStream</code>. Data will be read from the stream
3567+ * as needed until end-of-file is reached. The JDBC driver will
3568+ * do any necessary conversion from ASCII to the database char format.
3569+ *
3570+ * <P><B>Note:</B> This stream object can either be a standard
3571+ * Java stream object or your own subclass that implements the
3572+ * standard interface.
3573+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3574+ * it might be more efficient to use a version of
3575+ * <code>setAsciiStream</code> which takes a length parameter.
3576+ *
3577+ * @param parameterName the name of the parameter
3578+ * @param x the Java input stream that contains the ASCII parameter value
3579+ * @exception SQLException if a database access error occurs or
3580+ * this method is called on a closed <code>CallableStatement</code>
3581+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3582+ * @since 1.6
3583+ */
3584+ public void setAsciiStream(String parameterName, java.io.InputStream x)
3585+ throws SQLException{
3586+ throw new SQLFeatureNotSupportedException("Feature not supported");
3587+ }
3588+
3589+
3590+ /**
3591+ * Sets the designated parameter to the given input stream.
3592+ * When a very large binary value is input to a <code>LONGVARBINARY</code>
3593+ * parameter, it may be more practical to send it via a
3594+ * <code>java.io.InputStream</code> object. The data will be read from the
3595+ * stream as needed until end-of-file is reached.
3596+ *
3597+ * <P><B>Note:</B> This stream object can either be a standard
3598+ * Java stream object or your own subclass that implements the
3599+ * standard interface.
3600+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3601+ * it might be more efficient to use a version of
3602+ * <code>setBinaryStream</code> which takes a length parameter.
3603+ *
3604+ * @param parameterName the name of the parameter
3605+ * @param x the java input stream which contains the binary parameter value
3606+ * @exception SQLException if a database access error occurs or
3607+ * this method is called on a closed <code>CallableStatement</code>
3608+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3609+ * @since 1.6
3610+ */
3611+ public void setBinaryStream(String parameterName, java.io.InputStream x)
3612+ throws SQLException{
3613+ throw new SQLFeatureNotSupportedException("Feature not supported");
3614+ }
3615+
3616+
3617+
3618+ /**
3619+ * Sets the designated parameter to the given <code>Reader</code>
3620+ * object.
3621+ * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
3622+ * parameter, it may be more practical to send it via a
3623+ * <code>java.io.Reader</code> object. The data will be read from the stream
3624+ * as needed until end-of-file is reached. The JDBC driver will
3625+ * do any necessary conversion from UNICODE to the database char format.
3626+ *
3627+ * <P><B>Note:</B> This stream object can either be a standard
3628+ * Java stream object or your own subclass that implements the
3629+ * standard interface.
3630+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3631+ * it might be more efficient to use a version of
3632+ * <code>setCharacterStream</code> which takes a length parameter.
3633+ *
3634+ * @param parameterName the name of the parameter
3635+ * @param reader the <code>java.io.Reader</code> object that contains the
3636+ * Unicode data
3637+ * @exception SQLException if a database access error occurs or
3638+ * this method is called on a closed <code>CallableStatement</code>
3639+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3640+ * @since 1.6
3641+ */
3642+ public void setCharacterStream(String parameterName,
3643+ java.io.Reader reader) throws SQLException{
3644+ throw new SQLFeatureNotSupportedException("Feature not supported");
3645+ }
3646+
3647+
3648+ /**
3649+ * Sets the designated parameter in this <code>RowSet</code> object's command
3650+ * to a <code>Reader</code> object. The
3651+ * <code>Reader</code> reads the data till end-of-file is reached. The
3652+ * driver does the necessary conversion from Java character format to
3653+ * the national character set in the database.
3654+
3655+ * <P><B>Note:</B> This stream object can either be a standard
3656+ * Java stream object or your own subclass that implements the
3657+ * standard interface.
3658+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3659+ * it might be more efficient to use a version of
3660+ * <code>setNCharacterStream</code> which takes a length parameter.
3661+ *
3662+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
3663+ * @param value the parameter value
3664+ * @throws SQLException if the driver does not support national
3665+ * character sets; if the driver can detect that a data conversion
3666+ * error could occur ; if a database access error occurs; or
3667+ * this method is called on a closed <code>PreparedStatement</code>
3668+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3669+ * @since 1.6
3670+ */
3671+ public void setNCharacterStream(int parameterIndex, Reader value) throws SQLException{
3672+ throw new SQLFeatureNotSupportedException("Feature not supported");
3673+ }
3674+
3675+
3676+
3677+ /**
3678+ * Sets the value of the designated parameter with the given object. The second
3679+ * argument must be an object type; for integral values, the
3680+ * <code>java.lang</code> equivalent objects should be used.
3681+ *
3682+ * <p>The given Java object will be converted to the given targetSqlType
3683+ * before being sent to the database.
3684+ *
3685+ * If the object has a custom mapping (is of a class implementing the
3686+ * interface <code>SQLData</code>),
3687+ * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
3688+ * to the SQL data stream.
3689+ * If, on the other hand, the object is of a class implementing
3690+ * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
3691+ * <code>Struct</code>, <code>java.net.URL</code>,
3692+ * or <code>Array</code>, the driver should pass it to the database as a
3693+ * value of the corresponding SQL type.
3694+ * <P>
3695+ * Note that this method may be used to pass datatabase-
3696+ * specific abstract data types.
3697+ *
3698+ * @param parameterName the name of the parameter
3699+ * @param x the object containing the input parameter value
3700+ * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
3701+ * sent to the database. The scale argument may further qualify this type.
3702+ * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
3703+ * this is the number of digits after the decimal point. For all other
3704+ * types, this value will be ignored.
3705+ * @exception SQLException if a database access error occurs or
3706+ * this method is called on a closed <code>CallableStatement</code>
3707+ * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
3708+ * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
3709+ * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
3710+ * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
3711+ * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
3712+ * or <code>STRUCT</code> data type and the JDBC driver does not support
3713+ * this data type
3714+ * @see Types
3715+ * @see #getParams
3716+ * @since 1.4
3717+ */
3718+ public void setObject(String parameterName, Object x, int targetSqlType, int scale)
3719+ throws SQLException{
3720+ throw new SQLFeatureNotSupportedException("Feature not supported");
3721+ }
3722+
3723+
3724+
3725+ /**
3726+ * Sets the value of the designated parameter with the given object.
3727+ * This method is like the method <code>setObject</code>
3728+ * above, except that it assumes a scale of zero.
3729+ *
3730+ * @param parameterName the name of the parameter
3731+ * @param x the object containing the input parameter value
3732+ * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
3733+ * sent to the database
3734+ * @exception SQLException if a database access error occurs or
3735+ * this method is called on a closed <code>CallableStatement</code>
3736+ * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
3737+ * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
3738+ * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
3739+ * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
3740+ * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
3741+ * or <code>STRUCT</code> data type and the JDBC driver does not support
3742+ * this data type
3743+ * @see #getParams
3744+ * @since 1.4
3745+ */
3746+ public void setObject(String parameterName, Object x, int targetSqlType)
3747+ throws SQLException{
3748+ throw new SQLFeatureNotSupportedException("Feature not supported");
3749+ }
3750+
3751+
3752+ /**
3753+ * Sets the value of the designated parameter with the given object.
3754+ * The second parameter must be of type <code>Object</code>; therefore, the
3755+ * <code>java.lang</code> equivalent objects should be used for built-in types.
3756+ *
3757+ * <p>The JDBC specification specifies a standard mapping from
3758+ * Java <code>Object</code> types to SQL types. The given argument
3759+ * will be converted to the corresponding SQL type before being
3760+ * sent to the database.
3761+ *
3762+ * <p>Note that this method may be used to pass datatabase-
3763+ * specific abstract data types, by using a driver-specific Java
3764+ * type.
3765+ *
3766+ * If the object is of a class implementing the interface <code>SQLData</code>,
3767+ * the JDBC driver should call the method <code>SQLData.writeSQL</code>
3768+ * to write it to the SQL data stream.
3769+ * If, on the other hand, the object is of a class implementing
3770+ * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
3771+ * <code>Struct</code>, <code>java.net.URL</code>,
3772+ * or <code>Array</code>, the driver should pass it to the database as a
3773+ * value of the corresponding SQL type.
3774+ * <P>
3775+ * This method throws an exception if there is an ambiguity, for example, if the
3776+ * object is of a class implementing more than one of the interfaces named above.
3777+ *
3778+ * @param parameterName the name of the parameter
3779+ * @param x the object containing the input parameter value
3780+ * @exception SQLException if a database access error occurs,
3781+ * this method is called on a closed <code>CallableStatement</code> or if the given
3782+ * <code>Object</code> parameter is ambiguous
3783+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3784+ * this method
3785+ * @see #getParams
3786+ * @since 1.4
3787+ */
3788+ public void setObject(String parameterName, Object x) throws SQLException{
3789+ throw new SQLFeatureNotSupportedException("Feature not supported");
3790+ }
3791+
3792+
3793+
3794+ /**
3795+ * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number
3796+ * of characters specified by length otherwise a <code>SQLException</code> will be
3797+ * generated when the <code>PreparedStatement</code> is executed.
3798+ * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
3799+ * method because it informs the driver that the parameter value should be
3800+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
3801+ * the driver may have to do extra work to determine whether the parameter
3802+ * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
3803+ * @param parameterIndex index of the first parameter is 1,
3804+ * the second is 2, ...
3805+ * @param inputStream An object that contains the data to set the parameter
3806+ * value to.
3807+ * @param length the number of bytes in the parameter data.
3808+ * @throws SQLException if a database access error occurs,
3809+ * this method is called on a closed <code>PreparedStatement</code>,
3810+ * if parameterIndex does not correspond
3811+ * to a parameter marker in the SQL statement, if the length specified
3812+ * is less than zero or if the number of bytes in the inputstream does not match
3813+ * the specfied length.
3814+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3815+ *
3816+ * @since 1.6
3817+ */
3818+ public void setBlob(int parameterIndex, InputStream inputStream, long length)
3819+ throws SQLException{
3820+ throw new SQLFeatureNotSupportedException("Feature not supported");
3821+ }
3822+
3823+
3824+ /**
3825+ * Sets the designated parameter to a <code>InputStream</code> object.
3826+ * This method differs from the <code>setBinaryStream (int, InputStream)</code>
3827+ * method because it informs the driver that the parameter value should be
3828+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
3829+ * the driver may have to do extra work to determine whether the parameter
3830+ * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
3831+ *
3832+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3833+ * it might be more efficient to use a version of
3834+ * <code>setBlob</code> which takes a length parameter.
3835+ *
3836+ * @param parameterIndex index of the first parameter is 1,
3837+ * the second is 2, ...
3838+ * @param inputStream An object that contains the data to set the parameter
3839+ * value to.
3840+ * @throws SQLException if a database access error occurs,
3841+ * this method is called on a closed <code>PreparedStatement</code> or
3842+ * if parameterIndex does not correspond
3843+ * to a parameter marker in the SQL statement,
3844+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3845+ *
3846+ * @since 1.6
3847+ */
3848+ public void setBlob(int parameterIndex, InputStream inputStream)
3849+ throws SQLException{
3850+ throw new SQLFeatureNotSupportedException("Feature not supported");
3851+ }
3852+
3853+
3854+ /**
3855+ * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number
3856+ * of characters specified by length, otherwise a <code>SQLException</code> will be
3857+ * generated when the <code>CallableStatement</code> is executed.
3858+ * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
3859+ * method because it informs the driver that the parameter value should be
3860+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
3861+ * the driver may have to do extra work to determine whether the parameter
3862+ * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
3863+ *
3864+ * @param parameterName the name of the parameter to be set
3865+ * the second is 2, ...
3866+ *
3867+ * @param inputStream An object that contains the data to set the parameter
3868+ * value to.
3869+ * @param length the number of bytes in the parameter data.
3870+ * @throws SQLException if parameterIndex does not correspond
3871+ * to a parameter marker in the SQL statement, or if the length specified
3872+ * is less than zero; if the number of bytes in the inputstream does not match
3873+ * the specfied length; if a database access error occurs or
3874+ * this method is called on a closed <code>CallableStatement</code>
3875+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3876+ * this method
3877+ *
3878+ * @since 1.6
3879+ */
3880+ public void setBlob(String parameterName, InputStream inputStream, long length)
3881+ throws SQLException{
3882+ throw new SQLFeatureNotSupportedException("Feature not supported");
3883+ }
3884+
3885+
3886+ /**
3887+ * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
3888+ * The driver converts this to an SQL <code>BLOB</code> value when it
3889+ * sends it to the database.
3890+ *
3891+ * @param parameterName the name of the parameter
3892+ * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
3893+ * @exception SQLException if a database access error occurs or
3894+ * this method is called on a closed <code>CallableStatement</code>
3895+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3896+ * this method
3897+ * @since 1.6
3898+ */
3899+ public void setBlob (String parameterName, Blob x) throws SQLException{
3900+ throw new SQLFeatureNotSupportedException("Feature not supported");
3901+ }
3902+
3903+
3904+ /**
3905+ * Sets the designated parameter to a <code>InputStream</code> object.
3906+ * This method differs from the <code>setBinaryStream (int, InputStream)</code>
3907+ * method because it informs the driver that the parameter value should be
3908+ * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
3909+ * the driver may have to do extra work to determine whether the parameter
3910+ * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
3911+ *
3912+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3913+ * it might be more efficient to use a version of
3914+ * <code>setBlob</code> which takes a length parameter.
3915+ *
3916+ * @param parameterName the name of the parameter
3917+ * @param inputStream An object that contains the data to set the parameter
3918+ * value to.
3919+ * @throws SQLException if a database access error occurs or
3920+ * this method is called on a closed <code>CallableStatement</code>
3921+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3922+ *
3923+ * @since 1.6
3924+ */
3925+ public void setBlob(String parameterName, InputStream inputStream)
3926+ throws SQLException{
3927+ throw new SQLFeatureNotSupportedException("Feature not supported");
3928+ }
3929+
3930+
3931+ /**
3932+ * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
3933+ * of characters specified by length otherwise a <code>SQLException</code> will be
3934+ * generated when the <code>PreparedStatement</code> is executed.
3935+ *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
3936+ * because it informs the driver that the parameter value should be sent to
3937+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
3938+ * driver may have to do extra work to determine whether the parameter
3939+ * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
3940+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
3941+ * @param reader An object that contains the data to set the parameter value to.
3942+ * @param length the number of characters in the parameter data.
3943+ * @throws SQLException if a database access error occurs, this method is called on
3944+ * a closed <code>PreparedStatement</code>, if parameterIndex does not correspond to a parameter
3945+ * marker in the SQL statement, or if the length specified is less than zero.
3946+ *
3947+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3948+ * @since 1.6
3949+ */
3950+ public void setClob(int parameterIndex, Reader reader, long length)
3951+ throws SQLException{
3952+ throw new SQLFeatureNotSupportedException("Feature not supported");
3953+ }
3954+
3955+
3956+/**
3957+ * Sets the designated parameter to a <code>Reader</code> object.
3958+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
3959+ * because it informs the driver that the parameter value should be sent to
3960+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
3961+ * driver may have to do extra work to determine whether the parameter
3962+ * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
3963+ *
3964+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3965+ * it might be more efficient to use a version of
3966+ * <code>setClob</code> which takes a length parameter.
3967+ *
3968+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
3969+ * @param reader An object that contains the data to set the parameter value to.
3970+ * @throws SQLException if a database access error occurs, this method is called on
3971+ * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter
3972+ * marker in the SQL statement
3973+ *
3974+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
3975+ * @since 1.6
3976+ */
3977+ public void setClob(int parameterIndex, Reader reader)
3978+ throws SQLException{
3979+ throw new SQLFeatureNotSupportedException("Feature not supported");
3980+ }
3981+
3982+
3983+ /**
3984+ * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
3985+ * of characters specified by length otherwise a <code>SQLException</code> will be
3986+ * generated when the <code>CallableStatement</code> is executed.
3987+ * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
3988+ * because it informs the driver that the parameter value should be sent to
3989+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
3990+ * driver may have to do extra work to determine whether the parameter
3991+ * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
3992+ * @param parameterName the name of the parameter to be set
3993+ * @param reader An object that contains the data to set the parameter value to.
3994+ * @param length the number of characters in the parameter data.
3995+ * @throws SQLException if parameterIndex does not correspond to a parameter
3996+ * marker in the SQL statement; if the length specified is less than zero;
3997+ * a database access error occurs or
3998+ * this method is called on a closed <code>CallableStatement</code>
3999+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4000+ * this method
4001+ *
4002+ * @since 1.6
4003+ */
4004+ public void setClob(String parameterName, Reader reader, long length)
4005+ throws SQLException{
4006+ throw new SQLFeatureNotSupportedException("Feature not supported");
4007+ }
4008+
4009+
4010+ /**
4011+ * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
4012+ * The driver converts this to an SQL <code>CLOB</code> value when it
4013+ * sends it to the database.
4014+ *
4015+ * @param parameterName the name of the parameter
4016+ * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
4017+ * @exception SQLException if a database access error occurs or
4018+ * this method is called on a closed <code>CallableStatement</code>
4019+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4020+ * this method
4021+ * @since 1.6
4022+ */
4023+ public void setClob (String parameterName, Clob x) throws SQLException{
4024+ throw new SQLFeatureNotSupportedException("Feature not supported");
4025+ }
4026+
4027+
4028+ /**
4029+ * Sets the designated parameter to a <code>Reader</code> object.
4030+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
4031+ * because it informs the driver that the parameter value should be sent to
4032+ * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
4033+ * driver may have to do extra work to determine whether the parameter
4034+ * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
4035+ *
4036+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
4037+ * it might be more efficient to use a version of
4038+ * <code>setClob</code> which takes a length parameter.
4039+ *
4040+ * @param parameterName the name of the parameter
4041+ * @param reader An object that contains the data to set the parameter value to.
4042+ * @throws SQLException if a database access error occurs or this method is called on
4043+ * a closed <code>CallableStatement</code>
4044+ *
4045+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
4046+ * @since 1.6
4047+ */
4048+ public void setClob(String parameterName, Reader reader)
4049+ throws SQLException{
4050+ throw new SQLFeatureNotSupportedException("Feature not supported");
4051+ }
4052+
4053+
4054+ /**
4055+ * Sets the designated parameter to the given <code>java.sql.Date</code> value
4056+ * using the default time zone of the virtual machine that is running
4057+ * the application.
4058+ * The driver converts this
4059+ * to an SQL <code>DATE</code> value when it sends it to the database.
4060+ *
4061+ * @param parameterName the name of the parameter
4062+ * @param x the parameter value
4063+ * @exception SQLException if a database access error occurs or
4064+ * this method is called on a closed <code>CallableStatement</code>
4065+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4066+ * this method
4067+ * @see #getParams
4068+ * @since 1.4
4069+ */
4070+ public void setDate(String parameterName, java.sql.Date x)
4071+ throws SQLException{
4072+ throw new SQLFeatureNotSupportedException("Feature not supported");
4073+ }
4074+
4075+
4076+ /**
4077+ * Sets the designated parameter to the given <code>java.sql.Date</code> value,
4078+ * using the given <code>Calendar</code> object. The driver uses
4079+ * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
4080+ * which the driver then sends to the database. With a
4081+ * a <code>Calendar</code> object, the driver can calculate the date
4082+ * taking into account a custom timezone. If no
4083+ * <code>Calendar</code> object is specified, the driver uses the default
4084+ * timezone, which is that of the virtual machine running the application.
4085+ *
4086+ * @param parameterName the name of the parameter
4087+ * @param x the parameter value
4088+ * @param cal the <code>Calendar</code> object the driver will use
4089+ * to construct the date
4090+ * @exception SQLException if a database access error occurs or
4091+ * this method is called on a closed <code>CallableStatement</code>
4092+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4093+ * this method
4094+ * @see #getParams
4095+ * @since 1.4
4096+ */
4097+ public void setDate(String parameterName, java.sql.Date x, Calendar cal)
4098+ throws SQLException{
4099+ throw new SQLFeatureNotSupportedException("Feature not supported");
4100+ }
4101+
4102+
4103+ /**
4104+ * Sets the designated parameter to the given <code>java.sql.Time</code> value.
4105+ * The driver converts this
4106+ * to an SQL <code>TIME</code> value when it sends it to the database.
4107+ *
4108+ * @param parameterName the name of the parameter
4109+ * @param x the parameter value
4110+ * @exception SQLException if a database access error occurs or
4111+ * this method is called on a closed <code>CallableStatement</code>
4112+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4113+ * this method
4114+ * @see #getParams
4115+ * @since 1.4
4116+ */
4117+ public void setTime(String parameterName, java.sql.Time x)
4118+ throws SQLException{
4119+ throw new SQLFeatureNotSupportedException("Feature not supported");
4120+ }
4121+
4122+
4123+ /**
4124+ * Sets the designated parameter to the given <code>java.sql.Time</code> value,
4125+ * using the given <code>Calendar</code> object. The driver uses
4126+ * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
4127+ * which the driver then sends to the database. With a
4128+ * a <code>Calendar</code> object, the driver can calculate the time
4129+ * taking into account a custom timezone. If no
4130+ * <code>Calendar</code> object is specified, the driver uses the default
4131+ * timezone, which is that of the virtual machine running the application.
4132+ *
4133+ * @param parameterName the name of the parameter
4134+ * @param x the parameter value
4135+ * @param cal the <code>Calendar</code> object the driver will use
4136+ * to construct the time
4137+ * @exception SQLException if a database access error occurs or
4138+ * this method is called on a closed <code>CallableStatement</code>
4139+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4140+ * this method
4141+ * @see #getParams
4142+ * @since 1.4
4143+ */
4144+ public void setTime(String parameterName, java.sql.Time x, Calendar cal)
4145+ throws SQLException{
4146+ throw new SQLFeatureNotSupportedException("Feature not supported");
4147+ }
4148+
4149+
4150+ /**
4151+ * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
4152+ * using the given <code>Calendar</code> object. The driver uses
4153+ * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
4154+ * which the driver then sends to the database. With a
4155+ * a <code>Calendar</code> object, the driver can calculate the timestamp
4156+ * taking into account a custom timezone. If no
4157+ * <code>Calendar</code> object is specified, the driver uses the default
4158+ * timezone, which is that of the virtual machine running the application.
4159+ *
4160+ * @param parameterName the name of the parameter
4161+ * @param x the parameter value
4162+ * @param cal the <code>Calendar</code> object the driver will use
4163+ * to construct the timestamp
4164+ * @exception SQLException if a database access error occurs or
4165+ * this method is called on a closed <code>CallableStatement</code>
4166+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4167+ * this method
4168+ * @see #getParams
4169+ * @since 1.4
4170+ */
4171+ public void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
4172+ throws SQLException{
4173+ throw new SQLFeatureNotSupportedException("Feature not supported");
4174+ }
4175+
4176+
4177+ /**
4178+ * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
4179+ * SQL <code>XML</code> value when it sends it to the database.
4180+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
4181+ * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value
4182+ * @throws SQLException if a database access error occurs, this method
4183+ * is called on a closed result set,
4184+ * the <code>java.xml.transform.Result</code>,
4185+ * <code>Writer</code> or <code>OutputStream</code> has not been closed
4186+ * for the <code>SQLXML</code> object or
4187+ * if there is an error processing the XML value. The <code>getCause</code> method
4188+ * of the exception may provide a more detailed exception, for example, if the
4189+ * stream does not contain valid XML.
4190+ * @since 1.6
4191+ */
4192+ public void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException{
4193+ throw new SQLFeatureNotSupportedException("Feature not supported");
4194+ }
4195+
4196+
4197+ /**
4198+ * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
4199+ * <code>SQL XML</code> value when it sends it to the database.
4200+ * @param parameterName the name of the parameter
4201+ * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
4202+ * @throws SQLException if a database access error occurs, this method
4203+ * is called on a closed result set,
4204+ * the <code>java.xml.transform.Result</code>,
4205+ * <code>Writer</code> or <code>OutputStream</code> has not been closed
4206+ * for the <code>SQLXML</code> object or
4207+ * if there is an error processing the XML value. The <code>getCause</code> method
4208+ * of the exception may provide a more detailed exception, for example, if the
4209+ * stream does not contain valid XML.
4210+ * @since 1.6
4211+ */
4212+ public void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException{
4213+ throw new SQLFeatureNotSupportedException("Feature not supported");
4214+ }
4215+
4216+
4217+ /**
4218+ * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
4219+ * driver converts this to a SQL <code>ROWID</code> value when it sends it
4220+ * to the database
4221+ *
4222+ * @param parameterIndex the first parameter is 1, the second is 2, ...
4223+ * @param x the parameter value
4224+ * @throws SQLException if a database access error occurs
4225+ *
4226+ * @since 1.6
4227+ */
4228+ public void setRowId(int parameterIndex, RowId x) throws SQLException{
4229+ throw new SQLFeatureNotSupportedException("Feature not supported");
4230+ }
4231+
4232+
4233+ /**
4234+ * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
4235+ * driver converts this to a SQL <code>ROWID</code> when it sends it to the
4236+ * database.
4237+ *
4238+ * @param parameterName the name of the parameter
4239+ * @param x the parameter value
4240+ * @throws SQLException if a database access error occurs
4241+ * @since 1.6
4242+ */
4243+ public void setRowId(String parameterName, RowId x) throws SQLException{
4244+ throw new SQLFeatureNotSupportedException("Feature not supported");
4245+ }
4246+
4247+ /**
4248+ * Sets the designated paramter to the given <code>String</code> object.
4249+ * The driver converts this to a SQL <code>NCHAR</code> or
4250+ * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
4251+ * (depending on the argument's
4252+ * size relative to the driver's limits on <code>NVARCHAR</code> values)
4253+ * when it sends it to the database.
4254+ *
4255+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
4256+ * @param value the parameter value
4257+ * @throws SQLException if the driver does not support national
4258+ * character sets; if the driver can detect that a data conversion
4259+ * error could occur ; or if a database access error occurs
4260+ * @since 1.6
4261+ */
4262+ public void setNString(int parameterIndex, String value) throws SQLException{
4263+ throw new SQLFeatureNotSupportedException("Feature not supported");
4264+ }
4265+
4266+
4267+ /**
4268+ * Sets the designated paramter to the given <code>String</code> object.
4269+ * The driver converts this to a SQL <code>NCHAR</code> or
4270+ * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
4271+ * @param parameterName the name of the column to be set
4272+ * @param value the parameter value
4273+ * @throws SQLException if the driver does not support national
4274+ * character sets; if the driver can detect that a data conversion
4275+ * error could occur; or if a database access error occurs
4276+ * @since 1.6
4277+ */
4278+ public void setNString(String parameterName, String value)
4279+ throws SQLException{
4280+ throw new SQLFeatureNotSupportedException("Feature not supported");
4281+ }
4282+
4283+
4284+ /**
4285+ * Sets the designated parameter to a <code>Reader</code> object. The
4286+ * <code>Reader</code> reads the data till end-of-file is reached. The
4287+ * driver does the necessary conversion from Java character format to
4288+ * the national character set in the database.
4289+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
4290+ * @param value the parameter value
4291+ * @param length the number of characters in the parameter data.
4292+ * @throws SQLException if the driver does not support national
4293+ * character sets; if the driver can detect that a data conversion
4294+ * error could occur ; or if a database access error occurs
4295+ * @since 1.6
4296+ */
4297+ public void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException{
4298+ throw new SQLFeatureNotSupportedException("Feature not supported");
4299+ }
4300+
4301+
4302+ /**
4303+ * Sets the designated parameter to a <code>Reader</code> object. The
4304+ * <code>Reader</code> reads the data till end-of-file is reached. The
4305+ * driver does the necessary conversion from Java character format to
4306+ * the national character set in the database.
4307+ * @param parameterName the name of the column to be set
4308+ * @param value the parameter value
4309+ * @param length the number of characters in the parameter data.
4310+ * @throws SQLException if the driver does not support national
4311+ * character sets; if the driver can detect that a data conversion
4312+ * error could occur; or if a database access error occurs
4313+ * @since 1.6
4314+ */
4315+ public void setNCharacterStream(String parameterName, Reader value, long length)
4316+ throws SQLException{
4317+ throw new SQLFeatureNotSupportedException("Feature not supported");
4318+ }
4319+
4320+
4321+ /**
4322+ * Sets the designated parameter to a <code>Reader</code> object. The
4323+ * <code>Reader</code> reads the data till end-of-file is reached. The
4324+ * driver does the necessary conversion from Java character format to
4325+ * the national character set in the database.
4326+
4327+ * <P><B>Note:</B> This stream object can either be a standard
4328+ * Java stream object or your own subclass that implements the
4329+ * standard interface.
4330+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
4331+ * it might be more efficient to use a version of
4332+ * <code>setNCharacterStream</code> which takes a length parameter.
4333+ *
4334+ * @param parameterName the name of the parameter
4335+ * @param value the parameter value
4336+ * @throws SQLException if the driver does not support national
4337+ * character sets; if the driver can detect that a data conversion
4338+ * error could occur ; if a database access error occurs; or
4339+ * this method is called on a closed <code>CallableStatement</code>
4340+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
4341+ * @since 1.6
4342+ */
4343+ public void setNCharacterStream(String parameterName, Reader value) throws SQLException{
4344+ throw new SQLFeatureNotSupportedException("Feature not supported");
4345+ }
4346+
4347+
4348+ /**
4349+ * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
4350+ * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
4351+ * object maps to a SQL <code>NCLOB</code>.
4352+ * @param parameterName the name of the column to be set
4353+ * @param value the parameter value
4354+ * @throws SQLException if the driver does not support national
4355+ * character sets; if the driver can detect that a data conversion
4356+ * error could occur; or if a database access error occurs
4357+ * @since 1.6
4358+ */
4359+ public void setNClob(String parameterName, NClob value) throws SQLException{
4360+ throw new SQLFeatureNotSupportedException("Feature not supported");
4361+ }
4362+
4363+
4364+ /**
4365+ * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain * the number
4366+ * of characters specified by length otherwise a <code>SQLException</code> will be
4367+ * generated when the <code>CallableStatement</code> is executed.
4368+ * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
4369+ * because it informs the driver that the parameter value should be sent to
4370+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
4371+ * driver may have to do extra work to determine whether the parameter
4372+ * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
4373+ *
4374+ * @param parameterName the name of the parameter to be set
4375+ * @param reader An object that contains the data to set the parameter value to.
4376+ * @param length the number of characters in the parameter data.
4377+ * @throws SQLException if parameterIndex does not correspond to a parameter
4378+ * marker in the SQL statement; if the length specified is less than zero;
4379+ * if the driver does not support national
4380+ * character sets; if the driver can detect that a data conversion
4381+ * error could occur; if a database access error occurs or
4382+ * this method is called on a closed <code>CallableStatement</code>
4383+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4384+ * this method
4385+ * @since 1.6
4386+ */
4387+ public void setNClob(String parameterName, Reader reader, long length)
4388+ throws SQLException{
4389+ throw new SQLFeatureNotSupportedException("Feature not supported");
4390+ }
4391+
4392+
4393+ /**
4394+ * Sets the designated parameter to a <code>Reader</code> object.
4395+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
4396+ * because it informs the driver that the parameter value should be sent to
4397+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
4398+ * driver may have to do extra work to determine whether the parameter
4399+ * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
4400+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
4401+ * it might be more efficient to use a version of
4402+ * <code>setNClob</code> which takes a length parameter.
4403+ *
4404+ * @param parameterName the name of the parameter
4405+ * @param reader An object that contains the data to set the parameter value to.
4406+ * @throws SQLException if the driver does not support national character sets;
4407+ * if the driver can detect that a data conversion
4408+ * error could occur; if a database access error occurs or
4409+ * this method is called on a closed <code>CallableStatement</code>
4410+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
4411+ *
4412+ * @since 1.6
4413+ */
4414+ public void setNClob(String parameterName, Reader reader)
4415+ throws SQLException{
4416+ throw new SQLFeatureNotSupportedException("Feature not supported");
4417+ }
4418+
4419+
4420+ /**
4421+ * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
4422+ * of characters specified by length otherwise a <code>SQLException</code> will be
4423+ * generated when the <code>PreparedStatement</code> is executed.
4424+ * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
4425+ * because it informs the driver that the parameter value should be sent to
4426+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
4427+ * driver may have to do extra work to determine whether the parameter
4428+ * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
4429+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
4430+ * @param reader An object that contains the data to set the parameter value to.
4431+ * @param length the number of characters in the parameter data.
4432+ * @throws SQLException if parameterIndex does not correspond to a parameter
4433+ * marker in the SQL statement; if the length specified is less than zero;
4434+ * if the driver does not support national character sets;
4435+ * if the driver can detect that a data conversion
4436+ * error could occur; if a database access error occurs or
4437+ * this method is called on a closed <code>PreparedStatement</code>
4438+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
4439+ *
4440+ * @since 1.6
4441+ */
4442+ public void setNClob(int parameterIndex, Reader reader, long length)
4443+ throws SQLException{
4444+ throw new SQLFeatureNotSupportedException("Feature not supported");
4445+ }
4446+
4447+
4448+ /**
4449+ * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this oa
4450+ * SQL <code>NCLOB</code> value when it sends it to the database.
4451+ * @param parameterIndex of the first parameter is 1, the second is 2, ...
4452+ * @param value the parameter value
4453+ * @throws SQLException if the driver does not support national
4454+ * character sets; if the driver can detect that a data conversion
4455+ * error could occur ; or if a database access error occurs
4456+ * @since 1.6
4457+ */
4458+ public void setNClob(int parameterIndex, NClob value) throws SQLException{
4459+ throw new SQLFeatureNotSupportedException("Feature not supported");
4460+ }
4461+
4462+
4463+ /**
4464+ * Sets the designated parameter to a <code>Reader</code> object.
4465+ * This method differs from the <code>setCharacterStream (int, Reader)</code> method
4466+ * because it informs the driver that the parameter value should be sent to
4467+ * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
4468+ * driver may have to do extra work to determine whether the parameter
4469+ * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
4470+ * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
4471+ * it might be more efficient to use a version of
4472+ * <code>setNClob</code> which takes a length parameter.
4473+ *
4474+ * @param parameterIndex index of the first parameter is 1, the second is 2, ...
4475+ * @param reader An object that contains the data to set the parameter value to.
4476+ * @throws SQLException if parameterIndex does not correspond to a parameter
4477+ * marker in the SQL statement;
4478+ * if the driver does not support national character sets;
4479+ * if the driver can detect that a data conversion
4480+ * error could occur; if a database access error occurs or
4481+ * this method is called on a closed <code>PreparedStatement</code>
4482+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
4483+ *
4484+ * @since 1.6
4485+ */
4486+ public void setNClob(int parameterIndex, Reader reader)
4487+ throws SQLException{
4488+ throw new SQLFeatureNotSupportedException("Feature not supported");
4489+ }
4490+
4491+
4492+ /**
4493+ * Sets the designated parameter to the given <code>java.net.URL</code> value.
4494+ * The driver converts this to an SQL <code>DATALINK</code> value
4495+ * when it sends it to the database.
4496+ *
4497+ * @param parameterIndex the first parameter is 1, the second is 2, ...
4498+ * @param x the <code>java.net.URL</code> object to be set
4499+ * @exception SQLException if a database access error occurs or
4500+ * this method is called on a closed <code>PreparedStatement</code>
4501+ * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
4502+ * @since 1.4
4503+ */
4504+ public void setURL(int parameterIndex, java.net.URL x) throws SQLException{
4505+ throw new SQLFeatureNotSupportedException("Feature not supported");
4506+ }
4507+
4508+
4509+
4510+ static final long serialVersionUID = 4886719666485113312L;
4511+
4512+} //end class
java/pkg/javax/sql/rowset/CachedRowSet.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/CachedRowSet.java+1625−0
@@ -0,0 +1,1625 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import javax.naming.*;
31+import java.io.*;
32+import java.math.*;
33+import java.util.*;
34+
35+import javax.sql.rowset.spi.*;
36+
37+/**
38+ * The interface that all standard implementations of
39+ * <code>CachedRowSet</code> must implement.
40+ * <P>
41+ * The reference implementation of the <code>CachedRowSet</code> interface provided
42+ * by Oracle Corporation is a standard implementation. Developers may use this implementation
43+ * just as it is, they may extend it, or they may choose to write their own implementations
44+ * of this interface.
45+ * <P>
46+ * A <code>CachedRowSet</code> object is a container for rows of data
47+ * that caches its rows in memory, which makes it possible to operate without always being
48+ * connected to its data source. Further, it is a
49+ * JavaBeans<sup><font size=-2>TM</font></sup> component and is scrollable,
50+ * updatable, and serializable. A <code>CachedRowSet</code> object typically
51+ * contains rows from a result set, but it can also contain rows from any file
52+ * with a tabular format, such as a spread sheet. The reference implementation
53+ * supports getting data only from a <code>ResultSet</code> object, but
54+ * developers can extend the <code>SyncProvider</code> implementations to provide
55+ * access to other tabular data sources.
56+ * <P>
57+ * An application can modify the data in a <code>CachedRowSet</code> object, and
58+ * those modifications can then be propagated back to the source of the data.
59+ * <P>
60+ * A <code>CachedRowSet</code> object is a <i>disconnected</i> rowset, which means
61+ * that it makes use of a connection to its data source only briefly. It connects to its
62+ * data source while it is reading data to populate itself with rows and again
63+ * while it is propagating changes back to its underlying data source. The rest
64+ * of the time, a <code>CachedRowSet</code> object is disconnected, including
65+ * while its data is being modified. Being disconnected makes a <code>RowSet</code>
66+ * object much leaner and therefore much easier to pass to another component. For
67+ * example, a disconnected <code>RowSet</code> object can be serialized and passed
68+ * over the wire to a thin client such as a personal digital assistant (PDA).
69+ * <P>
70+ *
71+ * <h3>1.0 Creating a <code>CachedRowSet</code> Object</h3>
72+ * The following line of code uses the default constructor for
73+ * <code>CachedRowSet</code>
74+ * supplied in the reference implementation (RI) to create a default
75+ * <code>CachedRowSet</code> object.
76+ * <PRE>
77+ * CachedRowSetImpl crs = new CachedRowSetImpl();
78+ * </PRE>
79+ * This new <code>CachedRowSet</code> object will have its properties set to the
80+ * default properties of a <code>BaseRowSet</code> object, and, in addition, it will
81+ * have an <code>RIOptimisticProvider</code> object as its synchronization provider.
82+ * <code>RIOptimisticProvider</code>, one of two <code>SyncProvider</code>
83+ * implementations included in the RI, is the default provider that the
84+ * <code>SyncFactory</code> singleton will supply when no synchronization
85+ * provider is specified.
86+ * <P>
87+ * A <code>SyncProvider</code> object provides a <code>CachedRowSet</code> object
88+ * with a reader (a <code>RowSetReader</code> object) for reading data from a
89+ * data source to populate itself with data. A reader can be implemented to read
90+ * data from a <code>ResultSet</code> object or from a file with a tabular format.
91+ * A <code>SyncProvider</code> object also provides
92+ * a writer (a <code>RowSetWriter</code> object) for synchronizing any
93+ * modifications to the <code>CachedRowSet</code> object's data made while it was
94+ * disconnected with the data in the underlying data source.
95+ * <P>
96+ * A writer can be implemented to exercise various degrees of care in checking
97+ * for conflicts and in avoiding them.
98+ * (A conflict occurs when a value in the data source has been changed after
99+ * the rowset populated itself with that value.)
100+ * The <code>RIOptimisticProvider</code> implementation assumes there will be
101+ * few or no conflicts and therefore sets no locks. It updates the data source
102+ * with values from the <code>CachedRowSet</code> object only if there are no
103+ * conflicts.
104+ * Other writers can be implemented so that they always write modified data to
105+ * the data source, which can be accomplished either by not checking for conflicts
106+ * or, on the other end of the spectrum, by setting locks sufficient to prevent data
107+ * in the data source from being changed. Still other writer implementations can be
108+ * somewhere in between.
109+ * <P>
110+ * A <code>CachedRowSet</code> object may use any
111+ * <code>SyncProvider</code> implementation that has been registered
112+ * with the <code>SyncFactory</code> singleton. An application
113+ * can find out which <code>SyncProvider</code> implementations have been
114+ * registered by calling the following line of code.
115+ * <PRE>
116+ * java.util.Enumeration providers = SyncFactory.getRegisteredProviders();
117+ * </PRE>
118+ * <P>
119+ * There are two ways for a <code>CachedRowSet</code> object to specify which
120+ * <code>SyncProvider</code> object it will use.
121+ * <UL)
122+ * <LI>Supplying the name of the implementation to the constructor<BR>
123+ * The following line of code creates the <code>CachedRowSet</code>
124+ * object <i>crs2</i> that is initialized with default values except that its
125+ * <code>SyncProvider</code> object is the one specified.
126+ * <PRE>
127+ * CachedRowSetImpl crs2 = new CachedRowSetImpl(
128+ * "com.fred.providers.HighAvailabilityProvider");
129+ * </PRE>
130+ * <LI>Setting the <code>SyncProvider</code> using the <code>CachedRowSet</code>
131+ * method <code>setSyncProvider</code><BR>
132+ * The following line of code resets the <code>SyncProvider</code> object
133+ * for <i>crs</i>, the <code>CachedRowSet</code> object created with the
134+ * default constructor.
135+ * <PRE>
136+ * crs.setSyncProvider("com.fred.providers.HighAvailabilityProvider");
137+ * </PRE>
138+ * </UL)
139+ * See the comments for <code>SyncFactory</code> and <code>SyncProvider</code> for
140+ * more details.
141+ *
142+ * <P>
143+ * <h3>2.0 Retrieving Data from a <code>CachedRowSet</code> Object</h3>
144+ * Data is retrieved from a <code>CachedRowSet</code> object by using the
145+ * getter methods inherited from the <code>ResultSet</code>
146+ * interface. The following examples, in which <code>crs</code> is a
147+ * <code>CachedRowSet</code>
148+ * object, demonstrate how to iterate through the rows, retrieving the column
149+ * values in each row. The first example uses the version of the
150+ * getter methods that take a column number; the second example
151+ * uses the version that takes a column name. Column numbers are generally
152+ * used when the <code>RowSet</code> object's command
153+ * is of the form <code>SELECT * FROM TABLENAME</code>; column names are most
154+ * commonly used when the command specifies columns by name.
155+ * <PRE>
156+ * while (crs.next()) {
157+ * String name = crs.getString(1);
158+ * int id = crs.getInt(2);
159+ * Clob comment = crs.getClob(3);
160+ * short dept = crs.getShort(4);
161+ * System.out.println(name + " " + id + " " + comment + " " + dept);
162+ * }
163+ * </PRE>
164+ *
165+ * <PRE>
166+ * while (crs.next()) {
167+ * String name = crs.getString("NAME");
168+ * int id = crs.getInt("ID");
169+ * Clob comment = crs.getClob("COM");
170+ * short dept = crs.getShort("DEPT");
171+ * System.out.println(name + " " + id + " " + comment + " " + dept);
172+ * }
173+ * </PRE>
174+ * <h4>2.1 Retrieving <code>RowSetMetaData</code></h4>
175+ * An application can get information about the columns in a <code>CachedRowSet</code>
176+ * object by calling <code>ResultSetMetaData</code> and <code>RowSetMetaData</code>
177+ * methods on a <code>RowSetMetaData</code> object. The following code fragment,
178+ * in which <i>crs</i> is a <code>CachedRowSet</code> object, illustrates the process.
179+ * The first line creates a <code>RowSetMetaData</code> object with information
180+ * about the columns in <i>crs</i>. The method <code>getMetaData</code>,
181+ * inherited from the <code>ResultSet</code> interface, returns a
182+ * <code>ResultSetMetaData</code> object, which is cast to a
183+ * <code>RowSetMetaData</code> object before being assigned to the variable
184+ * <i>rsmd</i>. The second line finds out how many columns <i>jrs</i> has, and
185+ * the third line gets the JDBC type of values stored in the second column of
186+ * <code>jrs</code>.
187+ * <PRE>
188+ * RowSetMetaData rsmd = (RowSetMetaData)crs.getMetaData();
189+ * int count = rsmd.getColumnCount();
190+ * int type = rsmd.getColumnType(2);
191+ * </PRE>
192+ * The <code>RowSetMetaData</code> interface differs from the
193+ * <code>ResultSetMetaData</code> interface in two ways.
194+ * <UL>
195+ * <LI><i>It includes <code>setter</code> methods:</i> A <code>RowSet</code>
196+ * object uses these methods internally when it is populated with data from a
197+ * different <code>ResultSet</code> object.
198+ * <P>
199+ * <LI><i>It contains fewer <code>getter</code> methods:</i> Some
200+ * <code>ResultSetMetaData</code> methods to not apply to a <code>RowSet</code>
201+ * object. For example, methods retrieving whether a column value is writable
202+ * or read only do not apply because all of a <code>RowSet</code> object's
203+ * columns will be writable or read only, depending on whether the rowset is
204+ * updatable or not.
205+ * </UL>
206+ * NOTE: In order to return a <code>RowSetMetaData</code> object, implementations must
207+ * override the <code>getMetaData()</code> method defined in
208+ * <code>java.sql.ResultSet</code> and return a <code>RowSetMetaData</code> object.
209+ *
210+ * <h3>3.0 Updating a <code>CachedRowSet</code> Object</h3>
211+ * Updating a <code>CachedRowSet</code> object is similar to updating a
212+ * <code>ResultSet</code> object, but because the rowset is not connected to
213+ * its data source while it is being updated, it must take an additional step
214+ * to effect changes in its underlying data source. After calling the method
215+ * <code>updateRow</code> or <code>insertRow</code>, a
216+ * <code>CachedRowSet</code>
217+ * object must also call the method <code>acceptChanges</code> to have updates
218+ * written to the data source. The following example, in which the cursor is
219+ * on a row in the <code>CachedRowSet</code> object <i>crs</i>, shows
220+ * the code required to update two column values in the current row and also
221+ * update the <code>RowSet</code> object's underlying data source.
222+ * <PRE>
223+ * crs.updateShort(3, 58);
224+ * crs.updateInt(4, 150000);
225+ * crs.updateRow();
226+ * crs.acceptChanges();
227+ * </PRE>
228+ * <P>
229+ * The next example demonstrates moving to the insert row, building a new
230+ * row on the insert row, inserting it into the rowset, and then calling the
231+ * method <code>acceptChanges</code> to add the new row to the underlying data
232+ * source. Note that as with the getter methods, the updater methods may take
233+ * either a column index or a column name to designate the column being acted upon.
234+ * <PRE>
235+ * crs.moveToInsertRow();
236+ * crs.updateString("Name", "Shakespeare");
237+ * crs.updateInt("ID", 10098347);
238+ * crs.updateShort("Age", 58);
239+ * crs.updateInt("Sal", 150000);
240+ * crs.insertRow();
241+ * crs.moveToCurrentRow();
242+ * crs.acceptChanges();
243+ * </PRE>
244+ * <P>
245+ * NOTE: Where the <code>insertRow()</code> method inserts the contents of a
246+ * <code>CachedRowSet</code> object's insert row is implementation-defined.
247+ * The reference implementation for the <code>CachedRowSet</code> interface
248+ * inserts a new row immediately following the current row, but it could be
249+ * implemented to insert new rows in any number of other places.
250+ * <P>
251+ * Another thing to note about these examples is how they use the method
252+ * <code>acceptChanges</code>. It is this method that propagates changes in
253+ * a <code>CachedRowSet</code> object back to the underlying data source,
254+ * calling on the <code>RowSet</code> object's writer internally to write
255+ * changes to the data source. To do this, the writer has to incur the expense
256+ * of establishing a connection with that data source. The
257+ * preceding two code fragments call the method <code>acceptChanges</code>
258+ * immediately after calling <code>updateRow</code> or <code>insertRow</code>.
259+ * However, when there are multiple rows being changed, it is more efficient to call
260+ * <code>acceptChanges</code> after all calls to <code>updateRow</code>
261+ * and <code>insertRow</code> have been made. If <code>acceptChanges</code>
262+ * is called only once, only one connection needs to be established.
263+ * <P>
264+ * <h3>4.0 Updating the Underlying Data Source</h3>
265+ * When the method <code>acceptChanges</code> is executed, the
266+ * <code>CachedRowSet</code> object's writer, a <code>RowSetWriterImpl</code>
267+ * object, is called behind the scenes to write the changes made to the
268+ * rowset to the underlying data source. The writer is implemented to make a
269+ * connection to the data source and write updates to it.
270+ * <P>
271+ * A writer is made available through an implementation of the
272+ * <code>SyncProvider</code> interface, as discussed in section 1,
273+ * "Creating a <code>CachedRowSet</code> Object."
274+ * The default reference implementation provider, <code>RIOptimisticProvider</code>,
275+ * has its writer implemented to use an optimistic concurrency control
276+ * mechanism. That is, it maintains no locks in the underlying database while
277+ * the rowset is disconnected from the database and simply checks to see if there
278+ * are any conflicts before writing data to the data source. If there are any
279+ * conflicts, it does not write anything to the data source.
280+ * <P>
281+ * The reader/writer facility
282+ * provided by the <code>SyncProvider</code> class is pluggable, allowing for the
283+ * customization of data retrieval and updating. If a different concurrency
284+ * control mechanism is desired, a different implementation of
285+ * <code>SyncProvider</code> can be plugged in using the method
286+ * <code>setSyncProvider</code>.
287+ * <P>
288+ * In order to use the optimistic concurrency control routine, the
289+ * <code>RIOptismisticProvider</code> maintains both its current
290+ * value and its original value (the value it had immediately preceding the
291+ * current value). Note that if no changes have been made to the data in a
292+ * <code>RowSet</code> object, its current values and its original values are the same,
293+ * both being the values with which the <code>RowSet</code> object was initially
294+ * populated. However, once any values in the <code>RowSet</code> object have been
295+ * changed, the current values and the original values will be different, though at
296+ * this stage, the original values are still the initial values. With any subsequent
297+ * changes to data in a <code>RowSet</code> object, its original values and current
298+ * values will still differ, but its original values will be the values that
299+ * were previously the current values.
300+ * <P>
301+ * Keeping track of original values allows the writer to compare the <code>RowSet</code>
302+ * object's original value with the value in the database. If the values in
303+ * the database differ from the <code>RowSet</code> object's original values, which means that
304+ * the values in the database have been changed, there is a conflict.
305+ * Whether a writer checks for conflicts, what degree of checking it does, and how
306+ * it handles conflicts all depend on how it is implemented.
307+ * <P>
308+ * <h3>5.0 Registering and Notifying Listeners</h3>
309+ * Being JavaBeans components, all rowsets participate in the JavaBeans event
310+ * model, inheriting methods for registering listeners and notifying them of
311+ * changes from the <code>BaseRowSet</code> class. A listener for a
312+ * <code>CachedRowSet</code> object is a component that wants to be notified
313+ * whenever there is a change in the rowset. For example, if a
314+ * <code>CachedRowSet</code> object contains the results of a query and
315+ * those
316+ * results are being displayed in, say, a table and a bar graph, the table and
317+ * bar graph could be registered as listeners with the rowset so that they can
318+ * update themselves to reflect changes. To become listeners, the table and
319+ * bar graph classes must implement the <code>RowSetListener</code> interface.
320+ * Then they can be added to the <Code>CachedRowSet</code> object's list of
321+ * listeners, as is illustrated in the following lines of code.
322+ * <PRE>
323+ * crs.addRowSetListener(table);
324+ * crs.addRowSetListener(barGraph);
325+ * </PRE>
326+ * Each <code>CachedRowSet</code> method that moves the cursor or changes
327+ * data also notifies registered listeners of the changes, so
328+ * <code>table</code> and <code>barGraph</code> will be notified when there is
329+ * a change in <code>crs</code>.
330+ * <P>
331+ * <h3>6.0 Passing Data to Thin Clients</h3>
332+ * One of the main reasons to use a <code>CachedRowSet</code> object is to
333+ * pass data between different components of an application. Because it is
334+ * serializable, a <code>CachedRowSet</code> object can be used, for example,
335+ * to send the result of a query executed by an enterprise JavaBeans component
336+ * running in a server environment over a network to a client running in a
337+ * web browser.
338+ * <P>
339+ * While a <code>CachedRowSet</code> object is disconnected, it can be much
340+ * leaner than a <code>ResultSet</code> object with the same data.
341+ * As a result, it can be especially suitable for sending data to a thin client
342+ * such as a PDA, where it would be inappropriate to use a JDBC driver
343+ * due to resource limitations or security considerations.
344+ * Thus, a <code>CachedRowSet</code> object provides a means to "get rows in"
345+ * without the need to implement the full JDBC API.
346+ * <P>
347+ * <h3>7.0 Scrolling and Updating</h3>
348+ * A second major use for <code>CachedRowSet</code> objects is to provide
349+ * scrolling and updating for <code>ResultSet</code> objects that
350+ * do not provide these capabilities themselves. In other words, a
351+ * <code>CachedRowSet</code> object can be used to augment the
352+ * capabilities of a JDBC technology-enabled driver (hereafter called a
353+ * "JDBC driver") when the DBMS does not provide full support for scrolling and
354+ * updating. To achieve the effect of making a non-scrollble and read-only
355+ * <code>ResultSet</code> object scrollable and updatable, a programmer
356+ * simply needs to create a <code>CachedRowSet</code> object populated
357+ * with that <code>ResultSet</code> object's data. This is demonstrated
358+ * in the following code fragment, where <code>stmt</code> is a
359+ * <code>Statement</code> object.
360+ * <PRE>
361+ * ResultSet rs = stmt.executeQuery("SELECT * FROM EMPLOYEES");
362+ * CachedRowSetImpl crs = new CachedRowSetImpl();
363+ * crs.populate(rs);
364+ * </PRE>
365+ * <P>
366+ * The object <code>crs</code> now contains the data from the table
367+ * <code>EMPLOYEES</code>, just as the object <code>rs</code> does.
368+ * The difference is that the cursor for <code>crs</code> can be moved
369+ * forward, backward, or to a particular row even if the cursor for
370+ * <code>rs</code> can move only forward. In addition, <code>crs</code> is
371+ * updatable even if <code>rs</code> is not because by default, a
372+ * <code>CachedRowSet</code> object is both scrollable and updatable.
373+ * <P>
374+ * In summary, a <code>CachedRowSet</code> object can be thought of as simply
375+ * a disconnected set of rows that are being cached outside of a data source.
376+ * Being thin and serializable, it can easily be sent across a wire,
377+ * and it is well suited to sending data to a thin client. However, a
378+ * <code>CachedRowSet</code> object does have a limitation: It is limited in
379+ * size by the amount of data it can store in memory at one time.
380+ * <P>
381+ * <h3>8.0 Getting Universal Data Access</h3>
382+ * Another advantage of the <code>CachedRowSet</code> class is that it makes it
383+ * possible to retrieve and store data from sources other than a relational
384+ * database. The reader for a rowset can be implemented to read and populate
385+ * its rowset with data from any tabular data source, including a spreadsheet
386+ * or flat file.
387+ * Because both a <code>CachedRowSet</code> object and its metadata can be
388+ * created from scratch, a component that acts as a factory for rowsets
389+ * can use this capability to create a rowset containing data from
390+ * non-SQL data sources. Nevertheless, it is expected that most of the time,
391+ * <code>CachedRowSet</code> objects will contain data that was fetched
392+ * from an SQL database using the JDBC API.
393+ * <P>
394+ * <h3>9.0 Setting Properties</h3>
395+ * All rowsets maintain a set of properties, which will usually be set using
396+ * a tool. The number and kinds of properties a rowset has will vary,
397+ * depending on what the rowset does and how it gets its data. For example,
398+ * rowsets that get their data from a <code>ResultSet</code> object need to
399+ * set the properties that are required for making a database connection.
400+ * If a rowset uses the <code>DriverManager</code> facility to make a
401+ * connection, it needs to set a property for the JDBC URL that identifies
402+ * the appropriate driver, and it needs to set the properties that give the
403+ * user name and password.
404+ * If, on the other hand, the rowset uses a <code>DataSource</code> object
405+ * to make the connection, which is the preferred method, it does not need to
406+ * set the property for the JDBC URL. Instead, it needs to set
407+ * properties for the logical name of the data source, for the user name,
408+ * and for the password.
409+ * <P>
410+ * NOTE: In order to use a <code>DataSource</code> object for making a
411+ * connection, the <code>DataSource</code> object must have been registered
412+ * with a naming service that uses the Java Naming and Directory
413+ * Interface<sup><font size=-2>TM</font></sup> (JNDI) API. This registration
414+ * is usually done by a person acting in the capacity of a system
415+ * administrator.
416+ * <P>
417+ * In order to be able to populate itself with data from a database, a rowset
418+ * needs to set a command property. This property is a query that is a
419+ * <code>PreparedStatement</code> object, which allows the query to have
420+ * parameter placeholders that are set at run time, as opposed to design time.
421+ * To set these placeholder parameters with values, a rowset provides
422+ * setter methods for setting values of each data type,
423+ * similar to the setter methods provided by the <code>PreparedStatement</code>
424+ * interface.
425+ * <P>
426+ * The following code fragment illustrates how the <code>CachedRowSet</code>
427+ * object <code>crs</code> might have its command property set. Note that if a
428+ * tool is used to set properties, this is the code that the tool would use.
429+ * <PRE>
430+ * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS " +
431+ * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
432+ * </PRE>
433+ * <P>
434+ * The values that will be used to set the command's placeholder parameters are
435+ * contained in the <code>RowSet</code> object's <code>params</code> field, which is a
436+ * <code>Vector</code> object.
437+ * The <code>CachedRowSet</code> class provides a set of setter
438+ * methods for setting the elements in its <code>params</code> field. The
439+ * following code fragment demonstrates setting the two parameters in the
440+ * query from the previous example.
441+ * <PRE>
442+ * crs.setInt(1, 5000);
443+ * crs.setString(2, "West");
444+ * </PRE>
445+ * <P>
446+ * The <code>params</code> field now contains two elements, each of which is
447+ * an array two elements long. The first element is the parameter number;
448+ * the second is the value to be set.
449+ * In this case, the first element of <code>params</code> is
450+ * <code>1</code>, <code>5000</code>, and the second element is <code>2</code>,
451+ * <code>"West"</code>. When an application calls the method
452+ * <code>execute</code>, it will in turn call on this <code>RowSet</code> object's reader,
453+ * which will in turn invoke its <code>readData</code> method. As part of
454+ * its implementation, <code>readData</code> will get the values in
455+ * <code>params</code> and use them to set the command's placeholder
456+ * parameters.
457+ * The following code fragment gives an idea of how the reader
458+ * does this, after obtaining the <code>Connection</code> object
459+ * <code>con</code>.
460+ * <PRE>
461+ * PreparedStatement pstmt = con.prepareStatement(crs.getCommand());
462+ * reader.decodeParams();
463+ * // decodeParams figures out which setter methods to use and does something
464+ * // like the following:
465+ * // for (i = 0; i < params.length; i++) {
466+ * // pstmt.setObject(i + 1, params[i]);
467+ * // }
468+ * </PRE>
469+ * <P>
470+ * At this point, the command for <code>crs</code> is the query <code>"SELECT
471+ * FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS WHERE CREDIT_LIMIT > 5000
472+ * AND REGION = "West"</code>. After the <code>readData</code> method executes
473+ * this command with the following line of code, it will have the data from
474+ * <code>rs</code> with which to populate <code>crs</code>.
475+ * <PRE>
476+ * ResultSet rs = pstmt.executeQuery();
477+ * </PRE>
478+ * <P>
479+ * The preceding code fragments give an idea of what goes on behind the
480+ * scenes; they would not appear in an application, which would not invoke
481+ * methods like <code>readData</code> and <code>decodeParams</code>.
482+ * In contrast, the following code fragment shows what an application might do.
483+ * It sets the rowset's command, sets the command's parameters, and executes
484+ * the command. Simply by calling the <code>execute</code> method,
485+ * <code>crs</code> populates itself with the requested data from the
486+ * table <code>CUSTOMERS</code>.
487+ * <PRE>
488+ * crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
489+ * "WHERE CREDIT_LIMIT > ? AND REGION = ?");
490+ * crs.setInt(1, 5000);
491+ * crs.setString(2, "West");
492+ * crs.execute();
493+ * </PRE>
494+ *
495+ * <h3>10.0 Paging Data</h3>
496+ * Because a <code>CachedRowSet</code> object stores data in memory,
497+ * the amount of data that it can contain at any one
498+ * time is determined by the amount of memory available. To get around this limitation,
499+ * a <code>CachedRowSet</code> object can retrieve data from a <code>ResultSet</code>
500+ * object in chunks of data, called <i>pages</i>. To take advantage of this mechanism,
501+ * an application sets the number of rows to be included in a page using the method
502+ * <code>setPageSize</code>. In other words, if the page size is set to five, a chunk
503+ * of five rows of
504+ * data will be fetched from the data source at one time. An application can also
505+ * optionally set the maximum number of rows that may be fetched at one time. If the
506+ * maximum number of rows is set to zero, or no maximum number of rows is set, there is
507+ * no limit to the number of rows that may be fetched at a time.
508+ * <P>
509+ * After properties have been set,
510+ * the <code>CachedRowSet</code> object must be populated with data
511+ * using either the method <code>populate</code> or the method <code>execute</code>.
512+ * The following lines of code demonstrate using the method <code>populate</code>.
513+ * Note that this version of the method takes two parameters, a <code>ResultSet</code>
514+ * handle and the row in the <code>ResultSet</code> object from which to start
515+ * retrieving rows.
516+ * <PRE>
517+ * CachedRowSet crs = new CachedRowSetImpl();
518+ * crs.setMaxRows(20);
519+ * crs.setPageSize(4);
520+ * crs.populate(rsHandle, 10);
521+ * </PRE>
522+ * When this code runs, <i>crs</i> will be populated with four rows from
523+ * <i>rsHandle</i> starting with the tenth row.
524+ * <P>
525+ * The next code fragment shows populating a <code>CachedRowSet</code> object using the
526+ * method <code>execute</code>, which may or may not take a <code>Connection</code>
527+ * object as a parameter. This code passes <code>execute</code> the <code>Connection</code>
528+ * object <i>conHandle</i>.
529+ * <P>
530+ * Note that there are two differences between the following code
531+ * fragment and the previous one. First, the method <code>setMaxRows</code> is not
532+ * called, so there is no limit set for the number of rows that <i>crs</i> may contain.
533+ * (Remember that <i>crs</i> always has the overriding limit of how much data it can
534+ * store in memory.) The second difference is that the you cannot pass the method
535+ * <code>execute</code> the number of the row in the <code>ResultSet</code> object
536+ * from which to start retrieving rows. This method always starts with the first row.
537+ * <PRE>
538+ * CachedRowSet crs = new CachedRowSetImpl();
539+ * crs.setPageSize(5);
540+ * crs.execute(conHandle);
541+ * </PRE>
542+ * After this code has run, <i>crs</i> will contain five rows of data from the
543+ * <code>ResultSet</code> object produced by the command for <i>crs</i>. The writer
544+ * for <i>crs</i> will use <i>conHandle</i> to connect to the data source and
545+ * execute the command for <i>crs</i>. An application is then able to operate on the
546+ * data in <i>crs</i> in the same way that it would operate on data in any other
547+ * <code>CachedRowSet</code> object.
548+ * <P>
549+ * To access the next page (chunk of data), an application calls the method
550+ * <code>nextPage</code>. This method creates a new <code>CachedRowSet</code> object
551+ * and fills it with the next page of data. For example, assume that the
552+ * <code>CachedRowSet</code> object's command returns a <code>ResultSet</code> object
553+ * <i>rs</i> with 1000 rows of data. If the page size has been set to 100, the first
554+ * call to the method <code>nextPage</code> will create a <code>CachedRowSet</code> object
555+ * containing the first 100 rows of <i>rs</i>. After doing what it needs to do with the
556+ * data in these first 100 rows, the application can again call the method
557+ * <code>nextPage</code> to create another <code>CachedRowSet</code> object
558+ * with the second 100 rows from <i>rs</i>. The data from the first <code>CachedRowSet</code>
559+ * object will no longer be in memory because it is replaced with the data from the
560+ * second <code>CachedRowSet</code> object. After the tenth call to the method <code>nextPage</code>,
561+ * the tenth <code>CachedRowSet</code> object will contain the last 100 rows of data from
562+ * <i>rs</i>, which are stored in memory. At any given time, the data from only one
563+ * <code>CachedRowSet</code> object is stored in memory.
564+ * <P>
565+ * The method <code>nextPage</code> returns <code>true</code> as long as the current
566+ * page is not the last page of rows and <code>false</code> when there are no more pages.
567+ * It can therefore be used in a <code>while</code> loop to retrieve all of the pages,
568+ * as is demonstrated in the following lines of code.
569+ * <PRE>
570+ * CachedRowSet crs = CachedRowSetImpl();
571+ * crs.setPageSize(100);
572+ * crs.execute(conHandle);
573+ *
574+ * while(crs.nextPage()) {
575+ * while(crs.next()) {
576+ * . . . // operate on chunks (of 100 rows each) in crs,
577+ * // row by row
578+ * }
579+ * }
580+ * </PRE>
581+ * After this code fragment has been run, the application will have traversed all
582+ * 1000 rows, but it will have had no more than 100 rows in memory at a time.
583+ * <P>
584+ * The <code>CachedRowSet</code> interface also defines the method <code>previousPage</code>.
585+ * Just as the method <code>nextPage</code> is analogous to the <code>ResultSet</code>
586+ * method <code>next</code>, the method <code>previousPage</code> is analogous to
587+ * the <code>ResultSet</code> method <code>previous</code>. Similar to the method
588+ * <code>nextPage</code>, <code>previousPage</code> creates a <code>CachedRowSet</code>
589+ * object containing the number of rows set as the page size. So, for instance, the
590+ * method <code>previousPage</code> could be used in a <code>while</code> loop at
591+ * the end of the preceding code fragment to navigate back through the pages from the last
592+ * page to the first page.
593+ * The method <code>previousPage</code> is also similar to <code>nextPage</code>
594+ * in that it can be used in a <code>while</code>
595+ * loop, except that it returns <code>true</code> as long as there is another page
596+ * preceding it and <code>false</code> when there are no more pages ahead of it.
597+ * <P>
598+ * By positioning the cursor after the last row for each page,
599+ * as is done in the following code fragment, the method <code>previous</code>
600+ * navigates from the last row to the first row in each page.
601+ * The code could also have left the cursor before the first row on each page and then
602+ * used the method <code>next</code> in a <code>while</code> loop to navigate each page
603+ * from the first row to the last row.
604+ * <P>
605+ * The following code fragment assumes a continuation from the previous code fragment,
606+ * meaning that the cursor for the tenth <code>CachedRowSet</code> object is on the
607+ * last row. The code moves the cursor to after the last row so that the first
608+ * call to the method <code>previous</code> will put the cursor back on the last row.
609+ * After going through all of the rows in the last page (the <code>CachedRowSet</code>
610+ * object <i>crs</i>), the code then enters
611+ * the <code>while</code> loop to get to the ninth page, go through the rows backwards,
612+ * go to the eighth page, go through the rows backwards, and so on to the first row
613+ * of the first page.
614+ *
615+ * <PRE>
616+ * crs.afterLast();
617+ * while(crs.previous()) {
618+ * . . . // navigate through the rows, last to first
619+ * {
620+ * while(crs.previousPage()) {
621+ * crs.afterLast();
622+ * while(crs.previous()) {
623+ * . . . // go from the last row to the first row of each page
624+ * }
625+ * }
626+ * </PRE>
627+ *
628+ * @author Jonathan Bruce
629+ */
630+
631+public interface CachedRowSet extends RowSet, Joinable {
632+
633+ /**
634+ * Populates this <code>CachedRowSet</code> object with data from
635+ * the given <code>ResultSet</code> object.
636+ * <P>
637+ * This method can be used as an alternative to the <code>execute</code> method when an
638+ * application has a connection to an open <code>ResultSet</code> object.
639+ * Using the method <code>populate</code> can be more efficient than using
640+ * the version of the <code>execute</code> method that takes no parameters
641+ * because it does not open a new connection and re-execute this
642+ * <code>CachedRowSet</code> object's command. Using the <code>populate</code>
643+ * method is more a matter of convenience when compared to using the version
644+ * of <code>execute</code> that takes a <code>ResultSet</code> object.
645+ *
646+ * @param data the <code>ResultSet</code> object containing the data
647+ * to be read into this <code>CachedRowSet</code> object
648+ * @throws SQLException if a null <code>ResultSet</code> object is supplied
649+ * or this <code>CachedRowSet</code> object cannot
650+ * retrieve the associated <code>ResultSetMetaData</code> object
651+ * @see #execute
652+ * @see java.sql.ResultSet
653+ * @see java.sql.ResultSetMetaData
654+ */
655+ public void populate(ResultSet data) throws SQLException;
656+
657+ /**
658+ * Populates this <code>CachedRowSet</code> object with data, using the
659+ * given connection to produce the result set from which the data will be read.
660+ * This method should close any database connections that it creates to
661+ * ensure that this <code>CachedRowSet</code> object is disconnected except when
662+ * it is reading data from its data source or writing data to its data source.
663+ * <P>
664+ * The reader for this <code>CachedRowSet</code> object
665+ * will use <i>conn</i> to establish a connection to the data source
666+ * so that it can execute the rowset's command and read data from the
667+ * the resulting <code>ResultSet</code> object into this
668+ * <code>CachedRowSet</code> object. This method also closes <i>conn</i>
669+ * after it has populated this <code>CachedRowSet</code> object.
670+ * <P>
671+ * If this method is called when an implementation has already been
672+ * populated, the contents and the metadata are (re)set. Also, if this method is
673+ * called before the method <code>acceptChanges</code> has been called
674+ * to commit outstanding updates, those updates are lost.
675+ *
676+ * @param conn a standard JDBC <code>Connection</code> object with valid
677+ * properties
678+ * @throws SQLException if an invalid <code>Connection</code> object is supplied
679+ * or an error occurs in establishing the connection to the
680+ * data source
681+ * @see #populate
682+ * @see java.sql.Connection
683+ */
684+ public void execute(Connection conn) throws SQLException;
685+
686+ /**
687+ * Propagates row update, insert and delete changes made to this
688+ * <code>CachedRowSet</code> object to the underlying data source.
689+ * <P>
690+ * This method calls on this <code>CachedRowSet</code> object's writer
691+ * to do the work behind the scenes.
692+ * Standard <code>CachedRowSet</code> implementations should use the
693+ * <code>SyncFactory</code> singleton
694+ * to obtain a <code>SyncProvider</code> instance providing a
695+ * <code>RowSetWriter</code> object (writer). The writer will attempt
696+ * to propagate changes made in this <code>CachedRowSet</code> object
697+ * back to the data source.
698+ * <P>
699+ * When the method <code>acceptChanges</code> executes successfully, in
700+ * addition to writing changes to the data source, it
701+ * makes the values in the current row be the values in the original row.
702+ * <P>
703+ * Depending on the synchronization level of the <code>SyncProvider</code>
704+ * implementation being used, the writer will compare the original values
705+ * with those in the data source to check for conflicts. When there is a conflict,
706+ * the <code>RIOptimisticProvider</code> implementation, for example, throws a
707+ * <code>SyncProviderException</code> and does not write anything to the
708+ * data source.
709+ * <P>
710+ * An application may choose to catch the <code>SyncProviderException</code>
711+ * object and retrieve the <code>SyncResolver</code> object it contains.
712+ * The <code>SyncResolver</code> object lists the conflicts row by row and
713+ * sets a lock on the data source to avoid further conflicts while the
714+ * current conflicts are being resolved.
715+ * Further, for each conflict, it provides methods for examining the conflict
716+ * and setting the value that should be persisted in the data source.
717+ * After all conflicts have been resolved, an application must call the
718+ * <code>acceptChanges</code> method again to write resolved values to the
719+ * data source. If all of the values in the data source are already the
720+ * values to be persisted, the method <code>acceptChanges</code> does nothing.
721+ * <P>
722+ * Some provider implementations may use locks to ensure that there are no
723+ * conflicts. In such cases, it is guaranteed that the writer will succeed in
724+ * writing changes to the data source when the method <code>acceptChanges</code>
725+ * is called. This method may be called immediately after the methods
726+ * <code>updateRow</code>, <code>insertRow</code>, or <code>deleteRow</code>
727+ * have been called, but it is more efficient to call it only once after
728+ * all changes have been made so that only one connection needs to be
729+ * established.
730+ * <P>
731+ * Note: The <code>acceptChanges()</code> method will determine if the
732+ * <code>COMMIT_ON_ACCEPT_CHANGES</code> is set to true or not. If it is set
733+ * to true, all updates in the synchronization are committed to the data
734+ * source. Otherwise, the application <b>must</b> explicity call the
735+ * <code>commit()</code> or <code>rollback()</code> methods as appropriate.
736+ *
737+ * @throws SQLException if the cursor is on the insert row
738+ * @throws SyncProviderException if the underlying
739+ * synchronization provider's writer fails to write the updates
740+ * back to the data source
741+ * @see #acceptChanges(java.sql.Connection)
742+ * @see javax.sql.RowSetWriter
743+ * @see javax.sql.rowset.spi.SyncFactory
744+ * @see javax.sql.rowset.spi.SyncProvider
745+ * @see javax.sql.rowset.spi.SyncProviderException
746+ * @see javax.sql.rowset.spi.SyncResolver
747+ */
748+ public void acceptChanges() throws SyncProviderException;
749+
750+ /**
751+ * Propagates all row update, insert and delete changes to the
752+ * data source backing this <code>CachedRowSet</code> object
753+ * using the specified <code>Connection</code> object to establish a
754+ * connection to the data source.
755+ * <P>
756+ * The other version of the <code>acceptChanges</code> method is not passed
757+ * a connection because it uses
758+ * the <code>Connection</code> object already defined within the <code>RowSet</code>
759+ * object, which is the connection used for populating it initially.
760+ * <P>
761+ * This form of the method <code>acceptChanges</code> is similar to the
762+ * form that takes no arguments; however, unlike the other form, this form
763+ * can be used only when the underlying data source is a JDBC data source.
764+ * The updated <code>Connection</code> properties must be used by the
765+ * <code>SyncProvider</code> to reset the <code>RowSetWriter</code>
766+ * configuration to ensure that the contents of the <code>CachedRowSet</code>
767+ * object are synchronized correctly.
768+ * <P>
769+ * When the method <code>acceptChanges</code> executes successfully, in
770+ * addition to writing changes to the data source, it
771+ * makes the values in the current row be the values in the original row.
772+ * <P>
773+ * Depending on the synchronization level of the <code>SyncProvider</code>
774+ * implementation being used, the writer will compare the original values
775+ * with those in the data source to check for conflicts. When there is a conflict,
776+ * the <code>RIOptimisticProvider</code> implementation, for example, throws a
777+ * <code>SyncProviderException</code> and does not write anything to the
778+ * data source.
779+ * <P>
780+ * An application may choose to catch the <code>SyncProviderException</code>
781+ * object and retrieve the <code>SyncResolver</code> object it contains.
782+ * The <code>SyncResolver</code> object lists the conflicts row by row and
783+ * sets a lock on the data source to avoid further conflicts while the
784+ * current conflicts are being resolved.
785+ * Further, for each conflict, it provides methods for examining the conflict
786+ * and setting the value that should be persisted in the data source.
787+ * After all conflicts have been resolved, an application must call the
788+ * <code>acceptChanges</code> method again to write resolved values to the
789+ * data source. If all of the values in the data source are already the
790+ * values to be persisted, the method <code>acceptChanges</code> does nothing.
791+ * <P>
792+ * Some provider implementations may use locks to ensure that there are no
793+ * conflicts. In such cases, it is guaranteed that the writer will succeed in
794+ * writing changes to the data source when the method <code>acceptChanges</code>
795+ * is called. This method may be called immediately after the methods
796+ * <code>updateRow</code>, <code>insertRow</code>, or <code>deleteRow</code>
797+ * have been called, but it is more efficient to call it only once after
798+ * all changes have been made so that only one connection needs to be
799+ * established.
800+ * <P>
801+ * Note: The <code>acceptChanges()</code> method will determine if the
802+ * <code>COMMIT_ON_ACCEPT_CHANGES</code> is set to true or not. If it is set
803+ * to true, all updates in the synchronization are committed to the data
804+ * source. Otherwise, the application <b>must</b> explicity call the
805+ * <code>commit</code> or <code>rollback</code> methods as appropriate.
806+ *
807+ * @param con a standard JDBC <code>Connection</code> object
808+ * @throws SQLException if the cursor is on the insert row
809+ * @throws SyncProviderException if the underlying
810+ * synchronization provider's writer fails to write the updates
811+ * back to the data source
812+ * @see #acceptChanges()
813+ * @see javax.sql.RowSetWriter
814+ * @see javax.sql.rowset.spi.SyncFactory
815+ * @see javax.sql.rowset.spi.SyncProvider
816+ * @see javax.sql.rowset.spi.SyncProviderException
817+ * @see javax.sql.rowset.spi.SyncResolver
818+ */
819+ public void acceptChanges(Connection con) throws SyncProviderException;
820+
821+ /**
822+ * Restores this <code>CachedRowSet</code> object to its original
823+ * value, that is, its value before the last set of changes. If there
824+ * have been no changes to the rowset or only one set of changes,
825+ * the original value is the value with which this <code>CachedRowSet</code> object
826+ * was populated; otherwise, the original value is
827+ * the value it had immediately before its current value.
828+ * <P>
829+ * When this method is called, a <code>CachedRowSet</code> implementation
830+ * must ensure that all updates, inserts, and deletes to the current
831+ * rowset instance are replaced by the previous values. In addition,
832+ * the cursor should be
833+ * reset to the first row and a <code>rowSetChanged</code> event
834+ * should be fired to notify all registered listeners.
835+ *
836+ * @throws SQLException if an error occurs rolling back the current value of
837+ * this <code>CachedRowSet</code> object to its previous value
838+ * @see javax.sql.RowSetListener#rowSetChanged
839+ */
840+ public void restoreOriginal() throws SQLException;
841+
842+ /**
843+ * Releases the current contents of this <code>CachedRowSet</code>
844+ * object and sends a <code>rowSetChanged</code> event to all
845+ * registered listeners. Any outstanding updates are discarded and
846+ * the rowset contains no rows after this method is called. There
847+ * are no interactions with the underlying data source, and any rowset
848+ * content, metadata, and content updates should be non-recoverable.
849+ * <P>
850+ * This <code>CachedRowSet</code> object should lock until its contents and
851+ * associated updates are fully cleared, thus preventing 'dirty' reads by
852+ * other components that hold a reference to this <code>RowSet</code> object.
853+ * In addition, the contents cannot be released
854+ * until all all components reading this <code>CachedRowSet</code> object
855+ * have completed their reads. This <code>CachedRowSet</code> object
856+ * should be returned to normal behavior after firing the
857+ * <code>rowSetChanged</code> event.
858+ * <P>
859+ * The metadata, including JDBC properties and Synchronization SPI
860+ * properties, are maintained for future use. It is important that
861+ * properties such as the <code>command</code> property be
862+ * relevant to the originating data source from which this <code>CachedRowSet</code>
863+ * object was originally established.
864+ * <P>
865+ * This method empties a rowset, as opposed to the <code>close</code> method,
866+ * which marks the entire rowset as recoverable to allow the garbage collector
867+ * the rowset's Java VM resources.
868+ *
869+ * @throws SQLException if an error occurs flushing the contents of this
870+ * <code>CachedRowSet</code> object
871+ * @see javax.sql.RowSetListener#rowSetChanged
872+ * @see java.sql.ResultSet#close
873+ */
874+ public void release() throws SQLException;
875+
876+ /**
877+ * Cancels the deletion of the current row and notifies listeners that
878+ * a row has changed. After this method is called, the current row is
879+ * no longer marked for deletion. This method can be called at any
880+ * time during the lifetime of the rowset.
881+ * <P>
882+ * In addition, multiple cancellations of row deletions can be made
883+ * by adjusting the position of the cursor using any of the cursor
884+ * position control methods such as:
885+ * <ul>
886+ * <li><code>CachedRowSet.absolute</code>
887+ * <li><code>CachedRowSet.first</code>
888+ * <li><code>CachedRowSet.last</code>
889+ * </ul>
890+ *
891+ * @throws SQLException if (1) the current row has not been deleted or
892+ * (2) the cursor is on the insert row, before the first row, or
893+ * after the last row
894+ * @see javax.sql.rowset.CachedRowSet#undoInsert
895+ * @see java.sql.ResultSet#cancelRowUpdates
896+ */
897+ public void undoDelete() throws SQLException;
898+
899+ /**
900+ * Immediately removes the current row from this <code>CachedRowSet</code>
901+ * object if the row has been inserted, and also notifies listeners that a
902+ * row has changed. This method can be called at any time during the
903+ * lifetime of a rowset and assuming the current row is within
904+ * the exception limitations (see below), it cancels the row insertion
905+ * of the current row.
906+ * <P>
907+ * In addition, multiple cancellations of row insertions can be made
908+ * by adjusting the position of the cursor using any of the cursor
909+ * position control methods such as:
910+ * <ul>
911+ * <li><code>CachedRowSet.absolute</code>
912+ * <li><code>CachedRowSet.first</code>
913+ * <li><code>CachedRowSet.last</code>
914+ * </ul>
915+ *
916+ * @throws SQLException if (1) the current row has not been inserted or (2)
917+ * the cursor is before the first row, after the last row, or on the
918+ * insert row
919+ * @see javax.sql.rowset.CachedRowSet#undoDelete
920+ * @see java.sql.ResultSet#cancelRowUpdates
921+ */
922+ public void undoInsert() throws SQLException;
923+
924+
925+ /**
926+ * Immediately reverses the last update operation if the
927+ * row has been modified. This method can be
928+ * called to reverse updates on all columns until all updates in a row have
929+ * been rolled back to their state just prior to the last synchronization
930+ * (<code>acceptChanges</code>) or population. This method may also be called
931+ * while performing updates to the insert row.
932+ * <P>
933+ * <code>undoUpdate</code> may be called at any time during the lifetime of a
934+ * rowset; however, after a synchronization has occurred, this method has no
935+ * effect until further modification to the rowset data has occurred.
936+ *
937+ * @throws SQLException if the cursor is before the first row or after the last
938+ * row in in this <code>CachedRowSet</code> object
939+ * @see #undoDelete
940+ * @see #undoInsert
941+ * @see java.sql.ResultSet#cancelRowUpdates
942+ */
943+ public void undoUpdate() throws SQLException;
944+
945+ /**
946+ * Indicates whether the designated column in the current row of this
947+ * <code>CachedRowSet</code> object has been updated.
948+ *
949+ * @param idx an <code>int</code> identifying the column to be checked for updates
950+ * @return <code>true</code> if the designated column has been visibly updated;
951+ * <code>false</code> otherwise
952+ * @throws SQLException if the cursor is on the insert row, before the first row,
953+ * or after the last row
954+ * @see java.sql.DatabaseMetaData#updatesAreDetected
955+ */
956+ public boolean columnUpdated(int idx) throws SQLException;
957+
958+
959+ /**
960+ * Indicates whether the designated column in the current row of this
961+ * <code>CachedRowSet</code> object has been updated.
962+ *
963+ * @param columnName a <code>String</code> object giving the name of the
964+ * column to be checked for updates
965+ * @return <code>true</code> if the column has been visibly updated;
966+ * <code>false</code> otherwise
967+ * @throws SQLException if the cursor is on the insert row, before the first row,
968+ * or after the last row
969+ * @see java.sql.DatabaseMetaData#updatesAreDetected
970+ */
971+ public boolean columnUpdated(String columnName) throws SQLException;
972+
973+ /**
974+ * Converts this <code>CachedRowSet</code> object to a <code>Collection</code>
975+ * object that contains all of this <code>CachedRowSet</code> object's data.
976+ * Implementations have some latitude in
977+ * how they can represent this <code>Collection</code> object because of the
978+ * abstract nature of the <code>Collection</code> framework.
979+ * Each row must be fully represented in either a
980+ * general purpose <code>Collection</code> implementation or a specialized
981+ * <code>Collection</code> implementation, such as a <code>TreeMap</code>
982+ * object or a <code>Vector</code> object.
983+ * An SQL <code>NULL</code> column value must be represented as a <code>null</code>
984+ * in the Java programming language.
985+ * <P>
986+ * The standard reference implementation for the <code>CachedRowSet</code>
987+ * interface uses a <code>TreeMap</code> object for the rowset, with the
988+ * values in each row being contained in <code>Vector</code> objects. It is
989+ * expected that most implementations will do the same.
990+ * <P>
991+ * The <code>TreeMap</code> type of collection guarantees that the map will be in
992+ * ascending key order, sorted according to the natural order for the
993+ * key's class.
994+ * Each key references a <code>Vector</code> object that corresponds to one
995+ * row of a <code>RowSet</code> object. Therefore, the size of each
996+ * <code>Vector</code> object must be exactly equal to the number of
997+ * columns in the <code>RowSet</code> object.
998+ * The key used by the <code>TreeMap</code> collection is determined by the
999+ * implementation, which may choose to leverage a set key that is
1000+ * available within the internal <code>RowSet</code> tabular structure by
1001+ * virtue of a key already set either on the <code>RowSet</code> object
1002+ * itself or on the underlying SQL data.
1003+ * <P>
1004+ *
1005+ * @return a <code>Collection</code> object that contains the values in
1006+ * each row in this <code>CachedRowSet</code> object
1007+ * @throws SQLException if an error occurs generating the collection
1008+ * @see #toCollection(int)
1009+ * @see #toCollection(String)
1010+ */
1011+ public Collection<?> toCollection() throws SQLException;
1012+
1013+ /**
1014+ * Converts the designated column in this <code>CachedRowSet</code> object
1015+ * to a <code>Collection</code> object. Implementations have some latitude in
1016+ * how they can represent this <code>Collection</code> object because of the
1017+ * abstract nature of the <code>Collection</code> framework.
1018+ * Each column value should be fully represented in either a
1019+ * general purpose <code>Collection</code> implementation or a specialized
1020+ * <code>Collection</code> implementation, such as a <code>Vector</code> object.
1021+ * An SQL <code>NULL</code> column value must be represented as a <code>null</code>
1022+ * in the Java programming language.
1023+ * <P>
1024+ * The standard reference implementation uses a <code>Vector</code> object
1025+ * to contain the column values, and it is expected
1026+ * that most implementations will do the same. If a <code>Vector</code> object
1027+ * is used, it size must be exactly equal to the number of rows
1028+ * in this <code>CachedRowSet</code> object.
1029+ *
1030+ * @param column an <code>int</code> indicating the column whose values
1031+ * are to be represented in a <code>Collection</code> object
1032+ * @return a <code>Collection</code> object that contains the values
1033+ * stored in the specified column of this <code>CachedRowSet</code>
1034+ * object
1035+ * @throws SQLException if an error occurs generating the collection or
1036+ * an invalid column id is provided
1037+ * @see #toCollection
1038+ * @see #toCollection(String)
1039+ */
1040+ public Collection<?> toCollection(int column) throws SQLException;
1041+
1042+ /**
1043+ * Converts the designated column in this <code>CachedRowSet</code> object
1044+ * to a <code>Collection</code> object. Implementations have some latitude in
1045+ * how they can represent this <code>Collection</code> object because of the
1046+ * abstract nature of the <code>Collection</code> framework.
1047+ * Each column value should be fully represented in either a
1048+ * general purpose <code>Collection</code> implementation or a specialized
1049+ * <code>Collection</code> implementation, such as a <code>Vector</code> object.
1050+ * An SQL <code>NULL</code> column value must be represented as a <code>null</code>
1051+ * in the Java programming language.
1052+ * <P>
1053+ * The standard reference implementation uses a <code>Vector</code> object
1054+ * to contain the column values, and it is expected
1055+ * that most implementations will do the same. If a <code>Vector</code> object
1056+ * is used, it size must be exactly equal to the number of rows
1057+ * in this <code>CachedRowSet</code> object.
1058+ *
1059+ * @param column a <code>String</code> object giving the name of the
1060+ * column whose values are to be represented in a collection
1061+ * @return a <code>Collection</code> object that contains the values
1062+ * stored in the specified column of this <code>CachedRowSet</code>
1063+ * object
1064+ * @throws SQLException if an error occurs generating the collection or
1065+ * an invalid column id is provided
1066+ * @see #toCollection
1067+ * @see #toCollection(int)
1068+ */
1069+ public Collection<?> toCollection(String column) throws SQLException;
1070+
1071+ /**
1072+ * Retrieves the <code>SyncProvider</code> implementation for this
1073+ * <code>CachedRowSet</code> object. Internally, this method is used by a rowset
1074+ * to trigger read or write actions between the rowset
1075+ * and the data source. For example, a rowset may need to get a handle
1076+ * on the the rowset reader (<code>RowSetReader</code> object) from the
1077+ * <code>SyncProvider</code> to allow the rowset to be populated.
1078+ * <pre>
1079+ * RowSetReader rowsetReader = null;
1080+ * SyncProvider provider =
1081+ * SyncFactory.getInstance("javax.sql.rowset.provider.RIOptimisticProvider");
1082+ * if (provider instanceof RIOptimisticProvider) {
1083+ * rowsetReader = provider.getRowSetReader();
1084+ * }
1085+ * </pre>
1086+ * Assuming <i>rowsetReader</i> is a private, accessible field within
1087+ * the rowset implementation, when an application calls the <code>execute</code>
1088+ * method, it in turn calls on the reader's <code>readData</code> method
1089+ * to populate the <code>RowSet</code> object.
1090+ *<pre>
1091+ * rowsetReader.readData((RowSetInternal)this);
1092+ * </pre>
1093+ * <P>
1094+ * In addition, an application can use the <code>SyncProvider</code> object
1095+ * returned by this method to call methods that return information about the
1096+ * <code>SyncProvider</code> object, including information about the
1097+ * vendor, version, provider identification, synchronization grade, and locks
1098+ * it currently has set.
1099+ *
1100+ * @return the <code>SyncProvider</code> object that was set when the rowset
1101+ * was instantiated, or if none was was set, the default provider
1102+ * @throws SQLException if an error occurs while returning the
1103+ * <code>SyncProvider</code> object
1104+ * @see #setSyncProvider
1105+ */
1106+ public SyncProvider getSyncProvider() throws SQLException;
1107+
1108+ /**
1109+ * Sets the <code>SyncProvider</code> objec for this <code>CachedRowSet</code>
1110+ * object to the one specified. This method
1111+ * allows the <code>SyncProvider</code> object to be reset.
1112+ * <P>
1113+ * A <code>CachedRowSet</code> implementation should always be instantiated
1114+ * with an available <code>SyncProvider</code> mechanism, but there are
1115+ * cases where resetting the <code>SyncProvider</code> object is desirable
1116+ * or necessary. For example, an application might want to use the default
1117+ * <code>SyncProvider</code> object for a time and then choose to use a provider
1118+ * that has more recently become available and better fits its needs.
1119+ * <P>
1120+ * Resetting the <code>SyncProvider</code> object causes the
1121+ * <code>RowSet</code> object to request a new <code>SyncProvider</code> implementation
1122+ * from the <code>SyncFactory</code>. This has the effect of resetting
1123+ * all previous connections and relationships with the originating
1124+ * data source and can potentially drastically change the synchronization
1125+ * behavior of a disconnected rowset.
1126+ *
1127+ * @param provider a <code>String</code> object giving the fully qualified class
1128+ * name of a <code>SyncProvider</code> implementation
1129+ * @throws SQLException if an error occurs while attempting to reset the
1130+ * <code>SyncProvider</code> implementation
1131+ * @see #getSyncProvider
1132+ */
1133+ public void setSyncProvider(String provider) throws SQLException;
1134+
1135+ /**
1136+ * Returns the number of rows in this <code>CachedRowSet</code>
1137+ * object.
1138+ *
1139+ * @return number of rows in the rowset
1140+ */
1141+ public int size();
1142+
1143+ /**
1144+ * Sets the metadata for this <code>CachedRowSet</code> object with
1145+ * the given <code>RowSetMetaData</code> object. When a
1146+ * <code>RowSetReader</code> object is reading the contents of a rowset,
1147+ * it creates a <code>RowSetMetaData</code> object and initializes
1148+ * it using the methods in the <code>RowSetMetaData</code> implementation.
1149+ * The reference implementation uses the <code>RowSetMetaDataImpl</code>
1150+ * class. When the reader has completed reading the rowset contents,
1151+ * this method is called internally to pass the <code>RowSetMetaData</code>
1152+ * object to the rowset.
1153+ *
1154+ * @param md a <code>RowSetMetaData</code> object containing
1155+ * metadata about the columns in this <code>CachedRowSet</code> object
1156+ * @throws SQLException if invalid metadata is supplied to the
1157+ * rowset
1158+ */
1159+ public void setMetaData(RowSetMetaData md) throws SQLException;
1160+
1161+ /**
1162+ * Returns a <code>ResultSet</code> object containing the original value of this
1163+ * <code>CachedRowSet</code> object.
1164+ * <P>
1165+ * The cursor for the <code>ResultSet</code>
1166+ * object should be positioned before the first row.
1167+ * In addition, the returned <code>ResultSet</code> object should have the following
1168+ * properties:
1169+ * <UL>
1170+ * <LI>ResultSet.TYPE_SCROLL_INSENSITIVE
1171+ * <LI>ResultSet.CONCUR_UPDATABLE
1172+ * </UL>
1173+ * <P>
1174+ * The original value for a <code>RowSet</code> object is the value it had before
1175+ * the last synchronization with the underlying data source. If there have been
1176+ * no synchronizations, the original value will be the value with which the
1177+ * <code>RowSet</code> object was populated. This method is called internally
1178+ * when an aplication calls the method <code>acceptChanges</code> and the
1179+ * <code>SyncProvider</code> object has been implemented to check for conflicts.
1180+ * If this is the case, the writer compares the original value with the value
1181+ * currently in the data source to check for conflicts.
1182+ *
1183+ * @return a <code>ResultSet</code> object that contains the original value for
1184+ * this <code>CachedRowSet</code> object
1185+ * @throws SQLException if an error occurs producing the
1186+ * <code>ResultSet</code> object
1187+ */
1188+ public ResultSet getOriginal() throws SQLException;
1189+
1190+ /**
1191+ * Returns a <code>ResultSet</code> object containing the original value for the
1192+ * current row only of this <code>CachedRowSet</code> object.
1193+ * <P>
1194+ * The cursor for the <code>ResultSet</code>
1195+ * object should be positioned before the first row.
1196+ * In addition, the returned <code>ResultSet</code> object should have the following
1197+ * properties:
1198+ * <UL>
1199+ * <LI>ResultSet.TYPE_SCROLL_INSENSITIVE
1200+ * <LI>ResultSet.CONCUR_UPDATABLE
1201+ * </UL>
1202+ *
1203+ * @return the original result set of the row
1204+ * @throws SQLException if there is no current row
1205+ * @see #setOriginalRow
1206+ */
1207+ public ResultSet getOriginalRow() throws SQLException;
1208+
1209+ /**
1210+ * Sets the current row in this <code>CachedRowSet</code> object as the original
1211+ * row.
1212+ * <P>
1213+ * This method is called internally after the any modified values in the current
1214+ * row have been synchronized with the data source. The current row must be tagged
1215+ * as no longer inserted, deleted or updated.
1216+ * <P>
1217+ * A call to <code>setOriginalRow</code> is irreversible.
1218+ *
1219+ * @throws SQLException if there is no current row or an error is
1220+ * encountered resetting the contents of the original row
1221+ * @see #getOriginalRow
1222+ */
1223+ public void setOriginalRow() throws SQLException;
1224+
1225+ /**
1226+ * Returns an identifier for the object (table) that was used to
1227+ * create this <code>CachedRowSet</code> object. This name may be set on multiple occasions,
1228+ * and the specification imposes no limits on how many times this
1229+ * may occur or whether standard implementations should keep track
1230+ * of previous table names.
1231+ *
1232+ * @return a <code>String</code> object giving the name of the table that is the
1233+ * source of data for this <code>CachedRowSet</code> object or <code>null</code>
1234+ * if no name has been set for the table
1235+ * @throws SQLException if an error is encountered returning the table name
1236+ * @see javax.sql.RowSetMetaData#getTableName
1237+ */
1238+ public String getTableName() throws SQLException;
1239+
1240+ /**
1241+ * Sets the identifier for the table from which this <code>CachedRowSet</code>
1242+ * object was derived to the given table name. The writer uses this name to
1243+ * determine which table to use when comparing the values in the data source with the
1244+ * <code>CachedRowSet</code> object's values during a synchronization attempt.
1245+ * The table identifier also indicates where modified values from this
1246+ * <code>CachedRowSet</code> object should be written.
1247+ * <P>
1248+ * The implementation of this <code>CachedRowSet</code> object may obtain the
1249+ * the name internally from the <code>RowSetMetaDataImpl</code> object.
1250+ *
1251+ * @param tabName a <code>String</code> object identifying the table from which this
1252+ <code>CachedRowSet</code> object was derived; cannot be <code>null</code>
1253+ * but may be an empty string
1254+ * @throws SQLException if an error is encountered naming the table or
1255+ * <i>tabName</i> is <code>null</code>
1256+ * @see javax.sql.RowSetMetaData#setTableName
1257+ * @see javax.sql.RowSetWriter
1258+ * @see javax.sql.rowset.spi.SyncProvider
1259+ */
1260+ public void setTableName(String tabName) throws SQLException;
1261+
1262+ /**
1263+ * Returns an array containing one or more column numbers indicating the columns
1264+ * that form a key that uniquely
1265+ * identifies a row in this <code>CachedRowSet</code> object.
1266+ *
1267+ * @return an array containing the column number or numbers that indicate which columns
1268+ * constitute a primary key
1269+ * for a row in this <code>CachedRowSet</code> object. This array should be
1270+ * empty if no columns are representative of a primary key.
1271+ * @throws SQLException if this <code>CachedRowSet</code> object is empty
1272+ * @see #setKeyColumns
1273+ * @see Joinable#getMatchColumnIndexes
1274+ * @see Joinable#getMatchColumnNames
1275+ */
1276+ public int[] getKeyColumns() throws SQLException;
1277+
1278+ /**
1279+ * Sets this <code>CachedRowSet</code> object's <code>keyCols</code>
1280+ * field with the given array of column numbers, which forms a key
1281+ * for uniquely identifying a row in this <code>CachedRowSet</code> object.
1282+ * <p>
1283+ * If a <code>CachedRowSet</code> object becomes part of a <code>JoinRowSet</code>
1284+ * object, the keys defined by this method and the resulting constraints are
1285+ * maintained if the columns designated as key columns also become match
1286+ * columns.
1287+ *
1288+ * @param keys an array of <code>int</code> indicating the columns that form
1289+ * a primary key for this <code>CachedRowSet</code> object; every
1290+ * element in the array must be greater than <code>0</code> and
1291+ * less than or equal to the number of columns in this rowset
1292+ * @throws SQLException if any of the numbers in the given array
1293+ * are not valid for this rowset
1294+ * @see #getKeyColumns
1295+ * @see Joinable#setMatchColumn(String)
1296+ * @see Joinable#setMatchColumn(int)
1297+
1298+ */
1299+ public void setKeyColumns(int[] keys) throws SQLException;
1300+
1301+
1302+ /**
1303+ * Returns a new <code>RowSet</code> object backed by the same data as
1304+ * that of this <code>CachedRowSet</code> object. In effect, both
1305+ * <code>CachedRowSet</code> objects have a cursor over the same data.
1306+ * As a result, any changes made by a duplicate are visible to the original
1307+ * and to any other duplicates, just as a change made by the original is visible
1308+ * to all of its duplicates. If a duplicate calls a method that changes the
1309+ * underlying data, the method it calls notifies all registered listeners
1310+ * just as it would when it is called by the original <code>CachedRowSet</code>
1311+ * object.
1312+ * <P>
1313+ * In addition, any <code>RowSet</code> object
1314+ * created by this method will have the same properties as this
1315+ * <code>CachedRowSet</code> object. For example, if this <code>CachedRowSet</code>
1316+ * object is read-only, all of its duplicates will also be read-only. If it is
1317+ * changed to be updatable, the duplicates also become updatable.
1318+ * <P>
1319+ * NOTE: If multiple threads access <code>RowSet</code> objects created from
1320+ * the <code>createShared()</code> method, the following behavior is specified
1321+ * to preserve shared data integrity: reads and writes of all
1322+ * shared <code>RowSet</code> objects should be made serially between each
1323+ * object and the single underlying tabular structure.
1324+ *
1325+ * @return a new shared <code>RowSet</code> object that has the same properties
1326+ * as this <code>CachedRowSet</code> object and that has a cursor over
1327+ * the same data
1328+ * @throws SQLException if an error occurs or cloning is not
1329+ * supported in the underlying platform
1330+ * @see javax.sql.RowSetEvent
1331+ * @see javax.sql.RowSetListener
1332+ */
1333+ public RowSet createShared() throws SQLException;
1334+
1335+ /**
1336+ * Creates a <code>RowSet</code> object that is a deep copy of the data in
1337+ * this <code>CachedRowSet</code> object. In contrast to
1338+ * the <code>RowSet</code> object generated from a <code>createShared</code>
1339+ * call, updates made to the copy of the original <code>RowSet</code> object
1340+ * must not be visible to the original <code>RowSet</code> object. Also, any
1341+ * event listeners that are registered with the original
1342+ * <code>RowSet</code> must not have scope over the new
1343+ * <code>RowSet</code> copies. In addition, any constraint restrictions
1344+ * established must be maintained.
1345+ *
1346+ * @return a new <code>RowSet</code> object that is a deep copy
1347+ * of this <code>CachedRowSet</code> object and is
1348+ * completely independent of this <code>CachedRowSet</code> object
1349+ * @throws SQLException if an error occurs in generating the copy of
1350+ * the of this <code>CachedRowSet</code> object
1351+ * @see #createShared
1352+ * @see #createCopySchema
1353+ * @see #createCopyNoConstraints
1354+ * @see javax.sql.RowSetEvent
1355+ * @see javax.sql.RowSetListener
1356+ */
1357+ public CachedRowSet createCopy() throws SQLException;
1358+
1359+ /**
1360+ * Creates a <code>CachedRowSet</code> object that is an empty copy of this
1361+ * <code>CachedRowSet</code> object. The copy
1362+ * must not contain any contents but only represent the table
1363+ * structure of the original <code>CachedRowSet</code> object. In addition, primary
1364+ * or foreign key constraints set in the originating <code>CachedRowSet</code> object must
1365+ * be equally enforced in the new empty <code>CachedRowSet</code> object.
1366+ * In contrast to
1367+ * the <code>RowSet</code> object generated from a <code>createShared</code> method
1368+ * call, updates made to a copy of this <code>CachedRowSet</code> object with the
1369+ * <code>createCopySchema</code> method must not be visible to it.
1370+ * <P>
1371+ * Applications can form a <code>WebRowSet</code> object from the <code>CachedRowSet</code>
1372+ * object returned by this method in order
1373+ * to export the <code>RowSet</code> schema definition to XML for future use.
1374+ *
1375+ * @throws SQLException if an error occurs in cloning the structure of this
1376+ * <code>CachedRowSet</code> object
1377+ * @see #createShared
1378+ * @see #createCopySchema
1379+ * @see #createCopyNoConstraints
1380+ * @see javax.sql.RowSetEvent
1381+ * @see javax.sql.RowSetListener
1382+ */
1383+ public CachedRowSet createCopySchema() throws SQLException;
1384+
1385+ /**
1386+ * Creates a <code>CachedRowSet</code> object that is a deep copy of
1387+ * this <code>CachedRowSet</code> object's data but is independent of it.
1388+ * In contrast to
1389+ * the <code>RowSet</code> object generated from a <code>createShared</code>
1390+ * method call, updates made to a copy of this <code>CachedRowSet</code> object
1391+ * must not be visible to it. Also, any
1392+ * event listeners that are registered with this
1393+ * <code>CachedRowSet</code> object must not have scope over the new
1394+ * <code>RowSet</code> object. In addition, any constraint restrictions
1395+ * established for this <code>CachedRowSet</code> object must <b>not</b> be maintained
1396+ * in the copy.
1397+ *
1398+ * @return a new <code>CachedRowSet</code> object that is a deep copy
1399+ * of this <code>CachedRowSet</code> object and is
1400+ * completely independent of this <code>CachedRowSet</code> object
1401+ * @throws SQLException if an error occurs in generating the copy of
1402+ * the of this <code>CachedRowSet</code> object
1403+ * @see #createCopy
1404+ * @see #createShared
1405+ * @see #createCopySchema
1406+ * @see javax.sql.RowSetEvent
1407+ * @see javax.sql.RowSetListener
1408+ */
1409+ public CachedRowSet createCopyNoConstraints() throws SQLException;
1410+
1411+ /**
1412+ * Retrieves the first warning reported by calls on this <code>RowSet</code> object.
1413+ * Subsequent warnings on this <code>RowSet</code> object will be chained to the
1414+ * <code>RowSetWarning</code> object that this method returns.
1415+ *
1416+ * The warning chain is automatically cleared each time a new row is read.
1417+ * This method may not be called on a RowSet object that has been closed;
1418+ * doing so will cause a <code>SQLException</code> to be thrown.
1419+ *
1420+ * @return RowSetWarning the first <code>RowSetWarning</code>
1421+ * object reported or null if there are none
1422+ * @throws SQLException if this method is called on a closed RowSet
1423+ * @see RowSetWarning
1424+ */
1425+ public RowSetWarning getRowSetWarnings() throws SQLException;
1426+
1427+ /**
1428+ * Retrieves a <code>boolean</code> indicating whether rows marked
1429+ * for deletion appear in the set of current rows. If <code>true</code> is
1430+ * returned, deleted rows are visible with the current rows. If
1431+ * <code>false</code> is returned, rows are not visible with the set of
1432+ * current rows. The default value is <code>false</code>.
1433+ * <P>
1434+ * Standard rowset implementations may choose to restrict this behavior
1435+ * due to security considerations or to better fit certain deployment
1436+ * scenarios. This is left as implementation defined and does not
1437+ * represent standard behavior.
1438+ * <P>
1439+ * Note: Allowing deleted rows to remain visible complicates the behavior
1440+ * of some standard JDBC <code>RowSet</code> Implementations methods.
1441+ * However, most rowset users can simply ignore this extra detail because
1442+ * only very specialized applications will likely want to take advantage of
1443+ * this feature.
1444+ *
1445+ * @return <code>true</code> if deleted rows are visible;
1446+ * <code>false</code> otherwise
1447+ * @throws SQLException if a rowset implementation is unable to
1448+ * to determine whether rows marked for deletion are visible
1449+ * @see #setShowDeleted
1450+ */
1451+ public boolean getShowDeleted() throws SQLException;
1452+
1453+ /**
1454+ * Sets the property <code>showDeleted</code> to the given
1455+ * <code>boolean</code> value, which determines whether
1456+ * rows marked for deletion appear in the set of current rows.
1457+ * If the value is set to <code>true</code>, deleted rows are immediately
1458+ * visible with the set of current rows. If the value is set to
1459+ * <code>false</code>, the deleted rows are set as invisible with the
1460+ * current set of rows.
1461+ * <P>
1462+ * Standard rowset implementations may choose to restrict this behavior
1463+ * due to security considerations or to better fit certain deployment
1464+ * scenarios. This is left as implementations defined and does not
1465+ * represent standard behavior.
1466+ *
1467+ * @param b <code>true</code> if deleted rows should be shown;
1468+ * <code>false</code> otherwise
1469+ * @exception SQLException if a rowset implementation is unable to
1470+ * to reset whether deleted rows should be visible
1471+ * @see #getShowDeleted
1472+ */
1473+ public void setShowDeleted(boolean b) throws SQLException;
1474+
1475+ /**
1476+ * Each <code>CachedRowSet</code> object's <code>SyncProvider</code> contains
1477+ * a <code>Connection</code> object from the <code>ResultSet</code> or JDBC
1478+ * properties passed to it's constructors. This method wraps the
1479+ * <code>Connection</code> commit method to allow flexible
1480+ * auto commit or non auto commit transactional control support.
1481+ * <p>
1482+ * Makes all changes that are performed by the <code>acceptChanges()</code>
1483+ * method since the previous commit/rollback permanent. This method should
1484+ * be used only when auto-commit mode has been disabled.
1485+ *
1486+ * @throws SQLException if a database access error occurs or this
1487+ * Connection object within this <code>CachedRowSet</code> is in auto-commit mode
1488+ * @see java.sql.Connection#setAutoCommit
1489+ */
1490+ public void commit() throws SQLException;
1491+
1492+ /**
1493+ * Each <code>CachedRowSet</code> object's <code>SyncProvider</code> contains
1494+ * a <code>Connection</code> object from the original <code>ResultSet</code>
1495+ * or JDBC properties passed to it.
1496+ * <p>
1497+ * Undoes all changes made in the current transaction. This method
1498+ * should be used only when auto-commit mode has been disabled.
1499+ *
1500+ * @throws SQLException if a database access error occurs or this Connection
1501+ * object within this <code>CachedRowSet</code> is in auto-commit mode.
1502+ */
1503+ public void rollback() throws SQLException;
1504+
1505+ /**
1506+ * Each <code>CachedRowSet</code> object's <code>SyncProvider</code> contains
1507+ * a <code>Connection</code> object from the original <code>ResultSet</code>
1508+ * or JDBC properties passed to it.
1509+ * <p>
1510+ * Undoes all changes made in the current transaction back to the last
1511+ * <code>Savepoint</code> transaction marker. This method should be used only
1512+ * when auto-commit mode has been disabled.
1513+ *
1514+ * @param s A <code>Savepoint</code> transaction marker
1515+ * @throws SQLException if a database access error occurs or this Connection
1516+ * object within this <code>CachedRowSet</code> is in auto-commit mode.
1517+ */
1518+ public void rollback(Savepoint s) throws SQLException;
1519+
1520+ /**
1521+ * Causes the <code>CachedRowSet</code> object's <code>SyncProvider</code>
1522+ * to commit the changes when <code>acceptChanges()</code> is called. If
1523+ * set to false, the changes will <b>not</b> be committed until one of the
1524+ * <code>CachedRowSet</code> interface transaction methods is called.
1525+ *
1526+ * @deprecated Because this field is final (it is part of an interface),
1527+ * its value cannot be changed.
1528+ * @see #commit
1529+ * @see #rollback
1530+ */
1531+ @Deprecated
1532+ public static final boolean COMMIT_ON_ACCEPT_CHANGES = true;
1533+
1534+ /**
1535+ * Notifies registered listeners that a RowSet object in the given RowSetEvent
1536+ * object has populated a number of additional rows. The <code>numRows</code> parameter
1537+ * ensures that this event will only be fired every <code>numRow</code>.
1538+ * <p>
1539+ * The source of the event can be retrieved with the method event.getSource.
1540+ *
1541+ * @param event a <code>RowSetEvent</code> object that contains the
1542+ * <code>RowSet</code> object that is the source of the events
1543+ * @param numRows when populating, the number of rows interval on which the
1544+ * <code>CachedRowSet</code> populated should fire; the default value
1545+ * is zero; cannot be less than <code>fetchSize</code> or zero
1546+ */
1547+ public void rowSetPopulated(RowSetEvent event, int numRows) throws SQLException;
1548+
1549+ /**
1550+ * Populates this <code>CachedRowSet</code> object with data from
1551+ * the given <code>ResultSet</code> object. While related to the <code>populate(ResultSet)</code>
1552+ * method, an additional parameter is provided to allow starting position within
1553+ * the <code>ResultSet</code> from where to populate the CachedRowSet
1554+ * instance.
1555+ * <P>
1556+ * This method can be used as an alternative to the <code>execute</code> method when an
1557+ * application has a connection to an open <code>ResultSet</code> object.
1558+ * Using the method <code>populate</code> can be more efficient than using
1559+ * the version of the <code>execute</code> method that takes no parameters
1560+ * because it does not open a new connection and re-execute this
1561+ * <code>CachedRowSet</code> object's command. Using the <code>populate</code>
1562+ * method is more a matter of convenience when compared to using the version
1563+ * of <code>execute</code> that takes a <code>ResultSet</code> object.
1564+ *
1565+ * @param startRow the position in the <code>ResultSet</code> from where to start
1566+ * populating the records in this <code>CachedRowSet</code>
1567+ * @param rs the <code>ResultSet</code> object containing the data
1568+ * to be read into this <code>CachedRowSet</code> object
1569+ * @throws SQLException if a null <code>ResultSet</code> object is supplied
1570+ * or this <code>CachedRowSet</code> object cannot
1571+ * retrieve the associated <code>ResultSetMetaData</code> object
1572+ * @see #execute
1573+ * @see #populate(ResultSet)
1574+ * @see java.sql.ResultSet
1575+ * @see java.sql.ResultSetMetaData
1576+ */
1577+ public void populate(ResultSet rs, int startRow) throws SQLException;
1578+
1579+ /**
1580+ * Sets the <code>CachedRowSet</code> object's page-size. A <code>CachedRowSet</code>
1581+ * may be configured to populate itself in page-size sized batches of rows. When
1582+ * either <code>populate()</code> or <code>execute()</code> are called, the
1583+ * <code>CachedRowSet</code> fetches an additional page according to the
1584+ * original SQL query used to populate the RowSet.
1585+ *
1586+ * @param size the page-size of the <code>CachedRowSet</code>
1587+ * @throws SQLException if an error occurs setting the <code>CachedRowSet</code>
1588+ * page size or if the page size is less than 0.
1589+ */
1590+ public void setPageSize(int size) throws SQLException;
1591+
1592+ /**
1593+ * Returns the page-size for the <code>CachedRowSet</code> object
1594+ *
1595+ * @return an <code>int</code> page size
1596+ */
1597+ public int getPageSize();
1598+
1599+ /**
1600+ * Increments the current page of the <code>CachedRowSet</code>. This causes
1601+ * the <code>CachedRowSet</code> implementation to fetch the next page-size
1602+ * rows and populate the RowSet, if remaining rows remain within scope of the
1603+ * original SQL query used to populated the RowSet.
1604+ *
1605+ * @return true if more pages exist; false if this is the last page
1606+ * @throws SQLException if an error occurs fetching the next page, or if this
1607+ * method is called prematurely before populate or execute.
1608+ */
1609+ public boolean nextPage() throws SQLException;
1610+
1611+ /**
1612+ * Decrements the current page of the <code>CachedRowSet</code>. This causes
1613+ * the <code>CachedRowSet</code> implementation to fetch the previous page-size
1614+ * rows and populate the RowSet. The amount of rows returned in the previous
1615+ * page must always remain within scope of the original SQL query used to
1616+ * populate the RowSet.
1617+ *
1618+ * @return true if the previous page is successfully retrieved; false if this
1619+ * is the first page.
1620+ * @throws SQLException if an error occurs fetching the previous page, or if
1621+ * this method is called prematurely before populate or execute.
1622+ */
1623+ public boolean previousPage() throws SQLException;
1624+
1625+}
java/pkg/javax/sql/rowset/FilteredRowSet.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/FilteredRowSet.java+160−0
@@ -0,0 +1,160 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import javax.naming.*;
31+import java.io.*;
32+import java.math.*;
33+
34+/**
35+ * The standard interface that all standard implementations of
36+ * <code>FilteredRowSet</code> must implement. The <code>FilteredRowSetImpl</code> class
37+ * provides the reference implementation which may be extended if required.
38+ * Alternatively, a vendor is free to implement its own version
39+ * by implementing this interface.
40+ *
41+ * <h3>1.0 Background</h3>
42+ *
43+ * There are occasions when a <code>RowSet</code> object has a need to provide a degree
44+ * of filtering to its contents. One possible solution is to provide
45+ * a query language for all standard <code>RowSet</code> implementations; however,
46+ * this is an impractical approach for lightweight components such as disconnected
47+ * <code>RowSet</code>
48+ * objects. The <code>FilteredRowSet</code> interface seeks to address this need
49+ * without supplying a heavyweight query language along with the processing that
50+ * such a query language would require.
51+ * <p>
52+ * A JDBC <code>FilteredRowSet</code> standard implementation implements the
53+ * <code>RowSet</code> interfaces and extends the
54+ * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup> class. The
55+ * <code>CachedRowSet</code> class provides a set of protected cursor manipulation
56+ * methods, which a <code>FilteredRowSet</code> implementation can override
57+ * to supply filtering support.
58+ *
59+ * <h3>2.0 Predicate Sharing</h3>
60+ *
61+ * If a <code>FilteredRowSet</code> implementation is shared using the
62+ * inherited <code>createShared</code> method in parent interfaces, the
63+ * <code>Predicate</code> should be shared without modification by all
64+ * <code>FilteredRowSet</code> instance clones.
65+ *
66+ * <h3>3.0 Usage</h3>
67+ * <p>
68+ * By implementing a <code>Predicate</code> (see example in <a href="Predicate.html">Predicate</a>
69+ * class JavaDoc), a <code>FilteredRowSet</code> could then be used as described
70+ * below.
71+ * <P>
72+ * <code>
73+ * <pre>
74+ * FilteredRowSet frs = new FilteredRowSetImpl();
75+ * frs.populate(rs);
76+ *
77+ * Range name = new Range("Alpha", "Bravo", "columnName");
78+ * frs.setFilter(name);
79+ *
80+ * frs.next() // only names from "Alpha" to "Bravo" will be returned
81+ * </pre>
82+ * </code>
83+ * In the example above, we initialize a <code>Range</code> object which
84+ * implements the <code>Predicate</code> interface. This object expresses
85+ * the following constraints: All rows outputted or modified from this
86+ * <code>FilteredRowSet</code> object must fall between the values 'Alpha' and
87+ * 'Bravo' both values inclusive, in the column 'columnName'. If a filter is
88+ * applied to a <code>FilteredRowSet</code> object that contains no data that
89+ * falls within the range of the filter, no rows are returned.
90+ * <p>
91+ * This framework allows multiple classes implementing predicates to be
92+ * used in combination to achieved the required filtering result with
93+ * out the need for query language processing.
94+ * <p>
95+ * <h3>4.0 Updating a <code>FilteredRowSet</code> Object</h3>
96+ * The predicate set on a <code>FilteredRowSet</code> object
97+ * applies a criterion on all rows in a
98+ * <code>RowSet</code> object to manage a subset of rows in a <code>RowSet</code>
99+ * object. This criterion governs the subset of rows that are visible and also
100+ * defines which rows can be modified, deleted or inserted.
101+ * <p>
102+ * Therefore, the predicate set on a <code>FilteredRowSet</code> object must be
103+ * considered as bi-directional and the set criterion as the gating mechanism
104+ * for all views and updates to the <code>FilteredRowSet</code> object. Any attempt
105+ * to update the <code>FilteredRowSet</code> that violates the criterion will
106+ * result in a <code>SQLException</code> object being thrown.
107+ * <p>
108+ * The <code>FilteredRowSet</code> range criterion can be modified by applying
109+ * a new <code>Predicate</code> object to the <code>FilteredRowSet</code>
110+ * instance at any time. This is possible if no additional references to the
111+ * <code>FilteredRowSet</code> object are detected. A new filter has has an
112+ * immediate effect on criterion enforcement within the
113+ * <code>FilteredRowSet</code> object, and all subsequent views and updates will be
114+ * subject to similar enforcement.
115+ * <p>
116+ * <h3>5.0 Behavior of Rows Outside the Filter</h3>
117+ * Rows that fall outside of the filter set on a <code>FilteredRowSet</code>
118+ * object cannot be modified until the filter is removed or a
119+ * new filter is applied.
120+ * <p>
121+ * Furthermore, only rows that fall within the bounds of a filter will be
122+ * synchronized with the data source.
123+ *
124+ * @author Jonathan Bruce
125+ */
126+
127+public interface FilteredRowSet extends WebRowSet {
128+
129+ /**
130+ * Applies the given <code>Predicate</code> object to this
131+ * <code>FilteredRowSet</code>
132+ * object. The filter applies controls both to inbound and outbound views,
133+ * constraining which rows are visible and which
134+ * rows can be manipulated.
135+ * <p>
136+ * A new <code>Predicate</code> object may be set at any time. This has the
137+ * effect of changing constraints on the <code>RowSet</code> object's data.
138+ * In addition, modifying the filter at runtime presents issues whereby
139+ * multiple components may be operating on one <code>FilteredRowSet</code> object.
140+ * Application developers must take responsibility for managing multiple handles
141+ * to <code>FilteredRowSet</code> objects when their underling <code>Predicate</code>
142+ * objects change.
143+ *
144+ * @param p a <code>Predicate</code> object defining the filter for this
145+ * <code>FilteredRowSet</code> object. Setting a <b>null</b> value
146+ * will clear the predicate, allowing all rows to become visible.
147+ *
148+ * @throws SQLException if an error occurs when setting the
149+ * <code>Predicate</code> object
150+ */
151+ public void setFilter(Predicate p) throws SQLException;
152+
153+ /**
154+ * Retrieves the active filter for this <code>FilteredRowSet</code> object.
155+ *
156+ * @return p the <code>Predicate</code> for this <code>FilteredRowSet</code>
157+ * object; <code>null</code> if no filter has been set.
158+ */
159+ public Predicate getFilter() ;
160+}
java/pkg/javax/sql/rowset/JdbcRowSet.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/JdbcRowSet.java+287−0
@@ -0,0 +1,287 @@
1+/*
2+ * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import javax.naming.*;
31+import java.io.*;
32+import java.math.*;
33+import java.io.*;
34+
35+/**
36+ * The standard interface that all standard implementations of
37+ * <code>JdbcRowSet</code> must implement.
38+ *
39+ * <h3>1.0 Overview</h3>
40+ * A wrapper around a <code>ResultSet</code> object that makes it possible
41+ * to use the result set as a JavaBeans<sup><font size=-2>TM</font></sup>
42+ * component. Thus, a <code>JdbcRowSet</code> object can be one of the Beans that
43+ * a tool makes available for composing an application. Because
44+ * a <code>JdbcRowSet</code> is a connected rowset, that is, it continually
45+ * maintains its connection to a database using a JDBC technology-enabled
46+ * driver, it also effectively makes the driver a JavaBeans component.
47+ * <P>
48+ * Because it is always connected to its database, an instance of
49+ * <code>JdbcRowSet</code>
50+ * can simply take calls invoked on it and in turn call them on its
51+ * <code>ResultSet</code> object. As a consequence, a result set can, for
52+ * example, be a component in a Swing application.
53+ * <P>
54+ * Another advantage of a <code>JdbcRowSet</code> object is that it can be
55+ * used to make a <code>ResultSet</code> object scrollable and updatable. All
56+ * <code>RowSet</code> objects are by default scrollable and updatable. If
57+ * the driver and database being used do not support scrolling and/or updating
58+ * of result sets, an application can populate a <code>JdbcRowSet</code> object
59+ * with the data of a <code>ResultSet</code> object and then operate on the
60+ * <code>JdbcRowSet</code> object as if it were the <code>ResultSet</code>
61+ * object.
62+ * <P>
63+ * <h3>2.0 Creating a <code>JdbcRowSet</code> Object</h3>
64+ * The reference implementation of the <code>JdbcRowSet</code> interface,
65+ * <code>JdbcRowSetImpl</code>, provides an implementation of
66+ * the default constructor. A new instance is initialized with
67+ * default values, which can be set with new values as needed. A
68+ * new instance is not really functional until its <code>execute</code>
69+ * method is called. In general, this method does the following:
70+ * <UL>
71+ * <LI> establishes a connection with a database
72+ * <LI> creates a <code>PreparedStatement</code> object and sets any of its
73+ * placeholder parameters
74+ * <LI> executes the statement to create a <code>ResultSet</code> object
75+ * </UL>
76+ * If the <code>execute</code> method is successful, it will set the
77+ * appropriate private <code>JdbcRowSet</code> fields with the following:
78+ * <UL>
79+ * <LI> a <code>Connection</code> object -- the connection between the rowset
80+ * and the database
81+ * <LI> a <code>PreparedStatement</code> object -- the query that produces
82+ * the result set
83+ * <LI> a <code>ResultSet</code> object -- the result set that the rowset's
84+ * command produced and that is being made, in effect, a JavaBeans
85+ * component
86+ * </UL>
87+ * If these fields have not been set, meaning that the <code>execute</code>
88+ * method has not executed successfully, no methods other than
89+ * <code>execute</code> and <code>close</code> may be called on the
90+ * rowset. All other public methods will throw an exception.
91+ * <P>
92+ * Before calling the <code>execute</code> method, however, the command
93+ * and properties needed for establishing a connection must be set.
94+ * The following code fragment creates a <code>JdbcRowSetImpl</code> object,
95+ * sets the command and connection properties, sets the placeholder parameter,
96+ * and then invokes the method <code>execute</code>.
97+ * <PRE>
98+ * JdbcRowSetImpl jrs = new JdbcRowSetImpl();
99+ * jrs.setCommand("SELECT * FROM TITLES WHERE TYPE = ?");
100+ * jrs.setURL("jdbc:myDriver:myAttribute");
101+ * jrs.setUsername("cervantes");
102+ * jrs.setPassword("sancho");
103+ * jrs.setString(1, "BIOGRAPHY");
104+ * jrs.execute();
105+ * </PRE>
106+ * The variable <code>jrs</code> now represents an instance of
107+ * <code>JdbcRowSetImpl</code> that is a thin wrapper around the
108+ * <code>ResultSet</code> object containing all the rows in the
109+ * table <code>TITLES</code> where the type of book is biography.
110+ * At this point, operations called on <code>jrs</code> will
111+ * affect the rows in the result set, which is effectively a JavaBeans
112+ * component.
113+ * <P>
114+ * The implementation of the <code>RowSet</code> method <code>execute</code> in the
115+ * <code>JdbcRowSet</code> reference implementation differs from that in the
116+ * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
117+ * reference implementation to account for the different
118+ * requirements of connected and disconnected <code>RowSet</code> objects.
119+ * <p>
120+ *
121+ * @author Jonathan Bruce
122+ */
123+
124+public interface JdbcRowSet extends RowSet, Joinable {
125+
126+ /**
127+ * Retrieves a <code>boolean</code> indicating whether rows marked
128+ * for deletion appear in the set of current rows. If <code>true</code> is
129+ * returned, deleted rows are visible with the current rows. If
130+ * <code>false</code> is returned, rows are not visible with the set of
131+ * current rows. The default value is <code>false</code>.
132+ * <P>
133+ * Standard rowset implementations may choose to restrict this behavior
134+ * for security considerations or for certain deployment
135+ * scenarios. The visibility of deleted rows is implementation-defined
136+ * and does not represent standard behavior.
137+ * <P>
138+ * Note: Allowing deleted rows to remain visible complicates the behavior
139+ * of some standard JDBC <code>RowSet</code> implementations methods.
140+ * However, most rowset users can simply ignore this extra detail because
141+ * only very specialized applications will likely want to take advantage of
142+ * this feature.
143+ *
144+ * @return <code>true</code> if deleted rows are visible;
145+ * <code>false</code> otherwise
146+ * @exception SQLException if a rowset implementation is unable to
147+ * to determine whether rows marked for deletion remain visible
148+ * @see #setShowDeleted
149+ */
150+ public boolean getShowDeleted() throws SQLException;
151+
152+ /**
153+ * Sets the property <code>showDeleted</code> to the given
154+ * <code>boolean</code> value. This property determines whether
155+ * rows marked for deletion continue to appear in the set of current rows.
156+ * If the value is set to <code>true</code>, deleted rows are immediately
157+ * visible with the set of current rows. If the value is set to
158+ * <code>false</code>, the deleted rows are set as invisible with the
159+ * current set of rows.
160+ * <P>
161+ * Standard rowset implementations may choose to restrict this behavior
162+ * for security considerations or for certain deployment
163+ * scenarios. This is left as implementation-defined and does not
164+ * represent standard behavior.
165+ *
166+ * @param b <code>true</code> if deleted rows should be shown;
167+ * <code>false</code> otherwise
168+ * @exception SQLException if a rowset implementation is unable to
169+ * to reset whether deleted rows should be visible
170+ * @see #getShowDeleted
171+ */
172+ public void setShowDeleted(boolean b) throws SQLException;
173+
174+ /**
175+ * Retrieves the first warning reported by calls on this <code>JdbcRowSet</code>
176+ * object.
177+ * If a second warning was reported on this <code>JdbcRowSet</code> object,
178+ * it will be chained to the first warning and can be retrieved by
179+ * calling the method <code>RowSetWarning.getNextWarning</code> on the
180+ * first warning. Subsequent warnings on this <code>JdbcRowSet</code>
181+ * object will be chained to the <code>RowSetWarning</code> objects
182+ * returned by the method <code>RowSetWarning.getNextWarning</code>.
183+ *
184+ * The warning chain is automatically cleared each time a new row is read.
185+ * This method may not be called on a <code>RowSet</code> object
186+ * that has been closed;
187+ * doing so will cause an <code>SQLException</code> to be thrown.
188+ * <P>
189+ * Because it is always connected to its data source, a <code>JdbcRowSet</code>
190+ * object can rely on the presence of active
191+ * <code>Statement</code>, <code>Connection</code>, and <code>ResultSet</code>
192+ * instances. This means that applications can obtain additional
193+ * <code>SQLWarning</code>
194+ * notifications by calling the <code>getNextWarning</code> methods that
195+ * they provide.
196+ * Disconnected <code>Rowset</code> objects, such as a
197+ * <code>CachedRowSet</code> object, do not have access to
198+ * these <code>getNextWarning</code> methods.
199+ *
200+ * @return the first <code>RowSetWarning</code>
201+ * object reported on this <code>JdbcRowSet</code> object
202+ * or <code>null</code> if there are none
203+ * @throws SQLException if this method is called on a closed
204+ * <code>JdbcRowSet</code> object
205+ * @see RowSetWarning
206+ */
207+ public RowSetWarning getRowSetWarnings() throws SQLException;
208+
209+ /**
210+ * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
211+ * the <code>ResultSet</code> or JDBC properties passed to it's constructors.
212+ * This method wraps the <code>Connection</code> commit method to allow flexible
213+ * auto commit or non auto commit transactional control support.
214+ * <p>
215+ * Makes all changes made since the previous commit/rollback permanent
216+ * and releases any database locks currently held by this Connection
217+ * object. This method should be used only when auto-commit mode has
218+ * been disabled.
219+ *
220+ * @throws SQLException if a database access error occurs or this
221+ * Connection object within this <code>JdbcRowSet</code> is in auto-commit mode
222+ * @see java.sql.Connection#setAutoCommit
223+ */
224+ public void commit() throws SQLException;
225+
226+
227+ /**
228+ * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
229+ * the original <code>ResultSet</code> or JDBC properties passed to it. This
230+ * method wraps the <code>Connection</code>'s <code>getAutoCommit</code> method
231+ * to allow an application to determine the <code>JdbcRowSet</code> transaction
232+ * behavior.
233+ * <p>
234+ * Sets this connection's auto-commit mode to the given state. If a
235+ * connection is in auto-commit mode, then all its SQL statements will
236+ * be executed and committed as individual transactions. Otherwise, its
237+ * SQL statements are grouped into transactions that are terminated by a
238+ * call to either the method commit or the method rollback. By default,
239+ * new connections are in auto-commit mode.
240+ *
241+ * @throws SQLException if a database access error occurs
242+ * @see java.sql.Connection#getAutoCommit()
243+ */
244+ public boolean getAutoCommit() throws SQLException;
245+
246+
247+ /**
248+ * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
249+ * the original <code>ResultSet</code> or JDBC properties passed to it. This
250+ * method wraps the <code>Connection</code>'s <code>getAutoCommit</code> method
251+ * to allow an application to set the <code>JdbcRowSet</code> transaction behavior.
252+ * <p>
253+ * Sets the current auto-commit mode for this <code>Connection</code> object.
254+ *
255+ * @throws SQLException if a database access error occurs
256+ * @see java.sql.Connection#setAutoCommit(boolean)
257+ */
258+ public void setAutoCommit(boolean autoCommit) throws SQLException;
259+
260+ /**
261+ * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
262+ * the original <code>ResultSet</code> or JDBC properties passed to it.
263+ * Undoes all changes made in the current transaction and releases any
264+ * database locks currently held by this <code>Connection</code> object. This method
265+ * should be used only when auto-commit mode has been disabled.
266+ *
267+ * @throws SQLException if a database access error occurs or this <code>Connection</code>
268+ * object within this <code>JdbcRowSet</code> is in auto-commit mode.
269+ * @see #rollback(Savepoint)
270+ */
271+ public void rollback() throws SQLException;
272+
273+
274+ /**
275+ * Each <code>JdbcRowSet</code> contains a <code>Connection</code> object from
276+ * the original <code>ResultSet</code> or JDBC properties passed to it.
277+ * Undoes all changes made in the current transaction to the last set savepoint
278+ * and releases any database locks currently held by this <code>Connection</code>
279+ * object. This method should be used only when auto-commit mode has been disabled.
280+ *
281+ * @throws SQLException if a database access error occurs or this <code>Connection</code>
282+ * object within this <code>JdbcRowSet</code> is in auto-commit mode.
283+ * @see #rollback
284+ */
285+ public void rollback(Savepoint s) throws SQLException;
286+
287+}
java/pkg/javax/sql/rowset/JoinRowSet.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/JoinRowSet.java+537−0
@@ -0,0 +1,537 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import javax.naming.*;
31+import java.io.*;
32+import java.math.*;
33+import java.util.*;
34+
35+import javax.sql.rowset.*;
36+
37+/**
38+ * The <code>JoinRowSet</code> interface provides a mechanism for combining related
39+ * data from different <code>RowSet</code> objects into one <code>JoinRowSet</code>
40+ * object, which represents an SQL <code>JOIN</code>.
41+ * In other words, a <code>JoinRowSet</code> object acts as a
42+ * container for the data from <code>RowSet</code> objects that form an SQL
43+ * <code>JOIN</code> relationship.
44+ * <P>
45+ * The <code>Joinable</code> interface provides the methods for setting,
46+ * retrieving, and unsetting a match column, the basis for
47+ * establishing an SQL <code>JOIN</code> relationship. The match column may
48+ * alternatively be set by supplying it to the appropriate version of the
49+ * <code>JointRowSet</code> method <code>addRowSet</code>.
50+ * <P>
51+ * <p>
52+ * <h3>1.0 Overview</h3>
53+ * Disconnected <code>RowSet</code> objects (<code>CachedRowSet</code> objects
54+ * and implementations extending the <code>CachedRowSet</code> interface)
55+ * do not have a standard way to establish an SQL <code>JOIN</code> between
56+ * <code>RowSet</code> objects without the expensive operation of
57+ * reconnecting to the data source. The <code>JoinRowSet</code>
58+ * interface is specifically designed to address this need.
59+ * <P>
60+ * Any <code>RowSet</code> object
61+ * can be added to a <code>JoinRowSet</code> object to become
62+ * part of an SQL <code>JOIN</code> relationship. This means that both connected
63+ * and disconnected <code>RowSet</code> objects can be part of a <code>JOIN</code>.
64+ * <code>RowSet</code> objects operating in a connected environment
65+ * (<code>JdbcRowSet</code> objects) are
66+ * encouraged to use the database to which they are already
67+ * connected to establish SQL <code>JOIN</code> relationships between
68+ * tables directly. However, it is possible for a
69+ * <code>JdbcRowSet</code> object to be added to a <code>JoinRowSet</code> object
70+ * if necessary.
71+ * <P>
72+ * Any number of <code>RowSet</code> objects can be added to an
73+ * instance of <code>JoinRowSet</code> provided that they
74+ * can be related in an SQL <code>JOIN</code>.
75+ * By definition, the SQL <code>JOIN</code> statement is used to
76+ * combine the data contained in two or more relational database tables based
77+ * upon a common attribute. The <code>Joinable</code> interface provides the methods
78+ * for establishing a common attribute, which is done by setting a
79+ * <i>match column</i>. The match column commonly coincides with
80+ * the primary key, but there is
81+ * no requirement that the match column be the same as the primary key.
82+ * By establishing and then enforcing column matches,
83+ * a <code>JoinRowSet</code> object establishes <code>JOIN</code> relationships
84+ * between <code>RowSet</code> objects without the assistance of an available
85+ * relational database.
86+ * <P>
87+ * The type of <code>JOIN</code> to be established is determined by setting
88+ * one of the <code>JoinRowSet</code> constants using the method
89+ * <code>setJoinType</code>. The following SQL <code>JOIN</code> types can be set:
90+ * <UL>
91+ * <LI><code>CROSS_JOIN</code>
92+ * <LI><code>FULL_JOIN</code>
93+ * <LI><code>INNER_JOIN</code> - the default if no <code>JOIN</code> type has been set
94+ * <LI><code>LEFT_OUTER_JOIN</code>
95+ * <LI><code>RIGHT_OUTER_JOIN</code>
96+ * </UL>
97+ * Note that if no type is set, the <code>JOIN</code> will automatically be an
98+ * inner join. The comments for the fields in the
99+ * <code>JoinRowSet</code> interface explain these <code>JOIN</code> types, which are
100+ * standard SQL <code>JOIN</code> types.
101+ * <P>
102+ * <h3>2.0 Using a <code>JoinRowSet</code> Object for Creating a <code>JOIN</code></h3>
103+ * When a <code>JoinRowSet</code> object is created, it is empty.
104+ * The first <code>RowSet</code> object to be added becomes the basis for the
105+ * <code>JOIN</code> relationship.
106+ * Applications must determine which column in each of the
107+ * <code>RowSet</code> objects to be added to the <code>JoinRowSet</code> object
108+ * should be the match column. All of the
109+ * <code>RowSet</code> objects must contain a match column, and the values in
110+ * each match column must be ones that can be compared to values in the other match
111+ * columns. The columns do not have to have the same name, though they often do,
112+ * and they do not have to store the exact same data type as long as the data types
113+ * can be compared.
114+ * <P>
115+ * A match column can be be set in two ways:
116+ * <ul>
117+ * <li>By calling the <code>Joinable</code> method <code>setMatchColumn</code><br>
118+ * This is the only method that can set the match column before a <code>RowSet</code>
119+ * object is added to a <code>JoinRowSet</code> object. The <code>RowSet</code> object
120+ * must have implemented the <code>Joinable</code> interface in order to use the method
121+ * <code>setMatchColumn</code>. Once the match column value
122+ * has been set, this method can be used to reset the match column at any time.
123+ * <li>By calling one of the versions of the <code>JoinRowSet</code> method
124+ * <code>addRowSet</code> that takes a column name or number (or an array of
125+ * column names or numbers)<BR>
126+ * Four of the five <code>addRowSet</code> methods take a match column as a parameter.
127+ * These four methods set or reset the match column at the time a <code>RowSet</code>
128+ * object is being added to a <code>JoinRowSet</code> object.
129+ * </ul>
130+ * <h3>3.0 Sample Usage</h3>
131+ * <p>
132+ * The following code fragment adds two <code>CachedRowSet</code>
133+ * objects to a <code>JoinRowSet</code> object. Note that in this example,
134+ * no SQL <code>JOIN</code> type is set, so the default <code>JOIN</code> type,
135+ * which is <i>INNER_JOIN</i>, is established.
136+ * <p>
137+ * In the following code fragment, the table <code>EMPLOYEES</code>, whose match
138+ * column is set to the first column (<code>EMP_ID</code>), is added to the
139+ * <code>JoinRowSet</code> object <i>jrs</i>. Then
140+ * the table <code>ESSP_BONUS_PLAN</code>, whose match column is likewise
141+ * the <code>EMP_ID</code> column, is added. When this second
142+ * table is added to <i>jrs</i>, only the rows in
143+ * <code>ESSP_BONUS_PLAN</code> whose <code>EMP_ID</code> value matches an
144+ * <code>EMP_ID</code> value in the <code>EMPLOYEES</code> table are added.
145+ * In this case, everyone in the bonus plan is an employee, so all of the rows
146+ * in the table <code>ESSP_BONUS_PLAN</code> are added to the <code>JoinRowSet</code>
147+ * object. In this example, both <code>CachedRowSet</code> objects being added
148+ * have implemented the <code>Joinable</code> interface and can therefore call
149+ * the <code>Joinable</code> method <code>setMatchColumn</code>.
150+ * <PRE>
151+ * JoinRowSet jrs = new JoinRowSetImpl();
152+ *
153+ * ResultSet rs1 = stmt.executeQuery("SELECT * FROM EMPLOYEES");
154+ * CachedRowSet empl = new CachedRowSetImpl();
155+ * empl.populate(rs1);
156+ * empl.setMatchColumn(1);
157+ * jrs.addRowSet(empl);
158+ *
159+ * ResultSet rs2 = stmt.executeQuery("SELECT * FROM ESSP_BONUS_PLAN");
160+ * CachedRowSet bonus = new CachedRowSetImpl();
161+ * bonus.populate(rs2);
162+ * bonus.setMatchColumn(1); // EMP_ID is the first column
163+ * jrs.addRowSet(bonus);
164+ * </PRE>
165+ * <P>
166+ * At this point, <i>jrs</i> is an inside JOIN of the two <code>RowSet</code> objects
167+ * based on their <code>EMP_ID</code> columns. The application can now browse the
168+ * combined data as if it were browsing one single <code>RowSet</code> object.
169+ * Because <i>jrs</i> is itself a <code>RowSet</code> object, an application can
170+ * navigate or modify it using <code>RowSet</code> methods.
171+ * <PRE>
172+ * jrs.first();
173+ * int employeeID = jrs.getInt(1);
174+ * String employeeName = jrs.getString(2);
175+ * </PRE>
176+ * <P>
177+ * Note that because the SQL <code>JOIN</code> must be enforced when an application
178+ * adds a second or subsequent <code>RowSet</code> object, there
179+ * may be an initial degradation in performance while the <code>JOIN</code> is
180+ * being performed.
181+ * <P>
182+ * The following code fragment adds an additional <code>CachedRowSet</code> object.
183+ * In this case, the match column (<code>EMP_ID</code>) is set when the
184+ * <code>CachedRowSet</code> object is added to the <code>JoinRowSet</code> object.
185+ * <PRE>
186+ * ResultSet rs3 = stmt.executeQuery("SELECT * FROM 401K_CONTRIB");
187+ * CachedRowSet fourO1k = new CachedRowSetImpl();
188+ * four01k.populate(rs3);
189+ * jrs.addRowSet(four01k, 1);
190+ * </PRE>
191+ * <P>
192+ * The <code>JoinRowSet</code> object <i>jrs</i> now contains values from all three
193+ * tables. The data in each row in <i>four01k</i> in which the value for the
194+ * <code>EMP_ID</code> column matches a value for the <code>EMP_ID</code> column
195+ * in <i>jrs</i> has been added to <i>jrs</i>.
196+ * <P>
197+ * <h3>4.0 <code>JoinRowSet</code> Methods</h3>
198+ * The <code>JoinRowSet</code> interface supplies several methods for adding
199+ * <code>RowSet</code> objects and for getting information about the
200+ * <code>JoinRowSet</code> object.
201+ * <UL>
202+ * <LI>Methods for adding one or more <code>RowSet</code> objects<BR>
203+ * These methods allow an application to add one <code>RowSet</code> object
204+ * at a time or to add multiple <code>RowSet</code> objects at one time. In
205+ * either case, the methods may specify the match column for each
206+ * <code>RowSet</code> object being added.
207+ * <LI>Methods for getting information<BR>
208+ * One method retrieves the <code>RowSet</code> objects in the
209+ * <code>JoinRowSet</code> object, and another method retrieves the
210+ * <code>RowSet</code> names. A third method retrieves either the SQL
211+ * <code>WHERE</code> clause used behind the scenes to form the
212+ * <code>JOIN</code> or a text description of what the <code>WHERE</code>
213+ * clause does.
214+ * <LI>Methods related to the type of <code>JOIN</code><BR>
215+ * One method sets the <code>JOIN</code> type, and five methods find out whether
216+ * the <code>JoinRowSet</code> object supports a given type.
217+ * <LI>A method to make a separate copy of the <code>JoinRowSet</code> object<BR>
218+ * This method creates a copy that can be persisted to the data source.
219+ * </UL>
220+ * <P>
221+ */
222+
223+public interface JoinRowSet extends WebRowSet {
224+
225+ /**
226+ * Adds the given <code>RowSet</code> object to this <code>JoinRowSet</code>
227+ * object. If the <code>RowSet</code> object
228+ * is the first to be added to this <code>JoinRowSet</code>
229+ * object, it forms the basis of the <code>JOIN</code> relationship to be
230+ * established.
231+ * <P>
232+ * This method should be used only when the given <code>RowSet</code>
233+ * object already has a match column that was set with the <code>Joinable</code>
234+ * method <code>setMatchColumn</code>.
235+ * <p>
236+ * Note: A <code>Joinable</code> object is any <code>RowSet</code> object
237+ * that has implemented the <code>Joinable</code> interface.
238+ *
239+ * @param rowset the <code>RowSet</code> object that is to be added to this
240+ * <code>JoinRowSet</code> object; it must implement the
241+ * <code>Joinable</code> interface and have a match column set
242+ * @throws SQLException if (1) an empty rowset is added to the to this
243+ * <code>JoinRowSet</code> object, (2) a match column has not been
244+ * set for <i>rowset</i>, or (3) <i>rowset</i>
245+ * violates the active <code>JOIN</code>
246+ * @see Joinable#setMatchColumn
247+ */
248+ public void addRowSet(Joinable rowset) throws SQLException;
249+
250+ /**
251+ * Adds the given <code>RowSet</code> object to this <code>JoinRowSet</code>
252+ * object and sets the designated column as the match column for
253+ * the <code>RowSet</code> object. If the <code>RowSet</code> object
254+ * is the first to be added to this <code>JoinRowSet</code>
255+ * object, it forms the basis of the <code>JOIN</code> relationship to be
256+ * established.
257+ * <P>
258+ * This method should be used when <i>RowSet</i> does not already have a match
259+ * column set.
260+ *
261+ * @param rowset the <code>RowSet</code> object that is to be added to this
262+ * <code>JoinRowSet</code> object; it may implement the
263+ * <code>Joinable</code> interface
264+ * @param columnIdx an <code>int</code> that identifies the column to become the
265+ * match column
266+ * @throws SQLException if (1) <i>rowset</i> is an empty rowset or
267+ * (2) <i>rowset</i> violates the active <code>JOIN</code>
268+ * @see Joinable#unsetMatchColumn
269+ */
270+ public void addRowSet(RowSet rowset, int columnIdx) throws SQLException;
271+
272+ /**
273+ * Adds <i>rowset</i> to this <code>JoinRowSet</code> object and
274+ * sets the designated column as the match column. If <i>rowset</i>
275+ * is the first to be added to this <code>JoinRowSet</code>
276+ * object, it forms the basis for the <code>JOIN</code> relationship to be
277+ * established.
278+ * <P>
279+ * This method should be used when the given <code>RowSet</code> object
280+ * does not already have a match column.
281+ *
282+ * @param rowset the <code>RowSet</code> object that is to be added to this
283+ * <code>JoinRowSet</code> object; it may implement the
284+ * <code>Joinable</code> interface
285+ * @param columnName the <code>String</code> object giving the name of the
286+ * column to be set as the match column
287+ * @throws SQLException if (1) <i>rowset</i> is an empty rowset or
288+ * (2) the match column for <i>rowset</i> does not satisfy the
289+ * conditions of the <code>JOIN</code>
290+ */
291+ public void addRowSet(RowSet rowset,
292+ String columnName) throws SQLException;
293+
294+ /**
295+ * Adds one or more <code>RowSet</code> objects contained in the given
296+ * array of <code>RowSet</code> objects to this <code>JoinRowSet</code>
297+ * object and sets the match column for
298+ * each of the <code>RowSet</code> objects to the match columns
299+ * in the given array of column indexes. The first element in
300+ * <i>columnIdx</i> is set as the match column for the first
301+ * <code>RowSet</code> object in <i>rowset</i>, the second element of
302+ * <i>columnIdx</i> is set as the match column for the second element
303+ * in <i>rowset</i>, and so on.
304+ * <P>
305+ * The first <code>RowSet</code> object added to this <code>JoinRowSet</code>
306+ * object forms the basis for the <code>JOIN</code> relationship.
307+ * <P>
308+ * This method should be used when the given <code>RowSet</code> object
309+ * does not already have a match column.
310+ *
311+ * @param rowset an array of one or more <code>RowSet</code> objects
312+ * to be added to the <code>JOIN</code>; it may implement the
313+ * <code>Joinable</code> interface
314+ * @param columnIdx an array of <code>int</code> values indicating the index(es)
315+ * of the columns to be set as the match columns for the <code>RowSet</code>
316+ * objects in <i>rowset</i>
317+ * @throws SQLException if (1) an empty rowset is added to this
318+ * <code>JoinRowSet</code> object, (2) a match column is not set
319+ * for a <code>RowSet</code> object in <i>rowset</i>, or (3)
320+ * a <code>RowSet</code> object being added violates the active
321+ * <code>JOIN</code>
322+ */
323+ public void addRowSet(RowSet[] rowset,
324+ int[] columnIdx) throws SQLException;
325+
326+ /**
327+ * Adds one or more <code>RowSet</code> objects contained in the given
328+ * array of <code>RowSet</code> objects to this <code>JoinRowSet</code>
329+ * object and sets the match column for
330+ * each of the <code>RowSet</code> objects to the match columns
331+ * in the given array of column names. The first element in
332+ * <i>columnName</i> is set as the match column for the first
333+ * <code>RowSet</code> object in <i>rowset</i>, the second element of
334+ * <i>columnName</i> is set as the match column for the second element
335+ * in <i>rowset</i>, and so on.
336+ * <P>
337+ * The first <code>RowSet</code> object added to this <code>JoinRowSet</code>
338+ * object forms the basis for the <code>JOIN</code> relationship.
339+ * <P>
340+ * This method should be used when the given <code>RowSet</code> object(s)
341+ * does not already have a match column.
342+ *
343+ * @param rowset an array of one or more <code>RowSet</code> objects
344+ * to be added to the <code>JOIN</code>; it may implement the
345+ * <code>Joinable</code> interface
346+ * @param columnName an array of <code>String</code> values indicating the
347+ * names of the columns to be set as the match columns for the
348+ * <code>RowSet</code> objects in <i>rowset</i>
349+ * @throws SQLException if (1) an empty rowset is added to this
350+ * <code>JoinRowSet</code> object, (2) a match column is not set
351+ * for a <code>RowSet</code> object in <i>rowset</i>, or (3)
352+ * a <code>RowSet</code> object being added violates the active
353+ * <code>JOIN</code>
354+ */
355+ public void addRowSet(RowSet[] rowset,
356+ String[] columnName) throws SQLException;
357+
358+ /**
359+ * Returns a <code>Collection</code> object containing the
360+ * <code>RowSet</code> objects that have been added to this
361+ * <code>JoinRowSet</code> object.
362+ * This should return the 'n' number of RowSet contained
363+ * within the <code>JOIN</code> and maintain any updates that have occured while in
364+ * this union.
365+ *
366+ * @return a <code>Collection</code> object consisting of the
367+ * <code>RowSet</code> objects added to this <code>JoinRowSet</code>
368+ * object
369+ * @throws SQLException if an error occurs generating the
370+ * <code>Collection</code> object to be returned
371+ */
372+ public Collection<?> getRowSets() throws java.sql.SQLException;
373+
374+ /**
375+ * Returns a <code>String</code> array containing the names of the
376+ * <code>RowSet</code> objects added to this <code>JoinRowSet</code>
377+ * object.
378+ *
379+ * @return a <code>String</code> array of the names of the
380+ * <code>RowSet</code> objects in this <code>JoinRowSet</code>
381+ * object
382+ * @throws SQLException if an error occurs retrieving the names of
383+ * the <code>RowSet</code> objects
384+ * @see CachedRowSet#setTableName
385+ */
386+ public String[] getRowSetNames() throws java.sql.SQLException;
387+
388+ /**
389+ * Creates a new <code>CachedRowSet</code> object containing the
390+ * data in this <code>JoinRowSet</code> object, which can be saved
391+ * to a data source using the <code>SyncProvider</code> object for
392+ * the <code>CachedRowSet</code> object.
393+ * <P>
394+ * If any updates or modifications have been applied to the JoinRowSet
395+ * the CachedRowSet returned by the method will not be able to persist
396+ * it's changes back to the originating rows and tables in the
397+ * in the datasource. The CachedRowSet instance returned should not
398+ * contain modification data and it should clear all properties of
399+ * it's originating SQL statement. An application should reset the
400+ * SQL statement using the <code>RowSet.setCommand</code> method.
401+ * <p>
402+ * In order to allow changes to be persisted back to the datasource
403+ * to the originating tables, the <code>acceptChanges</code> method
404+ * should be used and called on a JoinRowSet object instance. Implementations
405+ * can leverage the internal data and update tracking in their
406+ * implementations to interact with the SyncProvider to persist any
407+ * changes.
408+ *
409+ * @return a CachedRowSet containing the contents of the JoinRowSet
410+ * @throws SQLException if an error occurs assembling the CachedRowSet
411+ * object
412+ * @see javax.sql.RowSet
413+ * @see javax.sql.rowset.CachedRowSet
414+ * @see javax.sql.rowset.spi.SyncProvider
415+ */
416+ public CachedRowSet toCachedRowSet() throws java.sql.SQLException;
417+
418+ /**
419+ * Indicates if CROSS_JOIN is supported by a JoinRowSet
420+ * implementation
421+ *
422+ * @return true if the CROSS_JOIN is supported; false otherwise
423+ */
424+ public boolean supportsCrossJoin();
425+
426+ /**
427+ * Indicates if INNER_JOIN is supported by a JoinRowSet
428+ * implementation
429+ *
430+ * @return true is the INNER_JOIN is supported; false otherwise
431+ */
432+ public boolean supportsInnerJoin();
433+
434+ /**
435+ * Indicates if LEFT_OUTER_JOIN is supported by a JoinRowSet
436+ * implementation
437+ *
438+ * @return true is the LEFT_OUTER_JOIN is supported; false otherwise
439+ */
440+ public boolean supportsLeftOuterJoin();
441+
442+ /**
443+ * Indicates if RIGHT_OUTER_JOIN is supported by a JoinRowSet
444+ * implementation
445+ *
446+ * @return true is the RIGHT_OUTER_JOIN is supported; false otherwise
447+ */
448+ public boolean supportsRightOuterJoin();
449+
450+ /**
451+ * Indicates if FULL_JOIN is supported by a JoinRowSet
452+ * implementation
453+ *
454+ * @return true is the FULL_JOIN is supported; false otherwise
455+ */
456+ public boolean supportsFullJoin();
457+
458+ /**
459+ * Allow the application to adjust the type of <code>JOIN</code> imposed
460+ * on tables contained within the JoinRowSet object instance.
461+ * Implementations should throw a SQLException if they do
462+ * not support a given <code>JOIN</code> type.
463+ *
464+ * @param joinType the standard JoinRowSet.XXX static field definition
465+ * of a SQL <code>JOIN</code> to re-configure a JoinRowSet instance on
466+ * the fly.
467+ * @throws SQLException if an unsupported <code>JOIN</code> type is set
468+ * @see #getJoinType
469+ */
470+ public void setJoinType(int joinType) throws SQLException;
471+
472+ /**
473+ * Return a SQL-like description of the WHERE clause being used
474+ * in a JoinRowSet object. An implementation can describe
475+ * the WHERE clause of the SQL <code>JOIN</code> by supplying a SQL
476+ * strings description of <code>JOIN</code> or provide a textual
477+ * description to assist applications using a <code>JoinRowSet</code>
478+ *
479+ * @return whereClause a textual or SQL description of the logical
480+ * WHERE clause used in the JoinRowSet instance
481+ * @throws SQLException if an error occurs in generating a representation
482+ * of the WHERE clause.
483+ */
484+ public String getWhereClause() throws SQLException;
485+
486+ /**
487+ * Returns a <code>int</code> describing the set SQL <code>JOIN</code> type
488+ * governing this JoinRowSet instance. The returned type will be one of
489+ * standard JoinRowSet types: <code>CROSS_JOIN</code>, <code>INNER_JOIN</code>,
490+ * <code>LEFT_OUTER_JOIN</code>, <code>RIGHT_OUTER_JOIN</code> or
491+ * <code>FULL_JOIN</code>.
492+ *
493+ * @return joinType one of the standard JoinRowSet static field
494+ * definitions of a SQL <code>JOIN</code>. <code>JoinRowSet.INNER_JOIN</code>
495+ * is returned as the default <code>JOIN</code> type is no type has been
496+ * explicitly set.
497+ * @throws SQLException if an error occurs determining the SQL <code>JOIN</code>
498+ * type supported by the JoinRowSet instance.
499+ * @see #setJoinType
500+ */
501+ public int getJoinType() throws SQLException;
502+
503+ /**
504+ * An ANSI-style <code>JOIN</code> providing a cross product of two tables
505+ */
506+ public static int CROSS_JOIN = 0;
507+
508+ /**
509+ * An ANSI-style <code>JOIN</code> providing a inner join between two tables. Any
510+ * unmatched rows in either table of the join should be discarded.
511+ */
512+ public static int INNER_JOIN = 1;
513+
514+ /**
515+ * An ANSI-style <code>JOIN</code> providing a left outer join between two
516+ * tables. In SQL, this is described where all records should be
517+ * returned from the left side of the JOIN statement.
518+ */
519+ public static int LEFT_OUTER_JOIN = 2;
520+
521+ /**
522+ * An ANSI-style <code>JOIN</code> providing a right outer join between
523+ * two tables. In SQL, this is described where all records from the
524+ * table on the right side of the JOIN statement even if the table
525+ * on the left has no matching record.
526+ */
527+ public static int RIGHT_OUTER_JOIN = 3;
528+
529+ /**
530+ * An ANSI-style <code>JOIN</code> providing a a full JOIN. Specifies that all
531+ * rows from either table be returned regardless of matching
532+ * records on the other table.
533+ */
534+ public static int FULL_JOIN = 4;
535+
536+
537+}
java/pkg/javax/sql/rowset/Joinable.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/Joinable.java+291−0
@@ -0,0 +1,291 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.SQLException;
29+
30+/**
31+ * <h3>1.0 Background</h3>
32+ * The <code>Joinable</code> interface provides the methods for getting and
33+ * setting a match column, which is the basis for forming the SQL <code>JOIN</code>
34+ * formed by adding <code>RowSet</code> objects to a <code>JoinRowSet</code>
35+ * object.
36+ * <P>
37+ * Any standard <code>RowSet</code> implementation <b>may</b> implement
38+ * the <code>Joinable</code> interface in order to be
39+ * added to a <code>JoinRowSet</code> object. Implementing this interface gives
40+ * a <code>RowSet</code> object the ability to use <code>Joinable</code> methods,
41+ * which set, retrieve, and get information about match columns. An
42+ * application may add a
43+ * <code>RowSet</code> object that has not implemented the <code>Joinable</code>
44+ * interface to a <code>JoinRowSet</code> object, but to do so it must use one
45+ * of the <code>JoinRowSet.addRowSet</code> methods that takes both a
46+ * <code>RowSet</code> object and a match column or an array of <code>RowSet</code>
47+ * objects and an array of match columns.
48+ * <P>
49+ * To get access to the methods in the <code>Joinable</code> interface, a
50+ * <code>RowSet</code> object implements at least one of the
51+ * five standard <code>RowSet</code> interfaces and also implements the
52+ * <code>Joinable</code> interface. In addition, most <code>RowSet</code>
53+ * objects extend the <code>BaseRowSet</code> class. For example:
54+ * <pre>
55+ * class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable {
56+ * :
57+ * :
58+ * }
59+ * </pre>
60+ * <P>
61+ * <h3>2.0 Usage Guidelines</h3>
62+ * <P>
63+ * The methods in the <code>Joinable</code> interface allow a <code>RowSet</code> object
64+ * to set a match column, retrieve a match column, or unset a match column, which is
65+ * the column upon which an SQL <code>JOIN</code> can be based.
66+ * An instance of a class that implements these methods can be added to a
67+ * <code>JoinRowSet</code> object to allow an SQL <code>JOIN</code> relationship to
68+ * be established.
69+ * <p>
70+ * <pre>
71+ * CachedRowSet crs = new MyRowSetImpl();
72+ * crs.populate((ResultSet)rs);
73+ * (Joinable)crs.setMatchColumnIndex(1);
74+ *
75+ * JoinRowSet jrs = new JoinRowSetImpl();
76+ * jrs.addRowSet(crs);
77+ * </pre>
78+ * In the previous example, <i>crs</i> is a <code>CachedRowSet</code> object that
79+ * has emplemented the <code>Joinable</code> interface. In the following example,
80+ * <i>crs2</i> has not, so it must supply the match column as an argument to the
81+ * <code>addRowSet</code> method. This example assumes that column 1 is the match
82+ * column.
83+ * <PRE>
84+ * CachedRowSet crs2 = new MyRowSetImpl();
85+ * crs2.populate((ResultSet)rs);
86+ *
87+ * JoinRowSet jrs2 = new JoinRowSetImpl();
88+ * jrs2.addRowSet(crs2, 1);
89+ * </PRE>
90+ * <p>
91+ * The <code>JoinRowSet</code> interface makes it possible to get data from one or
92+ * more <code>RowSet</code> objects consolidated into one table without having to incur
93+ * the expense of creating a connection to a database. It is therefore ideally suited
94+ * for use by disconnected <code>RowSet</code> objects. Nevertheless, any
95+ * <code>RowSet</code> object <b>may</b> implement this interface
96+ * regardless of whether it is connected or disconnected. Note that a
97+ * <code>JdbcRowSet</code> object, being always connected to its data source, can
98+ * become part of an SQL <code>JOIN</code> directly without having to become part
99+ * of a <code>JoinRowSet</code> object.
100+ * <P>
101+ * <h3>3.0 Managing Multiple Match Columns</h3>
102+ * The index array passed into the <code>setMatchColumn</code> methods indicates
103+ * how many match columns are being set (the length of the array) in addition to
104+ * which columns will be used for the match. For example:
105+ * <pre>
106+ * int[] i = {1, 2, 4, 7}; // indicates four match columns, with column
107+ * // indexes 1, 2, 4, 7 participating in the JOIN.
108+ * Joinable.setMatchColumn(i);
109+ * </pre>
110+ * Subsequent match columns may be added as follows to a different <code>Joinable</code>
111+ * object (a <code>RowSet</code> object that has implemented the <code>Joinable</code>
112+ * interface).
113+ * <pre>
114+ * int[] w = {3, 2, 5, 3};
115+ * Joinable2.setMatchColumn(w);
116+ * </pre>
117+ * When an application adds two or more <code>RowSet</code> objects to a
118+ * <code>JoinRowSet</code> object, the order of the indexes in the array is
119+ * particularly important. Each index of
120+ * the array maps directly to the corresponding index of the previously added
121+ * <code>RowSet</code> object. If overlap or underlap occurs, the match column
122+ * data is maintained in the event an additional <code>Joinable</code> RowSet is
123+ * added and needs to relate to the match column data. Therefore, applications
124+ * can set multiple match columns in any order, but
125+ * this order has a direct effect on the outcome of the <code>SQL</code> JOIN.
126+ * <p>
127+ * This assertion applies in exactly the same manner when column names are used
128+ * rather than column indexes to indicate match columns.
129+ *
130+ * @see JoinRowSet
131+ * @author Jonathan Bruce
132+ */
133+public interface Joinable {
134+
135+ /**
136+ * Sets the designated column as the match column for this <code>RowSet</code>
137+ * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
138+ * object based on the match column.
139+ * <p>
140+ * Sub-interfaces such as the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>
141+ * interface define the method <code>CachedRowSet.setKeyColumns</code>, which allows
142+ * primary key semantics to be enforced on specific columns.
143+ * Implementations of the <code>setMatchColumn(int columnIdx)</code> method
144+ * should ensure that the constraints on the key columns are maintained when
145+ * a <code>CachedRowSet</code> object sets a primary key column as a match column.
146+ *
147+ * @param columnIdx an <code>int</code> identifying the index of the column to be
148+ * set as the match column
149+ * @throws SQLException if an invalid column index is set
150+ * @see #setMatchColumn(int[])
151+ * @see #unsetMatchColumn(int)
152+ *
153+ */
154+ public void setMatchColumn(int columnIdx) throws SQLException;
155+
156+ /**
157+ * Sets the designated columns as the match column for this <code>RowSet</code>
158+ * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
159+ * object based on the match column.
160+ *
161+ * @param columnIdxes an array of <code>int</code> identifying the indexes of the
162+ * columns to be set as the match columns
163+ * @throws SQLException if an invalid column index is set
164+ * @see #setMatchColumn(int[])
165+ * @see #unsetMatchColumn(int[])
166+ */
167+ public void setMatchColumn(int[] columnIdxes) throws SQLException;
168+
169+ /**
170+ * Sets the designated column as the match column for this <code>RowSet</code>
171+ * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
172+ * object based on the match column.
173+ * <p>
174+ * Subinterfaces such as the <code>CachedRowSet</code> interface define
175+ * the method <code>CachedRowSet.setKeyColumns</code>, which allows
176+ * primary key semantics to be enforced on specific columns.
177+ * Implementations of the <code>setMatchColumn(String columnIdx)</code> method
178+ * should ensure that the constraints on the key columns are maintained when
179+ * a <code>CachedRowSet</code> object sets a primary key column as a match column.
180+ *
181+ * @param columnName a <code>String</code> object giving the name of the column
182+ * to be set as the match column
183+ * @throws SQLException if an invalid column name is set, the column name
184+ * is a null, or the column name is an empty string
185+ * @see #unsetMatchColumn
186+ * @see #setMatchColumn(int[])
187+ */
188+ public void setMatchColumn(String columnName) throws SQLException;
189+
190+ /**
191+ * Sets the designated columns as the match column for this <code>RowSet</code>
192+ * object. A <code>JoinRowSet</code> object can now add this <code>RowSet</code>
193+ * object based on the match column.
194+ *
195+ * @param columnNames an array of <code>String</code> objects giving the names
196+ * of the column to be set as the match columns
197+ * @throws SQLException if an invalid column name is set, the column name
198+ * is a null, or the column name is an empty string
199+ * @see #unsetMatchColumn
200+ * @see #setMatchColumn(int[])
201+ */
202+ public void setMatchColumn(String[] columnNames) throws SQLException;
203+
204+ /**
205+ * Retrieves the indexes of the match columns that were set for this
206+ * <code>RowSet</code> object with the method
207+ * <code>setMatchColumn(int[] columnIdxes)</code>.
208+ *
209+ * @return an <code>int</code> array identifying the indexes of the columns
210+ * that were set as the match columns for this <code>RowSet</code> object
211+ * @throws SQLException if no match column has been set
212+ * @see #setMatchColumn
213+ * @see #unsetMatchColumn
214+ */
215+ public int[] getMatchColumnIndexes() throws SQLException;
216+
217+ /**
218+ * Retrieves the names of the match columns that were set for this
219+ * <code>RowSet</code> object with the method
220+ * <code>setMatchColumn(String [] columnNames)</code>.
221+ *
222+ * @return an array of <code>String</code> objects giving the names of the columns
223+ * set as the match columns for this <code>RowSet</code> object
224+ * @throws SQLException if no match column has been set
225+ * @see #setMatchColumn
226+ * @see #unsetMatchColumn
227+ *
228+ */
229+ public String[] getMatchColumnNames() throws SQLException;
230+
231+ /**
232+ * Unsets the designated column as the match column for this <code>RowSet</code>
233+ * object.
234+ * <P>
235+ * <code>RowSet</code> objects that implement the <code>Joinable</code> interface
236+ * must ensure that a key-like constraint continues to be enforced until the
237+ * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the
238+ * designated column.
239+ *
240+ * @param columnIdx an <code>int</code> that identifies the index of the column
241+ * that is to be unset as a match column
242+ * @throws SQLException if an invalid column index is designated or if
243+ * the designated column was not previously set as a match
244+ * column
245+ * @see #setMatchColumn
246+ */
247+ public void unsetMatchColumn(int columnIdx) throws SQLException;
248+
249+ /**
250+ * Unsets the designated columns as the match column for this <code>RowSet</code>
251+ * object.
252+ *
253+ * @param columnIdxes an arrary of <code>int</code> that identifies the indexes
254+ * of the columns that are to be unset as match columns
255+ * @throws SQLException if an invalid column index is designated or if
256+ * the designated column was not previously set as a match
257+ * column
258+ * @see #setMatchColumn
259+ */
260+ public void unsetMatchColumn(int[] columnIdxes) throws SQLException;
261+
262+ /**
263+ * Unsets the designated column as the match column for this <code>RowSet</code>
264+ * object.
265+ * <P>
266+ * <code>RowSet</code> objects that implement the <code>Joinable</code> interface
267+ * must ensure that a key-like constraint continues to be enforced until the
268+ * method <code>CachedRowSet.unsetKeyColumns</code> has been called on the
269+ * designated column.
270+ *
271+ * @param columnName a <code>String</code> object giving the name of the column
272+ * that is to be unset as a match column
273+ * @throws SQLException if an invalid column name is designated or
274+ * the designated column was not previously set as a match
275+ * column
276+ * @see #setMatchColumn
277+ */
278+ public void unsetMatchColumn(String columnName) throws SQLException;
279+
280+ /**
281+ * Unsets the designated columns as the match columns for this <code>RowSet</code>
282+ * object.
283+ *
284+ * @param columnName an array of <code>String</code> objects giving the names of
285+ * the columns that are to be unset as the match columns
286+ * @throws SQLException if an invalid column name is designated or the
287+ * designated column was not previously set as a match column
288+ * @see #setMatchColumn
289+ */
290+ public void unsetMatchColumn(String[] columnName) throws SQLException;
291+}
java/pkg/javax/sql/rowset/Predicate.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/Predicate.java+164−0
@@ -0,0 +1,164 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import javax.sql.*;
29+import java.sql.*;
30+
31+/**
32+ * The standard interface that provides the framework for all
33+ * <code>FilteredRowSet</code> objects to describe their filters.
34+ * <p>
35+ * <h3>1.0 Background</h3>
36+ * The <code>Predicate</code> interface is a standard interface that
37+ * applications can implement to define the filter they wish to apply to a
38+ * a <code>FilteredRowSet</code> object. A <code>FilteredRowSet</code>
39+ * object consumes implementations of this interface and enforces the
40+ * constraints defined in the implementation of the method <code>evaluate</code>.
41+ * A <code>FilteredRowSet</code> object enforces the filter constraints in a
42+ * bi-directional manner: It outputs only rows that are within
43+ * the constraints of the filter; and conversely, it inserts, modifies, or updates
44+ * only rows that are within the constraints of the filter.
45+ *
46+ * <h3>2.0 Implementation Guidelines</h3>
47+ * In order to supply a predicate for the <code>FilteredRowSet</code>.
48+ * this interface must be implemented. At this time, the JDBC RowSet
49+ * Implementations (JSR-114) does not specify any standard filters definitions.
50+ * By specifying a standard means and mechanism for a range of filters to be
51+ * defined and deployed with both the reference and vendor implementations
52+ * of the <code>FilteredRowSet</code> interface, this allows for a flexible
53+ * and application motivated implementations of <code>Predicate</code> to emerge.
54+ * <p>
55+ * A sample implementation would look something like this:
56+ * <pre>
57+ * <code>
58+ * public class Range implements Predicate {
59+ *
60+ * private Object lo[];
61+ * private Object hi[];
62+ * private int idx[];
63+ *
64+ * public Range(Object[] lo, Object[] hi, int[] idx) {
65+ * this.lo = lo;
66+ * this.hi = hi;
67+ * this.idx = idx;
68+ * }
69+ *
70+ * public boolean evaluate(RowSet rs) {
71+ * CachedRowSet crs = (CachedRowSet)rs;
72+ * boolean bool1,bool2;
73+ *
74+ * // Check the present row determine if it lies
75+ * // within the filtering criteria.
76+ *
77+ * for (int i = 0; i < idx.length; i++) {
78+ *
79+ * if ((rs.getObject(idx[i]) >= lo[i]) &&
80+ * (rs.getObject(idx[i]) >= hi[i]) {
81+ * bool1 = true; // within filter constraints
82+ * } else {
83+ * bool2 = true; // outside of filter constraints
84+ * }
85+ * }
86+ *
87+ * if (bool2) {
88+ * return false;
89+ * } else {
90+ * return true;
91+ * }
92+ * }
93+ * </code>
94+ * </pre>
95+ * <P>
96+ * The example above implements a simple range predicate. Note, that
97+ * implementations should but are not required to provider <code>String</code>
98+ * and integer index based constructors to provide for JDBC RowSet Implementation
99+ * applications that use both column identification conventions.
100+ *
101+ * @author Jonathan Bruce, Amit Handa
102+ *
103+ */
104+
105+ // <h3>3.0 FilteredRowSet Internals</h3>
106+ // internalNext, Frist, Last. Discuss guidelines on how to approach this
107+ // and cite examples in reference implementations.
108+public interface Predicate {
109+ /**
110+ * This method is typically called a <code>FilteredRowSet</code> object
111+ * internal methods (not public) that control the <code>RowSet</code> object's
112+ * cursor moving from row to the next. In addition, if this internal method
113+ * moves the cursor onto a row that has been deleted, the internal method will
114+ * continue to ove the cursor until a valid row is found.
115+ *
116+ * @return <code>true</code> if there are more rows in the filter;
117+ * <code>false</code> otherwise
118+ */
119+ public boolean evaluate(RowSet rs);
120+
121+
122+ /**
123+ * This method is called by a <code>FilteredRowSet</code> object
124+ * to check whether the value lies between the filtering criterion (or criteria
125+ * if multiple constraints exist) set using the <code>setFilter()</code> method.
126+ * <P>
127+ * The <code>FilteredRowSet</code> object will use this method internally
128+ * while inserting new rows to a <code>FilteredRowSet</code> instance.
129+ *
130+ * @param value An <code>Object</code> value which needs to be checked,
131+ * whether it can be part of this <code>FilterRowSet</code> object.
132+ * @param column a <code>int</code> object that must match the
133+ * SQL index of a column in this <code>RowSet</code> object. This must
134+ * have been passed to <code>Predicate</code> as one of the columns
135+ * for filtering while initializing a <code>Predicate</code>
136+ * @return <code>true</code> ifrow value lies within the filter;
137+ * <code>false</code> otherwise
138+ * @throws SQLException if the column is not part of filtering criteria
139+ */
140+ public boolean evaluate(Object value, int column) throws SQLException;
141+
142+ /**
143+ * This method is called by the <code>FilteredRowSet</code> object
144+ * to check whether the value lies between the filtering criteria set
145+ * using the setFilter method.
146+ * <P>
147+ * The <code>FilteredRowSet</code> object will use this method internally
148+ * while inserting new rows to a <code>FilteredRowSet</code> instance.
149+ *
150+ * @param value An <code>Object</code> value which needs to be checked,
151+ * whether it can be part of this <code>FilterRowSet</code>.
152+ *
153+ * @param columnName a <code>String</code> object that must match the
154+ * SQL name of a column in this <code>RowSet</code>, ignoring case. This must
155+ * have been passed to <code>Predicate</code> as one of the columns for filtering
156+ * while initializing a <code>Predicate</code>
157+ *
158+ * @return <code>true</code> if value lies within the filter; <code>false</code> otherwise
159+ *
160+ * @throws SQLException if the column is not part of filtering criteria
161+ */
162+ public boolean evaluate(Object value, String columnName) throws SQLException;
163+
164+}
java/pkg/javax/sql/rowset/RowSetFactory.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetFactory.java+99−0
@@ -0,0 +1,99 @@
1+/*
2+ * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.SQLException;
29+
30+/**
31+ * An interface that defines the implementation of a factory that is used
32+ * to obtain different types of {@code RowSet} implementations.
33+ *
34+ * @author Lance Andersen
35+ * @since 1.7
36+ */
37+public interface RowSetFactory{
38+
39+ /**
40+ * <p>Creates a new instance of a CachedRowSet.</p>
41+ *
42+ * @return A new instance of a CachedRowSet.
43+ *
44+ * @throws SQLException if a CachedRowSet cannot
45+ * be created.
46+ *
47+ * @since 1.7
48+ */
49+ public CachedRowSet createCachedRowSet() throws SQLException;
50+
51+ /**
52+ * <p>Creates a new instance of a FilteredRowSet.</p>
53+ *
54+ * @return A new instance of a FilteredRowSet.
55+ *
56+ * @throws SQLException if a FilteredRowSet cannot
57+ * be created.
58+ *
59+ * @since 1.7
60+ */
61+ public FilteredRowSet createFilteredRowSet() throws SQLException;
62+
63+ /**
64+ * <p>Creates a new instance of a JdbcRowSet.</p>
65+ *
66+ * @return A new instance of a JdbcRowSet.
67+ *
68+ * @throws SQLException if a JdbcRowSet cannot
69+ * be created.
70+ *
71+ * @since 1.7
72+ */
73+ public JdbcRowSet createJdbcRowSet() throws SQLException;
74+
75+ /**
76+ * <p>Creates a new instance of a JoinRowSet.</p>
77+ *
78+ * @return A new instance of a JoinRowSet.
79+ *
80+ * @throws SQLException if a JoinRowSet cannot
81+ * be created.
82+ *
83+ * @since 1.7
84+ */
85+ public JoinRowSet createJoinRowSet() throws SQLException;
86+
87+ /**
88+ * <p>Creates a new instance of a WebRowSet.</p>
89+ *
90+ * @return A new instance of a WebRowSet.
91+ *
92+ * @throws SQLException if a WebRowSet cannot
93+ * be created.
94+ *
95+ * @since 1.7
96+ */
97+ public WebRowSet createWebRowSet() throws SQLException;
98+
99+}
java/pkg/javax/sql/rowset/RowSetMetaDataImpl$1.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetMetaDataImpl$ColInfo.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetMetaDataImpl.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetMetaDataImpl.java+1095−0
@@ -0,0 +1,1095 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import java.io.*;
31+
32+import java.lang.reflect.*;
33+
34+/**
35+ * Provides implementations for the methods that set and get
36+ * metadata information about a <code>RowSet</code> object's columns.
37+ * A <code>RowSetMetaDataImpl</code> object keeps track of the
38+ * number of columns in the rowset and maintains an internal array
39+ * of column attributes for each column.
40+ * <P>
41+ * A <code>RowSet</code> object creates a <code>RowSetMetaDataImpl</code>
42+ * object internally in order to set and retrieve information about
43+ * its columns.
44+ * <P>
45+ * NOTE: All metadata in a <code>RowSetMetaDataImpl</code> object
46+ * should be considered as unavailable until the <code>RowSet</code> object
47+ * that it describes is populated.
48+ * Therefore, any <code>RowSetMetaDataImpl</code> method that retrieves information
49+ * is defined as having unspecified behavior when it is called
50+ * before the <code>RowSet</code> object contains data.
51+ */
52+public class RowSetMetaDataImpl implements RowSetMetaData, Serializable {
53+
54+ /**
55+ * The number of columns in the <code>RowSet</code> object that created
56+ * this <code>RowSetMetaDataImpl</code> object.
57+ * @serial
58+ */
59+ private int colCount;
60+
61+ /**
62+ * An array of <code>ColInfo</code> objects used to store information
63+ * about each column in the <code>RowSet</code> object for which
64+ * this <code>RowSetMetaDataImpl</code> object was created. The first
65+ * <code>ColInfo</code> object in this array contains information about
66+ * the first column in the <code>RowSet</code> object, the second element
67+ * contains information about the second column, and so on.
68+ * @serial
69+ */
70+ private ColInfo[] colInfo;
71+
72+ /**
73+ * Checks to see that the designated column is a valid column number for
74+ * the <code>RowSet</code> object for which this <code>RowSetMetaDataImpl</code>
75+ * was created. To be valid, a column number must be greater than
76+ * <code>0</code> and less than or equal to the number of columns in a row.
77+ * @throws <code>SQLException</code> with the message "Invalid column index"
78+ * if the given column number is out of the range of valid column
79+ * numbers for the <code>RowSet</code> object
80+ */
81+ private void checkColRange(int col) throws SQLException {
82+ if (col <= 0 || col > colCount) {
83+ throw new SQLException("Invalid column index :"+col);
84+ }
85+ }
86+
87+ /**
88+ * Checks to see that the given SQL type is a valid column type and throws an
89+ * <code>SQLException</code> object if it is not.
90+ * To be valid, a SQL type must be one of the constant values
91+ * in the <code><a href="../../sql/Types.html">java.sql.Types</a></code>
92+ * class.
93+ *
94+ * @param SQLType an <code>int</code> defined in the class <code>java.sql.Types</code>
95+ * @throws SQLException if the given <code>int</code> is not a constant defined in the
96+ * class <code>java.sql.Types</code>
97+ */
98+ private void checkColType(int SQLType) throws SQLException {
99+ try {
100+ Class c = java.sql.Types.class;
101+ Field[] publicFields = c.getFields();
102+ int fieldValue = 0;
103+ for (int i = 0; i < publicFields.length; i++) {
104+ fieldValue = publicFields[i].getInt(c);
105+ if (fieldValue == SQLType) {
106+ return;
107+ }
108+ }
109+ } catch (Exception e) {
110+ throw new SQLException(e.getMessage());
111+ }
112+ throw new SQLException("Invalid SQL type for column");
113+ }
114+
115+ /**
116+ * Sets to the given number the number of columns in the <code>RowSet</code>
117+ * object for which this <code>RowSetMetaDataImpl</code> object was created.
118+ *
119+ * @param columnCount an <code>int</code> giving the number of columns in the
120+ * <code>RowSet</code> object
121+ * @throws SQLException if the given number is equal to or less than zero
122+ */
123+ public void setColumnCount(int columnCount) throws SQLException {
124+
125+ if (columnCount <= 0) {
126+ throw new SQLException("Invalid column count. Cannot be less " +
127+ "or equal to zero");
128+ }
129+
130+ colCount = columnCount;
131+
132+ // If the colCount is Integer.MAX_VALUE,
133+ // we do not initialize the colInfo object.
134+ // even if we try to initialize the colCount with
135+ // colCount = Integer.MAx_VALUE-1, the colInfo
136+ // initialization fails throwing an ERROR
137+ // OutOfMemory Exception. So we do not initialize
138+ // colInfo at Integer.MAX_VALUE. This is to pass TCK.
139+
140+ if(!(colCount == Integer.MAX_VALUE)) {
141+ colInfo = new ColInfo[colCount + 1];
142+
143+ for (int i=1; i <= colCount; i++) {
144+ colInfo[i] = new ColInfo();
145+ }
146+ }
147+
148+
149+ }
150+
151+ /**
152+ * Sets whether the designated column is automatically
153+ * numbered, thus read-only, to the given <code>boolean</code>
154+ * value.
155+ *
156+ * @param columnIndex the first column is 1, the second is 2, and so on;
157+ * must be between <code>1</code> and the number of columns
158+ * in the rowset, inclusive
159+ * @param property <code>true</code> if the given column is
160+ * automatically incremented; <code>false</code>
161+ * otherwise
162+ * @throws <code>SQLException</code> if a database access error occurs or
163+ * the given index is out of bounds
164+ */
165+ public void setAutoIncrement(int columnIndex, boolean property) throws SQLException {
166+ checkColRange(columnIndex);
167+ colInfo[columnIndex].autoIncrement = property;
168+ }
169+
170+ /**
171+ * Sets whether the name of the designated column is case sensitive to
172+ * the given <code>boolean</code>.
173+ *
174+ * @param columnIndex the first column is 1, the second is 2, and so on;
175+ * must be between <code>1</code> and the number of columns
176+ * in the rowset, inclusive
177+ * @param property <code>true</code> to indicate that the column
178+ * name is case sensitive; <code>false</code> otherwise
179+ * @throws SQLException if a database access error occurs or
180+ * the given column number is out of bounds
181+ */
182+ public void setCaseSensitive(int columnIndex, boolean property) throws SQLException {
183+ checkColRange(columnIndex);
184+ colInfo[columnIndex].caseSensitive = property;
185+ }
186+
187+ /**
188+ * Sets whether a value stored in the designated column can be used
189+ * in a <code>WHERE</code> clause to the given <code>boolean</code> value.
190+ *
191+ * @param columnIndex the first column is 1, the second is 2, and so on;
192+ * must be between <code>1</code> and the number
193+ * of columns in the rowset, inclusive
194+ * @param property <code>true</code> to indicate that a column
195+ * value can be used in a <code>WHERE</code> clause;
196+ * <code>false</code> otherwise
197+ *
198+ * @throws <code>SQLException</code> if a database access error occurs or
199+ * the given column number is out of bounds
200+ */
201+ public void setSearchable(int columnIndex, boolean property)
202+ throws SQLException {
203+ checkColRange(columnIndex);
204+ colInfo[columnIndex].searchable = property;
205+ }
206+
207+ /**
208+ * Sets whether a value stored in the designated column is a cash
209+ * value to the given <code>boolean</code>.
210+ *
211+ * @param columnIndex the first column is 1, the second is 2, and so on;
212+ * must be between <code>1</code> and the number of columns,
213+ * inclusive between <code>1</code> and the number of columns, inclusive
214+ * @param property true if the value is a cash value; false otherwise.
215+ * @throws <code>SQLException</code> if a database access error occurs
216+ * or the given column number is out of bounds
217+ */
218+ public void setCurrency(int columnIndex, boolean property)
219+ throws SQLException {
220+ checkColRange(columnIndex);
221+ colInfo[columnIndex].currency = property;
222+ }
223+
224+ /**
225+ * Sets whether a value stored in the designated column can be set
226+ * to <code>NULL</code> to the given constant from the interface
227+ * <code>ResultSetMetaData</code>.
228+ *
229+ * @param columnIndex the first column is 1, the second is 2, and so on;
230+ * must be between <code>1</code> and the number of columns, inclusive
231+ * @param property one of the following <code>ResultSetMetaData</code> constants:
232+ * <code>columnNoNulls</code>,
233+ * <code>columnNullable</code>, or
234+ * <code>columnNullableUnknown</code>
235+ *
236+ * @throws <code>SQLException</code> if a database access error occurs,
237+ * the given column number is out of bounds, or the value supplied
238+ * for the <i>property</i> parameter is not one of the following
239+ * constants:
240+ * <code>ResultSetMetaData.columnNoNulls</code>,
241+ * <code>ResultSetMetaData.columnNullable</code>, or
242+ * <code>ResultSetMetaData.columnNullableUnknown</code>
243+ */
244+ public void setNullable(int columnIndex, int property) throws SQLException {
245+ if ((property < ResultSetMetaData.columnNoNulls) ||
246+ property > ResultSetMetaData.columnNullableUnknown) {
247+ throw new SQLException("Invalid nullable constant set. Must be " +
248+ "either columnNoNulls, columnNullable or columnNullableUnknown");
249+ }
250+ checkColRange(columnIndex);
251+ colInfo[columnIndex].nullable = property;
252+ }
253+
254+ /**
255+ * Sets whether a value stored in the designated column is a signed
256+ * number to the given <code>boolean</code>.
257+ *
258+ * @param columnIndex the first column is 1, the second is 2, and so on;
259+ * must be between <code>1</code> and the number of columns, inclusive
260+ * @param property <code>true</code> to indicate that a column
261+ * value is a signed number;
262+ * <code>false</code> to indicate that it is not
263+ * @throws SQLException if a database access error occurs
264+ * or the given column number is out of bounds
265+ */
266+ public void setSigned(int columnIndex, boolean property) throws SQLException {
267+ checkColRange(columnIndex);
268+ colInfo[columnIndex].signed = property;
269+ }
270+
271+ /**
272+ * Sets the normal maximum number of chars in the designated column
273+ * to the given number.
274+ *
275+ * @param columnIndex the first column is 1, the second is 2, and so on;
276+ * must be between <code>1</code> and the number of columns, inclusive
277+ * @param size the maximum size of the column in chars; must be
278+ * <code>0</code> or more
279+ * @throws SQLException if a database access error occurs,
280+ * the given column number is out of bounds, or <i>size</i> is
281+ * less than <code>0</code>
282+ */
283+ public void setColumnDisplaySize(int columnIndex, int size) throws SQLException {
284+ if (size < 0) {
285+ throw new SQLException("Invalid column display size. Cannot be less " +
286+ "than zero");
287+ }
288+ checkColRange(columnIndex);
289+ colInfo[columnIndex].columnDisplaySize = size;
290+ }
291+
292+ /**
293+ * Sets the suggested column label for use in printouts and
294+ * displays, if any, to <i>label</i>. If <i>label</i> is
295+ * <code>null</code>, the column label is set to an empty string
296+ * ("").
297+ *
298+ * @param columnIndex the first column is 1, the second is 2, and so on;
299+ * must be between <code>1</code> and the number of columns, inclusive
300+ * @param label the column label to be used in printouts and displays; if the
301+ * column label is <code>null</code>, an empty <code>String</code> is
302+ * set
303+ * @throws SQLException if a database access error occurs
304+ * or the given column index is out of bounds
305+ */
306+ public void setColumnLabel(int columnIndex, String label) throws SQLException {
307+ checkColRange(columnIndex);
308+ if (label != null) {
309+ colInfo[columnIndex].columnLabel = label;
310+ } else {
311+ colInfo[columnIndex].columnLabel = "";
312+ }
313+ }
314+
315+ /**
316+ * Sets the column name of the designated column to the given name.
317+ *
318+ * @param columnIndex the first column is 1, the second is 2, and so on;
319+ * must be between <code>1</code> and the number of columns, inclusive
320+ * @param columnName a <code>String</code> object indicating the column name;
321+ * if the given name is <code>null</code>, an empty <code>String</code>
322+ * is set
323+ * @throws SQLException if a database access error occurs or the given column
324+ * index is out of bounds
325+ */
326+ public void setColumnName(int columnIndex, String columnName) throws SQLException {
327+ checkColRange(columnIndex);
328+ if (columnName != null) {
329+ colInfo[columnIndex].columnName = columnName;
330+ } else {
331+ colInfo[columnIndex].columnName = "";
332+ }
333+ }
334+
335+ /**
336+ * Sets the designated column's table's schema name, if any, to
337+ * <i>schemaName</i>. If <i>schemaName</i> is <code>null</code>,
338+ * the schema name is set to an empty string ("").
339+ *
340+ * @param columnIndex the first column is 1, the second is 2, and so on;
341+ * must be between <code>1</code> and the number of columns, inclusive
342+ * @param schemaName the schema name for the table from which a value in the
343+ * designated column was derived; may be an empty <code>String</code>
344+ * or <code>null</code>
345+ * @throws SQLException if a database access error occurs
346+ * or the given column number is out of bounds
347+ */
348+ public void setSchemaName(int columnIndex, String schemaName) throws SQLException {
349+ checkColRange(columnIndex);
350+ if (schemaName != null ) {
351+ colInfo[columnIndex].schemaName = schemaName;
352+ } else {
353+ colInfo[columnIndex].schemaName = "";
354+ }
355+ }
356+
357+ /**
358+ * Sets the total number of decimal digits in a value stored in the
359+ * designated column to the given number.
360+ *
361+ * @param columnIndex the first column is 1, the second is 2, and so on;
362+ * must be between <code>1</code> and the number of columns, inclusive
363+ * @param precision the total number of decimal digits; must be <code>0</code>
364+ * or more
365+ * @throws SQLException if a database access error occurs,
366+ * <i>columnIndex</i> is out of bounds, or <i>precision</i>
367+ * is less than <code>0</code>
368+ */
369+ public void setPrecision(int columnIndex, int precision) throws SQLException {
370+
371+ if (precision < 0) {
372+ throw new SQLException("Invalid precision value. Cannot be less " +
373+ "than zero");
374+ }
375+ checkColRange(columnIndex);
376+ colInfo[columnIndex].colPrecision = precision;
377+ }
378+
379+ /**
380+ * Sets the number of digits to the right of the decimal point in a value
381+ * stored in the designated column to the given number.
382+ *
383+ * @param columnIndex the first column is 1, the second is 2, and so on;
384+ * must be between <code>1</code> and the number of columns, inclusive
385+ * @param scale the number of digits to the right of the decimal point; must be
386+ * zero or greater
387+ * @throws SQLException if a database access error occurs,
388+ * <i>columnIndex</i> is out of bounds, or <i>scale</i>
389+ * is less than <code>0</code>
390+ */
391+ public void setScale(int columnIndex, int scale) throws SQLException {
392+ if (scale < 0) {
393+ throw new SQLException("Invalid scale size. Cannot be less " +
394+ "than zero");
395+ }
396+ checkColRange(columnIndex);
397+ colInfo[columnIndex].colScale = scale;
398+ }
399+
400+ /**
401+ * Sets the name of the table from which the designated column
402+ * was derived to the given table name.
403+ *
404+ * @param columnIndex the first column is 1, the second is 2, and so on;
405+ * must be between <code>1</code> and the number of columns, inclusive
406+ * @param tableName the column's table name; may be <code>null</code> or an
407+ * empty string
408+ * @throws SQLException if a database access error occurs
409+ * or the given column number is out of bounds
410+ */
411+ public void setTableName(int columnIndex, String tableName) throws SQLException {
412+ checkColRange(columnIndex);
413+ if (tableName != null) {
414+ colInfo[columnIndex].tableName = tableName;
415+ } else {
416+ colInfo[columnIndex].tableName = "";
417+ }
418+ }
419+
420+ /**
421+ * Sets the catalog name of the table from which the designated
422+ * column was derived to <i>catalogName</i>. If <i>catalogName</i>
423+ * is <code>null</code>, the catalog name is set to an empty string.
424+ *
425+ * @param columnIndex the first column is 1, the second is 2, and so on;
426+ * must be between <code>1</code> and the number of columns, inclusive
427+ * @param catalogName the column's table's catalog name; if the catalogName
428+ * is <code>null</code>, an empty <code>String</code> is set
429+ * @throws SQLException if a database access error occurs
430+ * or the given column number is out of bounds
431+ */
432+ public void setCatalogName(int columnIndex, String catalogName) throws SQLException {
433+ checkColRange(columnIndex);
434+ if (catalogName != null)
435+ colInfo[columnIndex].catName = catalogName;
436+ else
437+ colInfo[columnIndex].catName = "";
438+ }
439+
440+ /**
441+ * Sets the SQL type code for values stored in the designated column
442+ * to the given type code from the class <code>java.sql.Types</code>.
443+ *
444+ * @param columnIndex the first column is 1, the second is 2, and so on;
445+ * must be between <code>1</code> and the number of columns, inclusive
446+ * @param SQLType the designated column's SQL type, which must be one of the
447+ * constants in the class <code>java.sql.Types</code>
448+ * @throws SQLException if a database access error occurs,
449+ * the given column number is out of bounds, or the column type
450+ * specified is not one of the constants in
451+ * <code>java.sql.Types</code>
452+ * @see java.sql.Types
453+ */
454+ public void setColumnType(int columnIndex, int SQLType) throws SQLException {
455+ // examine java.sql.Type reflectively, loop on the fields and check
456+ // this. Separate out into a private method
457+ checkColType(SQLType);
458+ checkColRange(columnIndex);
459+ colInfo[columnIndex].colType = SQLType;
460+ }
461+
462+ /**
463+ * Sets the type name used by the data source for values stored in the
464+ * designated column to the given type name.
465+ *
466+ * @param columnIndex the first column is 1, the second is 2, and so on;
467+ * must be between <code>1</code> and the number of columns, inclusive
468+ * @param typeName the data source-specific type name; if <i>typeName</i> is
469+ * <code>null</code>, an empty <code>String</code> is set
470+ * @throws SQLException if a database access error occurs
471+ * or the given column number is out of bounds
472+ */
473+ public void setColumnTypeName(int columnIndex, String typeName)
474+ throws SQLException {
475+ checkColRange(columnIndex);
476+ if (typeName != null) {
477+ colInfo[columnIndex].colTypeName = typeName;
478+ } else {
479+ colInfo[columnIndex].colTypeName = "";
480+ }
481+ }
482+
483+ /**
484+ * Retrieves the number of columns in the <code>RowSet</code> object
485+ * for which this <code>RowSetMetaDataImpl</code> object was created.
486+ *
487+ * @return the number of columns
488+ * @throws SQLException if an error occurs determining the column count
489+ */
490+ public int getColumnCount() throws SQLException {
491+ return colCount;
492+ }
493+
494+ /**
495+ * Retrieves whether a value stored in the designated column is
496+ * automatically numbered, and thus readonly.
497+ *
498+ * @param columnIndex the first column is 1, the second is 2, and so on;
499+ * must be between <code>1</code> and the number of columns, inclusive
500+ * @return <code>true</code> if the column is automatically numbered;
501+ * <code>false</code> otherwise
502+ * @throws SQLException if a database access error occurs
503+ * or the given column number is out of bounds
504+ */
505+ public boolean isAutoIncrement(int columnIndex) throws SQLException {
506+ checkColRange(columnIndex);
507+ return colInfo[columnIndex].autoIncrement;
508+ }
509+
510+ /**
511+ * Indicates whether the case of the designated column's name
512+ * matters.
513+ *
514+ * @param columnIndex the first column is 1, the second is 2, and so on;
515+ * must be between <code>1</code> and the number of columns, inclusive
516+ * @return <code>true</code> if the column name is case sensitive;
517+ * <code>false</code> otherwise
518+ * @throws SQLException if a database access error occurs
519+ * or the given column number is out of bounds
520+ */
521+ public boolean isCaseSensitive(int columnIndex) throws SQLException {
522+ checkColRange(columnIndex);
523+ return colInfo[columnIndex].caseSensitive;
524+ }
525+
526+ /**
527+ * Indicates whether a value stored in the designated column
528+ * can be used in a <code>WHERE</code> clause.
529+ *
530+ * @param columnIndex the first column is 1, the second is 2, and so on;
531+ * must be between <code>1</code> and the number of columns, inclusive
532+ * @return <code>true</code> if a value in the designated column can be used in a
533+ * <code>WHERE</code> clause; <code>false</code> otherwise
534+ * @throws SQLException if a database access error occurs
535+ * or the given column number is out of bounds
536+ */
537+ public boolean isSearchable(int columnIndex) throws SQLException {
538+ checkColRange(columnIndex);
539+ return colInfo[columnIndex].searchable;
540+ }
541+
542+ /**
543+ * Indicates whether a value stored in the designated column
544+ * is a cash value.
545+ *
546+ * @param columnIndex the first column is 1, the second is 2, and so on;
547+ * must be between <code>1</code> and the number of columns, inclusive
548+ * @return <code>true</code> if a value in the designated column is a cash value;
549+ * <code>false</code> otherwise
550+ * @throws SQLException if a database access error occurs
551+ * or the given column number is out of bounds
552+ */
553+ public boolean isCurrency(int columnIndex) throws SQLException {
554+ checkColRange(columnIndex);
555+ return colInfo[columnIndex].currency;
556+ }
557+
558+ /**
559+ * Retrieves a constant indicating whether it is possible
560+ * to store a <code>NULL</code> value in the designated column.
561+ *
562+ * @param columnIndex the first column is 1, the second is 2, and so on;
563+ * must be between <code>1</code> and the number of columns, inclusive
564+ * @return a constant from the <code>ResultSetMetaData</code> interface;
565+ * either <code>columnNoNulls</code>,
566+ * <code>columnNullable</code>, or
567+ * <code>columnNullableUnknown</code>
568+ * @throws SQLException if a database access error occurs
569+ * or the given column number is out of bounds
570+ */
571+ public int isNullable(int columnIndex) throws SQLException {
572+ checkColRange(columnIndex);
573+ return colInfo[columnIndex].nullable;
574+ }
575+
576+ /**
577+ * Indicates whether a value stored in the designated column is
578+ * a signed number.
579+ *
580+ * @param columnIndex the first column is 1, the second is 2, and so on;
581+ * must be between <code>1</code> and the number of columns, inclusive
582+ * @return <code>true</code> if if a value in the designated column is a signed
583+ * number; <code>false</code> otherwise
584+ * @throws SQLException if a database access error occurs
585+ * or the given column number is out of bounds
586+ */
587+ public boolean isSigned(int columnIndex) throws SQLException {
588+ checkColRange(columnIndex);
589+ return colInfo[columnIndex].signed;
590+ }
591+
592+ /**
593+ * Retrieves the normal maximum width in chars of the designated column.
594+ *
595+ * @param columnIndex the first column is 1, the second is 2, and so on;
596+ * must be between <code>1</code> and the number of columns, inclusive
597+ * @return the maximum number of chars that can be displayed in the designated
598+ * column
599+ * @throws SQLException if a database access error occurs
600+ * or the given column number is out of bounds
601+ */
602+ public int getColumnDisplaySize(int columnIndex) throws SQLException {
603+ checkColRange(columnIndex);
604+ return colInfo[columnIndex].columnDisplaySize;
605+ }
606+
607+ /**
608+ * Retrieves the the suggested column title for the designated
609+ * column for use in printouts and displays.
610+ *
611+ * @param columnIndex the first column is 1, the second is 2, and so on;
612+ * must be between <code>1</code> and the number of columns, inclusive
613+ * @return the suggested column name to use in printouts and displays
614+ * @throws SQLException if a database access error occurs
615+ * or the given column number is out of bounds
616+ */
617+ public String getColumnLabel(int columnIndex) throws SQLException {
618+ checkColRange(columnIndex);
619+ return colInfo[columnIndex].columnLabel;
620+ }
621+
622+ /**
623+ * Retrieves the name of the designated column.
624+ *
625+ * @param columnIndex the first column is 1, the second is 2, and so on;
626+ * must be between <code>1</code> and the number of columns, inclusive
627+ * @return the column name of the designated column
628+ * @throws SQLException if a database access error occurs
629+ * or the given column number is out of bounds
630+ */
631+ public String getColumnName(int columnIndex) throws SQLException {
632+ checkColRange(columnIndex);
633+ return colInfo[columnIndex].columnName;
634+ }
635+
636+ /**
637+ * Retrieves the schema name of the table from which the value
638+ * in the designated column was derived.
639+ *
640+ * @param columnIndex the first column is 1, the second is 2, and so on;
641+ * must be between <code>1</code> and the number of columns,
642+ * inclusive
643+ * @return the schema name or an empty <code>String</code> if no schema
644+ * name is available
645+ * @throws SQLException if a database access error occurs
646+ * or the given column number is out of bounds
647+ */
648+ public String getSchemaName(int columnIndex) throws SQLException {
649+ checkColRange(columnIndex);
650+ String str ="";
651+ if(colInfo[columnIndex].schemaName == null){
652+ } else {
653+ str = colInfo[columnIndex].schemaName;
654+ }
655+ return str;
656+ }
657+
658+ /**
659+ * Retrieves the total number of digits for values stored in
660+ * the designated column.
661+ *
662+ * @param columnIndex the first column is 1, the second is 2, and so on;
663+ * must be between <code>1</code> and the number of columns, inclusive
664+ * @return the precision for values stored in the designated column
665+ * @throws SQLException if a database access error occurs
666+ * or the given column number is out of bounds
667+ */
668+ public int getPrecision(int columnIndex) throws SQLException {
669+ checkColRange(columnIndex);
670+ return colInfo[columnIndex].colPrecision;
671+ }
672+
673+ /**
674+ * Retrieves the number of digits to the right of the decimal point
675+ * for values stored in the designated column.
676+ *
677+ * @param columnIndex the first column is 1, the second is 2, and so on;
678+ * must be between <code>1</code> and the number of columns, inclusive
679+ * @return the scale for values stored in the designated column
680+ * @throws SQLException if a database access error occurs
681+ * or the given column number is out of bounds
682+ */
683+ public int getScale(int columnIndex) throws SQLException {
684+ checkColRange(columnIndex);
685+ return colInfo[columnIndex].colScale;
686+ }
687+
688+ /**
689+ * Retrieves the name of the table from which the value
690+ * in the designated column was derived.
691+ *
692+ * @param columnIndex the first column is 1, the second is 2, and so on;
693+ * must be between <code>1</code> and the number of columns, inclusive
694+ * @return the table name or an empty <code>String</code> if no table name
695+ * is available
696+ * @throws SQLException if a database access error occurs
697+ * or the given column number is out of bounds
698+ */
699+ public String getTableName(int columnIndex) throws SQLException {
700+ checkColRange(columnIndex);
701+ return colInfo[columnIndex].tableName;
702+ }
703+
704+ /**
705+ * Retrieves the catalog name of the table from which the value
706+ * in the designated column was derived.
707+ *
708+ * @param columnIndex the first column is 1, the second is 2, and so on;
709+ * must be between <code>1</code> and the number of columns, inclusive
710+ * @return the catalog name of the column's table or an empty
711+ * <code>String</code> if no catalog name is available
712+ * @throws SQLException if a database access error occurs
713+ * or the given column number is out of bounds
714+ */
715+ public String getCatalogName(int columnIndex) throws SQLException {
716+ checkColRange(columnIndex);
717+ String str ="";
718+ if(colInfo[columnIndex].catName == null){
719+ } else {
720+ str = colInfo[columnIndex].catName;
721+ }
722+ return str;
723+ }
724+
725+ /**
726+ * Retrieves the type code (one of the <code>java.sql.Types</code>
727+ * constants) for the SQL type of the value stored in the
728+ * designated column.
729+ *
730+ * @param columnIndex the first column is 1, the second is 2, and so on;
731+ * must be between <code>1</code> and the number of columns, inclusive
732+ * @return an <code>int</code> representing the SQL type of values
733+ * stored in the designated column
734+ * @throws SQLException if a database access error occurs
735+ * or the given column number is out of bounds
736+ * @see java.sql.Types
737+ */
738+ public int getColumnType(int columnIndex) throws SQLException {
739+ checkColRange(columnIndex);
740+ return colInfo[columnIndex].colType;
741+ }
742+
743+ /**
744+ * Retrieves the DBMS-specific type name for values stored in the
745+ * designated column.
746+ *
747+ * @param columnIndex the first column is 1, the second is 2, and so on;
748+ * must be between <code>1</code> and the number of columns, inclusive
749+ * @return the type name used by the data source
750+ * @throws SQLException if a database access error occurs
751+ * or the given column number is out of bounds
752+ */
753+ public String getColumnTypeName(int columnIndex) throws SQLException {
754+ checkColRange(columnIndex);
755+ return colInfo[columnIndex].colTypeName;
756+ }
757+
758+
759+ /**
760+ * Indicates whether the designated column is definitely
761+ * not writable, thus readonly.
762+ *
763+ * @param columnIndex the first column is 1, the second is 2, and so on;
764+ * must be between <code>1</code> and the number of columns, inclusive
765+ * @return <code>true</code> if this <code>RowSet</code> object is read-Only
766+ * and thus not updatable; <code>false</code> otherwise
767+ * @throws SQLException if a database access error occurs
768+ * or the given column number is out of bounds
769+ */
770+ public boolean isReadOnly(int columnIndex) throws SQLException {
771+ checkColRange(columnIndex);
772+ return colInfo[columnIndex].readOnly;
773+ }
774+
775+ /**
776+ * Indicates whether it is possible for a write operation on
777+ * the designated column to succeed. A return value of
778+ * <code>true</code> means that a write operation may or may
779+ * not succeed.
780+ *
781+ * @param columnIndex the first column is 1, the second is 2, and so on;
782+ * must be between <code>1</code> and the number of columns, inclusive
783+ * @return <code>true</code> if a write operation on the designated column may
784+ * will succeed; <code>false</code> otherwise
785+ * @throws SQLException if a database access error occurs
786+ * or the given column number is out of bounds
787+ */
788+ public boolean isWritable(int columnIndex) throws SQLException {
789+ checkColRange(columnIndex);
790+ return colInfo[columnIndex].writable;
791+ }
792+
793+ /**
794+ * Indicates whether a write operation on the designated column
795+ * will definitely succeed.
796+ *
797+ * @param columnIndex the first column is 1, the second is 2, and so on;
798+ * must be between <code>1</code> and the number of columns, inclusive
799+ * @return <code>true</code> if a write operation on the designated column will
800+ * definitely succeed; <code>false</code> otherwise
801+ * @throws SQLException if a database access error occurs
802+ * or the given column number is out of bounds
803+ */
804+ public boolean isDefinitelyWritable(int columnIndex)
805+ throws SQLException { return true;}
806+
807+ /**
808+ * Retrieves the fully-qualified name of the class in the Java
809+ * programming language to which a value in the designated column
810+ * will be mapped. For example, if the value is an <code>int</code>,
811+ * the class name returned by this method will be
812+ * <code>java.lang.Integer</code>.
813+ * <P>
814+ * If the value in the designated column has a custom mapping,
815+ * this method returns the name of the class that implements
816+ * <code>SQLData</code>. When the method <code>ResultSet.getObject</code>
817+ * is called to retrieve a value from the designated column, it will
818+ * create an instance of this class or one of its subclasses.
819+ *
820+ * @param columnIndex the first column is 1, the second is 2, and so on;
821+ * must be between <code>1</code> and the number of columns, inclusive
822+ * @return the fully-qualified name of the class in the Java programming
823+ * language that would be used by the method <code>RowSet.getObject</code> to
824+ * retrieve the value in the specified column. This is the class
825+ * name used for custom mapping when there is a custom mapping.
826+ * @throws SQLException if a database access error occurs
827+ * or the given column number is out of bounds
828+ */
829+ public String getColumnClassName(int columnIndex) throws SQLException {
830+ String className = String.class.getName();
831+
832+ int sqlType = getColumnType(columnIndex);
833+
834+ switch (sqlType) {
835+
836+ case Types.NUMERIC:
837+ case Types.DECIMAL:
838+ className = java.math.BigDecimal.class.getName();
839+ break;
840+
841+ case Types.BIT:
842+ className = java.lang.Boolean.class.getName();
843+ break;
844+
845+ case Types.TINYINT:
846+ className = java.lang.Byte.class.getName();
847+ break;
848+
849+ case Types.SMALLINT:
850+ className = java.lang.Short.class.getName();
851+ break;
852+
853+ case Types.INTEGER:
854+ className = java.lang.Integer.class.getName();
855+ break;
856+
857+ case Types.BIGINT:
858+ className = java.lang.Long.class.getName();
859+ break;
860+
861+ case Types.REAL:
862+ className = java.lang.Float.class.getName();
863+ break;
864+
865+ case Types.FLOAT:
866+ case Types.DOUBLE:
867+ className = java.lang.Double.class.getName();
868+ break;
869+
870+ case Types.BINARY:
871+ case Types.VARBINARY:
872+ case Types.LONGVARBINARY:
873+ className = "byte[]";
874+ break;
875+
876+ case Types.DATE:
877+ className = java.sql.Date.class.getName();
878+ break;
879+
880+ case Types.TIME:
881+ className = java.sql.Time.class.getName();
882+ break;
883+
884+ case Types.TIMESTAMP:
885+ className = java.sql.Timestamp.class.getName();
886+ break;
887+
888+ case Types.BLOB:
889+ className = java.sql.Blob.class.getName();
890+ break;
891+
892+ case Types.CLOB:
893+ className = java.sql.Clob.class.getName();
894+ break;
895+ }
896+
897+ return className;
898+ }
899+
900+ /**
901+ * Returns an object that implements the given interface to allow access to non-standard methods,
902+ * or standard methods not exposed by the proxy.
903+ * The result may be either the object found to implement the interface or a proxy for that object.
904+ * If the receiver implements the interface then that is the object. If the receiver is a wrapper
905+ * and the wrapped object implements the interface then that is the object. Otherwise the object is
906+ * the result of calling <code>unwrap</code> recursively on the wrapped object. If the receiver is not a
907+ * wrapper and does not implement the interface, then an <code>SQLException</code> is thrown.
908+ *
909+ * @param iface A Class defining an interface that the result must implement.
910+ * @return an object that implements the interface. May be a proxy for the actual implementing object.
911+ * @throws java.sql.SQLException If no object found that implements the interface
912+ * @since 1.6
913+ */
914+ public <T> T unwrap(java.lang.Class<T> iface) throws java.sql.SQLException {
915+
916+ if(isWrapperFor(iface)) {
917+ return iface.cast(this);
918+ } else {
919+ throw new SQLException("unwrap failed for:"+ iface);
920+ }
921+ }
922+
923+ /**
924+ * Returns true if this either implements the interface argument or is directly or indirectly a wrapper
925+ * for an object that does. Returns false otherwise. If this implements the interface then return true,
926+ * else if this is a wrapper then return the result of recursively calling <code>isWrapperFor</code> on the wrapped
927+ * object. If this does not implement the interface and is not a wrapper, return false.
928+ * This method should be implemented as a low-cost operation compared to <code>unwrap</code> so that
929+ * callers can use this method to avoid expensive <code>unwrap</code> calls that may fail. If this method
930+ * returns true then calling <code>unwrap</code> with the same argument should succeed.
931+ *
932+ * @param interfaces a Class defining an interface.
933+ * @return true if this implements the interface or directly or indirectly wraps an object that does.
934+ * @throws java.sql.SQLException if an error occurs while determining whether this is a wrapper
935+ * for an object with the given interface.
936+ * @since 1.6
937+ */
938+ public boolean isWrapperFor(Class<?> interfaces) throws SQLException {
939+ return interfaces.isInstance(this);
940+ }
941+
942+ static final long serialVersionUID = 6893806403181801867L;
943+
944+ private class ColInfo implements Serializable {
945+ /**
946+ * The field that indicates whether the value in this column is a number
947+ * that is incremented automatically, which makes the value read-only.
948+ * <code>true</code> means that the value in this column
949+ * is automatically numbered; <code>false</code> means that it is not.
950+ *
951+ * @serial
952+ */
953+ public boolean autoIncrement;
954+
955+ /**
956+ * The field that indicates whether the value in this column is case sensitive.
957+ * <code>true</code> means that it is; <code>false</code> that it is not.
958+ *
959+ * @serial
960+ */
961+ public boolean caseSensitive;
962+
963+ /**
964+ * The field that indicates whether the value in this column is a cash value
965+ * <code>true</code> means that it is; <code>false</code> that it is not.
966+ *
967+ * @serial
968+ */
969+ public boolean currency;
970+
971+ /**
972+ * The field that indicates whether the value in this column is nullable.
973+ * The possible values are the <code>ResultSet</code> constants
974+ * <code>columnNoNulls</code>, <code>columnNullable</code>, and
975+ * <code>columnNullableUnknown</code>.
976+ *
977+ * @serial
978+ */
979+ public int nullable;
980+
981+ /**
982+ * The field that indicates whether the value in this column is a signed number.
983+ * <code>true</code> means that it is; <code>false</code> that it is not.
984+ *
985+ * @serial
986+ */
987+ public boolean signed;
988+
989+ /**
990+ * The field that indicates whether the value in this column can be used in
991+ * a <code>WHERE</code> clause.
992+ * <code>true</code> means that it can; <code>false</code> that it cannot.
993+ *
994+ * @serial
995+ */
996+ public boolean searchable;
997+
998+ /**
999+ * The field that indicates the normal maximum width in characters for
1000+ * this column.
1001+ *
1002+ * @serial
1003+ */
1004+ public int columnDisplaySize;
1005+
1006+ /**
1007+ * The field that holds the suggested column title for this column, to be
1008+ * used in printing and displays.
1009+ *
1010+ * @serial
1011+ */
1012+ public String columnLabel;
1013+
1014+ /**
1015+ * The field that holds the name of this column.
1016+ *
1017+ * @serial
1018+ */
1019+ public String columnName;
1020+
1021+ /**
1022+ * The field that holds the schema name for the table from which this column
1023+ * was derived.
1024+ *
1025+ * @serial
1026+ */
1027+ public String schemaName;
1028+
1029+ /**
1030+ * The field that holds the precision of the value in this column. For number
1031+ * types, the precision is the total number of decimal digits; for character types,
1032+ * it is the maximum number of characters; for binary types, it is the maximum
1033+ * length in bytes.
1034+ *
1035+ * @serial
1036+ */
1037+ public int colPrecision;
1038+
1039+ /**
1040+ * The field that holds the scale (number of digits to the right of the decimal
1041+ * point) of the value in this column.
1042+ *
1043+ * @serial
1044+ */
1045+ public int colScale;
1046+
1047+ /**
1048+ * The field that holds the name of the table from which this column
1049+ * was derived. This value may be the empty string if there is no
1050+ * table name, such as when this column is produced by a join.
1051+ *
1052+ * @serial
1053+ */
1054+ public String tableName ="";
1055+
1056+ /**
1057+ * The field that holds the catalog name for the table from which this column
1058+ * was derived. If the DBMS does not support catalogs, the value may be the
1059+ * empty string.
1060+ *
1061+ * @serial
1062+ */
1063+ public String catName;
1064+
1065+ /**
1066+ * The field that holds the type code from the class <code>java.sql.Types</code>
1067+ * indicating the type of the value in this column.
1068+ *
1069+ * @serial
1070+ */
1071+ public int colType;
1072+
1073+ /**
1074+ * The field that holds the the type name used by this particular data source
1075+ * for the value stored in this column.
1076+ *
1077+ * @serial
1078+ */
1079+ public String colTypeName;
1080+
1081+ /**
1082+ * The field that holds the updatablity boolean per column of a RowSet
1083+ *
1084+ * @serial
1085+ */
1086+ public boolean readOnly = false;
1087+
1088+ /**
1089+ * The field that hold the writable boolean per column of a RowSet
1090+ *
1091+ *@serial
1092+ */
1093+ public boolean writable = true;
1094+ }
1095+}
java/pkg/javax/sql/rowset/RowSetProvider$1.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetProvider$2.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetProvider.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetProvider.java+311−0
@@ -0,0 +1,311 @@
1+/*
2+ * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.security.AccessController;
29+import java.security.PrivilegedAction;
30+import java.sql.SQLException;
31+import java.util.ServiceConfigurationError;
32+import java.util.ServiceLoader;
33+
34+/**
35+ * A factory API that enables applications to obtain a
36+ * {@code RowSetFactory} implementation that can be used to create different
37+ * types of {@code RowSet} implementations.
38+ * <p>
39+ * Example:
40+ * </p>
41+ * <pre>
42+ * RowSetFactory aFactory = RowSetProvider.newFactory();
43+ * CachedRowSet crs = aFactory.createCachedRowSet();
44+ * ...
45+ * RowSetFactory rsf = RowSetProvider.newFactory("com.sun.rowset.RowSetFactoryImpl", null);
46+ * WebRowSet wrs = rsf.createWebRowSet();
47+ * </pre>
48+ *<p>
49+ * Tracing of this class may be enabled by setting the System property
50+ * {@code javax.sql.rowset.RowSetFactory.debug} to any value but {@code false}.
51+ * </p>
52+ *
53+ * @author Lance Andersen
54+ * @since 1.7
55+ */
56+public class RowSetProvider {
57+
58+ private static final String ROWSET_DEBUG_PROPERTY = "javax.sql.rowset.RowSetProvider.debug";
59+ private static final String ROWSET_FACTORY_IMPL = "com.sun.rowset.RowSetFactoryImpl";
60+ private static final String ROWSET_FACTORY_NAME = "javax.sql.rowset.RowSetFactory";
61+ /**
62+ * Internal debug flag.
63+ */
64+ private static boolean debug = true;
65+
66+
67+ static {
68+ // Check to see if the debug property is set
69+ String val = getSystemProperty(ROWSET_DEBUG_PROPERTY);
70+ // Allow simply setting the prop to turn on debug
71+ debug = val != null && !"false".equals(val);
72+ }
73+
74+
75+ protected RowSetProvider () {
76+ }
77+
78+ /**
79+ * <p>Creates a new instance of a <code>RowSetFactory</code>
80+ * implementation. This method uses the following
81+ * look up order to determine
82+ * the <code>RowSetFactory</code> implementation class to load:</p>
83+ * <ul>
84+ * <li>
85+ * The System property {@code javax.sql.rowset.RowSetFactory}. For example:
86+ * <ul>
87+ * <li>
88+ * -Djavax.sql.rowset.RowSetFactory=com.sun.rowset.RowSetFactoryImpl
89+ * </li>
90+ * </ul>
91+ * <li>
92+ * The {@link ServiceLoader} API. The {@code ServiceLoader} API will look
93+ * for a class name in the file
94+ * {@code META-INF/services/javax.sql.rowset.RowSetFactory}
95+ * in jars available to the runtime. For example, to have the the RowSetFactory
96+ * implementation {@code com.sun.rowset.RowSetFactoryImpl } loaded, the
97+ * entry in {@code META-INF/services/javax.sql.rowset.RowSetFactory} would be:
98+ * <ul>
99+ * <li>
100+ * {@code com.sun.rowset.RowSetFactoryImpl }
101+ * </li>
102+ * </ul>
103+ * </li>
104+ * <li>
105+ * Platform default <code>RowSetFactory</code> instance.
106+ * </li>
107+ * </ul>
108+ *
109+ * <p>Once an application has obtained a reference to a {@code RowSetFactory},
110+ * it can use the factory to obtain RowSet instances.</p>
111+ *
112+ * @return New instance of a <code>RowSetFactory</code>
113+ *
114+ * @throws SQLException if the default factory class cannot be loaded,
115+ * instantiated. The cause will be set to actual Exception
116+ *
117+ * @see ServiceLoader
118+ * @since 1.7
119+ */
120+ public static RowSetFactory newFactory()
121+ throws SQLException {
122+ // Use the system property first
123+ RowSetFactory factory = null;
124+ String factoryClassName = null;
125+ try {
126+ trace("Checking for Rowset System Property...");
127+ factoryClassName = getSystemProperty(ROWSET_FACTORY_NAME);
128+ if (factoryClassName != null) {
129+ trace("Found system property, value=" + factoryClassName);
130+ factory = (RowSetFactory) getFactoryClass(factoryClassName, null, true).newInstance();
131+ }
132+ } catch (ClassNotFoundException e) {
133+ throw new SQLException(
134+ "RowSetFactory: " + factoryClassName + " not found", e);
135+ } catch (Exception e) {
136+ throw new SQLException(
137+ "RowSetFactory: " + factoryClassName + " could not be instantiated: " + e,
138+ e);
139+ }
140+
141+ // Check to see if we found the RowSetFactory via a System property
142+ if (factory == null) {
143+ // If the RowSetFactory is not found via a System Property, now
144+ // look it up via the ServiceLoader API and if not found, use the
145+ // Java SE default.
146+ factory = loadViaServiceLoader();
147+ factory =
148+ factory == null ? newFactory(ROWSET_FACTORY_IMPL, null) : factory;
149+ }
150+ return (factory);
151+ }
152+
153+ /**
154+ * <p>Creates a new instance of a <code>RowSetFactory</code> from the
155+ * specified factory class name.
156+ * This function is useful when there are multiple providers in the classpath.
157+ * It gives more control to the application as it can specify which provider
158+ * should be loaded.</p>
159+ *
160+ * <p>Once an application has obtained a reference to a <code>RowSetFactory</code>
161+ * it can use the factory to obtain RowSet instances.</p>
162+ *
163+ * @param factoryClassName fully qualified factory class name that
164+ * provides an implementation of <code>javax.sql.rowset.RowSetFactory</code>.
165+ *
166+ * @param cl <code>ClassLoader</code> used to load the factory
167+ * class. If <code>null</code> current <code>Thread</code>'s context
168+ * classLoader is used to load the factory class.
169+ *
170+ * @return New instance of a <code>RowSetFactory</code>
171+ *
172+ * @throws SQLException if <code>factoryClassName</code> is
173+ * <code>null</code>, or the factory class cannot be loaded, instantiated.
174+ *
175+ * @see #newFactory()
176+ *
177+ * @since 1.7
178+ */
179+ public static RowSetFactory newFactory(String factoryClassName, ClassLoader cl)
180+ throws SQLException {
181+
182+ trace("***In newInstance()");
183+ try {
184+ Class providerClass = getFactoryClass(factoryClassName, cl, false);
185+ RowSetFactory instance = (RowSetFactory) providerClass.newInstance();
186+ if (debug) {
187+ trace("Created new instance of " + providerClass +
188+ " using ClassLoader: " + cl);
189+ }
190+ return instance;
191+ } catch (ClassNotFoundException x) {
192+ throw new SQLException(
193+ "Provider " + factoryClassName + " not found", x);
194+ } catch (Exception x) {
195+ throw new SQLException(
196+ "Provider " + factoryClassName + " could not be instantiated: " + x,
197+ x);
198+ }
199+ }
200+
201+ /*
202+ * Returns the class loader to be used.
203+ * @return The ClassLoader to use.
204+ *
205+ */
206+ static private ClassLoader getContextClassLoader() throws SecurityException {
207+ return AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
208+
209+ public ClassLoader run() {
210+ ClassLoader cl = null;
211+
212+ cl = Thread.currentThread().getContextClassLoader();
213+
214+ if (cl == null) {
215+ cl = ClassLoader.getSystemClassLoader();
216+ }
217+
218+ return cl;
219+ }
220+ });
221+ }
222+
223+ /**
224+ * Attempt to load a class using the class loader supplied. If that fails
225+ * and fall back is enabled, the current (i.e. bootstrap) class loader is
226+ * tried.
227+ *
228+ * If the class loader supplied is <code>null</code>, first try using the
229+ * context class loader followed by the current class loader.
230+ * @return The class which was loaded
231+ */
232+ static private Class getFactoryClass(String factoryClassName, ClassLoader cl,
233+ boolean doFallback) throws ClassNotFoundException {
234+ try {
235+ if (cl == null) {
236+ cl = getContextClassLoader();
237+ if (cl == null) {
238+ throw new ClassNotFoundException();
239+ } else {
240+ return cl.loadClass(factoryClassName);
241+ }
242+ } else {
243+ return cl.loadClass(factoryClassName);
244+ }
245+ } catch (ClassNotFoundException e) {
246+ if (doFallback) {
247+ // Use current class loader
248+ return Class.forName(factoryClassName, true, RowSetFactory.class.getClassLoader());
249+ } else {
250+ throw e;
251+ }
252+ }
253+ }
254+
255+ /**
256+ * Use the ServiceLoader mechanism to load the default RowSetFactory
257+ * @return default RowSetFactory Implementation
258+ */
259+ static private RowSetFactory loadViaServiceLoader() throws SQLException {
260+ RowSetFactory theFactory = null;
261+ try {
262+ trace("***in loadViaServiceLoader():");
263+ for (RowSetFactory factory : ServiceLoader.load(javax.sql.rowset.RowSetFactory.class)) {
264+ trace(" Loading done by the java.util.ServiceLoader :" + factory.getClass().getName());
265+ theFactory = factory;
266+ break;
267+ }
268+ } catch (ServiceConfigurationError e) {
269+ throw new SQLException(
270+ "RowSetFactory: Error locating RowSetFactory using Service "
271+ + "Loader API: " + e, e);
272+ }
273+ return theFactory;
274+
275+ }
276+
277+ /**
278+ * Returns the requested System Property. If a {@code SecurityException}
279+ * occurs, just return NULL
280+ * @param propName - System property to retrieve
281+ * @return The System property value or NULL if the property does not exist
282+ * or a {@code SecurityException} occurs.
283+ */
284+ static private String getSystemProperty(final String propName) {
285+ String property = null;
286+ try {
287+ property = AccessController.doPrivileged(new PrivilegedAction<String>() {
288+
289+ public String run() {
290+ return System.getProperty(propName);
291+ }
292+ });
293+ } catch (SecurityException se) {
294+ if (debug) {
295+ se.printStackTrace();
296+ }
297+ }
298+ return property;
299+ }
300+
301+ /**
302+ * Debug routine which will output tracing if the System Property
303+ * -Djavax.sql.rowset.RowSetFactory.debug is set
304+ * @param msg - The debug message to display
305+ */
306+ private static void trace(String msg) {
307+ if (debug) {
308+ System.err.println("###RowSets: " + msg);
309+ }
310+ }
311+}
java/pkg/javax/sql/rowset/RowSetWarning.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/RowSetWarning.java+146−0
@@ -0,0 +1,146 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.SQLException;
29+
30+/**
31+ * An extension of <code>SQLException</code> that provides information
32+ * about database warnings set on <code>RowSet</code> objects.
33+ * Warnings are silently chained to the object whose method call
34+ * caused it to be reported.
35+ * This class complements the <code>SQLWarning</code> class.
36+ * <P>
37+ * Rowset warnings may be retrieved from <code>JdbcRowSet</code>,
38+ * <code>CachedRowSet</code><sup><font size=-2>TM</font></sup>,
39+ * <code>WebRowSet</code>, <code>FilteredRowSet</code>, or <code>JoinRowSet</code>
40+ * implementations. To retrieve the first warning reported on any
41+ * <code>RowSet</code>
42+ * implementation, use the method <code>getRowSetWarnings</code> defined
43+ * in the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code>
44+ * interface. To retrieve a warning chained to the first warning, use the
45+ * <code>RowSetWarning</code> method
46+ * <code>getNextWarning</code>. To retrieve subsequent warnings, call
47+ * <code>getNextWarning</code> on each <code>RowSetWarning</code> object that is
48+ * returned.
49+ * <P>
50+ * The inherited methods <code>getMessage</code>, <code>getSQLState</code>,
51+ * and <code>getErrorCode</code> retrieve information contained in a
52+ * <code>RowSetWarning</code> object.
53+ */
54+public class RowSetWarning extends SQLException {
55+
56+ /**
57+ * RowSetWarning object handle.
58+ */
59+ private RowSetWarning rwarning;
60+
61+ /**
62+ * Constructs a <code>RowSetWarning</code> object
63+ * with the given value for the reason; SQLState defaults to null,
64+ * and vendorCode defaults to 0.
65+ *
66+ * @param reason a <code>String</code> object giving a description
67+ * of the warning; if the <code>String</code> is <code>null</code>,
68+ * this constructor behaves like the default (zero parameter)
69+ * <code>RowSetWarning</code> constructor
70+ */
71+ public RowSetWarning(String reason) {
72+ super(reason);
73+ }
74+
75+ /**
76+ * Constructs a default <code>RowSetWarning</code> object. The reason
77+ * defaults to <code>null</code>, SQLState defaults to null and vendorCode
78+ * defaults to 0.
79+ */
80+ public RowSetWarning() {
81+ super();
82+ }
83+
84+ /**
85+ * Constructs a <code>RowSetWarning</code> object initialized with the
86+ * given values for the reason and SQLState. The vendor code defaults to 0.
87+ *
88+ * If the <code>reason</code> or <code>SQLState</code> parameters are <code>null</code>,
89+ * this constructor behaves like the default (zero parameter)
90+ * <code>RowSetWarning</code> constructor.
91+ *
92+ * @param reason a <code>String</code> giving a description of the
93+ * warning;
94+ * @param SQLState an XOPEN code identifying the warning; if a non standard
95+ * XOPEN <i>SQLState</i> is supplied, no exception is thrown.
96+ */
97+ public RowSetWarning(java.lang.String reason, java.lang.String SQLState) {
98+ super(reason, SQLState);
99+ }
100+
101+ /**
102+ * Constructs a fully specified <code>RowSetWarning</code> object initialized
103+ * with the given values for the reason, SQLState and vendorCode.
104+ *
105+ * If the <code>reason</code>, or the <code>SQLState</code>
106+ * parameters are <code>null</code>, this constructor behaves like the default
107+ * (zero parameter) <code>RowSetWarning</code> constructor.
108+ *
109+ * @param reason a <code>String</code> giving a description of the
110+ * warning;
111+ * @param SQLState an XOPEN code identifying the warning; if a non standard
112+ * XPOEN <i>SQLState</i> is supplied, no exception is thrown.
113+ * @param vendorCode a database vendor-specific warning code
114+ */
115+ public RowSetWarning(java.lang.String reason, java.lang.String SQLState, int vendorCode) {
116+ super(reason, SQLState, vendorCode);
117+ }
118+
119+ /**
120+ * Retrieves the warning chained to this <code>RowSetWarning</code>
121+ * object.
122+ *
123+ * @return the <code>RowSetWarning</code> object chained to this one; if no
124+ * <code>RowSetWarning</code> object is chained to this one,
125+ * <code>null</code> is returned (default value)
126+ * @see #setNextWarning
127+ */
128+ public RowSetWarning getNextWarning() {
129+ return rwarning;
130+ }
131+
132+ /**
133+ * Sets <i>warning</i> as the next warning, that is, the warning chained
134+ * to this <code>RowSetWarning</code> object.
135+ *
136+ * @param warning the <code>RowSetWarning</code> object to be set as the
137+ * next warning; if the <code>RowSetWarning</code> is null, this
138+ * represents the finish point in the warning chain
139+ * @see #getNextWarning
140+ */
141+ public void setNextWarning(RowSetWarning warning) {
142+ rwarning = warning;
143+ }
144+
145+ static final long serialVersionUID = 6678332766434564774L;
146+}
java/pkg/javax/sql/rowset/WebRowSet.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/WebRowSet.java+499−0
@@ -0,0 +1,499 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import javax.naming.*;
31+import java.io.*;
32+import java.math.*;
33+import org.xml.sax.*;
34+
35+/**
36+ * The standard interface that all implementations of a <code>WebRowSet</code>
37+ * must implement.
38+ * <P>
39+ * <h3>1.0 Overview</h3>
40+ * The <code>WebRowSetImpl</code> provides the standard
41+ * reference implementation, which may be extended if required.
42+ * <P>
43+ * The standard WebRowSet XML Schema definition is available at the following
44+ * URI:
45+ * <ul>
46+ * <pre>
47+ * <a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">http://java.sun.com/xml/ns/jdbc/webrowset.xsd</a>
48+ * </pre>
49+ * </ul>
50+ * It describes the standard XML document format required when describing a
51+ * <code>RowSet</code> object in XML and must be used be all standard implementations
52+ * of the <code>WebRowSet</code> interface to ensure interoperability. In addition,
53+ * the <code>WebRowSet</code> schema uses specific SQL/XML Schema annotations,
54+ * thus ensuring greater cross
55+ * platform inter-operability. This is an effort currently under way at the ISO
56+ * organization. The SQL/XML definition is available at the following URI:
57+ * <ul>
58+ * <pre>
59+ * <a href="http://standards.iso.org/iso/9075/2002/12/sqlxml">http://standards.iso.org/iso/9075/2002/12/sqlxml</a>
60+ * </pre>
61+ * </ul>
62+ * The schema definition describes the internal data of a <code>RowSet</code> object
63+ * in three distinct areas:
64+ * <UL>
65+ * <li><b>properties</b></li>
66+ * These properties describe the standard synchronization provider properties in
67+ * addition to the more general <code>RowSet</code> properties.
68+ * <p>
69+ * <li><b>metadata</b></li>
70+ * This describes the metadata associated with the tabular structure governed by a
71+ * <code>WebRowSet</code> object. The metadata described is closely aligned with the
72+ * metadata accessible in the underlying <code>java.sql.ResultSet</code> interface.
73+ * <p>
74+ * <li><b>data</b></li>
75+ * This describes the original data (the state of data since the last population
76+ * or last synchronization of the <code>WebRowSet</code> object) and the current
77+ * data. By keeping track of the delta between the original data and the current data,
78+ * a <code>WebRowSet</code> maintains
79+ * the ability to synchronize changes in its data back to the originating data source.
80+ * </ul>
81+ * <P>
82+ * <h3>2.0 WebRowSet States</h3>
83+ * The following sections demonstrates how a <code>WebRowSet</code> implementation
84+ * should use the XML Schema to describe update, insert, and delete operations
85+ * and to describe the state of a <code>WebRowSet</code> object in XML.
86+ * <p>
87+ * <h4>2.1 State 1 - Outputting a <code>WebRowSet</code> Object to XML</h3>
88+ * In this example, a <code>WebRowSet</code> object is created and populated with a simple 2 column,
89+ * 5 row table from a data source. Having the 5 rows in a <code>WebRowSet</code> object
90+ * makes it possible to describe them in XML. The
91+ * metadata describing the various standard JavaBeans properties as defined
92+ * in the RowSet interface plus the standard properties defined in
93+ * the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup> interface
94+ * provide key details that describe WebRowSet
95+ * properties. Outputting the WebRowSet object to XML using the standard
96+ * <code>writeXml</code> methods describes the internal properties as follows:
97+ * <PRE>
98+ * &lt;<font color=red>properties</font>&gt;
99+ * &lt;<font color=red>command</font>&gt;select co1, col2 from test_table&lt;<font color=red>/command</font>&gt;
100+ * &lt;<font color=red>concurrency</font>&gt;1&lt;<font color=red>/concurrency</font>&gt;
101+ * &lt;<font color=red>datasource/</font>&gt;
102+ * &lt;<font color=red>escape-processing</font>&gt;true&lt;<font color=red>/escape-processing</font>&gt;
103+ * &lt;<font color=red>fetch-direction</font>&gt;0&lt;<font color=red>/fetch-direction</font>&gt;
104+ * &lt;<font color=red>fetch-size</font>&gt;0&lt;<font color=red>/fetch-size</font>&gt;
105+ * &lt;<font color=red>isolation-level</font>&gt;1&lt;<font color=red>/isolation-level</font>&gt;
106+ * &lt;<font color=red>key-columns/</font>&gt;
107+ * &lt;<font color=red>map/</font>&gt;
108+ * &lt;<font color=red>max-field-size</font>&gt;0&lt;<font color=red>/max-field-size</font>&gt;
109+ * &lt;<font color=red>max-rows</font>&gt;0&lt;<font color=red>/max-rows</font>&gt;
110+ * &lt;<font color=red>query-timeout</font>&gt;0&lt;<font color=red>/query-timeout</font>&gt;
111+ * &lt;<font color=red>read-only</font>&gt;false&lt;<font color=red>/read-only</font>&gt;
112+ * &lt;<font color=red>rowset-type</font>&gt;TRANSACTION_READ_UNCOMMITED&lt;<font color=red>/rowset-type</font>&gt;
113+ * &lt;<font color=red>show-deleted</font>&gt;false&lt;<font color=red>/show-deleted</font>&gt;
114+ * &lt;<font color=red>table-name/</font>&gt;
115+ * &lt;<font color=red>url</font>&gt;jdbc:thin:oracle&lt;<font color=red>/url</font>&gt;
116+ * &lt;<font color=red>sync-provider</font>&gt;
117+ * &lt;<font color=red>sync-provider-name</font>&gt;.com.rowset.provider.RIOptimisticProvider&lt;<font color=red>/sync-provider-name</font>&gt;
118+ * &lt;<font color=red>sync-provider-vendor</font>&gt;Oracle Corporation&lt;<font color=red>/sync-provider-vendor</font>&gt;
119+ * &lt;<font color=red>sync-provider-version</font>&gt;1.0&lt;<font color=red>/sync-provider-name</font>&gt;
120+ * &lt;<font color=red>sync-provider-grade</font>&gt;LOW&lt;<font color=red>/sync-provider-grade</font>&gt;
121+ * &lt;<font color=red>data-source-lock</font>&gt;NONE&lt;<font color=red>/data-source-lock</font>&gt;
122+ * &lt;<font color=red>/sync-provider</font>&gt;
123+ * &lt;<font color=red>/properties</font>&gt;
124+ * </PRE>
125+ * The meta-data describing the make up of the WebRowSet is described
126+ * in XML as detailed below. Note both columns are described between the
127+ * <code>column-definition</code> tags.
128+ * <PRE>
129+ * &lt;<font color=red>metadata</font>&gt;
130+ * &lt;<font color=red>column-count</font>&gt;2&lt;<font color=red>/column-count</font>&gt;
131+ * &lt;<font color=red>column-definition</font>&gt;
132+ * &lt;<font color=red>column-index</font>&gt;1&lt;<font color=red>/column-index</font>&gt;
133+ * &lt;<font color=red>auto-increment</font>&gt;false&lt;<font color=red>/auto-increment</font>&gt;
134+ * &lt;<font color=red>case-sensitive</font>&gt;true&lt;<font color=red>/case-sensitive</font>&gt;
135+ * &lt;<font color=red>currency</font>&gt;false&lt;<font color=red>/currency</font>&gt;
136+ * &lt;<font color=red>nullable</font>&gt;1&lt;<font color=red>/nullable</font>&gt;
137+ * &lt;<font color=red>signed</font>&gt;false&lt;<font color=red>/signed</font>&gt;
138+ * &lt;<font color=red>searchable</font>&gt;true&lt;<font color=red>/searchable</font>&gt;
139+ * &lt;<font color=red>column-display-size</font>&gt;10&lt;<font color=red>/column-display-size</font>&gt;
140+ * &lt;<font color=red>column-label</font>&gt;COL1&lt;<font color=red>/column-label</font>&gt;
141+ * &lt;<font color=red>column-name</font>&gt;COL1&lt;<font color=red>/column-name</font>&gt;
142+ * &lt;<font color=red>schema-name/</font>&gt;
143+ * &lt;<font color=red>column-precision</font>&gt;10&lt;<font color=red>/column-precision</font>&gt;
144+ * &lt;<font color=red>column-scale</font>&gt;0&lt;<font color=red>/column-scale</font>&gt;
145+ * &lt;<font color=red>table-name/</font>&gt;
146+ * &lt;<font color=red>catalog-name/</font>&gt;
147+ * &lt;<font color=red>column-type</font>&gt;1&lt;<font color=red>/column-type</font>&gt;
148+ * &lt;<font color=red>column-type-name</font>&gt;CHAR&lt;<font color=red>/column-type-name</font>&gt;
149+ * &lt;<font color=red>/column-definition</font>&gt;
150+ * &lt;<font color=red>column-definition</font>&gt;
151+ * &lt;<font color=red>column-index</font>&gt;2&lt;<font color=red>/column-index</font>&gt;
152+ * &lt;<font color=red>auto-increment</font>&gt;false&lt;<font color=red>/auto-increment</font>&gt;
153+ * &lt;<font color=red>case-sensitive</font>&gt;false&lt;<font color=red>/case-sensitive</font>&gt;
154+ * &lt;<font color=red>currency</font>&gt;false&lt;<font color=red>/currency</font>&gt;
155+ * &lt;<font color=red>nullable</font>&gt;1&lt;<font color=red>/nullable</font>&gt;
156+ * &lt;<font color=red>signed</font>&gt;true&lt;<font color=red>/signed</font>&gt;
157+ * &lt;<font color=red>searchable</font>&gt;true&lt;<font color=red>/searchable</font>&gt;
158+ * &lt;<font color=red>column-display-size</font>&gt;39&lt;<font color=red>/column-display-size</font>&gt;
159+ * &lt;<font color=red>column-label</font>&gt;COL2&lt;<font color=red>/column-label</font>&gt;
160+ * &lt;<font color=red>column-name</font>&gt;COL2&lt;<font color=red>/column-name</font>&gt;
161+ * &lt;<font color=red>schema-name/</font>&gt;
162+ * &lt;<font color=red>column-precision</font>&gt;38&lt;<font color=red>/column-precision</font>&gt;
163+ * &lt;<font color=red>column-scale</font>&gt;0&lt;<font color=red>/column-scale</font>&gt;
164+ * &lt;<font color=red>table-name/</font>&gt;
165+ * &lt;<font color=red>catalog-name/</font>&gt;
166+ * &lt;<font color=red>column-type</font>&gt;3&lt;<font color=red>/column-type</font>&gt;
167+ * &lt;<font color=red>column-type-name</font>&gt;NUMBER&lt;<font color=red>/column-type-name</font>&gt;
168+ * &lt;<font color=red>/column-definition</font>&gt;
169+ * &lt;<font color=red>/metadata</font>&gt;
170+ * </PRE>
171+ * Having detailed how the properties and metadata are described, the following details
172+ * how the contents of a <code>WebRowSet</code> object is described in XML. Note, that
173+ * this describes a <code>WebRowSet</code> object that has not undergone any
174+ * modifications since its instantiation.
175+ * A <code>currentRow</code> tag is mapped to each row of the table structure that the
176+ * <code>WebRowSet</code> object provides. A <code>columnValue</code> tag may contain
177+ * either the <code>stringData</code> or <code>binaryData</code> tag, according to
178+ * the SQL type that
179+ * the XML value is mapping back to. The <code>binaryData</code> tag contains data in the
180+ * Base64 encoding and is typically used for <code>BLOB</code> and <code>CLOB</code> type data.
181+ * <PRE>
182+ * &lt;<font color=red>data</font>&gt;
183+ * &lt;<font color=red>currentRow</font>&gt;
184+ * &lt;<font color=red>columnValue</font>&gt;
185+ * firstrow
186+ * &lt;<font color=red>/columnValue</font>&gt;
187+ * &lt;<font color=red>columnValue</font>&gt;
188+ * 1
189+ * &lt;<font color=red>/columnValue</font>&gt;
190+ * &lt;<font color=red>/currentRow</font>&gt;
191+ * &lt;<font color=red>currentRow</font>&gt;
192+ * &lt;<font color=red>columnValue</font>&gt;
193+ * secondrow
194+ * &lt;<font color=red>/columnValue</font>&gt;
195+ * &lt;<font color=red>columnValue</font>&gt;
196+ * 2
197+ * &lt;<font color=red>/columnValue</font>&gt;
198+ * &lt;<font color=red>/currentRow</font>&gt;
199+ * &lt;<font color=red>currentRow</font>&gt;
200+ * &lt;<font color=red>columnValue</font>&gt;
201+ * thirdrow
202+ * &lt;<font color=red>/columnValue</font>&gt;
203+ * &lt;<font color=red>columnValue</font>&gt;
204+ * 3
205+ * &lt;<font color=red>/columnValue</font>&gt;
206+ * &lt;<font color=red>/currentRow</font>&gt;
207+ * &lt;<font color=red>currentRow</font>&gt;
208+ * &lt;<font color=red>columnValue</font>&gt;
209+ * fourthrow
210+ * &lt;<font color=red>/columnValue</font>&gt;
211+ * &lt;<font color=red>columnValue</font>&gt;
212+ * 4
213+ * &lt;<font color=red>/columnValue</font>&gt;
214+ * &lt;<font color=red>/currentRow</font>&gt;
215+ * &lt;<font color=red>/data</font>&gt;
216+ * </PRE>
217+ * <h4>2.2 State 2 - Deleting a Row</h4>
218+ * Deleting a row in a <code>WebRowSet</code> object involves simply moving to the row
219+ * to be deleted and then calling the method <code>deleteRow</code>, as in any other
220+ * <code>RowSet</code> object. The following
221+ * two lines of code, in which <i>wrs</i> is a <code>WebRowSet</code> object, delete
222+ * the third row.
223+ * <PRE>
224+ * wrs.absolute(3);
225+ * wrs.deleteRow();
226+ * </PRE>
227+ * The XML description shows the third row is marked as a <code>deleteRow</code>,
228+ * which eliminates the third row in the <code>WebRowSet</code> object.
229+ * <PRE>
230+ * &lt;<font color=red>data</font>&gt;
231+ * &lt;<font color=red>currentRow</font>&gt;
232+ * &lt;<font color=red>columnValue</font>&gt;
233+ * firstrow
234+ * &lt;<font color=red>/columnValue</font>&gt;
235+ * &lt;<font color=red>columnValue</font>&gt;
236+ * 1
237+ * &lt;<font color=red>/columnValue</font>&gt;
238+ * &lt;<font color=red>/currentRow</font>&gt;
239+ * &lt;<font color=red>currentRow</font>&gt;
240+ * &lt;<font color=red>columnValue</font>&gt;
241+ * secondrow
242+ * &lt;<font color=red>/columnValue</font>&gt;
243+ * &lt;<font color=red>columnValue</font>&gt;
244+ * 2
245+ * &lt;<font color=red>/columnValue</font>&gt;
246+ * &lt;<font color=red>/currentRow</font>&gt;
247+ * &lt;<font color=red>deleteRow</font>&gt;
248+ * &lt;<font color=red>columnValue</font>&gt;
249+ * thirdrow
250+ * &lt;<font color=red>/columnValue</font>&gt;
251+ * &lt;<font color=red>columnValue</font>&gt;
252+ * 3
253+ * &lt;<font color=red>/columnValue</font>&gt;
254+ * &lt;<font color=red>/deleteRow</font>&gt;
255+ * &lt;<font color=red>currentRow</font>&gt;
256+ * &lt;<font color=red>columnValue</font>&gt;
257+ * fourthrow
258+ * &lt;<font color=red>/columnValue</font>&gt;
259+ * &lt;<font color=red>columnValue</font>&gt;
260+ * 4
261+ * &lt;<font color=red>/columnValue</font>&gt;
262+ * &lt;<font color=red>/currentRow</font>&gt;
263+ * &lt;<font color=red>/data</font>&gt;
264+ * </PRE>
265+ * <h4>2.3 State 3 - Inserting a Row</h4>
266+ * A <code>WebRowSet</code> object can insert a new row by moving to the insert row,
267+ * calling the appropriate updater methods for each column in the row, and then
268+ * calling the method <code>insertRow</code>.
269+ * <PRE>
270+ * wrs.moveToInsertRow();
271+ * wrs.updateString(1, "fifththrow");
272+ * wrs.updateString(2, "5");
273+ * wrs.insertRow();
274+ * </PRE>
275+ * The following code fragment changes the second column value in the row just inserted.
276+ * Note that this code applies when new rows are inserted right after the current row,
277+ * which is why the method <code>next</code> moves the cursor to the correct row.
278+ * Calling the method <code>acceptChanges</code> writes the change to the data source.
279+ *
280+ * <PRE>
281+ * wrs.moveToCurrentRow();
282+ * wrs.next();
283+ * wrs.updateString(2, "V");
284+ * wrs.acceptChanges();
285+ * :
286+ * </PRE>
287+ * Describing this in XML demonstrates where the Java code inserts a new row and then
288+ * performs an update on the newly inserted row on an individual field.
289+ * <PRE>
290+ * &lt;<font color=red>data</font>&gt;
291+ * &lt;<font color=red>currentRow</font>&gt;
292+ * &lt;<font color=red>columnValue</font>&gt;
293+ * firstrow
294+ * &lt;<font color=red>/columnValue</font>&gt;
295+ * &lt;<font color=red>columnValue</font>&gt;
296+ * 1
297+ * &lt;<font color=red>/columnValue</font>&gt;
298+ * &lt;<font color=red>/currentRow</font>&gt;
299+ * &lt;<font color=red>currentRow</font>&gt;
300+ * &lt;<font color=red>columnValue</font>&gt;
301+ * secondrow
302+ * &lt;<font color=red>/columnValue</font>&gt;
303+ * &lt;<font color=red>columnValue</font>&gt;
304+ * 2
305+ * &lt;<font color=red>/columnValue</font>&gt;
306+ * &lt;<font color=red>/currentRow</font>&gt;
307+ * &lt;<font color=red>currentRow</font>&gt;
308+ * &lt;<font color=red>columnValue</font>&gt;
309+ * newthirdrow
310+ * &lt;<font color=red>/columnValue</font>&gt;
311+ * &lt;<font color=red>columnValue</font>&gt;
312+ * III
313+ * &lt;<font color=red>/columnValue</font>&gt;
314+ * &lt;<font color=red>/currentRow</font>&gt;
315+ * &lt;<font color=red>insertRow</font>&gt;
316+ * &lt;<font color=red>columnValue</font>&gt;
317+ * fifthrow
318+ * &lt;<font color=red>/columnValue</font>&gt;
319+ * &lt;<font color=red>columnValue</font>&gt;
320+ * 5
321+ * &lt;<font color=red>/columnValue</font>&gt;
322+ * &lt;<font color=red>updateValue</font>&gt;
323+ * V
324+ * &lt;<font color=red>/updateValue</font>&gt;
325+ * &lt;<font color=red>/insertRow</font>&gt;
326+ * &lt;<font color=red>currentRow</font>&gt;
327+ * &lt;<font color=red>columnValue</font>&gt;
328+ * fourthrow
329+ * &lt;<font color=red>/columnValue</font>&gt;
330+ * &lt;<font color=red>columnValue</font>&gt;
331+ * 4
332+ * &lt;<font color=red>/columnValue</font>&gt;
333+ * &lt;<font color=red>/currentRow</font>&gt;
334+ * &lt;<font color=red>/date</font>&gt;
335+ * </PRE>
336+ * <h4>2.4 State 4 - Modifying a Row</h4>
337+ * Modifying a row produces specific XML that records both the new value and the
338+ * value that was replaced. The value that was replaced becomes the original value,
339+ * and the new value becomes the current value. The following
340+ * code moves the cursor to a specific row, performs some modifications, and updates
341+ * the row when complete.
342+ * <PRE>
343+ * wrs.absolute(5);
344+ * wrs.updateString(1, "new4thRow");
345+ * wrs.updateString(2, "IV");
346+ * wrs.updateRow();
347+ * </PRE>
348+ * In XML, this is described by the <code>modifyRow</code> tag. Both the original and new
349+ * values are contained within the tag for original row tracking purposes.
350+ * <PRE>
351+ * &lt;<font color=red>data</font>&gt;
352+ * &lt;<font color=red>currentRow</font>&gt;
353+ * &lt;<font color=red>columnValue</font>&gt;
354+ * firstrow
355+ * &lt;<font color=red>/columnValue</font>&gt;
356+ * &lt;<font color=red>columnValue</font>&gt;
357+ * 1
358+ * &lt;<font color=red>/columnValue</font>&gt;
359+ * &lt;<font color=red>/currentRow</font>&gt;
360+ * &lt;<font color=red>currentRow</font>&gt;
361+ * &lt;<font color=red>columnValue</font>&gt;
362+ * secondrow
363+ * &lt;<font color=red>/columnValue</font>&gt;
364+ * &lt;<font color=red>columnValue</font>&gt;
365+ * 2
366+ * &lt;<font color=red>/columnValue</font>&gt;
367+ * &lt;<font color=red>/currentRow</font>&gt;
368+ * &lt;<font color=red>currentRow</font>&gt;
369+ * &lt;<font color=red>columnValue</font>&gt;
370+ * newthirdrow
371+ * &lt;<font color=red>/columnValue</font>&gt;
372+ * &lt;<font color=red>columnValue</font>&gt;
373+ * III
374+ * &lt;<font color=red>/columnValue</font>&gt;
375+ * &lt;<font color=red>/currentRow</font>&gt;
376+ * &lt;<font color=red>currentRow</font>&gt;
377+ * &lt;<font color=red>columnValue</font>&gt;
378+ * fifthrow
379+ * &lt;<font color=red>/columnValue</font>&gt;
380+ * &lt;<font color=red>columnValue</font>&gt;
381+ * 5
382+ * &lt;<font color=red>/columnValue</font>&gt;
383+ * &lt;<font color=red>/currentRow</font>&gt;
384+ * &lt;<font color=red>modifyRow</font>&gt;
385+ * &lt;<font color=red>columnValue</font>&gt;
386+ * fourthrow
387+ * &lt;<font color=red>/columnValue</font>&gt;
388+ * &lt;<font color=red>updateValue</font>&gt;
389+ * new4thRow
390+ * &lt;<font color=red>/updateValue</font>&gt;
391+ * &lt;<font color=red>columnValue</font>&gt;
392+ * 4
393+ * &lt;<font color=red>/columnValue</font>&gt;
394+ * &lt;<font color=red>updateValue</font>&gt;
395+ * IV
396+ * &lt;<font color=red>/updateValue</font>&gt;
397+ * &lt;<font color=red>/modifyRow</font>&gt;
398+ * &lt;<font color=red>/data</font>&gt;
399+ * </PRE>
400+ *
401+ * @see javax.sql.rowset.JdbcRowSet
402+ * @see javax.sql.rowset.CachedRowSet
403+ * @see javax.sql.rowset.FilteredRowSet
404+ * @see javax.sql.rowset.JoinRowSet
405+ */
406+
407+public interface WebRowSet extends CachedRowSet {
408+
409+ /**
410+ * Reads a <code>WebRowSet</code> object in its XML format from the given
411+ * <code>Reader</code> object.
412+ *
413+ * @param reader the <code>java.io.Reader</code> stream from which this
414+ * <code>WebRowSet</code> object will be populated
415+
416+ * @throws SQLException if a database access error occurs
417+ */
418+ public void readXml(java.io.Reader reader) throws SQLException;
419+
420+ /**
421+ * Reads a stream based XML input to populate this <code>WebRowSet</code>
422+ * object.
423+ *
424+ * @param iStream the <code>java.io.InputStream</code> from which this
425+ * <code>WebRowSet</code> object will be populated
426+ * @throws SQLException if a data source access error occurs
427+ * @throws IOException if an IO exception occurs
428+ */
429+ public void readXml(java.io.InputStream iStream) throws SQLException, IOException;
430+
431+ /**
432+ * Populates this <code>WebRowSet</code> object with
433+ * the contents of the given <code>ResultSet</code> object and writes its
434+ * data, properties, and metadata
435+ * to the given <code>Writer</code> object in XML format.
436+ * <p>
437+ * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the
438+ * contents to the XML data source. If implemented in this way, the cursor <b>must</b>
439+ * be returned to its position just prior to the <code>writeXml()</code> call.
440+ *
441+ * @param rs the <code>ResultSet</code> object with which to populate this
442+ * <code>WebRowSet</code> object
443+ * @param writer the <code>java.io.Writer</code> object to write to.
444+ * @throws SQLException if an error occurs writing out the rowset
445+ * contents in XML format
446+ */
447+ public void writeXml(ResultSet rs, java.io.Writer writer) throws SQLException;
448+
449+ /**
450+ * Populates this <code>WebRowSet</code> object with
451+ * the contents of the given <code>ResultSet</code> object and writes its
452+ * data, properties, and metadata
453+ * to the given <code>OutputStream</code> object in XML format.
454+ * <p>
455+ * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the
456+ * contents to the XML data source. If implemented in this way, the cursor <b>must</b>
457+ * be returned to its position just prior to the <code>writeXml()</code> call.
458+ *
459+ * @param rs the <code>ResultSet</code> object with which to populate this
460+ * <code>WebRowSet</code> object
461+ * @param oStream the <code>java.io.OutputStream</code> to write to
462+ * @throws SQLException if a data source access error occurs
463+ * @throws IOException if a IO exception occurs
464+ */
465+ public void writeXml(ResultSet rs, java.io.OutputStream oStream) throws SQLException, IOException;
466+
467+ /**
468+ * Writes the data, properties, and metadata for this <code>WebRowSet</code> object
469+ * to the given <code>Writer</code> object in XML format.
470+ *
471+ * @param writer the <code>java.io.Writer</code> stream to write to
472+ * @throws SQLException if an error occurs writing out the rowset
473+ * contents to XML
474+ */
475+ public void writeXml(java.io.Writer writer) throws SQLException;
476+
477+ /**
478+ * Writes the data, properties, and metadata for this <code>WebRowSet</code> object
479+ * to the given <code>OutputStream</code> object in XML format.
480+ *
481+ * @param oStream the <code>java.io.OutputStream</code> stream to write to
482+ * @throws SQLException if a data source access error occurs
483+ * @throws IOException if a IO exception occurs
484+ */
485+ public void writeXml(java.io.OutputStream oStream) throws SQLException, IOException;
486+
487+ /**
488+ * The public identifier for the XML Schema definition that defines the XML
489+ * tags and their valid values for a <code>WebRowSet</code> implementation.
490+ */
491+ public static String PUBLIC_XML_SCHEMA =
492+ "--//Oracle Corporation//XSD Schema//EN";
493+
494+ /**
495+ * The URL for the XML Schema definition file that defines the XML tags and
496+ * their valid values for a <code>WebRowSet</code> implementation.
497+ */
498+ public static String SCHEMA_SYSTEM_ID = "http://java.sun.com/xml/ns/jdbc/webrowset.xsd";
499+}
java/pkg/javax/sql/rowset/mkfile+24−0
@@ -0,0 +1,24 @@
1+<../../../../../mkconfig
2+
3+DIRS=\
4+ serial\
5+ spi\
6+
7+TARG=\
8+ BaseRowSet.dis\
9+ CachedRowSet.dis\
10+ FilteredRowSet.dis\
11+ JdbcRowSet.dis\
12+ Joinable.dis\
13+ JoinRowSet.dis\
14+ Predicate.dis\
15+ RowSetFactory.dis\
16+ RowSetMetaDataImpl.dis\
17+ RowSetProvider.dis\
18+ RowSetWarning.dis\
19+ WebRowSet.dis\
20+
21+DISBIN=$ROOT/java/dis/java/java/javax/sql/rowset
22+
23+<$ROOT/mkfiles/mkjava
24+<$ROOT/mkfiles/mksubdirs
java/pkg/javax/sql/rowset/package.html+309−0
@@ -0,0 +1,309 @@
1+<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
2+<html>
3+<head>
4+
5+ <meta http-equiv="Content-Type"
6+ content="text/html; charset=iso-8859-1">
7+<!--
8+Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
9+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10+
11+This code is free software; you can redistribute it and/or modify it
12+under the terms of the GNU General Public License version 2 only, as
13+published by the Free Software Foundation. Oracle designates this
14+particular file as subject to the "Classpath" exception as provided
15+by Oracle in the LICENSE file that accompanied this code.
16+
17+This code is distributed in the hope that it will be useful, but WITHOUT
18+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20+version 2 for more details (a copy is included in the LICENSE file that
21+accompanied this code).
22+
23+You should have received a copy of the GNU General Public License version
24+2 along with this work; if not, write to the Free Software Foundation,
25+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
26+
27+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
28+or visit www.oracle.com if you need additional information or have any
29+questions.
30+
31+-->
32+ <title>javax.sql.rowset Package</title>
33+</head>
34+ <body bgcolor="#ffffff">
35+
36+<!-- Description clause -->
37+Standard interfaces and base classes for JDBC <code>RowSet</code>
38+implementations. This package contains interfaces and classes
39+that a standard <code>RowSet</code> implementation either implements or extends.
40+
41+
42+<h2>Table of Contents</h2>
43+<ul>
44+<li><a href="#pkgspec">1.0 Package Specification</a>
45+<li><a href="#stdrowset">2.0 Standard RowSet Definitions</a>
46+<li><a href="#impl">3.0 Implementater's Guide</a>
47+<li><a href="#relspec">4.0 Related Specifications</a>
48+<li><a href="#reldocs">5.0 Related Documentation</a>
49+</ul>
50+
51+<h3><a name="pkgspec">1.0 Package Specification</a></h3>
52+This package specifies five standard JDBC <code>RowSet</code> interfaces.
53+ All five extend the
54+<a href="../RowSet.html">RowSet</a> interface described in the JDBC 3.0
55+specification. It is anticipated that additional definitions
56+of more specialized JDBC <code>RowSet</code> types will emerge as this technology
57+matures. Future definitions <i>should</i> be specified as subinterfaces using
58+inheritance similar to the way it is used in this specification.
59+<p>
60+<i>Note:</i> The interface definitions provided in this package form the basis for
61+all compliant JDBC <code>RowSet</code> implementations. Vendors and more advanced
62+developers who intend to provide their own compliant <code>RowSet</code> implementations
63+should pay particular attention to the assertions detailed in specification
64+interfaces.
65+
66+<h3><a name="stdrowset">2.0 Standard RowSet Definitions</a></h3>
67+<ul>
68+<li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around
69+a <tt>ResultSet</tt> object that makes it possible to use the result set as a
70+JavaBeans<sup><font size=-2>TM</font></sup> component. Thus,
71+a <tt>JdbcRowSet</tt> object can be a Bean that any tool
72+makes available for assembling an application as part of a component based
73+architecture . A <tt>JdbcRowSet</tt> object is a connected <code>RowSet</code>
74+object, that is, it
75+<b>must</b> continually maintain its connection to its data source using a JDBC
76+technology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code>
77+object provides a fully updatable and scrollable tabular
78+data structure as defined in the JDBC 3.0 specification.
79+<p>
80+<li><a href="CachedRowSet.html">
81+<b><code>CachedRowSet</code>&trade;</b></a>
82+ - A <tt>CachedRowSet</tt> object is a JavaBeans<sup><font size=-2>TM</font></sup>
83+ component that is scrollable, updatable, serializable, and generally disconnected from
84+ the source of its data. A <tt>CachedRowSet</tt> object
85+typically contains rows from a result set, but it can also contain rows from any
86+file with a tabular format, such as a spreadsheet. <tt>CachedRowSet</tt> implementations
87+<b>must</b> use the <tt>SyncFactory</tt> to manage and obtain pluggable
88+<code>SyncProvider</code> objects to provide synchronization between the
89+disconnected <code>RowSet</code> object and the originating data source.
90+Typically a <code>SyncProvider</code> implementation relies upon a JDBC
91+driver to obtain connectivity to a particular data source.
92+Further details on this mechanism are discussed in the <a
93+href="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> package
94+specification.
95+<p>
96+<li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A
97+<code>WebRowSet</code> object is an extension of <tt>CachedRowSet</tt>
98+that can read and write a <code>RowSet</code> object in a well formed XML format.
99+This class calls an <a href="spi/XmlReader.html"><code>XmlReader</code></a> object
100+(an extension of the <a href="../RowSetReader.html"><code>RowSetReader</code></a>
101+interface) to read a rowset in XML format. It calls an
102+<a href="spi/XmlWriter.html"><code>XmlWriter</code></a> object (an extension of the
103+<a href="../RowSetWriter.html"><code>RowSetWriter</code></a> interface)
104+to write a rowset in XML format. The reader and writer required by
105+<code>WebRowSet</code> objects are provided by the
106+<code>SyncFactory</code> in the form of <code>SyncProvider</code>
107+implementations. In order to ensure well formed XML usage, a standard generic XML
108+Schema is defined and published at
109+<a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">
110+<code>http://java.sun.com/xml/ns/jdbc/webrowset.xsd</code></a>.
111+<p>
112+<li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A
113+<tt>FilteredRowSet</tt> object provides filtering functionality in a programmatic
114+and extensible way. There are many instances when a <tt>RowSet</tt> <code>object</code>
115+has a need to provide filtering in its contents without sacrificing the disconnected
116+environment, thus saving the expense of having to create a connection to the data source.
117+Solutions to this need vary from providing heavyweight full scale
118+SQL query abilities, to portable components, to more lightweight
119+approaches. A <code>FilteredRowSet</code> object consumes
120+an implementation of the <a href="Predicate.html"><code>Predicate</code></a>
121+interface, which <b>may</b> define a filter at run time. In turn, a
122+<code>FilteredRowSet</code> object is tasked with enforcing the set filter for both
123+inbound and outbound read and write operations. That is, all filters can be
124+considered as bi-directional. No standard filters are defined;
125+however, sufficient mechanics are specified to permit any required filter to be
126+implemented.
127+<p>
128+<li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <tt>JoinRowSet</tt>
129+interface describes a mechanism by which relationships can be established between
130+two or more standard <code>RowSet</code> implementations. Any number of <tt>RowSet</tt>
131+ objects can be added to a <tt>JoinRowSet</tt> object provided the <tt>RowSet</tt>objects
132+can be related in a SQL <tt>JOIN</tt> like fashion. By definition, the SQL <tt>JOIN</tt>
133+statement is used to combine the data contained in two (<i>or more</i>) relational
134+database tables based upon a common attribute. By establishing and then enforcing
135+column matches, a <tt>JoinRowSet</tt> object establishes relationships between
136+<tt>RowSet</tt> instances without the need to touch the originating data source.
137+</ul>
138+
139+<h3><a name="impl">3.0 Implementer's Guide</a></h3>
140+Compliant implementations of JDBC <code>RowSet</code> Implementations
141+<b>must</b> follow the assertions described in this specification. In accordance
142+with the terms of the <a href="http://www.jcp.org">Java Community Process</a>, a
143+Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
144+specification. The following paragraphs outline a number of starting points for
145+implementers of the standard JDBC <code>RowSet</code> definitions. Implementers
146+should also consult the <i>Implementer's Guide</i> in the <a
147+href="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelines
148+on <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations.
149+<p>
150+<ul>
151+<li><b>3.1 Constructor</b>
152+<p>
153+ All <code>RowSet</code> implementations <strong>must</strong> provide a
154+no-argument constructor.
155+</li>
156+<li><b>3.2 Role of the <code>BaseRowSet</code> Class</b>
157+<p>
158+A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more
159+standard interfaces specified in this package and and <b>may</b> extend the
160+<a href="BaseRowSet.html"><code>BaseRowSet</code></a> abstract class. For example, a
161+<code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code>
162+interface and extend the <code>BaseRowSet</code> abstract class. The
163+<code>BaseRowSet</code> class provides the standard architecture on which all
164+<code>RowSet</code> implementations should be built, regardless of whether the
165+<code>RowSet</code> objects exist in a connected or disconnected environment.
166+The <tt>BaseRowSet</tt> abstract class provides any <tt>RowSet</tt> implementation
167+with its base functionality, including property manipulation and event notification
168+that is fully compliant with <a href="http://java.sun.com/products/javabeans">JavaBeans</a>
169+component requirements. As an example, all implementations provided in the
170+reference implementations (contained in the <tt>com.sun.rowset</tt> package) use
171+the <tt>BaseRowSet</tt> class as a basis for their implementations.
172+<P>
173+The following table illustrates the features that the <code>BaseRowSet</code>
174+abstract class provides.
175+ <blockquote>
176+ <table cellpadding="2" cellspacing="2" border="1" width="75%">
177+ <tbody>
178+ <tr>
179+ <td valign="top"><b>Feature</b><br>
180+ </td>
181+ <td valign="top"><b>Details</b><br>
182+ </td>
183+ </tr>
184+ <tr>
185+ <td valign="top">Properties<br>
186+ </td>
187+ <td valign="top">Provides standard JavaBeans property manipulation
188+ mechanisms to allow applications to get and set <code>RowSet</code> command and
189+property values. Refer to the documentation of the <tt>javax.sql.RowSet</tt>
190+interface (available in the JDBC 3.0 specification) for more details on
191+the standard <code>RowSet</code> properties.<br>
192+ </td>
193+ </tr>
194+ <tr>
195+ <td valign="top">Event notification<br>
196+ </td>
197+ <td valign="top">Provides standard JavaBeans event notifications
198+ to registered event listeners. Refer to the documentation of <tt>javax.sql.RowSetEvent
199+ </tt> interface (available in the JDBC 3.0 specification) for
200+more details on how to register and handle standard RowSet events generated
201+by compliant implementations.<br>
202+ </td>
203+ </tr>
204+ <tr>
205+ <td valign="top">Setters for a RowSet object's command<br>
206+ </td>
207+ <td valign="top">Provides a complete set of setter methods
208+ for setting RowSet command parameters.<br>
209+ </td>
210+ </tr>
211+ <tr>
212+ <td valign="top">Streams<br>
213+ </td>
214+ <td valign="top">Provides fields for storing of stream instances
215+ in addition to providing a set of constants for stream type designation.<br>
216+ </td>
217+ </tr>
218+
219+ </tbody>
220+ </table>
221+ </blockquote>
222+<p>
223+<li><b>3.3 Connected RowSet Requirements</b>
224+<p>
225+The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
226+be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
227+should ensure that this connection is provided solely by a JDBC driver.
228+Furthermore, <code>RowSet</code> objects that are implementations of the
229+<code>JdbcRowSet</code> interface and are therefore operating in a connected environment
230+do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
231+or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
232+supply their needs by virtue of the presence of an underlying updatable and scrollable
233+<code>ResultSet</code> implementation.
234+<p>
235+
236+<li>
237+<b>3.4 Disconnected RowSet Requirements</b>
238+<p>
239+A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object,
240+<b>should</b> delegate
241+connection management to a <code>SyncProvider</code> object provided by the
242+<code>SyncFactory</code>. To ensure fully disconnected semantics, all
243+disconnected <code>RowSet</code> objects <b>must</b> ensure
244+that the original connection made to the data source to populate the <code>RowSet</code>
245+object is closed to permit the garbage collector to recover and release resources. The
246+<code>SyncProvider</code> object ensures that the critical JDBC properties are
247+maintained in order to re-establish a connection to the data source when a
248+synchronization is required. A disconnected <code>RowSet</code> object should
249+therefore ensure that no
250+extraneous references remain on the <code>Connection</code> object.
251+<p>
252+<li><b>3.5 Role of RowSetMetaDataImpl</b>
253+<p>
254+The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the
255+<a href="../RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
256+method implementations for metadata for both connected and disconnected
257+<code>RowSet</code> objects. All implementations are free to use this standard
258+implementation but are not required to do so.
259+<p>
260+<li><b>3.6 RowSetWarning Class</b>
261+<p>
262+The <code>RowSetWarning</code> class provides warnings that can be set
263+on <code>RowSet</code> implementations.
264+Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects,
265+<code>RowSetWarning</code> objects are silently chained to the object whose method
266+caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>
267+ensure that this chaining occurs if a warning is generated and also ensure that the
268+warnings are available via the <code>getRowSetWarnings</code> method defined in either
269+the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface.
270+After a warning has been retrieved with one of the
271+<code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method
272+<code>getNextWarning</code> can be called on it to retrieve any warnings that might
273+be chained on it. If a warning is returned, <code>getNextWarning</code> can be called
274+on it, and so on until there are no more warnings.
275+
276+
277+<P>
278+<li><b>3.7 The Joinable Interface</b>
279+<P>
280+The <code>Joinable</code> interface provides both connected and disconnected
281+<code>RowSet</code> objects with the capability to be added to a
282+<code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.
283+A <code>RowSet</code> object that has implemented the <code>Joinable</code>
284+interface can set a match column, retrieve a match column, or unset a match column.
285+A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
286+match column as a basis for adding the <code>RowSet</code> object.
287+</li>
288+
289+<li><b>3.8 The RowSetFactory Interface</b>
290+ <p>
291+ A <code>RowSetFactory</code> implementation <strong>must</strong>
292+ be provided.
293+</li>
294+</ul>
295+
296+<h3><a name="relspec">4.0 Related Specifications</a></h3>
297+<ul>
298+<li><a href="http://java.sun.com/products/jdbc">JDBC 3.0 Specification</a>
299+<li><a href="http://www.w3.org/XML/Schema">XML Schema</a>
300+<li><a href="http://www.syncml.org">SyncML</a>
301+</ul>
302+
303+<h3><a name="reldocs">5.0 Related Documentation</a></h3>
304+<ul>
305+<li><a href="http://java.sun.com/developer/Books/JDBCTutorial/chapter5.html">
306+JDBC RowSet Tutorial</a>
307+</ul>
308+</body>
309+</html>
java/pkg/javax/sql/rowset/rowset.properties+12−0
@@ -0,0 +1,12 @@
1+#Default JDBC RowSet sync providers listing
2+#
3+
4+# Optimistic synchonriztaion provider
5+rowset.provider.classname.0=com.sun.rowset.providers.RIOptimisticProvider
6+rowset.provider.vendor.0=Oracle Corporation
7+rowset.provider.version.0=1.0
8+
9+# XML Provider using standard XML schema
10+rowset.provider.classname.1=com.sun.rowset.providers.RIXMLProvider
11+rowset.provider.vendor.1=Oracle Corporation
12+rowset.provider.version.1=1.0
java/pkg/javax/sql/rowset/serial/SQLInputImpl.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SQLInputImpl.java+830−0
@@ -0,0 +1,830 @@
1+/*
2+ * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import java.io.*;
31+import java.math.*;
32+import java.util.Map;
33+
34+/**
35+ * An input stream used for custom mapping user-defined types (UDTs).
36+ * An <code>SQLInputImpl</code> object is an input stream that contains a
37+ * stream of values that are the attributes of a UDT.
38+ * <p>
39+ * This class is used by the driver behind the scenes when the method
40+ * <code>getObject</code> is called on an SQL structured or distinct type
41+ * that has a custom mapping; a programmer never invokes
42+ * <code>SQLInputImpl</code> methods directly. They are provided here as a
43+ * convenience for those who write <code>RowSet</code> implementations.
44+ * <P>
45+ * The <code>SQLInputImpl</code> class provides a set of
46+ * reader methods analogous to the <code>ResultSet</code> getter
47+ * methods. These methods make it possible to read the values in an
48+ * <code>SQLInputImpl</code> object.
49+ * <P>
50+ * The method <code>wasNull</code> is used to determine whether the
51+ * the last value read was SQL <code>NULL</code>.
52+ * <P>When the method <code>getObject</code> is called with an
53+ * object of a class implementing the interface <code>SQLData</code>,
54+ * the JDBC driver calls the method <code>SQLData.getSQLType</code>
55+ * to determine the SQL type of the UDT being custom mapped. The driver
56+ * creates an instance of <code>SQLInputImpl</code>, populating it with the
57+ * attributes of the UDT. The driver then passes the input
58+ * stream to the method <code>SQLData.readSQL</code>, which in turn
59+ * calls the <code>SQLInputImpl</code> reader methods
60+ * to read the attributes from the input stream.
61+ * @see java.sql.SQLData
62+ */
63+public class SQLInputImpl implements SQLInput {
64+
65+ /**
66+ * <code>true</code> if the last value returned was <code>SQL NULL</code>;
67+ * <code>false</code> otherwise.
68+ */
69+ private boolean lastValueWasNull;
70+
71+ /**
72+ * The current index into the array of SQL structured type attributes
73+ * that will be read from this <code>SQLInputImpl</code> object and
74+ * mapped to the fields of a class in the Java programming language.
75+ */
76+ private int idx;
77+
78+ /**
79+ * The array of attributes to be read from this stream. The order
80+ * of the attributes is the same as the order in which they were
81+ * listed in the SQL definition of the UDT.
82+ */
83+ private Object attrib[];
84+
85+ /**
86+ * The type map to use when the method <code>readObject</code>
87+ * is invoked. This is a <code>java.util.Map</code> object in which
88+ * there may be zero or more entries. Each entry consists of the
89+ * fully qualified name of a UDT (the value to be mapped) and the
90+ * <code>Class</code> object for a class that implements
91+ * <code>SQLData</code> (the Java class that defines how the UDT
92+ * will be mapped).
93+ */
94+ private Map map;
95+
96+
97+ /**
98+ * Creates an <code>SQLInputImpl</code> object initialized with the
99+ * given array of attributes and the given type map. If any of the
100+ * attributes is a UDT whose name is in an entry in the type map,
101+ * the attribute will be mapped according to the corresponding
102+ * <code>SQLData</code> implementation.
103+ *
104+ * @param attributes an array of <code>Object</code> instances in which
105+ * each element is an attribute of a UDT. The order of the
106+ * attributes in the array is the same order in which
107+ * the attributes were defined in the UDT definition.
108+ * @param map a <code>java.util.Map</code> object containing zero or more
109+ * entries, with each entry consisting of 1) a <code>String</code>
110+ * giving the fully
111+ * qualified name of the UDT and 2) the <code>Class</code> object
112+ * for the <code>SQLData</code> implementation that defines how
113+ * the UDT is to be mapped
114+ * @throws SQLException if the <code>attributes</code> or the <code>map</code>
115+ * is a <code>null</code> value
116+ */
117+
118+ public SQLInputImpl(Object[] attributes, Map<String,Class<?>> map)
119+ throws SQLException
120+ {
121+ if ((attributes == null) || (map == null)) {
122+ throw new SQLException("Cannot instantiate a SQLInputImpl " +
123+ "object with null parameters");
124+ }
125+ // assign our local reference to the attribute stream
126+ attrib = attributes;
127+ // init the index point before the head of the stream
128+ idx = -1;
129+ // set the map
130+ this.map = map;
131+ }
132+
133+
134+ /**
135+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
136+ * as an <code>Object</code> in the Java programming language.
137+ *
138+ * @return the next value in the input stream
139+ * as an <code>Object</code> in the Java programming language
140+ * @throws SQLException if the read position is located at an invalid
141+ * position or if there are no further values in the stream
142+ */
143+ private Object getNextAttribute() throws SQLException {
144+ if (++idx >= attrib.length) {
145+ throw new SQLException("SQLInputImpl exception: Invalid read " +
146+ "position");
147+ } else {
148+ return attrib[idx];
149+ }
150+ }
151+
152+
153+ //================================================================
154+ // Methods for reading attributes from the stream of SQL data.
155+ // These methods correspond to the column-accessor methods of
156+ // java.sql.ResultSet.
157+ //================================================================
158+
159+ /**
160+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
161+ * a <code>String</code> in the Java programming language.
162+ * <p>
163+ * This method does not perform type-safe checking to determine if the
164+ * returned type is the expected type; this responsibility is delegated
165+ * to the UDT mapping as defined by a <code>SQLData</code>
166+ * implementation.
167+ * <p>
168+ * @return the next attribute in this <code>SQLInputImpl</code> object;
169+ * if the value is <code>SQL NULL</code>, return <code>null</code>
170+ * @throws SQLException if the read position is located at an invalid
171+ * position or if there are no further values in the stream.
172+ */
173+ public String readString() throws SQLException {
174+
175+ String attrib = (String)getNextAttribute();
176+
177+ if (attrib == null) {
178+ lastValueWasNull = true;
179+ return null;
180+ } else {
181+ lastValueWasNull = false;
182+ return attrib;
183+ }
184+ }
185+
186+ /**
187+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
188+ * a <code>boolean</code> in the Java programming language.
189+ * <p>
190+ * This method does not perform type-safe checking to determine if the
191+ * returned type is the expected type; this responsibility is delegated
192+ * to the UDT mapping as defined by a <code>SQLData</code>
193+ * implementation.
194+ * <p>
195+ * @return the next attribute in this <code>SQLInputImpl</code> object;
196+ * if the value is <code>SQL NULL</code>, return <code>null</code>
197+ * @throws SQLException if the read position is located at an invalid
198+ * position or if there are no further values in the stream.
199+ */
200+ public boolean readBoolean() throws SQLException {
201+
202+ Boolean attrib = (Boolean)getNextAttribute();
203+
204+ if (attrib == null) {
205+ lastValueWasNull = true;
206+ return false;
207+ } else {
208+ lastValueWasNull = false;
209+ return attrib.booleanValue();
210+ }
211+ }
212+
213+ /**
214+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
215+ * a <code>byte</code> in the Java programming language.
216+ * <p>
217+ * This method does not perform type-safe checking to determine if the
218+ * returned type is the expected type; this responsibility is delegated
219+ * to the UDT mapping as defined by a <code>SQLData</code>
220+ * implementation.
221+ * <p>
222+ * @return the next attribute in this <code>SQLInputImpl</code> object;
223+ * if the value is <code>SQL NULL</code>, return <code>null</code>
224+ * @throws SQLException if the read position is located at an invalid
225+ * position or if there are no further values in the stream
226+ */
227+ public byte readByte() throws SQLException {
228+ Byte attrib = (Byte)getNextAttribute();
229+
230+ if (attrib == null) {
231+ lastValueWasNull = true;
232+ return (byte)0;
233+ } else {
234+ lastValueWasNull = false;
235+ return attrib.byteValue();
236+ }
237+ }
238+
239+ /**
240+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
241+ * as a <code>short</code> in the Java programming language.
242+ * <P>
243+ * This method does not perform type-safe checking to determine if the
244+ * returned type is the expected type; this responsibility is delegated
245+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
246+ * <P>
247+ * @return the next attribute in this <code>SQLInputImpl</code> object;
248+ * if the value is <code>SQL NULL</code>, return <code>null</code>
249+ * @throws SQLException if the read position is located at an invalid
250+ * position or if there are no more values in the stream
251+ */
252+ public short readShort() throws SQLException {
253+ Short attrib = (Short)getNextAttribute();
254+
255+ if (attrib == null) {
256+ lastValueWasNull = true;
257+ return (short)0;
258+ } else {
259+ lastValueWasNull = false;
260+ return attrib.shortValue();
261+ }
262+ }
263+
264+ /**
265+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
266+ * as an <code>int</code> in the Java programming language.
267+ * <P>
268+ * This method does not perform type-safe checking to determine if the
269+ * returned type is the expected type; this responsibility is delegated
270+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
271+ * <P>
272+ * @return the next attribute in this <code>SQLInputImpl</code> object;
273+ * if the value is <code>SQL NULL</code>, return <code>null</code>
274+ * @throws SQLException if the read position is located at an invalid
275+ * position or if there are no more values in the stream
276+ */
277+ public int readInt() throws SQLException {
278+ Integer attrib = (Integer)getNextAttribute();
279+
280+ if (attrib == null) {
281+ lastValueWasNull = true;
282+ return (int)0;
283+ } else {
284+ lastValueWasNull = false;
285+ return attrib.intValue();
286+ }
287+ }
288+
289+ /**
290+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
291+ * as a <code>long</code> in the Java programming language.
292+ * <P>
293+ * This method does not perform type-safe checking to determine if the
294+ * returned type is the expected type; this responsibility is delegated
295+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
296+ * <P>
297+ * @return the next attribute in this <code>SQLInputImpl</code> object;
298+ * if the value is <code>SQL NULL</code>, return <code>null</code>
299+ * @throws SQLException if the read position is located at an invalid
300+ * position or if there are no more values in the stream
301+ */
302+ public long readLong() throws SQLException {
303+ Long attrib = (Long)getNextAttribute();
304+
305+ if (attrib == null) {
306+ lastValueWasNull = true;
307+ return (long)0;
308+ } else {
309+ lastValueWasNull = false;
310+ return attrib.longValue();
311+ }
312+ }
313+
314+ /**
315+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
316+ * as a <code>float</code> in the Java programming language.
317+ * <P>
318+ * This method does not perform type-safe checking to determine if the
319+ * returned type is the expected type; this responsibility is delegated
320+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
321+ * <P>
322+ * @return the next attribute in this <code>SQLInputImpl</code> object;
323+ * if the value is <code>SQL NULL</code>, return <code>null</code>
324+ * @throws SQLException if the read position is located at an invalid
325+ * position or if there are no more values in the stream
326+ */
327+ public float readFloat() throws SQLException {
328+ Float attrib = (Float)getNextAttribute();
329+
330+ if (attrib == null) {
331+ lastValueWasNull = true;
332+ return (float)0;
333+ } else {
334+ lastValueWasNull = false;
335+ return attrib.floatValue();
336+ }
337+ }
338+
339+ /**
340+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
341+ * as a <code>double</code> in the Java programming language.
342+ * <P>
343+ * This method does not perform type-safe checking to determine if the
344+ * returned type is the expected type; this responsibility is delegated
345+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
346+ * <P>
347+ * @return the next attribute in this <code>SQLInputImpl</code> object;
348+ * if the value is <code>SQL NULL</code>, return <code>null</code>
349+ * @throws SQLException if the read position is located at an invalid
350+ * position or if there are no more values in the stream
351+ */
352+ public double readDouble() throws SQLException {
353+ Double attrib = (Double)getNextAttribute();
354+
355+ if (attrib == null) {
356+ lastValueWasNull = true;
357+ return (double)0;
358+ } else {
359+ lastValueWasNull = false;
360+ return attrib.doubleValue();
361+ }
362+ }
363+
364+ /**
365+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
366+ * as a <code>java.math.BigDecimal</code>.
367+ * <P>
368+ * This method does not perform type-safe checking to determine if the
369+ * returned type is the expected type; this responsibility is delegated
370+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
371+ * <P>
372+ * @return the next attribute in this <code>SQLInputImpl</code> object;
373+ * if the value is <code>SQL NULL</code>, return <code>null</code>
374+ * @throws SQLException if the read position is located at an invalid
375+ * position or if there are no more values in the stream
376+ */
377+ public java.math.BigDecimal readBigDecimal() throws SQLException {
378+ java.math.BigDecimal attrib = (java.math.BigDecimal)getNextAttribute();
379+
380+ if (attrib == null) {
381+ lastValueWasNull = true;
382+ return null;
383+ } else {
384+ lastValueWasNull = false;
385+ return attrib;
386+ }
387+ }
388+
389+ /**
390+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
391+ * as an array of bytes.
392+ * <p>
393+ * This method does not perform type-safe checking to determine if the
394+ * returned type is the expected type; this responsibility is delegated
395+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
396+ * <P>
397+ * @return the next attribute in this <code>SQLInputImpl</code> object;
398+ * if the value is <code>SQL NULL</code>, return <code>null</code>
399+ * @throws SQLException if the read position is located at an invalid
400+ * position or if there are no more values in the stream
401+ */
402+ public byte[] readBytes() throws SQLException {
403+ byte[] attrib = (byte[])getNextAttribute();
404+
405+ if (attrib == null) {
406+ lastValueWasNull = true;
407+ return null;
408+ } else {
409+ lastValueWasNull = false;
410+ return attrib;
411+ }
412+ }
413+
414+ /**
415+ * Retrieves the next attribute in this <code>SQLInputImpl</code> as
416+ * a <code>java.sql.Date</code> object.
417+ * <P>
418+ * This method does not perform type-safe checking to determine if the
419+ * returned type is the expected type; this responsibility is delegated
420+ * to the UDT mapping as defined by a <code>SQLData</code> implementation.
421+ * <P>
422+ * @return the next attribute in this <code>SQLInputImpl</code> object;
423+ * if the value is <code>SQL NULL</code>, return <code>null</code>
424+ * @throws SQLException if the read position is located at an invalid
425+ * position or if there are no more values in the stream
426+ */
427+ public java.sql.Date readDate() throws SQLException {
428+ java.sql.Date attrib = (java.sql.Date)getNextAttribute();
429+
430+ if (attrib == null) {
431+ lastValueWasNull = true;
432+ return null;
433+ } else {
434+ lastValueWasNull = false;
435+ return attrib;
436+ }
437+ }
438+
439+ /**
440+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
441+ * a <code>java.sql.Time</code> object.
442+ * <P>
443+ * This method does not perform type-safe checking to determine if the
444+ * returned type is the expected type as this responsibility is delegated
445+ * to the UDT mapping as implemented by a <code>SQLData</code>
446+ * implementation.
447+ *
448+ * @return the attribute; if the value is <code>SQL NULL</code>, return
449+ * <code>null</code>
450+ * @throws SQLException if the read position is located at an invalid
451+ * position; or if there are no further values in the stream.
452+ */
453+ public java.sql.Time readTime() throws SQLException {
454+ java.sql.Time attrib = (java.sql.Time)getNextAttribute();
455+
456+ if (attrib == null) {
457+ lastValueWasNull = true;
458+ return null;
459+ } else {
460+ lastValueWasNull = false;
461+ return attrib;
462+ }
463+ }
464+
465+ /**
466+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object as
467+ * a <code>java.sql.Timestamp</code> object.
468+ *
469+ * @return the attribute; if the value is <code>SQL NULL</code>, return
470+ * <code>null</code>
471+ * @throws SQLException if the read position is located at an invalid
472+ * position; or if there are no further values in the stream.
473+ */
474+ public java.sql.Timestamp readTimestamp() throws SQLException {
475+ java.sql.Timestamp attrib = (java.sql.Timestamp)getNextAttribute();
476+
477+ if (attrib == null) {
478+ lastValueWasNull = true;
479+ return null;
480+ } else {
481+ lastValueWasNull = false;
482+ return attrib;
483+ }
484+ }
485+
486+ /**
487+ * Retrieves the next attribute in this <code>SQLInputImpl</code> object
488+ * as a stream of Unicode characters.
489+ * <P>
490+ * This method does not perform type-safe checking to determine if the
491+ * returned type is the expected type as this responsibility is delegated
492+ * to the UDT mapping as implemented by a <code>SQLData</code>
493+ * implementation.
494+ *
495+ * @return the attribute; if the value is <code>SQL NULL</code>, return <code>null</code>
496+ * @throws SQLException if the read position is located at an invalid
497+ * position; or if there are no further values in the stream.
498+ */
499+ public java.io.Reader readCharacterStream() throws SQLException {
500+ java.io.Reader attrib = (java.io.Reader)getNextAttribute();
501+
502+ if (attrib == null) {
503+ lastValueWasNull = true;
504+ return null;
505+ } else {
506+ lastValueWasNull = false;
507+ return attrib;
508+ }
509+ }
510+
511+ /**
512+ * Returns the next attribute in this <code>SQLInputImpl</code> object
513+ * as a stream of ASCII characters.
514+ * <P>
515+ * This method does not perform type-safe checking to determine if the
516+ * returned type is the expected type as this responsibility is delegated
517+ * to the UDT mapping as implemented by a <code>SQLData</code>
518+ * implementation.
519+ *
520+ * @return the attribute; if the value is <code>SQL NULL</code>,
521+ * return <code>null</code>
522+ * @throws SQLException if the read position is located at an invalid
523+ * position; or if there are no further values in the stream.
524+ */
525+ public java.io.InputStream readAsciiStream() throws SQLException {
526+ java.io.InputStream attrib = (java.io.InputStream)getNextAttribute();
527+
528+ if (attrib == null) {
529+ lastValueWasNull = true;
530+ return null;
531+ } else {
532+ lastValueWasNull = false;
533+ return attrib;
534+ }
535+ }
536+
537+ /**
538+ * Returns the next attribute in this <code>SQLInputImpl</code> object
539+ * as a stream of uninterpreted bytes.
540+ * <P>
541+ * This method does not perform type-safe checking to determine if the
542+ * returned type is the expected type as this responsibility is delegated
543+ * to the UDT mapping as implemented by a <code>SQLData</code>
544+ * implementation.
545+ *
546+ * @return the attribute; if the value is <code>SQL NULL</code>, return
547+ * <code>null</code>
548+ * @throws SQLException if the read position is located at an invalid
549+ * position; or if there are no further values in the stream.
550+ */
551+ public java.io.InputStream readBinaryStream() throws SQLException {
552+ java.io.InputStream attrib = (java.io.InputStream)getNextAttribute();
553+
554+ if (attrib == null) {
555+ lastValueWasNull = true;
556+ return null;
557+ } else {
558+ lastValueWasNull = false;
559+ return attrib;
560+ }
561+ }
562+
563+ //================================================================
564+ // Methods for reading items of SQL user-defined types from the stream.
565+ //================================================================
566+
567+ /**
568+ * Retrieves the value at the head of this <code>SQLInputImpl</code>
569+ * object as an <code>Object</code> in the Java programming language. The
570+ * actual type of the object returned is determined by the default
571+ * mapping of SQL types to types in the Java programming language unless
572+ * there is a custom mapping, in which case the type of the object
573+ * returned is determined by this stream's type map.
574+ * <P>
575+ * The JDBC technology-enabled driver registers a type map with the stream
576+ * before passing the stream to the application.
577+ * <P>
578+ * When the datum at the head of the stream is an SQL <code>NULL</code>,
579+ * this method returns <code>null</code>. If the datum is an SQL
580+ * structured or distinct type with a custom mapping, this method
581+ * determines the SQL type of the datum at the head of the stream,
582+ * constructs an object of the appropriate class, and calls the method
583+ * <code>SQLData.readSQL</code> on that object. The <code>readSQL</code>
584+ * method then calls the appropriate <code>SQLInputImpl.readXXX</code>
585+ * methods to retrieve the attribute values from the stream.
586+ *
587+ * @return the value at the head of the stream as an <code>Object</code>
588+ * in the Java programming language; <code>null</code> if
589+ * the value is SQL <code>NULL</code>
590+ * @throws SQLException if the read position is located at an invalid
591+ * position; or if there are no further values in the stream.
592+ */
593+ public Object readObject() throws SQLException {
594+ Object attrib = (Object)getNextAttribute();
595+
596+ if (attrib == null) {
597+ lastValueWasNull = true;
598+ return null;
599+ } else {
600+ lastValueWasNull = false;
601+ if (attrib instanceof Struct) {
602+ Struct s = (Struct)attrib;
603+ // look up the class in the map
604+ Class c = (Class)map.get(s.getSQLTypeName());
605+ if (c != null) {
606+ // create new instance of the class
607+ SQLData obj = null;
608+ try {
609+ obj = (SQLData)c.newInstance();
610+ } catch (java.lang.InstantiationException ex) {
611+ throw new SQLException("Unable to instantiate: " +
612+ ex.getMessage());
613+ } catch (java.lang.IllegalAccessException ex) {
614+ throw new SQLException("Unable to instantiate: " +
615+ ex.getMessage());
616+ }
617+ // get the attributes from the struct
618+ Object attribs[] = s.getAttributes(map);
619+ // create the SQLInput "stream"
620+ SQLInputImpl sqlInput = new SQLInputImpl(attribs, map);
621+ // read the values...
622+ obj.readSQL(sqlInput, s.getSQLTypeName());
623+ return (Object)obj;
624+ }
625+ }
626+ return (Object)attrib;
627+ }
628+ }
629+
630+ /**
631+ * Retrieves the value at the head of this <code>SQLInputImpl</code> object
632+ * as a <code>Ref</code> object in the Java programming language.
633+ *
634+ * @return a <code>Ref</code> object representing the SQL
635+ * <code>REF</code> value at the head of the stream; if the value
636+ * is <code>SQL NULL</code> return <code>null</code>
637+ * @throws SQLException if the read position is located at an invalid
638+ * position; or if there are no further values in the stream.
639+ */
640+ public Ref readRef() throws SQLException {
641+ Ref attrib = (Ref)getNextAttribute();
642+
643+ if (attrib == null) {
644+ lastValueWasNull = true;
645+ return null;
646+ } else {
647+ lastValueWasNull = false;
648+ return attrib;
649+ }
650+ }
651+
652+ /**
653+ * Retrieves the <code>BLOB</code> value at the head of this
654+ * <code>SQLInputImpl</code> object as a <code>Blob</code> object
655+ * in the Java programming language.
656+ * <P>
657+ * This method does not perform type-safe checking to determine if the
658+ * returned type is the expected type as this responsibility is delegated
659+ * to the UDT mapping as implemented by a <code>SQLData</code>
660+ * implementation.
661+ *
662+ * @return a <code>Blob</code> object representing the SQL
663+ * <code>BLOB</code> value at the head of this stream;
664+ * if the value is <code>SQL NULL</code>, return
665+ * <code>null</code>
666+ * @throws SQLException if the read position is located at an invalid
667+ * position; or if there are no further values in the stream.
668+ */
669+ public Blob readBlob() throws SQLException {
670+ Blob attrib = (Blob)getNextAttribute();
671+
672+ if (attrib == null) {
673+ lastValueWasNull = true;
674+ return null;
675+ } else {
676+ lastValueWasNull = false;
677+ return attrib;
678+ }
679+ }
680+
681+ /**
682+ * Retrieves the <code>CLOB</code> value at the head of this
683+ * <code>SQLInputImpl</code> object as a <code>Clob</code> object
684+ * in the Java programming language.
685+ * <P>
686+ * This method does not perform type-safe checking to determine if the
687+ * returned type is the expected type as this responsibility is delegated
688+ * to the UDT mapping as implemented by a <code>SQLData</code>
689+ * implementation.
690+ *
691+ * @return a <code>Clob</code> object representing the SQL
692+ * <code>CLOB</code> value at the head of the stream;
693+ * if the value is <code>SQL NULL</code>, return
694+ * <code>null</code>
695+ * @throws SQLException if the read position is located at an invalid
696+ * position; or if there are no further values in the stream.
697+ */
698+ public Clob readClob() throws SQLException {
699+
700+ Clob attrib = (Clob)getNextAttribute();
701+ if (attrib == null) {
702+ lastValueWasNull = true;
703+ return null;
704+ } else {
705+ lastValueWasNull = false;
706+ return attrib;
707+ }
708+ }
709+
710+ /**
711+ * Reads an SQL <code>ARRAY</code> value from the stream and
712+ * returns it as an <code>Array</code> object in the Java programming
713+ * language.
714+ * <P>
715+ * This method does not perform type-safe checking to determine if the
716+ * returned type is the expected type as this responsibility is delegated
717+ * to the UDT mapping as implemented by a <code>SQLData</code>
718+ * implementation.
719+ *
720+ * @return an <code>Array</code> object representing the SQL
721+ * <code>ARRAY</code> value at the head of the stream; *
722+ * if the value is <code>SQL NULL</code>, return
723+ * <code>null</code>
724+ * @throws SQLException if the read position is located at an invalid
725+ * position; or if there are no further values in the stream.
726+
727+ */
728+ public Array readArray() throws SQLException {
729+ Array attrib = (Array)getNextAttribute();
730+
731+ if (attrib == null) {
732+ lastValueWasNull = true;
733+ return null;
734+ } else {
735+ lastValueWasNull = false;
736+ return attrib;
737+ }
738+ }
739+
740+ /**
741+ * Ascertains whether the last value read from this
742+ * <code>SQLInputImpl</code> object was <code>null</code>.
743+ *
744+ * @return <code>true</code> if the SQL value read most recently was
745+ * <code>null</code>; otherwise, <code>false</code>; by default it
746+ * will return false
747+ * @throws SQLException if an error occurs determining the last value
748+ * read was a <code>null</code> value or not;
749+ */
750+ public boolean wasNull() throws SQLException {
751+ return lastValueWasNull;
752+ }
753+
754+ /**
755+ * Reads an SQL <code>DATALINK</code> value from the stream and
756+ * returns it as an <code>URL</code> object in the Java programming
757+ * language.
758+ * <P>
759+ * This method does not perform type-safe checking to determine if the
760+ * returned type is the expected type as this responsibility is delegated
761+ * to the UDT mapping as implemented by a <code>SQLData</code>
762+ * implementation.
763+ *
764+ * @return an <code>URL</code> object representing the SQL
765+ * <code>DATALINK</code> value at the head of the stream; *
766+ * if the value is <code>SQL NULL</code>, return
767+ * <code>null</code>
768+ * @throws SQLException if the read position is located at an invalid
769+ * position; or if there are no further values in the stream.
770+ */
771+ public java.net.URL readURL() throws SQLException {
772+ throw new SQLException("Operation not supported");
773+ }
774+
775+ //---------------------------- JDBC 4.0 -------------------------
776+
777+ /**
778+ * Reads an SQL <code>NCLOB</code> value from the stream and returns it as a
779+ * <code>Clob</code> object in the Java programming language.
780+ *
781+ * @return a <code>NClob</code> object representing data of the SQL <code>NCLOB</code> value
782+ * at the head of the stream; <code>null</code> if the value read is
783+ * SQL <code>NULL</code>
784+ * @exception SQLException if a database access error occurs
785+ */
786+ public NClob readNClob() throws SQLException {
787+ throw new UnsupportedOperationException("Operation not supported");
788+ }
789+
790+ /**
791+ * Reads the next attribute in the stream and returns it as a <code>String</code>
792+ * in the Java programming language. It is intended for use when
793+ * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
794+ * and <code>LONGNVARCHAR</code> columns.
795+ *
796+ * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
797+ * @exception SQLException if a database access error occurs
798+ */
799+ public String readNString() throws SQLException {
800+ throw new UnsupportedOperationException("Operation not supported");
801+ }
802+
803+ /**
804+ * Reads an SQL <code>XML</code> value from the stream and returns it as a
805+ * <code>SQLXML</code> object in the Java programming language.
806+ *
807+ * @return a <code>SQLXML</code> object representing data of the SQL <code>XML</code> value
808+ * at the head of the stream; <code>null</code> if the value read is
809+ * SQL <code>NULL</code>
810+ * @exception SQLException if a database access error occurs
811+ */
812+ public SQLXML readSQLXML() throws SQLException {
813+ throw new UnsupportedOperationException("Operation not supported");
814+ }
815+
816+ /**
817+ * Reads an SQL <code>ROWID</code> value from the stream and returns it as a
818+ * <code>RowId</code> object in the Java programming language.
819+ *
820+ * @return a <code>RowId</code> object representing data of the SQL <code>ROWID</code> value
821+ * at the head of the stream; <code>null</code> if the value read is
822+ * SQL <code>NULL</code>
823+ * @exception SQLException if a database access error occurs
824+ */
825+ public RowId readRowId() throws SQLException {
826+ throw new UnsupportedOperationException("Operation not supported");
827+ }
828+
829+
830+}
java/pkg/javax/sql/rowset/serial/SQLOutputImpl.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SQLOutputImpl.java+618−0
@@ -0,0 +1,618 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import java.io.*;
31+import java.lang.String;
32+import java.math.*;
33+import java.util.Map;
34+import java.util.Vector;
35+
36+/**
37+ * The output stream for writing the attributes of a
38+ * custom-mapped user-defined type (UDT) back to the database.
39+ * The driver uses this interface internally, and its
40+ * methods are never directly invoked by an application programmer.
41+ * <p>
42+ * When an application calls the
43+ * method <code>PreparedStatement.setObject</code>, the driver
44+ * checks to see whether the value to be written is a UDT with
45+ * a custom mapping. If it is, there will be an entry in a
46+ * type map containing the <code>Class</code> object for the
47+ * class that implements <code>SQLData</code> for this UDT.
48+ * If the value to be written is an instance of <code>SQLData</code>,
49+ * the driver will create an instance of <code>SQLOutputImpl</code>
50+ * and pass it to the method <code>SQLData.writeSQL</code>.
51+ * The method <code>writeSQL</code> in turn calls the
52+ * appropriate <code>SQLOutputImpl.writeXXX</code> methods
53+ * to write data from the <code>SQLData</code> object to
54+ * the <code>SQLOutputImpl</code> output stream as the
55+ * representation of an SQL user-defined type.
56+ */
57+public class SQLOutputImpl implements SQLOutput {
58+
59+ /**
60+ * A reference to an existing vector that
61+ * contains the attributes of a <code>Struct</code> object.
62+ */
63+ private Vector attribs;
64+
65+ /**
66+ * The type map the driver supplies to a newly created
67+ * <code>SQLOutputImpl</code> object. This type map
68+ * indicates the <code>SQLData</code> class whose
69+ * <code>writeSQL</code> method will be called. This
70+ * method will in turn call the appropriate
71+ * <code>SQLOutputImpl</code> writer methods.
72+ */
73+ private Map map;
74+
75+ /**
76+ * Creates a new <code>SQLOutputImpl</code> object
77+ * initialized with the given vector of attributes and
78+ * type map. The driver will use the type map to determine
79+ * which <code>SQLData.writeSQL</code> method to invoke.
80+ * This method will then call the appropriate
81+ * <code>SQLOutputImpl</code> writer methods in order and
82+ * thereby write the attributes to the new output stream.
83+ *
84+ * @param attributes a <code>Vector</code> object containing the attributes of
85+ * the UDT to be mapped to one or more objects in the Java
86+ * programming language
87+ *
88+ * @param map a <code>java.util.Map</code> object containing zero or
89+ * more entries, with each entry consisting of 1) a <code>String</code>
90+ * giving the fully qualified name of a UDT and 2) the
91+ * <code>Class</code> object for the <code>SQLData</code> implementation
92+ * that defines how the UDT is to be mapped
93+ * @throws SQLException if the <code>attributes</code> or the <code>map</code>
94+ * is a <code>null</code> value
95+ */
96+ public SQLOutputImpl(Vector<?> attributes, Map<String,?> map)
97+ throws SQLException
98+ {
99+ if ((attributes == null) || (map == null)) {
100+ throw new SQLException("Cannot instantiate a SQLOutputImpl " +
101+ "instance with null parameters");
102+ }
103+ this.attribs = attributes;
104+ this.map = map;
105+ }
106+
107+ //================================================================
108+ // Methods for writing attributes to the stream of SQL data.
109+ // These methods correspond to the column-accessor methods of
110+ // java.sql.ResultSet.
111+ //================================================================
112+
113+ /**
114+ * Writes a <code>String</code> in the Java programming language
115+ * to this <code>SQLOutputImpl</code> object. The driver converts
116+ * it to an SQL <code>CHAR</code>, <code>VARCHAR</code>, or
117+ * <code>LONGVARCHAR</code> before returning it to the database.
118+ *
119+ * @param x the value to pass to the database
120+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
121+ * use by a <code>SQLData</code> object attempting to write the attribute
122+ * values of a UDT to the database.
123+ */
124+ public void writeString(String x) throws SQLException {
125+ //System.out.println("Adding :"+x);
126+ attribs.add(x);
127+ }
128+
129+ /**
130+ * Writes a <code>boolean</code> in the Java programming language
131+ * to this <code>SQLOutputImpl</code> object. The driver converts
132+ * it to an SQL <code>BIT</code> before returning it to the database.
133+ *
134+ * @param x the value to pass to the database
135+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
136+ * use by a <code>SQLData</code> object attempting to write the attribute
137+ * values of a UDT to the database.
138+ */
139+ public void writeBoolean(boolean x) throws SQLException {
140+ attribs.add(Boolean.valueOf(x));
141+ }
142+
143+ /**
144+ * Writes a <code>byte</code> in the Java programming language
145+ * to this <code>SQLOutputImpl</code> object. The driver converts
146+ * it to an SQL <code>BIT</code> before returning it to the database.
147+ *
148+ * @param x the value to pass to the database
149+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
150+ * use by a <code>SQLData</code> object attempting to write the attribute
151+ * values of a UDT to the database.
152+ */
153+ public void writeByte(byte x) throws SQLException {
154+ attribs.add(Byte.valueOf(x));
155+ }
156+
157+ /**
158+ * Writes a <code>short</code> in the Java programming language
159+ * to this <code>SQLOutputImpl</code> object. The driver converts
160+ * it to an SQL <code>SMALLINT</code> before returning it to the database.
161+ *
162+ * @param x the value to pass to the database
163+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
164+ * use by a <code>SQLData</code> object attempting to write the attribute
165+ * values of a UDT to the database.
166+ */
167+ public void writeShort(short x) throws SQLException {
168+ attribs.add(Short.valueOf(x));
169+ }
170+
171+ /**
172+ * Writes an <code>int</code> in the Java programming language
173+ * to this <code>SQLOutputImpl</code> object. The driver converts
174+ * it to an SQL <code>INTEGER</code> before returning it to the database.
175+ *
176+ * @param x the value to pass to the database
177+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
178+ * use by a <code>SQLData</code> object attempting to write the attribute
179+ * values of a UDT to the database.
180+ */
181+ public void writeInt(int x) throws SQLException {
182+ attribs.add(Integer.valueOf(x));
183+ }
184+
185+ /**
186+ * Writes a <code>long</code> in the Java programming language
187+ * to this <code>SQLOutputImpl</code> object. The driver converts
188+ * it to an SQL <code>BIGINT</code> before returning it to the database.
189+ *
190+ * @param x the value to pass to the database
191+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
192+ * use by a <code>SQLData</code> object attempting to write the attribute
193+ * values of a UDT to the database.
194+ */
195+ public void writeLong(long x) throws SQLException {
196+ attribs.add(Long.valueOf(x));
197+ }
198+
199+ /**
200+ * Writes a <code>float</code> in the Java programming language
201+ * to this <code>SQLOutputImpl</code> object. The driver converts
202+ * it to an SQL <code>REAL</code> before returning it to the database.
203+ *
204+ * @param x the value to pass to the database
205+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
206+ * use by a <code>SQLData</code> object attempting to write the attribute
207+ * values of a UDT to the database.
208+ */
209+ public void writeFloat(float x) throws SQLException {
210+ attribs.add(new Float(x));
211+ }
212+
213+ /**
214+ * Writes a <code>double</code> in the Java programming language
215+ * to this <code>SQLOutputImpl</code> object. The driver converts
216+ * it to an SQL <code>DOUBLE</code> before returning it to the database.
217+ *
218+ * @param x the value to pass to the database
219+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
220+ * use by a <code>SQLData</code> object attempting to write the attribute
221+ * values of a UDT to the database.
222+ */
223+ public void writeDouble(double x) throws SQLException{
224+ attribs.add(new Double(x));
225+ }
226+
227+ /**
228+ * Writes a <code>java.math.BigDecimal</code> object in the Java programming
229+ * language to this <code>SQLOutputImpl</code> object. The driver converts
230+ * it to an SQL <code>NUMERIC</code> before returning it to the database.
231+ *
232+ * @param x the value to pass to the database
233+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
234+ * use by a <code>SQLData</code> object attempting to write the attribute
235+ * values of a UDT to the database.
236+ */
237+ public void writeBigDecimal(java.math.BigDecimal x) throws SQLException{
238+ attribs.add(x);
239+ }
240+
241+ /**
242+ * Writes an array of <code>bytes</code> in the Java programming language
243+ * to this <code>SQLOutputImpl</code> object. The driver converts
244+ * it to an SQL <code>VARBINARY</code> or <code>LONGVARBINARY</code>
245+ * before returning it to the database.
246+ *
247+ * @param x the value to pass to the database
248+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
249+ * use by a <code>SQLData</code> object attempting to write the attribute
250+ * values of a UDT to the database.
251+ */
252+ public void writeBytes(byte[] x) throws SQLException {
253+ attribs.add(x);
254+ }
255+
256+ /**
257+ * Writes a <code>java.sql.Date</code> object in the Java programming
258+ * language to this <code>SQLOutputImpl</code> object. The driver converts
259+ * it to an SQL <code>DATE</code> before returning it to the database.
260+ *
261+ * @param x the value to pass to the database
262+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
263+ * use by a <code>SQLData</code> object attempting to write the attribute
264+ * values of a UDT to the database.
265+ */
266+ public void writeDate(java.sql.Date x) throws SQLException {
267+ attribs.add(x);
268+ }
269+
270+ /**
271+ * Writes a <code>java.sql.Time</code> object in the Java programming
272+ * language to this <code>SQLOutputImpl</code> object. The driver converts
273+ * it to an SQL <code>TIME</code> before returning it to the database.
274+ *
275+ * @param x the value to pass to the database
276+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
277+ * use by a <code>SQLData</code> object attempting to write the attribute
278+ * values of a UDT to the database.
279+ */
280+ public void writeTime(java.sql.Time x) throws SQLException {
281+ attribs.add(x);
282+ }
283+
284+ /**
285+ * Writes a <code>java.sql.Timestamp</code> object in the Java programming
286+ * language to this <code>SQLOutputImpl</code> object. The driver converts
287+ * it to an SQL <code>TIMESTAMP</code> before returning it to the database.
288+ *
289+ * @param x the value to pass to the database
290+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
291+ * use by a <code>SQLData</code> object attempting to write the attribute
292+ * values of a UDT to the database.
293+ */
294+ public void writeTimestamp(java.sql.Timestamp x) throws SQLException {
295+ attribs.add(x);
296+ }
297+
298+ /**
299+ * Writes a stream of Unicode characters to this
300+ * <code>SQLOutputImpl</code> object. The driver will do any necessary
301+ * conversion from Unicode to the database <code>CHAR</code> format.
302+ *
303+ * @param x the value to pass to the database
304+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
305+ * use by a <code>SQLData</code> object attempting to write the attribute
306+ * values of a UDT to the database.
307+ */
308+ public void writeCharacterStream(java.io.Reader x) throws SQLException {
309+ BufferedReader bufReader = new BufferedReader(x);
310+ try {
311+ int i;
312+ while( (i = bufReader.read()) != -1 ) {
313+ char ch = (char)i;
314+ StringBuffer strBuf = new StringBuffer();
315+ strBuf.append(ch);
316+
317+ String str = new String(strBuf);
318+ String strLine = bufReader.readLine();
319+
320+ writeString(str.concat(strLine));
321+ }
322+ } catch(IOException ioe) {
323+
324+ }
325+ }
326+
327+ /**
328+ * Writes a stream of ASCII characters to this
329+ * <code>SQLOutputImpl</code> object. The driver will do any necessary
330+ * conversion from ASCII to the database <code>CHAR</code> format.
331+ *
332+ * @param x the value to pass to the database
333+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
334+ * use by a <code>SQLData</code> object attempting to write the attribute
335+ * values of a UDT to the database.
336+ */
337+ public void writeAsciiStream(java.io.InputStream x) throws SQLException {
338+ BufferedReader bufReader = new BufferedReader(new InputStreamReader(x));
339+ try {
340+ int i;
341+ while( (i=bufReader.read()) != -1 ) {
342+ char ch = (char)i;
343+
344+ StringBuffer strBuf = new StringBuffer();
345+ strBuf.append(ch);
346+
347+ String str = new String(strBuf);
348+ String strLine = bufReader.readLine();
349+
350+ writeString(str.concat(strLine));
351+ }
352+ }catch(IOException ioe) {
353+ throw new SQLException(ioe.getMessage());
354+ }
355+ }
356+
357+ /**
358+ * Writes a stream of uninterpreted bytes to this <code>SQLOutputImpl</code>
359+ * object.
360+ *
361+ * @param x the value to pass to the database
362+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
363+ * use by a <code>SQLData</code> object attempting to write the attribute
364+ * values of a UDT to the database.
365+ */
366+ public void writeBinaryStream(java.io.InputStream x) throws SQLException {
367+ BufferedReader bufReader = new BufferedReader(new InputStreamReader(x));
368+ try {
369+ int i;
370+ while( (i=bufReader.read()) != -1 ) {
371+ char ch = (char)i;
372+
373+ StringBuffer strBuf = new StringBuffer();
374+ strBuf.append(ch);
375+
376+ String str = new String(strBuf);
377+ String strLine = bufReader.readLine();
378+
379+ writeString(str.concat(strLine));
380+ }
381+ } catch(IOException ioe) {
382+ throw new SQLException(ioe.getMessage());
383+ }
384+ }
385+
386+ //================================================================
387+ // Methods for writing items of SQL user-defined types to the stream.
388+ // These methods pass objects to the database as values of SQL
389+ // Structured Types, Distinct Types, Constructed Types, and Locator
390+ // Types. They decompose the Java object(s) and write leaf data
391+ // items using the methods above.
392+ //================================================================
393+
394+ /**
395+ * Writes to the stream the data contained in the given
396+ * <code>SQLData</code> object.
397+ * When the <code>SQLData</code> object is <code>null</code>, this
398+ * method writes an SQL <code>NULL</code> to the stream.
399+ * Otherwise, it calls the <code>SQLData.writeSQL</code>
400+ * method of the given object, which
401+ * writes the object's attributes to the stream.
402+ * <P>
403+ * The implementation of the method <code>SQLData.writeSQ</code>
404+ * calls the appropriate <code>SQLOutputImpl.writeXXX</code> method(s)
405+ * for writing each of the object's attributes in order.
406+ * The attributes must be read from an <code>SQLInput</code>
407+ * input stream and written to an <code>SQLOutputImpl</code>
408+ * output stream in the same order in which they were
409+ * listed in the SQL definition of the user-defined type.
410+ *
411+ * @param x the object representing data of an SQL structured or
412+ * distinct type
413+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
414+ * use by a <code>SQLData</code> object attempting to write the attribute
415+ * values of a UDT to the database.
416+ */
417+ public void writeObject(SQLData x) throws SQLException {
418+
419+ /*
420+ * Except for the types that are passed as objects
421+ * this seems to be the only way for an object to
422+ * get a null value for a field in a structure.
423+ *
424+ * Note: this means that the class defining SQLData
425+ * will need to track if a field is SQL null for itself
426+ */
427+ if (x == null) {
428+ attribs.add(x);
429+ return;
430+ }
431+
432+ /*
433+ * We have to write out a SerialStruct that contains
434+ * the name of this class otherwise we don't know
435+ * what to re-instantiate during readSQL()
436+ */
437+ attribs.add(new SerialStruct((SQLData)x, map));
438+ }
439+
440+ /**
441+ * Writes a <code>Ref</code> object in the Java programming language
442+ * to this <code>SQLOutputImpl</code> object. The driver converts
443+ * it to a serializable <code>SerialRef</code> SQL <code>REF</code> value
444+ * before returning it to the database.
445+ *
446+ * @param x an object representing an SQL <code>REF</code> value
447+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
448+ * use by a <code>SQLData</code> object attempting to write the attribute
449+ * values of a UDT to the database.
450+ */
451+ public void writeRef(Ref x) throws SQLException {
452+ if (x == null) {
453+ attribs.add(x);
454+ return;
455+ }
456+ attribs.add(new SerialRef(x));
457+ }
458+
459+ /**
460+ * Writes a <code>Blob</code> object in the Java programming language
461+ * to this <code>SQLOutputImpl</code> object. The driver converts
462+ * it to a serializable <code>SerialBlob</code> SQL <code>BLOB</code> value
463+ * before returning it to the database.
464+ *
465+ * @param x an object representing an SQL <code>BLOB</code> value
466+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
467+ * use by a <code>SQLData</code> object attempting to write the attribute
468+ * values of a UDT to the database.
469+ */
470+ public void writeBlob(Blob x) throws SQLException {
471+ if (x == null) {
472+ attribs.add(x);
473+ return;
474+ }
475+ attribs.add(new SerialBlob(x));
476+ }
477+
478+ /**
479+ * Writes a <code>Clob</code> object in the Java programming language
480+ * to this <code>SQLOutputImpl</code> object. The driver converts
481+ * it to a serializable <code>SerialClob</code> SQL <code>CLOB</code> value
482+ * before returning it to the database.
483+ *
484+ * @param x an object representing an SQL <code>CLOB</code> value
485+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
486+ * use by a <code>SQLData</code> object attempting to write the attribute
487+ * values of a UDT to the database.
488+ */
489+ public void writeClob(Clob x) throws SQLException {
490+ if (x == null) {
491+ attribs.add(x);
492+ return;
493+ }
494+ attribs.add(new SerialClob(x));
495+ }
496+
497+ /**
498+ * Writes a <code>Struct</code> object in the Java
499+ * programming language to this <code>SQLOutputImpl</code>
500+ * object. The driver converts this value to an SQL structured type
501+ * before returning it to the database.
502+ * <P>
503+ * This method should be used when an SQL structured type has been
504+ * mapped to a <code>Struct</code> object in the Java programming
505+ * language (the standard mapping). The method
506+ * <code>writeObject</code> should be used if an SQL structured type
507+ * has been custom mapped to a class in the Java programming language.
508+ *
509+ * @param x an object representing the attributes of an SQL structured type
510+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
511+ * use by a <code>SQLData</code> object attempting to write the attribute
512+ * values of a UDT to the database.
513+ */
514+ public void writeStruct(Struct x) throws SQLException {
515+ SerialStruct s = new SerialStruct(x,map);;
516+ attribs.add(s);
517+ }
518+
519+ /**
520+ * Writes an <code>Array</code> object in the Java
521+ * programming language to this <code>SQLOutputImpl</code>
522+ * object. The driver converts this value to a serializable
523+ * <code>SerialArray</code> SQL <code>ARRAY</code>
524+ * value before returning it to the database.
525+ *
526+ * @param x an object representing an SQL <code>ARRAY</code> value
527+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
528+ * use by a <code>SQLData</code> object attempting to write the attribute
529+ * values of a UDT to the database.
530+ */
531+ public void writeArray(Array x) throws SQLException {
532+ if (x == null) {
533+ attribs.add(x);
534+ return;
535+ }
536+ attribs.add(new SerialArray(x, map));
537+ }
538+
539+ /**
540+ * Writes an <code>java.sql.Type.DATALINK</code> object in the Java
541+ * programming language to this <code>SQLOutputImpl</code> object. The
542+ * driver converts this value to a serializable <code>SerialDatalink</code>
543+ * SQL <code>DATALINK</code> value before return it to the database.
544+ *
545+ * @param url an object representing a SQL <code>DATALINK</code> value
546+ * @throws SQLException if the <code>SQLOutputImpl</code> object is in
547+ * use by a <code>SQLData</code> object attempting to write the attribute
548+ * values of a UDT to the database.
549+ */
550+ public void writeURL(java.net.URL url) throws SQLException {
551+ if (url == null) {
552+ attribs.add(url);
553+ return;
554+ }
555+ attribs.add(new SerialDatalink(url));
556+
557+ }
558+
559+
560+ /**
561+ * Writes the next attribute to the stream as a <code>String</code>
562+ * in the Java programming language. The driver converts this to a
563+ * SQL <code>NCHAR</code> or
564+ * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
565+ * (depending on the argument's
566+ * size relative to the driver's limits on <code>NVARCHAR</code> values)
567+ * when it sends it to the stream.
568+ *
569+ * @param x the value to pass to the database
570+ * @exception SQLException if a database access error occurs
571+ * @since 1.6
572+ */
573+ public void writeNString(String x) throws SQLException {
574+ throw new UnsupportedOperationException("Operation not supported");
575+ }
576+
577+ /**
578+ * Writes an SQL <code>NCLOB</code> value to the stream.
579+ *
580+ * @param x a <code>NClob</code> object representing data of an SQL
581+ * <code>NCLOB</code> value
582+ *
583+ * @exception SQLException if a database access error occurs
584+ * @since 1.6
585+ */
586+ public void writeNClob(NClob x) throws SQLException {
587+ throw new UnsupportedOperationException("Operation not supported");
588+ }
589+
590+
591+ /**
592+ * Writes an SQL <code>ROWID</code> value to the stream.
593+ *
594+ * @param x a <code>RowId</code> object representing data of an SQL
595+ * <code>ROWID</code> value
596+ *
597+ * @exception SQLException if a database access error occurs
598+ * @since 1.6
599+ */
600+ public void writeRowId(RowId x) throws SQLException {
601+ throw new UnsupportedOperationException("Operation not supported");
602+ }
603+
604+
605+ /**
606+ * Writes an SQL <code>XML</code> value to the stream.
607+ *
608+ * @param x a <code>SQLXML</code> object representing data of an SQL
609+ * <code>XML</code> value
610+ *
611+ * @exception SQLException if a database access error occurs
612+ * @since 1.6
613+ */
614+ public void writeSQLXML(SQLXML x) throws SQLException {
615+ throw new UnsupportedOperationException("Operation not supported");
616+ }
617+
618+}
java/pkg/javax/sql/rowset/serial/SerialArray.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialArray.java+535−0
@@ -0,0 +1,535 @@
1+/*
2+ * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import java.io.*;
30+import java.util.Map;
31+import java.net.URL;
32+
33+
34+/**
35+ * A serialized version of an <code>Array</code>
36+ * object, which is the mapping in the Java programming language of an SQL
37+ * <code>ARRAY</code> value.
38+ * <P>
39+ * The <code>SerialArray</code> class provides a constructor for creating
40+ * a <code>SerialArray</code> instance from an <code>Array</code> object,
41+ * methods for getting the base type and the SQL name for the base type, and
42+ * methods for copying all or part of a <code>SerialArray</code> object.
43+ * <P>
44+ * Note: In order for this class to function correctly, a connection to the
45+ * data source
46+ * must be available in order for the SQL <code>Array</code> object to be
47+ * materialized (have all of its elements brought to the client server)
48+ * if necessary. At this time, logical pointers to the data in the data source,
49+ * such as locators, are not currently supported.
50+ */
51+public class SerialArray implements Array, Serializable, Cloneable {
52+
53+ /**
54+ * A serialized array in which each element is an <code>Object</code>
55+ * in the Java programming language that represents an element
56+ * in the SQL <code>ARRAY</code> value.
57+ * @serial
58+ */
59+ private Object[] elements;
60+
61+ /**
62+ * The SQL type of the elements in this <code>SerialArray</code> object. The
63+ * type is expressed as one of the constants from the class
64+ * <code>java.sql.Types</code>.
65+ * @serial
66+ */
67+ private int baseType;
68+
69+ /**
70+ * The type name used by the DBMS for the elements in the SQL <code>ARRAY</code>
71+ * value that this <code>SerialArray</code> object represents.
72+ * @serial
73+ */
74+ private String baseTypeName;
75+
76+ /**
77+ * The number of elements in this <code>SerialArray</code> object, which
78+ * is also the number of elements in the SQL <code>ARRAY</code> value
79+ * that this <code>SerialArray</code> object represents.
80+ * @serial
81+ */
82+ private int len;
83+
84+ /**
85+ * Constructs a new <code>SerialArray</code> object from the given
86+ * <code>Array</code> object, using the given type map for the custom
87+ * mapping of each element when the elements are SQL UDTs.
88+ * <P>
89+ * This method does custom mapping if the array elements are a UDT
90+ * and the given type map has an entry for that UDT.
91+ * Custom mapping is recursive,
92+ * meaning that if, for instance, an element of an SQL structured type
93+ * is an SQL structured type that itself has an element that is an SQL
94+ * structured type, each structured type that has a custom mapping will be
95+ * mapped according to the given type map.
96+ * <P>
97+ * The new <code>SerialArray</code>
98+ * object contains the same elements as the <code>Array</code> object
99+ * from which it is built, except when the base type is the SQL type
100+ * <code>STRUCT</code>, <code>ARRAY</code>, <code>BLOB</code>,
101+ * <code>CLOB</code>, <code>DATALINK</code> or <code>JAVA_OBJECT</code>.
102+ * In this case, each element in the new
103+ * <code>SerialArray</code> object is the appropriate serialized form,
104+ * that is, a <code>SerialStruct</code>, <code>SerialArray</code>,
105+ * <code>SerialBlob</code>, <code>SerialClob</code>,
106+ * <code>SerialDatalink</code>, or <code>SerialJavaObject</code> object.
107+ * <P>
108+ * Note: (1) The <code>Array</code> object from which a <code>SerialArray</code>
109+ * object is created must have materialized the SQL <code>ARRAY</code> value's
110+ * data on the client before it is passed to the constructor. Otherwise,
111+ * the new <code>SerialArray</code> object will contain no data.
112+ * <p>
113+ * Note: (2) If the <code>Array</code> contains <code>java.sql.Types.JAVA_OBJECT</code>
114+ * types, the <code>SerialJavaObject</code> constructor is called where checks
115+ * are made to ensure this object is serializable.
116+ * <p>
117+ * Note: (3) The <code>Array</code> object supplied to this constructor cannot
118+ * return <code>null</code> for any <code>Array.getArray()</code> methods.
119+ * <code>SerialArray</code> cannot serialize null array values.
120+ *
121+ *
122+ * @param array the <code>Array</code> object to be serialized
123+ * @param map a <code>java.util.Map</code> object in which
124+ * each entry consists of 1) a <code>String</code> object
125+ * giving the fully qualified name of a UDT (an SQL structured type or
126+ * distinct type) and 2) the
127+ * <code>Class</code> object for the <code>SQLData</code> implementation
128+ * that defines how the UDT is to be mapped. The <i>map</i>
129+ * parameter does not have any effect for <code>Blob</code>,
130+ * <code>Clob</code>, <code>DATALINK</code>, or
131+ * <code>JAVA_OBJECT</code> types.
132+ * @throws SerialException if an error occurs serializing the
133+ * <code>Array</code> object
134+ * @throws SQLException if a database access error occurs or if the
135+ * <i>array</i> or the <i>map</i> values are <code>null</code>
136+ */
137+ public SerialArray(Array array, Map<String,Class<?>> map)
138+ throws SerialException, SQLException
139+ {
140+
141+ if ((array == null) || (map == null)) {
142+ throw new SQLException("Cannot instantiate a SerialArray " +
143+ "object with null parameters");
144+ }
145+
146+ if ((elements = (Object[])array.getArray()) == null) {
147+ throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
148+ "return null value which cannot be serialized");
149+ }
150+
151+ elements = (Object[])array.getArray(map);
152+ baseType = array.getBaseType();
153+ baseTypeName = array.getBaseTypeName();
154+ len = elements.length;
155+
156+ switch (baseType) {
157+ case java.sql.Types.STRUCT:
158+ for (int i = 0; i < len; i++) {
159+ elements[i] = new SerialStruct((Struct)elements[i], map);
160+ }
161+ break;
162+
163+ case java.sql.Types.ARRAY:
164+ for (int i = 0; i < len; i++) {
165+ elements[i] = new SerialArray((Array)elements[i], map);
166+ }
167+ break;
168+
169+ case java.sql.Types.BLOB:
170+ for (int i = 0; i < len; i++) {
171+ elements[i] = new SerialBlob((Blob)elements[i]);
172+ }
173+ break;
174+
175+ case java.sql.Types.CLOB:
176+ for (int i = 0; i < len; i++) {
177+ elements[i] = new SerialClob((Clob)elements[i]);
178+ }
179+ break;
180+
181+ case java.sql.Types.DATALINK:
182+ for (int i = 0; i < len; i++) {
183+ elements[i] = new SerialDatalink((URL)elements[i]);
184+ }
185+ break;
186+
187+ case java.sql.Types.JAVA_OBJECT:
188+ for (int i = 0; i < len; i++) {
189+ elements[i] = new SerialJavaObject((Object)elements[i]);
190+ }
191+ default:
192+ ;
193+ }
194+ }
195+
196+ /**
197+ * This method frees the <code>Array</code> object and releases the resources that
198+ * it holds. The object is invalid once the <code>free</code>
199+ * method is called.
200+ *<p>
201+ * After <code>free</code> has been called, any attempt to invoke a
202+ * method other than <code>free</code> will result in a <code>SQLException</code>
203+ * being thrown. If <code>free</code> is called multiple times, the subsequent
204+ * calls to <code>free</code> are treated as a no-op.
205+ *<p>
206+ *
207+ * @throws SQLException if an error occurs releasing
208+ * the Array's resources
209+ * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
210+ * this method
211+ * @since 1.6
212+ */
213+ public void free() throws SQLException {
214+ throw new SQLFeatureNotSupportedException("Feature not supported");
215+ }
216+
217+ /**
218+ * Constructs a new <code>SerialArray</code> object from the given
219+ * <code>Array</code> object.
220+ * <P>
221+ * This constructor does not do custom mapping. If the base type of the array
222+ * is an SQL structured type and custom mapping is desired, the constructor
223+ * <code>SerialArray(Array array, Map map)</code> should be used.
224+ * <P>
225+ * The new <code>SerialArray</code>
226+ * object contains the same elements as the <code>Array</code> object
227+ * from which it is built, except when the base type is the SQL type
228+ * <code>BLOB</code>,
229+ * <code>CLOB</code>, <code>DATALINK</code> or <code>JAVA_OBJECT</code>.
230+ * In this case, each element in the new
231+ * <code>SerialArray</code> object is the appropriate serialized form,
232+ * that is, a <code>SerialBlob</code>, <code>SerialClob</code>,
233+ * <code>SerialDatalink</code>, or <code>SerialJavaObject</code> object.
234+ * <P>
235+ * Note: (1) The <code>Array</code> object from which a <code>SerialArray</code>
236+ * object is created must have materialized the SQL <code>ARRAY</code> value's
237+ * data on the client before it is passed to the constructor. Otherwise,
238+ * the new <code>SerialArray</code> object will contain no data.
239+ * <p>
240+ * Note: (2) The <code>Array</code> object supplied to this constructor cannot
241+ * return <code>null</code> for any <code>Array.getArray()</code> methods.
242+ * <code>SerialArray</code> cannot serialize <code>null</code> array values.
243+ *
244+ * @param array the <code>Array</code> object to be serialized
245+ * @throws SerialException if an error occurs serializing the
246+ * <code>Array</code> object
247+ * @throws SQLException if a database access error occurs or the
248+ * <i>array</i> parameter is <code>null</code>.
249+ */
250+ public SerialArray(Array array) throws SerialException, SQLException {
251+ if (array == null) {
252+ throw new SQLException("Cannot instantiate a SerialArray " +
253+ "object with a null Array object");
254+ }
255+
256+ if ((elements = (Object[])array.getArray()) == null) {
257+ throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
258+ "return null value which cannot be serialized");
259+ }
260+
261+ //elements = (Object[])array.getArray();
262+ baseType = array.getBaseType();
263+ baseTypeName = array.getBaseTypeName();
264+ len = elements.length;
265+
266+ switch (baseType) {
267+
268+ case java.sql.Types.BLOB:
269+ for (int i = 0; i < len; i++) {
270+ elements[i] = new SerialBlob((Blob)elements[i]);
271+ }
272+ break;
273+
274+ case java.sql.Types.CLOB:
275+ for (int i = 0; i < len; i++) {
276+ elements[i] = new SerialClob((Clob)elements[i]);
277+ }
278+ break;
279+
280+ case java.sql.Types.DATALINK:
281+ for (int i = 0; i < len; i++) {
282+ elements[i] = new SerialDatalink((URL)elements[i]);
283+ }
284+ break;
285+
286+ case java.sql.Types.JAVA_OBJECT:
287+ for (int i = 0; i < len; i++) {
288+ elements[i] = new SerialJavaObject((Object)elements[i]);
289+ }
290+
291+ default:
292+ ;
293+ }
294+
295+
296+ }
297+
298+ /**
299+ * Returns a new array that is a copy of this <code>SerialArray</code>
300+ * object.
301+ *
302+ * @return a copy of this <code>SerialArray</code> object as an
303+ * <code>Object</code> in the Java programming language
304+ * @throws SerialException if an error occurs retrieving a copy of
305+ * this <code>SerialArray</code> object
306+ */
307+ public Object getArray() throws SerialException {
308+ Object dst = new Object[len];
309+ System.arraycopy((Object)elements, 0, dst, 0, len);
310+ return dst;
311+ }
312+
313+ //[if an error occurstype map used??]
314+ /**
315+ * Returns a new array that is a copy of this <code>SerialArray</code>
316+ * object, using the given type map for the custom
317+ * mapping of each element when the elements are SQL UDTs.
318+ * <P>
319+ * This method does custom mapping if the array elements are a UDT
320+ * and the given type map has an entry for that UDT.
321+ * Custom mapping is recursive,
322+ * meaning that if, for instance, an element of an SQL structured type
323+ * is an SQL structured type that itself has an element that is an SQL
324+ * structured type, each structured type that has a custom mapping will be
325+ * mapped according to the given type map.
326+ *
327+ * @param map a <code>java.util.Map</code> object in which
328+ * each entry consists of 1) a <code>String</code> object
329+ * giving the fully qualified name of a UDT and 2) the
330+ * <code>Class</code> object for the <code>SQLData</code> implementation
331+ * that defines how the UDT is to be mapped
332+ * @return a copy of this <code>SerialArray</code> object as an
333+ * <code>Object</code> in the Java programming language
334+ * @throws SerialException if an error occurs
335+ */
336+ public Object getArray(Map<String, Class<?>> map) throws SerialException {
337+ Object dst[] = new Object[len];
338+ System.arraycopy((Object)elements, 0, dst, 0, len);
339+ return dst;
340+ }
341+
342+ /**
343+ * Returns a new array that is a copy of a slice
344+ * of this <code>SerialArray</code> object, starting with the
345+ * element at the given index and containing the given number
346+ * of consecutive elements.
347+ *
348+ * @param index the index into this <code>SerialArray</code> object
349+ * of the first element to be copied;
350+ * the index of the first element is <code>0</code>
351+ * @param count the number of consecutive elements to be copied, starting
352+ * at the given index
353+ * @return a copy of the designated elements in this <code>SerialArray</code>
354+ * object as an <code>Object</code> in the Java programming language
355+ * @throws SerialException if an error occurs
356+ */
357+ public Object getArray(long index, int count) throws SerialException {
358+ Object dst = new Object[count];
359+ System.arraycopy((Object)elements, (int)index, dst, 0, count);
360+ return dst;
361+ }
362+
363+ /**
364+ * Returns a new array that is a copy of a slice
365+ * of this <code>SerialArray</code> object, starting with the
366+ * element at the given index and containing the given number
367+ * of consecutive elements.
368+ * <P>
369+ * This method does custom mapping if the array elements are a UDT
370+ * and the given type map has an entry for that UDT.
371+ * Custom mapping is recursive,
372+ * meaning that if, for instance, an element of an SQL structured type
373+ * is an SQL structured type that itself has an element that is an SQL
374+ * structured type, each structured type that has a custom mapping will be
375+ * mapped according to the given type map.
376+ *
377+ * @param index the index into this <code>SerialArray</code> object
378+ * of the first element to be copied; the index of the
379+ * first element in the array is <code>0</code>
380+ * @param count the number of consecutive elements to be copied, starting
381+ * at the given index
382+ * @param map a <code>java.util.Map</code> object in which
383+ * each entry consists of 1) a <code>String</code> object
384+ * giving the fully qualified name of a UDT and 2) the
385+ * <code>Class</code> object for the <code>SQLData</code> implementation
386+ * that defines how the UDT is to be mapped
387+ * @return a copy of the designated elements in this <code>SerialArray</code>
388+ * object as an <code>Object</code> in the Java programming language
389+ * @throws SerialException if an error occurs
390+ */
391+ public Object getArray(long index, int count, Map<String,Class<?>> map)
392+ throws SerialException
393+ {
394+ Object dst = new Object[count];
395+ System.arraycopy((Object)elements, (int)index, dst, 0, count);
396+ return dst;
397+ }
398+
399+ /**
400+ * Retrieves the SQL type of the elements in this <code>SerialArray</code>
401+ * object. The <code>int</code> returned is one of the constants in the class
402+ * <code>java.sql.Types</code>.
403+ *
404+ * @return one of the constants in <code>java.sql.Types</code>, indicating
405+ * the SQL type of the elements in this <code>SerialArray</code> object
406+ * @throws SerialException if an error occurs
407+ */
408+ public int getBaseType() throws SerialException {
409+ return baseType;
410+ }
411+
412+ /**
413+ * Retrieves the DBMS-specific type name for the elements in this
414+ * <code>SerialArray</code> object.
415+ *
416+ * @return the SQL type name used by the DBMS for the base type of this
417+ * <code>SerialArray</code> object
418+ * @throws SerialException if an error occurs
419+ */
420+ public String getBaseTypeName() throws SerialException {
421+ return baseTypeName;
422+ }
423+
424+ /**
425+ * Retrieves a <code>ResultSet</code> object holding the elements of
426+ * the subarray that starts at
427+ * index <i>index</i> and contains up to <i>count</i> successive elements.
428+ * This method uses the connection's type map to map the elements of
429+ * the array if the map contains
430+ * an entry for the base type. Otherwise, the standard mapping is used.
431+ *
432+ * @param index the index into this <code>SerialArray</code> object
433+ * of the first element to be copied; the index of the
434+ * first element in the array is <code>0</code>
435+ * @param count the number of consecutive elements to be copied, starting
436+ * at the given index
437+ * @return a <code>ResultSet</code> object containing the designated
438+ * elements in this <code>SerialArray</code> object, with a
439+ * separate row for each element
440+ * @throws SerialException, which in turn throws an
441+ * <code>UnsupportedOperationException</code>, if this method is called
442+ */
443+ public ResultSet getResultSet(long index, int count) throws SerialException {
444+ throw new UnsupportedOperationException();
445+ }
446+
447+ /**
448+ *
449+ * Retrieves a <code>ResultSet</code> object that contains all of
450+ * the elements of the SQL <code>ARRAY</code>
451+ * value represented by this <code>SerialArray</code> object. This method uses
452+ * the specified map for type map customizations unless the base type of the
453+ * array does not match a user-defined type (UDT) in <i>map</i>, in
454+ * which case it uses the
455+ * standard mapping. This version of the method <code>getResultSet</code>
456+ * uses either the given type map or the standard mapping; it never uses the
457+ * type map associated with the connection.
458+ *
459+ * @param map a <code>java.util.Map</code> object in which
460+ * each entry consists of 1) a <code>String</code> object
461+ * giving the fully qualified name of a UDT and 2) the
462+ * <code>Class</code> object for the <code>SQLData</code> implementation
463+ * that defines how the UDT is to be mapped
464+ * @return a <code>ResultSet</code> object containing all of the
465+ * elements in this <code>SerialArray</code> object, with a
466+ * separate row for each element
467+ * @throws SerialException, which in turn throws an
468+ * <code>UnsupportedOperationException</code>, if this method is called
469+ */
470+ public ResultSet getResultSet(Map<String, Class<?>> map)
471+ throws SerialException
472+ {
473+ throw new UnsupportedOperationException();
474+ }
475+
476+ /**
477+ * Retrieves a <code>ResultSet</code> object that contains all of
478+ * the elements in the <code>ARRAY</code> value that this
479+ * <code>SerialArray</code> object represents.
480+ * If appropriate, the elements of the array are mapped using the connection's
481+ * type map; otherwise, the standard mapping is used.
482+ *
483+ * @return a <code>ResultSet</code> object containing all of the
484+ * elements in this <code>SerialArray</code> object, with a
485+ * separate row for each element
486+ * @throws SerialException if called, which in turn throws an
487+ * <code>UnsupportedOperationException</code>, if this method is called
488+ */
489+ public ResultSet getResultSet() throws SerialException {
490+ throw new UnsupportedOperationException();
491+ }
492+
493+
494+ /**
495+ * Retrieves a result set holding the elements of the subarray that starts at
496+ * Retrieves a <code>ResultSet</code> object that contains a subarray of the
497+ * elements in this <code>SerialArray</code> object, starting at
498+ * index <i>index</i> and containing up to <i>count</i> successive
499+ * elements. This method uses
500+ * the specified map for type map customizations unless the base type of the
501+ * array does not match a user-defined type (UDT) in <i>map</i>, in
502+ * which case it uses the
503+ * standard mapping. This version of the method <code>getResultSet</code> uses
504+ * either the given type map or the standard mapping; it never uses the type
505+ * map associated with the connection.
506+ *
507+ * @param index the index into this <code>SerialArray</code> object
508+ * of the first element to be copied; the index of the
509+ * first element in the array is <code>0</code>
510+ * @param count the number of consecutive elements to be copied, starting
511+ * at the given index
512+ * @param map a <code>java.util.Map</code> object in which
513+ * each entry consists of 1) a <code>String</code> object
514+ * giving the fully qualified name of a UDT and 2) the
515+ * <code>Class</code> object for the <code>SQLData</code> implementation
516+ * that defines how the UDT is to be mapped
517+ * @return a <code>ResultSet</code> object containing the designated
518+ * elements in this <code>SerialArray</code> object, with a
519+ * separate row for each element
520+ * @throws SerialException if called, which in turn throws an
521+ * <code>UnsupportedOperationException</code>
522+ */
523+ public ResultSet getResultSet(long index, int count,
524+ Map<String,Class<?>> map)
525+ throws SerialException
526+ {
527+ throw new UnsupportedOperationException();
528+ }
529+
530+ /**
531+ * The identifier that assists in the serialization of this <code>SerialArray</code>
532+ * object.
533+ */
534+ static final long serialVersionUID = -8466174297270688520L;
535+}
java/pkg/javax/sql/rowset/serial/SerialBlob.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialBlob.java+457−0
@@ -0,0 +1,457 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import java.io.*;
30+import java.lang.reflect.*;
31+
32+
33+/**
34+ * A serialized mapping in the Java programming language of an SQL
35+ * <code>BLOB</code> value.
36+ * <P>
37+ * The <code>SerialBlob</code> class provides a constructor for creating
38+ * an instance from a <code>Blob</code> object. Note that the
39+ * <code>Blob</code>
40+ * object should have brought the SQL <code>BLOB</code> value's data over
41+ * to the client before a <code>SerialBlob</code> object
42+ * is constructed from it. The data of an SQL <code>BLOB</code> value can
43+ * be materialized on the client as an array of bytes (using the method
44+ * <code>Blob.getBytes</code>) or as a stream of uninterpreted bytes
45+ * (using the method <code>Blob.getBinaryStream</code>).
46+ * <P>
47+ * <code>SerialBlob</code> methods make it possible to make a copy of a
48+ * <code>SerialBlob</code> object as an array of bytes or as a stream.
49+ * They also make it possible to locate a given pattern of bytes or a
50+ * <code>Blob</code> object within a <code>SerialBlob</code> object
51+ * and to update or truncate a <code>Blob</code> object.
52+ *
53+ * @author Jonathan Bruce
54+ */
55+public class SerialBlob implements Blob, Serializable, Cloneable {
56+
57+ /**
58+ * A serialized array of uninterpreted bytes representing the
59+ * value of this <code>SerialBlob</code> object.
60+ * @serial
61+ */
62+ private byte buf[];
63+
64+ /**
65+ * The internal representation of the <code>Blob</code> object on which this
66+ * <code>SerialBlob</code> object is based.
67+ */
68+ private Blob blob;
69+
70+ /**
71+ * The number of bytes in this <code>SerialBlob</code> object's
72+ * array of bytes.
73+ * @serial
74+ */
75+ private long len;
76+
77+ /**
78+ * The orginal number of bytes in this <code>SerialBlob</code> object's
79+ * array of bytes when it was first established.
80+ * @serial
81+ */
82+ private long origLen;
83+
84+ /**
85+ * Constructs a <code>SerialBlob</code> object that is a serialized version of
86+ * the given <code>byte</code> array.
87+ * <p>
88+ * The new <code>SerialBlob</code> object is initialized with the data from the
89+ * <code>byte</code> array, thus allowing disconnected <code>RowSet</code>
90+ * objects to establish serialized <code>Blob</code> objects without
91+ * touching the data source.
92+ *
93+ * @param b the <code>byte</code> array containing the data for the
94+ * <code>Blob</code> object to be serialized
95+ * @throws SerialException if an error occurs during serialization
96+ * @throws SQLException if a SQL errors occurs
97+ */
98+ public SerialBlob(byte[] b) throws SerialException, SQLException {
99+
100+ len = b.length;
101+ buf = new byte[(int)len];
102+ for(int i = 0; i < len; i++) {
103+ buf[i] = b[i];
104+ }
105+ origLen = len;
106+ }
107+
108+
109+ /**
110+ * Constructs a <code>SerialBlob</code> object that is a serialized
111+ * version of the given <code>Blob</code> object.
112+ * <P>
113+ * The new <code>SerialBlob</code> object is initialized with the
114+ * data from the <code>Blob</code> object; therefore, the
115+ * <code>Blob</code> object should have previously brought the
116+ * SQL <code>BLOB</code> value's data over to the client from
117+ * the database. Otherwise, the new <code>SerialBlob</code> object
118+ * will contain no data.
119+ *
120+ * @param blob the <code>Blob</code> object from which this
121+ * <code>SerialBlob</code> object is to be constructed;
122+ * cannot be null.
123+ * @throws SerialException if an error occurs during serialization
124+ * @throws SQLException if the <code>Blob</code> passed to this
125+ * to this constructor is a <code>null</code>.
126+ * @see java.sql.Blob
127+ */
128+ public SerialBlob (Blob blob) throws SerialException, SQLException {
129+
130+ if (blob == null) {
131+ throw new SQLException("Cannot instantiate a SerialBlob " +
132+ "object with a null Blob object");
133+ }
134+
135+ len = blob.length();
136+ buf = blob.getBytes(1, (int)len );
137+ this.blob = blob;
138+
139+ //if ( len < 10240000)
140+ // len = 10240000;
141+ origLen = len;
142+ }
143+
144+ /**
145+ * Copies the specified number of bytes, starting at the given
146+ * position, from this <code>SerialBlob</code> object to
147+ * another array of bytes.
148+ * <P>
149+ * Note that if the given number of bytes to be copied is larger than
150+ * the length of this <code>SerialBlob</code> object's array of
151+ * bytes, the given number will be shortened to the array's length.
152+ *
153+ * @param pos the ordinal position of the first byte in this
154+ * <code>SerialBlob</code> object to be copied;
155+ * numbering starts at <code>1</code>; must not be less
156+ * than <code>1</code> and must be less than or equal
157+ * to the length of this <code>SerialBlob</code> object
158+ * @param length the number of bytes to be copied
159+ * @return an array of bytes that is a copy of a region of this
160+ * <code>SerialBlob</code> object, starting at the given
161+ * position and containing the given number of consecutive bytes
162+ * @throws SerialException if the given starting position is out of bounds
163+ */
164+ public byte[] getBytes(long pos, int length) throws SerialException {
165+ if (length > len) {
166+ length = (int)len;
167+ }
168+
169+ if (pos < 1 || len - pos < 0 ) {
170+ throw new SerialException("Invalid arguments: position cannot be "
171+ + "less than 1 or greater than the length of the SerialBlob");
172+ }
173+
174+ pos--; // correct pos to array index
175+
176+ byte[] b = new byte[length];
177+
178+ for (int i = 0; i < length; i++) {
179+ b[i] = this.buf[(int)pos];
180+ pos++;
181+ }
182+ return b;
183+ }
184+
185+ /**
186+ * Retrieves the number of bytes in this <code>SerialBlob</code>
187+ * object's array of bytes.
188+ *
189+ * @return a <code>long</code> indicating the length in bytes of this
190+ * <code>SerialBlob</code> object's array of bytes
191+ * @throws SerialException if an error occurs
192+ */
193+ public long length() throws SerialException {
194+ return len;
195+ }
196+
197+ /**
198+ * Returns this <code>SerialBlob</code> object as an input stream.
199+ * Unlike the related method, <code>setBinaryStream</code>,
200+ * a stream is produced regardless of whether the <code>SerialBlob</code>
201+ * was created with a <code>Blob</code> object or a <code>byte</code> array.
202+ *
203+ * @return a <code>java.io.InputStream</code> object that contains
204+ * this <code>SerialBlob</code> object's array of bytes
205+ * @throws SerialException if an error occurs
206+ * @see #setBinaryStream
207+ */
208+ public java.io.InputStream getBinaryStream() throws SerialException {
209+ InputStream stream = new ByteArrayInputStream(buf);
210+ return (java.io.InputStream)stream;
211+ }
212+
213+ /**
214+ * Returns the position in this <code>SerialBlob</code> object where
215+ * the given pattern of bytes begins, starting the search at the
216+ * specified position.
217+ *
218+ * @param pattern the pattern of bytes for which to search
219+ * @param start the position of the byte in this
220+ * <code>SerialBlob</code> object from which to begin
221+ * the search; the first position is <code>1</code>;
222+ * must not be less than <code>1</code> nor greater than
223+ * the length of this <code>SerialBlob</code> object
224+ * @return the position in this <code>SerialBlob</code> object
225+ * where the given pattern begins, starting at the specified
226+ * position; <code>-1</code> if the pattern is not found
227+ * or the given starting position is out of bounds; position
228+ * numbering for the return value starts at <code>1</code>
229+ * @throws SerialException if an error occurs when serializing the blob
230+ * @throws SQLException if there is an error accessing the <code>BLOB</code>
231+ * value from the database
232+ */
233+ public long position(byte[] pattern, long start)
234+ throws SerialException, SQLException {
235+ if (start < 1 || start > len) {
236+ return -1;
237+ }
238+
239+ int pos = (int)start-1; // internally Blobs are stored as arrays.
240+ int i = 0;
241+ long patlen = pattern.length;
242+
243+ while (pos < len) {
244+ if (pattern[i] == buf[pos]) {
245+ if (i + 1 == patlen) {
246+ return (pos + 1) - (patlen - 1);
247+ }
248+ i++; pos++; // increment pos, and i
249+ } else if (pattern[i] != buf[pos]) {
250+ pos++; // increment pos only
251+ }
252+ }
253+ return -1; // not found
254+ }
255+
256+ /**
257+ * Returns the position in this <code>SerialBlob</code> object where
258+ * the given <code>Blob</code> object begins, starting the search at the
259+ * specified position.
260+ *
261+ * @param pattern the <code>Blob</code> object for which to search;
262+ * @param start the position of the byte in this
263+ * <code>SerialBlob</code> object from which to begin
264+ * the search; the first position is <code>1</code>;
265+ * must not be less than <code>1</code> nor greater than
266+ * the length of this <code>SerialBlob</code> object
267+ * @return the position in this <code>SerialBlob</code> object
268+ * where the given <code>Blob</code> object begins, starting
269+ * at the specified position; <code>-1</code> if the pattern is
270+ * not found or the given starting position is out of bounds;
271+ * position numbering for the return value starts at <code>1</code>
272+ * @throws SerialException if an error occurs when serializing the blob
273+ * @throws SQLException if there is an error accessing the <code>BLOB</code>
274+ * value from the database
275+ */
276+ public long position(Blob pattern, long start)
277+ throws SerialException, SQLException {
278+ return position(pattern.getBytes(1, (int)(pattern.length())), start);
279+ }
280+
281+ /**
282+ * Writes the given array of bytes to the <code>BLOB</code> value that
283+ * this <code>Blob</code> object represents, starting at position
284+ * <code>pos</code>, and returns the number of bytes written.
285+ *
286+ * @param pos the position in the SQL <code>BLOB</code> value at which
287+ * to start writing. The first position is <code>1</code>;
288+ * must not be less than <code>1</code> nor greater than
289+ * the length of this <code>SerialBlob</code> object.
290+ * @param bytes the array of bytes to be written to the <code>BLOB</code>
291+ * value that this <code>Blob</code> object represents
292+ * @return the number of bytes written
293+ * @throws SerialException if there is an error accessing the
294+ * <code>BLOB</code> value; or if an invalid position is set; if an
295+ * invalid offset value is set
296+ * @throws SQLException if there is an error accessing the <code>BLOB</code>
297+ * value from the database
298+ * @see #getBytes
299+ */
300+ public int setBytes(long pos, byte[] bytes)
301+ throws SerialException, SQLException {
302+ return (setBytes(pos, bytes, 0, bytes.length));
303+ }
304+
305+ /**
306+ * Writes all or part of the given <code>byte</code> array to the
307+ * <code>BLOB</code> value that this <code>Blob</code> object represents
308+ * and returns the number of bytes written.
309+ * Writing starts at position <code>pos</code> in the <code>BLOB</code>
310+ * value; <i>len</i> bytes from the given byte array are written.
311+ *
312+ * @param pos the position in the <code>BLOB</code> object at which
313+ * to start writing. The first position is <code>1</code>;
314+ * must not be less than <code>1</code> nor greater than
315+ * the length of this <code>SerialBlob</code> object.
316+ * @param bytes the array of bytes to be written to the <code>BLOB</code>
317+ * value
318+ * @param offset the offset in the <code>byte</code> array at which
319+ * to start reading the bytes. The first offset position is
320+ * <code>0</code>; must not be less than <code>0</code> nor greater
321+ * than the length of the <code>byte</code> array
322+ * @param length the number of bytes to be written to the
323+ * <code>BLOB</code> value from the array of bytes <i>bytes</i>.
324+ *
325+ * @return the number of bytes written
326+ * @throws SerialException if there is an error accessing the
327+ * <code>BLOB</code> value; if an invalid position is set; if an
328+ * invalid offset value is set; if number of bytes to be written
329+ * is greater than the <code>SerialBlob</code> length; or the combined
330+ * values of the length and offset is greater than the Blob buffer
331+ * @throws SQLException if there is an error accessing the <code>BLOB</code>
332+ * value from the database.
333+ * @see #getBytes
334+ */
335+ public int setBytes(long pos, byte[] bytes, int offset, int length)
336+ throws SerialException, SQLException {
337+
338+ if (offset < 0 || offset > bytes.length) {
339+ throw new SerialException("Invalid offset in byte array set");
340+ }
341+
342+ if (pos < 1 || pos > this.length()) {
343+ throw new SerialException("Invalid position in BLOB object set");
344+ }
345+
346+ if ((long)(length) > origLen) {
347+ throw new SerialException("Buffer is not sufficient to hold the value");
348+ }
349+
350+ if ((length + offset) > bytes.length) {
351+ throw new SerialException("Invalid OffSet. Cannot have combined offset " +
352+ "and length that is greater that the Blob buffer");
353+ }
354+
355+ int i = 0;
356+ pos--; // correct to array indexing
357+ while ( i < length || (offset + i +1) < (bytes.length-offset) ) {
358+ this.buf[(int)pos + i] = bytes[offset + i ];
359+ i++;
360+ }
361+ return i;
362+ }
363+
364+ /**
365+ * Retrieves a stream that can be used to write to the <code>BLOB</code>
366+ * value that this <code>Blob</code> object represents. The stream begins
367+ * at position <code>pos</code>. This method forwards the
368+ * <code>setBinaryStream()</code> call to the underlying <code>Blob</code> in
369+ * the event that this <code>SerialBlob</code> object is instantiated with a
370+ * <code>Blob</code>. If this <code>SerialBlob</code> is instantiated with
371+ * a <code>byte</code> array, a <code>SerialException</code> is thrown.
372+ *
373+ * @param pos the position in the <code>BLOB</code> value at which
374+ * to start writing
375+ * @return a <code>java.io.OutputStream</code> object to which data can
376+ * be written
377+ * @throws SQLException if there is an error accessing the
378+ * <code>BLOB</code> value
379+ * @throws SerialException if the SerialBlob in not instantiated with a
380+ * <code>Blob</code> object that supports <code>setBinaryStream()</code>
381+ * @see #getBinaryStream
382+ */
383+ public java.io.OutputStream setBinaryStream(long pos)
384+ throws SerialException, SQLException {
385+ if (this.blob.setBinaryStream(pos) != null) {
386+ return this.blob.setBinaryStream(pos);
387+ } else {
388+ throw new SerialException("Unsupported operation. SerialBlob cannot " +
389+ "return a writable binary stream, unless instantiated with a Blob object " +
390+ "that provides a setBinaryStream() implementation");
391+ }
392+ }
393+
394+ /**
395+ * Truncates the <code>BLOB</code> value that this <code>Blob</code>
396+ * object represents to be <code>len</code> bytes in length.
397+ *
398+ * @param length the length, in bytes, to which the <code>BLOB</code>
399+ * value that this <code>Blob</code> object represents should be
400+ * truncated
401+ * @throws SerialException if there is an error accessing the Blob value;
402+ * or the length to truncate is greater that the SerialBlob length
403+ */
404+ public void truncate(long length) throws SerialException {
405+
406+ if (length > len) {
407+ throw new SerialException
408+ ("Length more than what can be truncated");
409+ } else if((int)length == 0) {
410+ buf = new byte[0];
411+ len = length;
412+ } else {
413+ len = length;
414+ buf = this.getBytes(1, (int)len);
415+ }
416+ }
417+
418+
419+ /**
420+ * Returns an <code>InputStream</code> object that contains a partial <code>Blob</code> value,
421+ * starting with the byte specified by pos, which is length bytes in length.
422+ *
423+ * @param pos the offset to the first byte of the partial value to be retrieved.
424+ * The first byte in the <code>Blob</code> is at position 1
425+ * @param length the length in bytes of the partial value to be retrieved
426+ * @return <code>InputStream</code> through which the partial <code>Blob</code> value can be read.
427+ * @throws SQLException if pos is less than 1 or if pos is greater than the number of bytes
428+ * in the <code>Blob</code> or if pos + length is greater than the number of bytes
429+ * in the <code>Blob</code>
430+ *
431+ * @since 1.6
432+ */
433+ public InputStream getBinaryStream(long pos,long length) throws SQLException {
434+ throw new java.lang.UnsupportedOperationException("Not supported");
435+ }
436+
437+
438+ /**
439+ * This method frees the <code>Blob</code> object and releases the resources that it holds.
440+ * <code>Blob</code> object. The object is invalid once the <code>free</code>
441+ * method is called. If <code>free</code> is called multiple times, the subsequent
442+ * calls to <code>free</code> are treated as a no-op.
443+ *
444+ * @throws SQLException if an error occurs releasing
445+ * the Blob's resources
446+ * @since 1.6
447+ */
448+ public void free() throws SQLException {
449+ throw new java.lang.UnsupportedOperationException("Not supported");
450+ }
451+ /**
452+ * The identifier that assists in the serialization of this <code>SerialBlob</code>
453+ * object.
454+ */
455+
456+ static final long serialVersionUID = -8144641928112860441L;
457+}
java/pkg/javax/sql/rowset/serial/SerialClob.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialClob.java+522−0
@@ -0,0 +1,522 @@
1+/*
2+ * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import java.io.*;
30+
31+/**
32+ * A serialized mapping in the Java programming language of an SQL
33+ * <code>CLOB</code> value.
34+ * <P>
35+ * The <code>SerialClob</code> class provides a constructor for creating
36+ * an instance from a <code>Clob</code> object. Note that the <code>Clob</code>
37+ * object should have brought the SQL <code>CLOB</code> value's data over
38+ * to the client before a <code>SerialClob</code> object
39+ * is constructed from it. The data of an SQL <code>CLOB</code> value can
40+ * be materialized on the client as a stream of Unicode characters.
41+ * <P>
42+ * <code>SerialClob</code> methods make it possible to get a substring
43+ * from a <code>SerialClob</code> object or to locate the start of
44+ * a pattern of characters.
45+ *
46+ * @author Jonathan Bruce
47+ */
48+public class SerialClob implements Clob, Serializable, Cloneable {
49+
50+ /**
51+ * A serialized array of characters containing the data of the SQL
52+ * <code>CLOB</code> value that this <code>SerialClob</code> object
53+ * represents.
54+ *
55+ * @serial
56+ */
57+ private char buf[];
58+
59+ /**
60+ * Internal Clob representation if SerialClob is initialized with a
61+ * Clob. Null if SerialClob is initialized with a char[].
62+ */
63+ private final Clob clob;
64+
65+ /**
66+ * The length in characters of this <code>SerialClob</code> object's
67+ * internal array of characters.
68+ *
69+ * @serial
70+ */
71+ private long len;
72+
73+ /**
74+ * The original length in characters of this <code>SerialClob</code>
75+ * object's internal array of characters.
76+ *
77+ * @serial
78+ */
79+ private final long origLen;
80+
81+ /**
82+ * Constructs a <code>SerialClob</code> object that is a serialized version of
83+ * the given <code>char</code> array.
84+ * <p>
85+ * The new <code>SerialClob</code> object is initialized with the data from the
86+ * <code>char</code> array, thus allowing disconnected <code>RowSet</code>
87+ * objects to establish a serialized <code>Clob</code> object without touching
88+ * the data source.
89+ *
90+ * @param ch the char array representing the <code>Clob</code> object to be
91+ * serialized
92+ * @throws SerialException if an error occurs during serialization
93+ * @throws SQLException if a SQL error occurs
94+ */
95+ public SerialClob(char ch[]) throws SerialException, SQLException {
96+
97+ // %%% JMB. Agreed. Add code here to throw a SQLException if no
98+ // support is available for locatorsUpdateCopy=false
99+ // Serializing locators is not supported.
100+
101+ len = ch.length;
102+ buf = new char[(int)len];
103+ for (int i = 0; i < len ; i++){
104+ buf[i] = ch[i];
105+ }
106+ origLen = len;
107+ clob = null;
108+ }
109+
110+ /**
111+ * Constructs a <code>SerialClob</code> object that is a serialized
112+ * version of the given <code>Clob</code> object.
113+ * <P>
114+ * The new <code>SerialClob</code> object is initialized with the
115+ * data from the <code>Clob</code> object; therefore, the
116+ * <code>Clob</code> object should have previously brought the
117+ * SQL <code>CLOB</code> value's data over to the client from
118+ * the database. Otherwise, the new <code>SerialClob</code> object
119+ * object will contain no data.
120+ * <p>
121+ * Note: The <code>Clob</code> object supplied to this constructor must
122+ * return non-null for both the <code>Clob.getCharacterStream()</code>
123+ * and <code>Clob.getAsciiStream</code> methods. This <code>SerialClob</code>
124+ * constructor cannot serialize a <code>Clob</code> object in this instance
125+ * and will throw an <code>SQLException</code> object.
126+ *
127+ * @param clob the <code>Clob</code> object from which this
128+ * <code>SerialClob</code> object is to be constructed; cannot be null
129+ * @throws SerialException if an error occurs during serialization
130+ * @throws SQLException if a SQL error occurs in capturing the CLOB;
131+ * if the <code>Clob</code> object is a null; or if either of the
132+ * <code>Clob.getCharacterStream()</code> and <code>Clob.getAsciiStream()</code>
133+ * methods on the <code>Clob</code> returns a null
134+ * @see java.sql.Clob
135+ */
136+ public SerialClob(Clob clob) throws SerialException, SQLException {
137+
138+ if (clob == null) {
139+ throw new SQLException("Cannot instantiate a SerialClob " +
140+ "object with a null Clob object");
141+ }
142+ len = clob.length();
143+ this.clob = clob;
144+ buf = new char[(int)len];
145+ int read = 0;
146+ int offset = 0;
147+
148+ try (Reader charStream = clob.getCharacterStream()) {
149+ if (charStream == null) {
150+ throw new SQLException("Invalid Clob object. The call to getCharacterStream " +
151+ "returned null which cannot be serialized.");
152+ }
153+
154+ // Note: get an ASCII stream in order to null-check it,
155+ // even though we don't do anything with it.
156+ try (InputStream asciiStream = clob.getAsciiStream()) {
157+ if (asciiStream == null) {
158+ throw new SQLException("Invalid Clob object. The call to getAsciiStream " +
159+ "returned null which cannot be serialized.");
160+ }
161+ }
162+
163+ try (Reader reader = new BufferedReader(charStream)) {
164+ do {
165+ read = reader.read(buf, offset, (int)(len - offset));
166+ offset += read;
167+ } while (read > 0);
168+ }
169+ } catch (java.io.IOException ex) {
170+ throw new SerialException("SerialClob: " + ex.getMessage());
171+ }
172+
173+ origLen = len;
174+ }
175+
176+ /**
177+ * Retrieves the number of characters in this <code>SerialClob</code>
178+ * object's array of characters.
179+ *
180+ * @return a <code>long</code> indicating the length in characters of this
181+ * <code>SerialClob</code> object's array of character
182+ * @throws SerialException if an error occurs
183+ */
184+ public long length() throws SerialException {
185+ return len;
186+ }
187+
188+ /**
189+ * Returns this <code>SerialClob</code> object's data as a stream
190+ * of Unicode characters. Unlike the related method, <code>getAsciiStream</code>,
191+ * a stream is produced regardless of whether the <code>SerialClob</code> object
192+ * was created with a <code>Clob</code> object or a <code>char</code> array.
193+ *
194+ * @return a <code>java.io.Reader</code> object containing this
195+ * <code>SerialClob</code> object's data
196+ * @throws SerialException if an error occurs
197+ */
198+ public java.io.Reader getCharacterStream() throws SerialException {
199+ return (java.io.Reader) new CharArrayReader(buf);
200+ }
201+
202+ /**
203+ * Retrieves the <code>CLOB</code> value designated by this <code>SerialClob</code>
204+ * object as an ascii stream. This method forwards the <code>getAsciiStream</code>
205+ * call to the underlying <code>Clob</code> object in the event that this
206+ * <code>SerialClob</code> object is instantiated with a <code>Clob</code>
207+ * object. If this <code>SerialClob</code> object is instantiated with
208+ * a <code>char</code> array, a <code>SerialException</code> object is thrown.
209+ *
210+ * @return a <code>java.io.InputStream</code> object containing
211+ * this <code>SerialClob</code> object's data
212+ * @throws SerialException if this <code>SerialClob</code> object was not instantiated
213+ * with a <code>Clob</code> object
214+ * @throws SQLException if there is an error accessing the
215+ * <code>CLOB</code> value represented by the <code>Clob</code> object that was
216+ * used to create this <code>SerialClob</code> object
217+ */
218+ public java.io.InputStream getAsciiStream() throws SerialException, SQLException {
219+ if (this.clob != null) {
220+ return this.clob.getAsciiStream();
221+ } else {
222+ throw new SerialException("Unsupported operation. SerialClob cannot " +
223+ "return a the CLOB value as an ascii stream, unless instantiated " +
224+ "with a fully implemented Clob object.");
225+ }
226+ }
227+
228+ /**
229+ * Returns a copy of the substring contained in this
230+ * <code>SerialClob</code> object, starting at the given position
231+ * and continuing for the specified number or characters.
232+ *
233+ * @param pos the position of the first character in the substring
234+ * to be copied; the first character of the
235+ * <code>SerialClob</code> object is at position
236+ * <code>1</code>; must not be less than <code>1</code>,
237+ * and the sum of the starting position and the length
238+ * of the substring must be less than the length of this
239+ * <code>SerialClob</code> object
240+ * @param length the number of characters in the substring to be
241+ * returned; must not be greater than the length of
242+ * this <code>SerialClob</code> object, and the
243+ * sum of the starting position and the length
244+ * of the substring must be less than the length of this
245+ * <code>SerialClob</code> object
246+ * @return a <code>String</code> object containing a substring of
247+ * this <code>SerialClob</code> object beginning at the
248+ * given position and containing the specified number of
249+ * consecutive characters
250+ * @throws SerialException if either of the arguments is out of bounds
251+ */
252+ public String getSubString(long pos, int length) throws SerialException {
253+
254+ if (pos < 1 || pos > this.length()) {
255+ throw new SerialException("Invalid position in BLOB object set");
256+ }
257+
258+ if ((pos-1) + length > this.length()) {
259+ throw new SerialException("Invalid position and substring length");
260+ }
261+
262+ try {
263+ return new String(buf, (int)pos - 1, length);
264+
265+ } catch (StringIndexOutOfBoundsException e) {
266+ throw new SerialException("StringIndexOutOfBoundsException: " +
267+ e.getMessage());
268+ }
269+
270+ }
271+
272+ /**
273+ * Returns the position in this <code>SerialClob</code> object
274+ * where the given <code>String</code> object begins, starting
275+ * the search at the specified position. This method returns
276+ * <code>-1</code> if the pattern is not found.
277+ *
278+ * @param searchStr the <code>String</code> object for which to
279+ * search
280+ * @param start the position in this <code>SerialClob</code> object
281+ * at which to start the search; the first position is
282+ * <code>1</code>; must not be less than <code>1</code> nor
283+ * greater than the length of this <code>SerialClob</code> object
284+ * @return the position at which the given <code>String</code> object
285+ * begins, starting the search at the specified position;
286+ * <code>-1</code> if the given <code>String</code> object is
287+ * not found or the starting position is out of bounds; position
288+ * numbering for the return value starts at <code>1</code>
289+ * @throws SerialException if an error occurs locating the String signature
290+ * @throws SQLException if there is an error accessing the Blob value
291+ * from the database.
292+ */
293+ public long position(String searchStr, long start)
294+ throws SerialException, SQLException {
295+
296+ if (start < 1 || start > len) {
297+ return -1;
298+ }
299+
300+ char pattern[] = searchStr.toCharArray();
301+
302+ int pos = (int)start-1;
303+ int i = 0;
304+ long patlen = pattern.length;
305+
306+ while (pos < len) {
307+ if (pattern[i] == buf[pos]) {
308+ if (i + 1 == patlen) {
309+ return (pos + 1) - (patlen - 1);
310+ }
311+ i++; pos++; // increment pos, and i
312+
313+ } else if (pattern[i] != buf[pos]) {
314+ pos++; // increment pos only
315+ }
316+ }
317+ return -1; // not found
318+ }
319+
320+ /**
321+ * Returns the position in this <code>SerialClob</code> object
322+ * where the given <code>Clob</code> signature begins, starting
323+ * the search at the specified position. This method returns
324+ * <code>-1</code> if the pattern is not found.
325+ *
326+ * @param searchStr the <code>Clob</code> object for which to search
327+ * @param start the position in this <code>SerialClob</code> object
328+ * at which to begin the search; the first position is
329+ * <code>1</code>; must not be less than <code>1</code> nor
330+ * greater than the length of this <code>SerialClob</code> object
331+ * @return the position at which the given <code>Clob</code>
332+ * object begins in this <code>SerialClob</code> object,
333+ * at or after the specified starting position
334+ * @throws SerialException if an error occurs locating the Clob signature
335+ * @throws SQLException if there is an error accessing the Blob value
336+ * from the database
337+ */
338+ public long position(Clob searchStr, long start)
339+ throws SerialException, SQLException {
340+
341+ return position(searchStr.getSubString(1,(int)searchStr.length()), start);
342+ }
343+
344+ /**
345+ * Writes the given Java <code>String</code> to the <code>CLOB</code>
346+ * value that this <code>SerialClob</code> object represents, at the position
347+ * <code>pos</code>.
348+ *
349+ * @param pos the position at which to start writing to the <code>CLOB</code>
350+ * value that this <code>SerialClob</code> object represents; the first
351+ * position is <code>1</code>; must not be less than <code>1</code> nor
352+ * greater than the length of this <code>SerialClob</code> object
353+ * @param str the string to be written to the <code>CLOB</code>
354+ * value that this <code>SerialClob</code> object represents
355+ * @return the number of characters written
356+ * @throws SerialException if there is an error accessing the
357+ * <code>CLOB</code> value; if an invalid position is set; if an
358+ * invalid offset value is set; if number of bytes to be written
359+ * is greater than the <code>SerialClob</code> length; or the combined
360+ * values of the length and offset is greater than the Clob buffer
361+ */
362+ public int setString(long pos, String str) throws SerialException {
363+ return (setString(pos, str, 0, str.length()));
364+ }
365+
366+ /**
367+ * Writes <code>len</code> characters of <code>str</code>, starting
368+ * at character <code>offset</code>, to the <code>CLOB</code> value
369+ * that this <code>Clob</code> represents.
370+ *
371+ * @param pos the position at which to start writing to the <code>CLOB</code>
372+ * value that this <code>SerialClob</code> object represents; the first
373+ * position is <code>1</code>; must not be less than <code>1</code> nor
374+ * greater than the length of this <code>SerialClob</code> object
375+ * @param str the string to be written to the <code>CLOB</code>
376+ * value that this <code>Clob</code> object represents
377+ * @param offset the offset into <code>str</code> to start reading
378+ * the characters to be written
379+ * @param length the number of characters to be written
380+ * @return the number of characters written
381+ * @throws SerialException if there is an error accessing the
382+ * <code>CLOB</code> value; if an invalid position is set; if an
383+ * invalid offset value is set; if number of bytes to be written
384+ * is greater than the <code>SerialClob</code> length; or the combined
385+ * values of the length and offset is greater than the Clob buffer
386+ */
387+ public int setString(long pos, String str, int offset, int length)
388+ throws SerialException {
389+ String temp = str.substring(offset);
390+ char cPattern[] = temp.toCharArray();
391+
392+ if (offset < 0 || offset > str.length()) {
393+ throw new SerialException("Invalid offset in byte array set");
394+ }
395+
396+ if (pos < 1 || pos > this.length()) {
397+ throw new SerialException("Invalid position in BLOB object set");
398+ }
399+
400+ if ((long)(length) > origLen) {
401+ throw new SerialException("Buffer is not sufficient to hold the value");
402+ }
403+
404+ if ((length + offset) > str.length()) {
405+ // need check to ensure length + offset !> bytes.length
406+ throw new SerialException("Invalid OffSet. Cannot have combined offset " +
407+ " and length that is greater that the Blob buffer");
408+ }
409+
410+ int i = 0;
411+ pos--; //values in the array are at position one less
412+ while ( i < length || (offset + i +1) < (str.length() - offset ) ) {
413+ this.buf[(int)pos + i ] = cPattern[offset + i ];
414+ i++;
415+ }
416+ return i;
417+ }
418+
419+ /**
420+ * Retrieves a stream to be used to write Ascii characters to the
421+ * <code>CLOB</code> value that this <code>SerialClob</code> object represents,
422+ * starting at position <code>pos</code>. This method forwards the
423+ * <code>setAsciiStream()</code> call to the underlying <code>Clob</code> object in
424+ * the event that this <code>SerialClob</code> object is instantiated with a
425+ * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated
426+ * with a <code>char</code> array, a <code>SerialException</code> object is thrown.
427+ *
428+ * @param pos the position at which to start writing to the
429+ * <code>CLOB</code> object
430+ * @return the stream to which ASCII encoded characters can be written
431+ * @throws SerialException if SerialClob is not instantiated with a
432+ * Clob object that supports <code>setAsciiStream</code>
433+ * @throws SQLException if there is an error accessing the
434+ * <code>CLOB</code> value
435+ * @see #getAsciiStream
436+ */
437+ public java.io.OutputStream setAsciiStream(long pos)
438+ throws SerialException, SQLException {
439+ if (this.clob.setAsciiStream(pos) != null) {
440+ return this.clob.setAsciiStream(pos);
441+ } else {
442+ throw new SerialException("Unsupported operation. SerialClob cannot " +
443+ "return a writable ascii stream\n unless instantiated with a Clob object " +
444+ "that has a setAsciiStream() implementation");
445+ }
446+ }
447+
448+ /**
449+ * Retrieves a stream to be used to write a stream of Unicode characters
450+ * to the <code>CLOB</code> value that this <code>SerialClob</code> object
451+ * represents, at position <code>pos</code>. This method forwards the
452+ * <code>setCharacterStream()</code> call to the underlying <code>Clob</code>
453+ * object in the event that this <code>SerialClob</code> object is instantiated with a
454+ * <code>Clob</code> object. If this <code>SerialClob</code> object is instantiated with
455+ * a <code>char</code> array, a <code>SerialException</code> is thrown.
456+ *
457+ * @param pos the position at which to start writing to the
458+ * <code>CLOB</code> value
459+ *
460+ * @return a stream to which Unicode encoded characters can be written
461+ * @throws SerialException if the SerialClob is not instantiated with
462+ * a Clob object that supports <code>setCharacterStream</code>
463+ * @throws SQLException if there is an error accessing the
464+ * <code>CLOB</code> value
465+ * @see #getCharacterStream
466+ */
467+ public java.io.Writer setCharacterStream(long pos)
468+ throws SerialException, SQLException {
469+ if (this.clob.setCharacterStream(pos) != null) {
470+ return this.clob.setCharacterStream(pos);
471+ } else {
472+ throw new SerialException("Unsupported operation. SerialClob cannot " +
473+ "return a writable character stream\n unless instantiated with a Clob object " +
474+ "that has a setCharacterStream implementation");
475+ }
476+ }
477+
478+ /**
479+ * Truncates the <code>CLOB</code> value that this <code>SerialClob</code>
480+ * object represents so that it has a length of <code>len</code>
481+ * characters.
482+ * <p>
483+ * Truncating a <code>SerialClob</code> object to length 0 has the effect of
484+ * clearing its contents.
485+ *
486+ * @param length the length, in bytes, to which the <code>CLOB</code>
487+ * value should be truncated
488+ * @throws SQLException if there is an error accessing the
489+ * <code>CLOB</code> value
490+ */
491+ public void truncate(long length) throws SerialException {
492+ if (length > len) {
493+ throw new SerialException
494+ ("Length more than what can be truncated");
495+ } else {
496+ len = length;
497+ // re-size the buffer
498+
499+ if (len == 0) {
500+ buf = new char[] {};
501+ } else {
502+ buf = (this.getSubString(1, (int)len)).toCharArray();
503+ }
504+
505+ }
506+ }
507+
508+
509+ public Reader getCharacterStream(long pos, long length) throws SQLException {
510+ throw new java.lang.UnsupportedOperationException("Not supported");
511+ }
512+
513+ public void free() throws SQLException {
514+ throw new java.lang.UnsupportedOperationException("Not supported");
515+ }
516+
517+ /**
518+ * The identifier that assists in the serialization of this <code>SerialClob</code>
519+ * object.
520+ */
521+ static final long serialVersionUID = -1662519690087375313L;
522+}
java/pkg/javax/sql/rowset/serial/SerialDatalink.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialDatalink.java+109−0
@@ -0,0 +1,109 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import java.io.*;
30+import java.net.URL;
31+
32+
33+/**
34+ * A serialized mapping in the Java programming language of an SQL
35+ * <code>DATALINK</code> value. A <code>DATALINK</code> value
36+ * references a file outside of the underlying data source that the
37+ * data source manages.
38+ * <P>
39+ * <code>RowSet</code> implementations can use the method <code>RowSet.getURL</code>
40+ * to retrieve a <code>java.net.URL</code> object, which can be used
41+ * to manipulate the external data.
42+ * <pre>
43+ * java.net.URL url = rowset.getURL(1);
44+ * </pre>
45+ */
46+public class SerialDatalink implements Serializable, Cloneable {
47+
48+ /**
49+ * The extracted URL field retrieved from the DATALINK field.
50+ * @serial
51+ */
52+ private URL url;
53+
54+ /**
55+ * The SQL type of the elements in this <code>SerialDatalink</code>
56+ * object. The type is expressed as one of the contants from the
57+ * class <code>java.sql.Types</code>.
58+ * @serial
59+ */
60+ private int baseType;
61+
62+ /**
63+ * The type name used by the DBMS for the elements in the SQL
64+ * <code>DATALINK</code> value that this SerialDatalink object
65+ * represents.
66+ * @serial
67+ */
68+ private String baseTypeName;
69+
70+ /**
71+ * Constructs a new <code>SerialDatalink</code> object from the given
72+ * <code>java.net.URL</code> object.
73+ * <P>
74+ * @throws SerialException if url parameter is a null
75+ */
76+ public SerialDatalink(URL url) throws SerialException {
77+ if (url == null) {
78+ throw new SerialException("Cannot serialize empty URL instance");
79+ }
80+ this.url = url;
81+ }
82+
83+ /**
84+ * Returns a new URL that is a copy of this <code>SerialDatalink</code>
85+ * object.
86+ *
87+ * @return a copy of this <code>SerialDatalink</code> object as a
88+ * <code>URL</code> object in the Java programming language.
89+ * @throws SerialException if the <code>URL</code> object cannot be de-serialized
90+ */
91+ public URL getDatalink() throws SerialException {
92+
93+ URL aURL = null;
94+
95+ try {
96+ aURL = new URL((this.url).toString());
97+ } catch (java.net.MalformedURLException e) {
98+ throw new SerialException("MalformedURLException: " + e.getMessage());
99+ }
100+ return aURL;
101+ }
102+
103+
104+ /**
105+ * The identifier that assists in the serialization of this <code>SerialDatalink</code>
106+ * object.
107+ */
108+ static final long serialVersionUID = 2826907821828733626L;
109+}
java/pkg/javax/sql/rowset/serial/SerialException.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialException.java+56−0
@@ -0,0 +1,56 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.SQLException;
29+
30+/**
31+ * Indicates and an error with the serialization or de-serialization of
32+ * SQL types such as <code>BLOB, CLOB, STRUCT or ARRAY</code> in
33+ * addition to SQL types such as <code>DATALINK and JAVAOBJECT</code>
34+ *
35+ */
36+public class SerialException extends java.sql.SQLException {
37+
38+ /**
39+ * Creates a new <code>SerialException</code> without a
40+ * message.
41+ */
42+ public SerialException() {
43+ }
44+
45+ /**
46+ * Creates a new <code>SerialException</code> with the
47+ * specified message.
48+ *
49+ * @param msg the detail message
50+ */
51+ public SerialException(String msg) {
52+ super(msg);
53+ }
54+
55+ static final long serialVersionUID = -489794565168592690L;
56+}
java/pkg/javax/sql/rowset/serial/SerialJavaObject.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialJavaObject.java+156−0
@@ -0,0 +1,156 @@
1+/*
2+ * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.io.*;
29+import java.lang.reflect.*;
30+import javax.sql.rowset.RowSetWarning;
31+
32+/**
33+ * A serializable mapping in the Java programming language of an SQL
34+ * <code>JAVA_OBJECT</code> value. Assuming the Java object
35+ * implements the <code>Serializable</code> interface, this class simply wraps the
36+ * serialization process.
37+ * <P>
38+ * If however, the serialization is not possible because
39+ * the Java object is not immediately serializable, this class will
40+ * attempt to serialize all non-static members to permit the object
41+ * state to be serialized.
42+ * Static or transient fields cannot be serialized; an attempt to serialize
43+ * them will result in a <code>SerialException</code> object being thrown.
44+ *
45+ * @author Jonathan Bruce
46+ */
47+public class SerialJavaObject implements Serializable, Cloneable {
48+
49+ /**
50+ * Placeholder for object to be serialized.
51+ */
52+ private final Object obj;
53+
54+
55+ /**
56+ * Placeholder for all fields in the <code>JavaObject</code> being serialized.
57+ */
58+ private transient Field[] fields;
59+
60+ /**
61+ * Constructor for <code>SerialJavaObject</code> helper class.
62+ * <p>
63+ *
64+ * @param obj the Java <code>Object</code> to be serialized
65+ * @throws SerialException if the object is found not to be serializable
66+ */
67+ public SerialJavaObject(Object obj) throws SerialException {
68+
69+ // if any static fields are found, an exception
70+ // should be thrown
71+
72+
73+ // get Class. Object instance should always be available
74+ Class<?> c = obj.getClass();
75+
76+ // determine if object implements Serializable i/f
77+ if (!(obj instanceof java.io.Serializable)) {
78+ setWarning(new RowSetWarning("Warning, the object passed to the constructor does not implement Serializable"));
79+ }
80+
81+ // can only determine public fields (obviously). If
82+ // any of these are static, this should invalidate
83+ // the action of attempting to persist these fields
84+ // in a serialized form
85+
86+ boolean anyStaticFields = false;
87+ fields = c.getFields();
88+
89+ for (int i = 0; i < fields.length; i++ ) {
90+ if ( fields[i].getModifiers() == Modifier.STATIC ) {
91+ anyStaticFields = true;
92+ }
93+ }
94+
95+
96+ if (anyStaticFields) {
97+ throw new SerialException("Located static fields in " +
98+ "object instance. Cannot serialize");
99+ }
100+
101+ this.obj = obj;
102+ }
103+
104+ /**
105+ * Returns an <code>Object</code> that is a copy of this <code>SerialJavaObject</code>
106+ * object.
107+ *
108+ * @return a copy of this <code>SerialJavaObject</code> object as an
109+ * <code>Object</code> in the Java programming language
110+ * @throws SerialException if the instance is corrupt
111+ */
112+ public Object getObject() throws SerialException {
113+ return this.obj;
114+ }
115+
116+ /**
117+ * Returns an array of <code>Field</code> objects that contains each
118+ * field of the object that this helper class is serializing.
119+ *
120+ * @return an array of <code>Field</code> objects
121+ * @throws SerialException if an error is encountered accessing
122+ * the serialized object
123+ */
124+ public Field[] getFields() throws SerialException {
125+ if (fields != null) {
126+ Class<?> c = this.obj.getClass();
127+ return c.getFields();
128+ } else {
129+ throw new SerialException("SerialJavaObject does not contain" +
130+ " a serialized object instance");
131+ }
132+ }
133+
134+ /**
135+ * The identifier that assists in the serialization of this
136+ * <code>SerialJavaObject</code> object.
137+ */
138+ static final long serialVersionUID = -1465795139032831023L;
139+
140+ /**
141+ * A container for the warnings issued on this <code>SerialJavaObject</code>
142+ * object. When there are multiple warnings, each warning is chained to the
143+ * previous warning.
144+ */
145+ java.util.Vector chain;
146+
147+ /**
148+ * Registers the given warning.
149+ */
150+ private void setWarning(RowSetWarning e) {
151+ if (chain == null) {
152+ chain = new java.util.Vector();
153+ }
154+ chain.add(e);
155+ }
156+}
java/pkg/javax/sql/rowset/serial/SerialRef.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialRef.java+172−0
@@ -0,0 +1,172 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import java.io.*;
30+import java.util.*;
31+
32+/**
33+ * A serialized mapping of a <code>Ref</code> object, which is the mapping in the
34+ * Java programming language of an SQL <code>REF</code> value.
35+ * <p>
36+ * The <code>SerialRef</code> class provides a constructor for
37+ * creating a <code>SerialRef</code> instance from a <code>Ref</code>
38+ * object and provides methods for getting and setting the <code>Ref</code> object.
39+ */
40+public class SerialRef implements Ref, Serializable, Cloneable {
41+
42+ /**
43+ * String containing the base type name.
44+ * @serial
45+ */
46+ private String baseTypeName;
47+
48+ /**
49+ * This will store the type <code>Ref</code> as an <code>Object</code>.
50+ */
51+ private Object object;
52+
53+ /**
54+ * Private copy of the Ref reference.
55+ */
56+ private Ref reference;
57+
58+ /**
59+ * Constructs a <code>SerialRef</code> object from the given <code>Ref</code>
60+ * object.
61+ *
62+ * @param ref a Ref object; cannot be <code>null</code>
63+ * @throws SQLException if a database access occurs; if <code>ref</code>
64+ * is <code>null</code>; or if the <code>Ref</code> object returns a
65+ * <code>null</code> value base type name.
66+ * @throws SerialException if an error occurs serializing the <code>Ref</code>
67+ * object
68+ */
69+ public SerialRef(Ref ref) throws SerialException, SQLException {
70+ if (ref == null) {
71+ throw new SQLException("Cannot instantiate a SerialRef object " +
72+ "with a null Ref object");
73+ }
74+ reference = ref;
75+ object = ref;
76+ if (ref.getBaseTypeName() == null) {
77+ throw new SQLException("Cannot instantiate a SerialRef object " +
78+ "that returns a null base type name");
79+ } else {
80+ baseTypeName = ref.getBaseTypeName();
81+ }
82+ }
83+
84+ /**
85+ * Returns a string describing the base type name of the <code>Ref</code>.
86+ *
87+ * @return a string of the base type name of the Ref
88+ * @throws SerialException in no Ref object has been set
89+ */
90+ public String getBaseTypeName() throws SerialException {
91+ return baseTypeName;
92+ }
93+
94+ /**
95+ * Returns an <code>Object</code> representing the SQL structured type
96+ * to which this <code>SerialRef</code> object refers. The attributes
97+ * of the structured type are mapped according to the given type map.
98+ *
99+ * @param map a <code>java.util.Map</code> object containing zero or
100+ * more entries, with each entry consisting of 1) a <code>String</code>
101+ * giving the fully qualified name of a UDT and 2) the
102+ * <code>Class</code> object for the <code>SQLData</code> implementation
103+ * that defines how the UDT is to be mapped
104+ * @return an object instance resolved from the Ref reference and mapped
105+ * according to the supplied type map
106+ * @throws SerialException if an error is encountered in the reference
107+ * resolution
108+ */
109+ public Object getObject(java.util.Map<String,Class<?>> map)
110+ throws SerialException
111+ {
112+ map = new Hashtable(map);
113+ if (object != null) {
114+ return map.get(object);
115+ } else {
116+ throw new SerialException("The object is not set");
117+ }
118+ }
119+
120+ /**
121+ * Returns an <code>Object</code> representing the SQL structured type
122+ * to which this <code>SerialRef</code> object refers.
123+ *
124+ * @return an object instance resolved from the Ref reference
125+ * @throws SerialException if an error is encountered in the reference
126+ * resolution
127+ */
128+ public Object getObject() throws SerialException {
129+
130+ if (reference != null) {
131+ try {
132+ return reference.getObject();
133+ } catch (SQLException e) {
134+ throw new SerialException("SQLException: " + e.getMessage());
135+ }
136+ }
137+
138+ if (object != null) {
139+ return object;
140+ }
141+
142+
143+ throw new SerialException("The object is not set");
144+
145+ }
146+
147+ /**
148+ * Sets the SQL structured type that this <code>SerialRef</code> object
149+ * references to the given <code>Object</code> object.
150+ *
151+ * @param obj an <code>Object</code> representing the SQL structured type
152+ * to be referenced
153+ * @throws SerialException if an error is encountered generating the
154+ * the structured type referenced by this <code>SerialRef</code> object
155+ */
156+ public void setObject(Object obj) throws SerialException {
157+ try {
158+ reference.setObject(obj);
159+ } catch (SQLException e) {
160+ throw new SerialException("SQLException: " + e.getMessage());
161+ }
162+ object = obj;
163+ }
164+
165+ /**
166+ * The identifier that assists in the serialization of this <code>SerialRef</code>
167+ * object.
168+ */
169+ static final long serialVersionUID = -4727123500609662274L;
170+
171+
172+}
java/pkg/javax/sql/rowset/serial/SerialStruct.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/serial/SerialStruct.java+254−0
@@ -0,0 +1,254 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.serial;
27+
28+import java.sql.*;
29+import javax.sql.*;
30+import java.io.*;
31+import java.math.*;
32+import java.util.Map;
33+import java.util.Vector;
34+
35+import javax.sql.rowset.*;
36+
37+/**
38+ * A serialized mapping in the Java programming language of an SQL
39+ * structured type. Each attribute that is not already serialized
40+ * is mapped to a serialized form, and if an attribute is itself
41+ * a structured type, each of its attributes that is not already
42+ * serialized is mapped to a serialized form.
43+ * <P>
44+ * In addition, the structured type is custom mapped to a class in the
45+ * Java programming language if there is such a mapping, as are
46+ * its attributes, if appropriate.
47+ * <P>
48+ * The <code>SerialStruct</code> class provides a constructor for creating
49+ * an instance from a <code>Struct</code> object, a method for retrieving
50+ * the SQL type name of the SQL structured type in the database, and methods
51+ * for retrieving its attribute values.
52+ */
53+public class SerialStruct implements Struct, Serializable, Cloneable {
54+
55+
56+ /**
57+ * The SQL type name for the structured type that this
58+ * <code>SerialStruct</code> object represents. This is the name
59+ * used in the SQL definition of the SQL structured type.
60+ *
61+ * @serial
62+ */
63+ private String SQLTypeName;
64+
65+ /**
66+ * An array of <code>Object</code> instances in which each
67+ * element is an attribute of the SQL structured type that this
68+ * <code>SerialStruct</code> object represents. The attributes are
69+ * ordered according to their order in the definition of the
70+ * SQL structured type.
71+ *
72+ * @serial
73+ */
74+ private Object attribs[];
75+
76+ /**
77+ * Constructs a <code>SerialStruct</code> object from the given
78+ * <code>Struct</code> object, using the given <code>java.util.Map</code>
79+ * object for custom mapping the SQL structured type or any of its
80+ * attributes that are SQL structured types.
81+ *
82+ * @param map a <code>java.util.Map</code> object in which
83+ * each entry consists of 1) a <code>String</code> object
84+ * giving the fully qualified name of a UDT and 2) the
85+ * <code>Class</code> object for the <code>SQLData</code> implementation
86+ * that defines how the UDT is to be mapped
87+ * @throws SerialException if an error occurs
88+ * @see java.sql.Struct
89+ */
90+ public SerialStruct(Struct in, Map<String,Class<?>> map)
91+ throws SerialException
92+ {
93+
94+ try {
95+
96+ // get the type name
97+ SQLTypeName = in.getSQLTypeName();
98+ System.out.println("SQLTypeName: " + SQLTypeName);
99+
100+ // get the attributes of the struct
101+ attribs = in.getAttributes(map);
102+
103+ /*
104+ * the array may contain further Structs
105+ * and/or classes that have been mapped,
106+ * other types that we have to serialize
107+ */
108+ mapToSerial(map);
109+
110+ } catch (SQLException e) {
111+ throw new SerialException(e.getMessage());
112+ }
113+ }
114+
115+ /**
116+ * Constructs a <code>SerialStruct</code> object from the
117+ * given <code>SQLData</code> object, using the given type
118+ * map to custom map it to a class in the Java programming
119+ * language. The type map gives the SQL type and the class
120+ * to which it is mapped. The <code>SQLData</code> object
121+ * defines the class to which the SQL type will be mapped.
122+ *
123+ * @param in an instance of the <code>SQLData</code> class
124+ * that defines the mapping of the SQL structured
125+ * type to one or more objects in the Java programming language
126+ * @param map a <code>java.util.Map</code> object in which
127+ * each entry consists of 1) a <code>String</code> object
128+ * giving the fully qualified name of a UDT and 2) the
129+ * <code>Class</code> object for the <code>SQLData</code> implementation
130+ * that defines how the UDT is to be mapped
131+ * @throws SerialException if an error occurs
132+ */
133+ public SerialStruct(SQLData in, Map<String,Class<?>> map)
134+ throws SerialException
135+ {
136+
137+ try {
138+
139+ //set the type name
140+ SQLTypeName = in.getSQLTypeName();
141+
142+ Vector tmp = new Vector();
143+ in.writeSQL(new SQLOutputImpl(tmp, map));
144+ attribs = tmp.toArray();
145+
146+ } catch (SQLException e) {
147+ throw new SerialException(e.getMessage());
148+ }
149+ }
150+
151+
152+ /**
153+ * Retrieves the SQL type name for this <code>SerialStruct</code>
154+ * object. This is the name used in the SQL definition of the
155+ * structured type
156+ *
157+ * @return a <code>String</code> object representing the SQL
158+ * type name for the SQL structured type that this
159+ * <code>SerialStruct</code> object represents
160+ * @throws SerialException if an error occurs
161+ */
162+ public String getSQLTypeName() throws SerialException {
163+ return SQLTypeName;
164+ }
165+
166+ /**
167+ * Retrieves an array of <code>Object</code> values containing the
168+ * attributes of the SQL structured type that this
169+ * <code>SerialStruct</code> object represents.
170+ *
171+ * @return an array of <code>Object</code> values, with each
172+ * element being an attribute of the SQL structured type
173+ * that this <code>SerialStruct</code> object represents
174+ * @throws SerialException if an error occurs
175+ */
176+ public Object[] getAttributes() throws SerialException {
177+ return attribs;
178+ }
179+
180+ /**
181+ * Retrieves the attributes for the SQL structured type that
182+ * this <code>SerialStruct</code> represents as an array of
183+ * <code>Object</code> values, using the given type map for
184+ * custom mapping if appropriate.
185+ *
186+ * @param map a <code>java.util.Map</code> object in which
187+ * each entry consists of 1) a <code>String</code> object
188+ * giving the fully qualified name of a UDT and 2) the
189+ * <code>Class</code> object for the <code>SQLData</code> implementation
190+ * that defines how the UDT is to be mapped
191+ * @return an array of <code>Object</code> values, with each
192+ * element being an attribute of the SQL structured
193+ * type that this <code>SerialStruct</code> object
194+ * represents
195+ * @throws SerialException if an error occurs
196+ */
197+ public Object[] getAttributes(Map<String,Class<?>> map)
198+ throws SerialException
199+ {
200+ return attribs;
201+ }
202+
203+
204+ /**
205+ * Maps attributes of an SQL structured type that are not
206+ * serialized to a serialized form, using the given type map
207+ * for custom mapping when appropriate. The following types
208+ * in the Java programming language are mapped to their
209+ * serialized forms: <code>Struct</code>, <code>SQLData</code>,
210+ * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, and
211+ * <code>Array</code>.
212+ * <P>
213+ * This method is called internally and is not used by an
214+ * application programmer.
215+ *
216+ * @param map a <code>java.util.Map</code> object in which
217+ * each entry consists of 1) a <code>String</code> object
218+ * giving the fully qualified name of a UDT and 2) the
219+ * <code>Class</code> object for the <code>SQLData</code> implementation
220+ * that defines how the UDT is to be mapped
221+ * @throws SerialException if an error occurs
222+ */
223+ private void mapToSerial(Map map) throws SerialException {
224+
225+ try {
226+
227+ for (int i = 0; i < attribs.length; i++) {
228+ if (attribs[i] instanceof Struct) {
229+ attribs[i] = new SerialStruct((Struct)attribs[i], map);
230+ } else if (attribs[i] instanceof SQLData) {
231+ attribs[i] = new SerialStruct((SQLData)attribs[i], map);
232+ } else if (attribs[i] instanceof Blob) {
233+ attribs[i] = new SerialBlob((Blob)attribs[i]);
234+ } else if (attribs[i] instanceof Clob) {
235+ attribs[i] = new SerialClob((Clob)attribs[i]);
236+ } else if (attribs[i] instanceof Ref) {
237+ attribs[i] = new SerialRef((Ref)attribs[i]);
238+ } else if (attribs[i] instanceof java.sql.Array) {
239+ attribs[i] = new SerialArray((java.sql.Array)attribs[i], map);
240+ }
241+ }
242+
243+ } catch (SQLException e) {
244+ throw new SerialException(e.getMessage());
245+ }
246+ return;
247+ }
248+
249+ /**
250+ * The identifier that assists in the serialization of this
251+ * <code>SerialStruct</code> object.
252+ */
253+ static final long serialVersionUID = -8322445504027483372L;
254+}
java/pkg/javax/sql/rowset/serial/mkfile+17−0
@@ -0,0 +1,17 @@
1+<../../../../../../mkconfig
2+
3+TARG=\
4+ SerialArray.dis\
5+ SerialBlob.dis\
6+ SerialClob.dis\
7+ SerialDatalink.dis\
8+ SerialException.dis\
9+ SerialJavaObject.dis\
10+ SerialRef.dis\
11+ SerialStruct.dis\
12+ SQLInputImpl.dis\
13+ SQLOutputImpl.dis\
14+
15+DISBIN=$ROOT/java/dis/java/java/javax/sql/rowset/serial
16+
17+<$ROOT/mkfiles/mkjava
java/pkg/javax/sql/rowset/serial/package.html+239−0
@@ -0,0 +1,239 @@
1+<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
2+<html>
3+<head>
4+
5+ <meta http-equiv="Content-Type"
6+ content="text/html; charset=iso-8859-1">
7+
8+ <meta name="GENERATOR"
9+ content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
10+<!--
11+Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
12+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
13+
14+This code is free software; you can redistribute it and/or modify it
15+under the terms of the GNU General Public License version 2 only, as
16+published by the Free Software Foundation. Oracle designates this
17+particular file as subject to the "Classpath" exception as provided
18+by Oracle in the LICENSE file that accompanied this code.
19+
20+This code is distributed in the hope that it will be useful, but WITHOUT
21+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
22+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
23+version 2 for more details (a copy is included in the LICENSE file that
24+accompanied this code).
25+
26+You should have received a copy of the GNU General Public License version
27+2 along with this work; if not, write to the Free Software Foundation,
28+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
29+
30+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
31+or visit www.oracle.com if you need additional information or have any
32+questions.
33+-->
34+<title>javax.sql.rowset.serial</title>
35+</head>
36+<body bgcolor="#ffffff">
37+Provides utility classes to allow serializable mappings between SQL types
38+and data types in the Java programming language.
39+<p> Standard JDBC <code>RowSet</code> implementations may use these utility
40+classes to
41+assist in the serialization of disconnected <code>RowSet</code> objects.
42+This is useful
43+when transmitting a disconnected <tt>RowSet</tt> object over the wire to
44+a different VM or across layers within an application.<br>
45+</p>
46+
47+<h3>1.0 SerialArray</h3>
48+A serializable mapping in the Java programming language of an SQL ARRAY
49+value. <br>
50+<br>
51+The <tt>SerialArray </tt>class provides a constructor for creating a <tt>SerialArray
52+</tt>instance from an Array object, methods for getting the base type and
53+the SQL name for the base type, and methods for copying all or part of a
54+<tt>SerialArray </tt>object. <br>
55+
56+<h3>2.0 SerialBlob</h3>
57+A serializable mapping in the Java programming language of an SQL BLOB
58+value. <br>
59+<br>
60+The <tt>SerialBlob </tt>class provides a constructor for creating an instance
61+from a Blob object. Note that the Blob object should have brought the SQL
62+BLOB value's data over to the client before a <tt>SerialBlob </tt>object
63+is constructed from it. The data of an SQL BLOB value can be materialized
64+on the client as an array of bytes (using the method <tt>Blob.getBytes</tt>)
65+or as a stream of uninterpreted bytes (using the method <tt>Blob.getBinaryStream</tt>).
66+<br>
67+<br>
68+<tt>SerialBlob </tt>methods make it possible to make a copy of a <tt>SerialBlob
69+</tt>object as an array of bytes or as a stream. They also make it possible
70+to locate a given pattern of bytes or a <tt>Blob </tt>object within a <tt>SerialBlob
71+</tt>object. <br>
72+
73+<h3>3.0 SerialClob</h3>
74+A serializable mapping in the Java programming language of an SQL CLOB
75+value. <br>
76+<br>
77+The <tt>SerialClob </tt>class provides a constructor for creating an instance
78+from a <tt>Clob </tt>object. Note that the <tt>Clob </tt>object should have
79+brought the SQL CLOB value's data over to the client before a <tt>SerialClob
80+</tt>object is constructed from it. The data of an SQL CLOB value can be
81+materialized on the client as a stream of Unicode characters. <br>
82+<br>
83+<tt>SerialClob </tt>methods make it possible to get a substring from a
84+<tt>SerialClob </tt>object or to locate the start of a pattern of characters.
85+<br>
86+
87+<h3>5.0 SerialDatalink</h3>
88+A serializable mapping in the Java programming language of an SQL DATALINK
89+value. A DATALINK value references a file outside of the underlying data source
90+that the the originating data source manages. <br>
91+<br>
92+<code>RowSet</code> implementations can use the method <tt>RowSet.getURL() </tt>to retrieve
93+a <code>java.net.URL</code> object, which can be used to manipulate the external data.
94+<br>
95+<br>
96+&nbsp;&nbsp;<tt>&nbsp;&nbsp;&nbsp; java.net.URL url = rowset.getURL(1);</tt><br>
97+
98+<h3>6.0 SerialJavaObject</h3>
99+A serializable mapping in the Java programming language of an SQL JAVA_OBJECT
100+value. Assuming the Java object instance implements the Serializable interface,
101+this simply wraps the serialization process. <br>
102+<br>
103+If however, the serialization is not possible in the case where the Java
104+object is not immediately serializable, this class will attempt to serialize
105+all non static members to permit the object instance state to be serialized.
106+Static or transient fields cannot be serialized and attempting to do so
107+will result in a <tt>SerialException </tt>being thrown. <br>
108+
109+<h3>7.0 SerialRef</h3>
110+A serializable mapping between the SQL REF type and the Java programming
111+language. <br>
112+<br>
113+The <tt>SerialRef </tt>class provides a constructor for creating a <tt>SerialRef
114+</tt>instance from a <tt>Ref</tt> type and provides methods for getting
115+and setting the <tt>Ref</tt> object type. <br>
116+
117+<h3>8.0 SerialStruct</h3>
118+A serializable mapping in the Java programming language of an SQL structured
119+type. Each attribute that is not already serializable is mapped to a serializable
120+form, and if an attribute is itself a structured type, each of its attributes
121+that is not already serializable is mapped to a serializable form. <br>
122+<br>
123+In addition, if a <code>Map</code> object is passed to one of the constructors or
124+to the method <code>getAttributes</code>, the structured type is custom mapped
125+according to the mapping specified in the <code>Map</code> object.
126+ <br>
127+ The <tt>SerialStruct </tt>class provides a constructor for creating an
128+instance from a <tt>Struct</tt> object, a method for retrieving the SQL
129+type name of the SQL structured type in the database, and methods for retrieving
130+its attribute values. <br>
131+
132+<h3>9.0 SQLInputImpl</h3>
133+ An input stream used for custom mapping user-defined types (UDTs). An
134+ <tt>SQLInputImpl</tt> object is an input stream that contains a stream of
135+ values that are
136+the attributes of a UDT. This class is used by the driver behind the scenes
137+when the method <tt>getObject</tt> is called on an SQL structured or distinct
138+type that has a custom mapping; a programmer never invokes <tt>SQLInputImpl
139+</tt> methods directly. <br>
140+ <br>
141+ The <tt>SQLInputImpl</tt> class provides a set of reader methods
142+ analogous to the <tt>ResultSet</tt> getter methods. These methods make it
143+ possible to read the values in an <tt>SQLInputImpl</tt> object. The method
144+<code>wasNull</code> is used to determine whether the the last value read was SQL NULL.
145+ <br>
146+ <br>
147+ When a constructor or getter method that takes a <code>Map</code> object is called,
148+the JDBC driver calls the method
149+<tt>SQLData.getSQLType</tt> to determine the SQL type of the UDT being custom
150+mapped. The driver creates an instance of <code>SQLInputImpl</code>, populating it with
151+the attributes of the UDT. The driver then passes the input stream to the
152+method <tt>SQLData.readSQL</tt>, which in turn calls the <tt>SQLInputImpl</tt>
153+methods to read the attributes from the input stream. <br>
154+
155+<h3>10.0 SQLOutputImpl</h3>
156+ The output stream for writing the attributes of a custom mapped user-defined
157+ type (UDT) back to the database. The driver uses this interface internally,
158+ and its methods are never directly invoked by an application programmer.
159+<br>
160+ <br>
161+ When an application calls the method <tt>PreparedStatement.setObject, </tt>the
162+ driver checks to see whether the value to be written is a UDT with a custom
163+ mapping. If it is, there will be an entry in a type map containing the Class
164+ object for the class that implements <tt>SQLData </tt>for this UDT. If the
165+ value to be written is an instance of <tt>SQLData</tt>, the driver will
166+create an instance of <code>SQLOutputImpl</code> and pass it to the method
167+<tt>SQLData.writeSQL</tt>.
168+ The method <code>writeSQL</code> in turn calls the appropriate <tt>SQLOutputImpl</tt>
169+writer methods to write data from the <code>SQLData</code> object to the
170+<code>SQLOutputImpl</code>
171+output stream as the representation of an SQL user-defined type.
172+
173+<h3>Custom Mapping</h3>
174+The JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT
175+type to the Java programming language. Typically, a structured type is mapped
176+to a class, and its attributes are mapped to fields in the class.
177+(A DISTINCT type can thought of as having one attribute.) However, there are
178+many other possibilities, and there may be any number of different mappings.
179+<P>
180+A programmer defines the mapping by implementing the interface <code>SQLData</code>.
181+For example, if an SQL structured type named AUTHORS has the attributes NAME,
182+TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The
183+Authors class could have the fields name, title, and publisher, to which the
184+attributes of AUTHORS are mapped. In such a case, the implementation of
185+<code>SQLData</code> could look like the following:
186+<PRE>
187+ public class Authors implements SQLData {
188+ public String name;
189+ public String title;
190+ public String publisher;
191+
192+ private String sql_type;
193+ public String getSQLTypeName() {
194+ return sql_type;
195+ }
196+
197+ public void readSQL(SQLInput stream, String type)
198+ throws SQLException {
199+ sql_type = type;
200+ name = stream.readString();
201+ title = stream.readString();
202+ publisher = stream.readString();
203+ }
204+
205+ public void writeSQL(SQLOutput stream) throws SQLException {
206+ stream.writeString(name);
207+ stream.writeString(title);
208+ stream.writeString(publisher);
209+ }
210+ }
211+</PRE>
212+
213+A <code>java.util.Map</code> object is used to associate the SQL structured
214+type with its mapping to the class <code>Authors</code>. The following code fragment shows
215+how a <code>Map</code> object might be created and given an entry associating
216+<code>AUTHORS</code> and <code>Authors</code>.
217+<PRE>
218+ java.util.Map map = new java.util.HashMap();
219+ map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
220+</PRE>
221+
222+The <code>Map</code> object <i>map</i> now contains an entry with the
223+fully qualified name of the SQL structured type and the <code>Class</code>
224+ object for the class <code>Authors</code>. It can be passed to a method
225+to tell the driver how to map <code>AUTHORS</code> to <code>Authors</code>.
226+<P>
227+For a disconnected <code>RowSet</code> object, custom mapping can be done
228+only when a <code>Map</code> object is passed to the method or constructor
229+that will be doing the custom mapping. The situation is different for
230+connected <code>RowSet</code> objects because they maintain a connection
231+with the data source. A method that does custom mapping and is called by
232+a disconnected <code>RowSet</code> object may use the <code>Map</code>
233+object that is associated with the <code>Connection</code> object being
234+used. So, in other words, if no map is specified, the connection's type
235+map can be used by default.
236+
237+<br>
238+</body>
239+</html>
java/pkg/javax/sql/rowset/spi/ProviderImpl.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncFactory$1.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncFactory$SyncFactoryHolder.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncFactory.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncFactory.java+934−0
@@ -0,0 +1,934 @@
1+/*
2+ * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.spi;
27+
28+import java.util.logging.*;
29+import java.util.*;
30+
31+import java.sql.*;
32+import javax.sql.*;
33+
34+import java.io.FileInputStream;
35+import java.io.InputStream;
36+import java.io.IOException;
37+import java.io.FileNotFoundException;
38+
39+import javax.naming.*;
40+
41+/**
42+ * The Service Provider Interface (SPI) mechanism that generates <code>SyncProvider</code>
43+ * instances to be used by disconnected <code>RowSet</code> objects.
44+ * The <code>SyncProvider</code> instances in turn provide the
45+ * <code>javax.sql.RowSetReader</code> object the <code>RowSet</code> object
46+ * needs to populate itself with data and the
47+ * <code>javax.sql.RowSetWriter</code> object it needs to
48+ * propagate changes to its
49+ * data back to the underlying data source.
50+ * <P>
51+ * Because the methods in the <code>SyncFactory</code> class are all static,
52+ * there is only one <code>SyncFactory</code> object
53+ * per Java VM at any one time. This ensures that there is a single source from which a
54+ * <code>RowSet</code> implementation can obtain its <code>SyncProvider</code>
55+ * implementation.
56+ * <p>
57+ * <h3>1.0 Overview</h3>
58+ * The <code>SyncFactory</code> class provides an internal registry of available
59+ * synchronization provider implementations (<code>SyncProvider</code> objects).
60+ * This registry may be queried to determine which
61+ * synchronization providers are available.
62+ * The following line of code gets an enumeration of the providers currently registered.
63+ * <PRE>
64+ * java.util.Enumeration e = SyncFactory.getRegisteredProviders();
65+ * </PRE>
66+ * All standard <code>RowSet</code> implementations must provide at least two providers:
67+ * <UL>
68+ * <LI>an optimistic provider for use with a <code>CachedRowSet</code> implementation
69+ * or an implementation derived from it
70+ * <LI>an XML provider, which is used for reading and writing XML, such as with
71+ * <code>WebRowSet</code> objects
72+ * </UL>
73+ * Note that the JDBC RowSet Implementations include the <code>SyncProvider</code>
74+ * implemtations <code>RIOptimisticProvider</code> and <code>RIXmlProvider</code>,
75+ * which satisfy this requirement.
76+ * <P>
77+ * The <code>SyncFactory</code> class provides accessor methods to assist
78+ * applications in determining which synchronization providers are currently
79+ * registered with the <code>SyncFactory</code>.
80+ * <p>
81+ * Other methods let <code>RowSet</code> persistence providers be
82+ * registered or de-registered with the factory mechanism. This
83+ * allows additional synchronization provider implementations to be made
84+ * available to <code>RowSet</code> objects at run time.
85+ * <p>
86+ * Applications can apply a degree of filtering to determine the level of
87+ * synchronization that a <code>SyncProvider</code> implementation offers.
88+ * The following criteria determine whether a provider is
89+ * made available to a <code>RowSet</code> object:
90+ * <ol>
91+ * <li>If a particular provider is specified by a <code>RowSet</code> object, and
92+ * the <code>SyncFactory</code> does not contain a reference to this provider,
93+ * a <code>SyncFactoryException</code> is thrown stating that the synchronization
94+ * provider could not be found.
95+ * <p>
96+ * <li>If a <code>RowSet</code> implementation is instantiated with a specified
97+ * provider and the specified provider has been properly registered, the
98+ * requested provider is supplied. Otherwise a <code>SyncFactoryException</code>
99+ * is thrown.
100+ * <p>
101+ * <li>If a <code>RowSet</code> object does not specify a
102+ * <code>SyncProvider</code> implementation and no additional
103+ * <code>SyncProvider</code> implementations are available, the reference
104+ * implementation providers are supplied.
105+ * </ol>
106+ * <h3>2.0 Registering <code>SyncProvider</code> Implementations</h3>
107+ * <p>
108+ * Both vendors and developers can register <code>SyncProvider</code>
109+ * implementations using one of the following mechanisms.
110+ * <ul>
111+ * <LI><B>Using the command line</B><BR>
112+ * The name of the provider is supplied on the command line, which will add
113+ * the provider to the system properties.
114+ * For example:
115+ * <PRE>
116+ * -Drowset.provider.classname=com.fred.providers.HighAvailabilityProvider
117+ * </PRE>
118+ * <li><b>Using the Standard Properties File</b><BR>
119+ * The reference implementation is targeted
120+ * to ship with J2SE 1.5, which will include an additional resource file
121+ * that may be edited by hand. Here is an example of the properties file
122+ * included in the reference implementation:
123+ * <PRE>
124+ * #Default JDBC RowSet sync providers listing
125+ * #
126+ *
127+ * # Optimistic synchronization provider
128+ * rowset.provider.classname.0=com.sun.rowset.providers.RIOptimisticProvider
129+ * rowset.provider.vendor.0=Oracle Corporation
130+ * rowset.provider.version.0=1.0
131+ *
132+ * # XML Provider using standard XML schema
133+ * rowset.provider.classname.1=com.sun.rowset.providers.RIXMLProvider
134+ * rowset.provider.vendor.1=Oracle Corporation
135+ * rowset.provider.version.1=1.0
136+ * </PRE>
137+ * The <code>SyncFactory</code> checks this file and registers the
138+ * <code>SyncProvider</code> implementations that it contains. A
139+ * developer or vendor can add other implementations to this file.
140+ * For example, here is a possible addition:
141+ * <PRE>
142+ * rowset.provider.classname.2=com.fred.providers.HighAvailabilityProvider
143+ * rowset.provider.vendor.2=Fred, Inc.
144+ * rowset.provider.version.2=1.0
145+ * </PRE>
146+ * <p>
147+ * <li><b>Using a JNDI Context</b><BR>
148+ * Available providers can be registered on a JNDI
149+ * context, and the <code>SyncFactory</code> will attempt to load
150+ * <code>SyncProvider</code> implementations from that JNDI context.
151+ * For example, the following code fragment registers a provider implementation
152+ * on a JNDI context. This is something a deployer would normally do. In this
153+ * example, <code>MyProvider</code> is being registered on a CosNaming
154+ * namespace, which is the namespace used by J2EE resources.
155+ * <PRE>
156+ * import javax.naming.*;
157+ *
158+ * Hashtable svrEnv = new Hashtable();
159+ * srvEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");
160+ *
161+ * Context ctx = new InitialContext(svrEnv);
162+ * com.fred.providers.MyProvider = new MyProvider();
163+ * ctx.rebind("providers/MyProvider", syncProvider);
164+ * </PRE>
165+ * </ul>
166+ * Next, an application will register the JNDI context with the
167+ * <code>SyncFactory</code> instance. This allows the <code>SyncFactory</code>
168+ * to browse within the JNDI context looking for <code>SyncProvider</code>
169+ * implementations.
170+ * <PRE>
171+ * Hashtable appEnv = new Hashtable();
172+ * appEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");
173+ * appEnv.put(Context.PROVIDER_URL, "iiop://hostname/providers");
174+ * Context ctx = new InitialContext(appEnv);
175+ *
176+ * SyncFactory.registerJNDIContext(ctx);
177+ * </PRE>
178+ * If a <code>RowSet</code> object attempts to obtain a <code>MyProvider</code>
179+ * object, the <code>SyncFactory</code> will try to locate it. First it searches
180+ * for it in the system properties, then it looks in the resource files, and
181+ * finally it checks the JNDI context that has been set. The <code>SyncFactory</code>
182+ * instance verifies that the requested provider is a valid extension of the
183+ * <code>SyncProvider</code> abstract class and then gives it to the
184+ * <code>RowSet</code> object. In the following code fragment, a new
185+ * <code>CachedRowSet</code> object is created and initialized with
186+ * <i>env</i>, which contains the binding to <code>MyProvider</code>.
187+ * <PRE>
188+ * Hashtable env = new Hashtable();
189+ * env.put(SyncFactory.ROWSET_SYNC_PROVIDER, "com.fred.providers.MyProvider");
190+ * CachedRowSet crs = new com.sun.rowset.CachedRowSetImpl(env);
191+ * </PRE>
192+ * Further details on these mechanisms are available in the
193+ * <code>javax.sql.rowset.spi</code> package specification.
194+ *
195+ * @author Jonathan Bruce
196+ * @see javax.sql.rowset.spi.SyncProvider
197+ * @see javax.sql.rowset.spi.SyncFactoryException
198+ */
199+public class SyncFactory {
200+
201+ /**
202+ * Creates a new <code>SyncFactory</code> object, which is the singleton
203+ * instance.
204+ * Having a private constructor guarantees that no more than
205+ * one <code>SyncProvider</code> object can exist at a time.
206+ */
207+ private SyncFactory() {
208+ }
209+
210+ /**
211+ * The standard property-id for a synchronization provider implementation
212+ * name.
213+ */
214+ public static final String ROWSET_SYNC_PROVIDER =
215+ "rowset.provider.classname";
216+ /**
217+ * The standard property-id for a synchronization provider implementation
218+ * vendor name.
219+ */
220+ public static final String ROWSET_SYNC_VENDOR =
221+ "rowset.provider.vendor";
222+ /**
223+ * The standard property-id for a synchronization provider implementation
224+ * version tag.
225+ */
226+ public static final String ROWSET_SYNC_PROVIDER_VERSION =
227+ "rowset.provider.version";
228+ /**
229+ * The standard resource file name.
230+ */
231+ private static String ROWSET_PROPERTIES = "rowset.properties";
232+ /**
233+ * The RI Optimistic Provider.
234+ */
235+ private static String default_provider =
236+ "com.sun.rowset.providers.RIOptimisticProvider";
237+ /**
238+ * Permission required to invoke setJNDIContext and setLogger
239+ */
240+ private static final SQLPermission SET_SYNCFACTORY_PERMISSION =
241+ new SQLPermission("setSyncFactory");
242+ /**
243+ * The initial JNDI context where <code>SyncProvider</code> implementations can
244+ * be stored and from which they can be invoked.
245+ */
246+ private static Context ic;
247+ /**
248+ * The <code>Logger</code> object to be used by the <code>SyncFactory</code>.
249+ */
250+ private static volatile Logger rsLogger;
251+ /**
252+ *
253+ */
254+ private static Level rsLevel;
255+ /**
256+ * The registry of available <code>SyncProvider</code> implementations.
257+ * See section 2.0 of the class comment for <code>SyncFactory</code> for an
258+ * explanation of how a provider can be added to this registry.
259+ */
260+ private static Hashtable implementations;
261+ /**
262+ * Internal sync object used to maintain the SPI as a singleton
263+ */
264+ private static Object logSync = new Object();
265+ /**
266+ * Internal PrintWriter field for logging facility
267+ */
268+ private static java.io.PrintWriter logWriter = null;
269+
270+ /**
271+ * Adds the the given synchronization provider to the factory register. Guidelines
272+ * are provided in the <code>SyncProvider</code> specification for the
273+ * required naming conventions for <code>SyncProvider</code>
274+ * implementations.
275+ * <p>
276+ * Synchronization providers bound to a JNDI context can be
277+ * registered by binding a SyncProvider instance to a JNDI namespace.
278+ * <ul>
279+ * <pre>
280+ * SyncProvider p = new MySyncProvider();
281+ * InitialContext ic = new InitialContext();
282+ * ic.bind ("jdbc/rowset/MySyncProvider", p);
283+ * </pre>
284+ * </ul>
285+ * Furthermore, an initial JNDI context should be set with the
286+ * <code>SyncFactory</code> using the <code>setJNDIContext</code> method.
287+ * The <code>SyncFactory</code> leverages this context to search for
288+ * available <code>SyncProvider</code> objects bound to the JNDI
289+ * context and its child nodes.
290+ *
291+ * @param providerID A <code>String</code> object with the unique ID of the
292+ * synchronization provider being registered
293+ * @throws SyncFactoryException if an attempt is made to supply an empty
294+ * or null provider name
295+ * @see #setJNDIContext
296+ */
297+ public static synchronized void registerProvider(String providerID)
298+ throws SyncFactoryException {
299+
300+ ProviderImpl impl = new ProviderImpl();
301+ impl.setClassname(providerID);
302+ initMapIfNecessary();
303+ implementations.put(providerID, impl);
304+
305+ }
306+
307+ /**
308+ * Returns the <code>SyncFactory</code> singleton.
309+ *
310+ * @return the <code>SyncFactory</code> instance
311+ */
312+ public static SyncFactory getSyncFactory() {
313+ /*
314+ * Using Initialization on Demand Holder idiom as
315+ * Effective Java 2nd Edition,ITEM 71, indicates it is more performant
316+ * than the Double-Check Locking idiom.
317+ */
318+ return SyncFactoryHolder.factory;
319+ }
320+
321+ /**
322+ * Removes the designated currently registered synchronization provider from the
323+ * Factory SPI register.
324+ *
325+ * @param providerID The unique-id of the synchronization provider
326+ * @throws SyncFactoryException If an attempt is made to
327+ * unregister a SyncProvider implementation that was not registered.
328+ */
329+ public static synchronized void unregisterProvider(String providerID)
330+ throws SyncFactoryException {
331+ initMapIfNecessary();
332+ if (implementations.containsKey(providerID)) {
333+ implementations.remove(providerID);
334+ }
335+ }
336+ private static String colon = ":";
337+ private static String strFileSep = "/";
338+
339+ private static synchronized void initMapIfNecessary() throws SyncFactoryException {
340+
341+ // Local implementation class names and keys from Properties
342+ // file, translate names into Class objects using Class.forName
343+ // and store mappings
344+ Properties properties = new Properties();
345+
346+ if (implementations == null) {
347+ implementations = new Hashtable();
348+
349+ try {
350+
351+ // check if user is supplying his Synchronisation Provider
352+ // Implementation if not using Oracle's implementation.
353+ // properties.load(new FileInputStream(ROWSET_PROPERTIES));
354+
355+ // The rowset.properties needs to be in jdk/jre/lib when
356+ // integrated with jdk.
357+ // else it should be picked from -D option from command line.
358+
359+ // -Drowset.properties will add to standard properties. Similar
360+ // keys will over-write
361+
362+ /*
363+ * Dependent on application
364+ */
365+ String strRowsetProperties = System.getProperty("rowset.properties");
366+ if (strRowsetProperties != null) {
367+ // Load user's implementation of SyncProvider
368+ // here. -Drowset.properties=/abc/def/pqr.txt
369+ ROWSET_PROPERTIES = strRowsetProperties;
370+ try (FileInputStream fis = new FileInputStream(ROWSET_PROPERTIES)) {
371+ properties.load(fis);
372+ }
373+ parseProperties(properties);
374+ }
375+
376+ /*
377+ * Always available
378+ */
379+ ROWSET_PROPERTIES = "javax" + strFileSep + "sql" +
380+ strFileSep + "rowset" + strFileSep +
381+ "rowset.properties";
382+
383+ ClassLoader cl = Thread.currentThread().getContextClassLoader();
384+
385+ try (InputStream stream =
386+ (cl == null) ? ClassLoader.getSystemResourceAsStream(ROWSET_PROPERTIES)
387+ : cl.getResourceAsStream(ROWSET_PROPERTIES)) {
388+ if (stream == null) {
389+ throw new SyncFactoryException(
390+ "Resource " + ROWSET_PROPERTIES + " not found");
391+ }
392+ properties.load(stream);
393+ }
394+
395+ parseProperties(properties);
396+
397+ // removed else, has properties should sum together
398+
399+ } catch (FileNotFoundException e) {
400+ throw new SyncFactoryException("Cannot locate properties file: " + e);
401+ } catch (IOException e) {
402+ throw new SyncFactoryException("IOException: " + e);
403+ }
404+
405+ /*
406+ * Now deal with -Drowset.provider.classname
407+ * load additional properties from -D command line
408+ */
409+ properties.clear();
410+ String providerImpls = System.getProperty(ROWSET_SYNC_PROVIDER);
411+
412+ if (providerImpls != null) {
413+ int i = 0;
414+ if (providerImpls.indexOf(colon) > 0) {
415+ StringTokenizer tokenizer = new StringTokenizer(providerImpls, colon);
416+ while (tokenizer.hasMoreElements()) {
417+ properties.put(ROWSET_SYNC_PROVIDER + "." + i, tokenizer.nextToken());
418+ i++;
419+ }
420+ } else {
421+ properties.put(ROWSET_SYNC_PROVIDER, providerImpls);
422+ }
423+ parseProperties(properties);
424+ }
425+ }
426+ }
427+
428+ /**
429+ * The internal debug switch.
430+ */
431+ private static boolean debug = false;
432+ /**
433+ * Internal registry count for the number of providers contained in the
434+ * registry.
435+ */
436+ private static int providerImplIndex = 0;
437+
438+ /**
439+ * Internal handler for all standard property parsing. Parses standard
440+ * ROWSET properties and stores lazy references into the the internal registry.
441+ */
442+ private static void parseProperties(Properties p) {
443+
444+ ProviderImpl impl = null;
445+ String key = null;
446+ String[] propertyNames = null;
447+
448+ for (Enumeration e = p.propertyNames(); e.hasMoreElements();) {
449+
450+ String str = (String) e.nextElement();
451+
452+ int w = str.length();
453+
454+ if (str.startsWith(SyncFactory.ROWSET_SYNC_PROVIDER)) {
455+
456+ impl = new ProviderImpl();
457+ impl.setIndex(providerImplIndex++);
458+
459+ if (w == (SyncFactory.ROWSET_SYNC_PROVIDER).length()) {
460+ // no property index has been set.
461+ propertyNames = getPropertyNames(false);
462+ } else {
463+ // property index has been set.
464+ propertyNames = getPropertyNames(true, str.substring(w - 1));
465+ }
466+
467+ key = p.getProperty(propertyNames[0]);
468+ impl.setClassname(key);
469+ impl.setVendor(p.getProperty(propertyNames[1]));
470+ impl.setVersion(p.getProperty(propertyNames[2]));
471+ implementations.put(key, impl);
472+ }
473+ }
474+ }
475+
476+ /**
477+ * Used by the parseProperties methods to disassemble each property tuple.
478+ */
479+ private static String[] getPropertyNames(boolean append) {
480+ return getPropertyNames(append, null);
481+ }
482+
483+ /**
484+ * Disassembles each property and its associated value. Also handles
485+ * overloaded property names that contain indexes.
486+ */
487+ private static String[] getPropertyNames(boolean append,
488+ String propertyIndex) {
489+ String dot = ".";
490+ String[] propertyNames =
491+ new String[]{SyncFactory.ROWSET_SYNC_PROVIDER,
492+ SyncFactory.ROWSET_SYNC_VENDOR,
493+ SyncFactory.ROWSET_SYNC_PROVIDER_VERSION};
494+ if (append) {
495+ for (int i = 0; i < propertyNames.length; i++) {
496+ propertyNames[i] = propertyNames[i] +
497+ dot +
498+ propertyIndex;
499+ }
500+ return propertyNames;
501+ } else {
502+ return propertyNames;
503+ }
504+ }
505+
506+ /**
507+ * Internal debug method that outputs the registry contents.
508+ */
509+ private static void showImpl(ProviderImpl impl) {
510+ System.out.println("Provider implementation:");
511+ System.out.println("Classname: " + impl.getClassname());
512+ System.out.println("Vendor: " + impl.getVendor());
513+ System.out.println("Version: " + impl.getVersion());
514+ System.out.println("Impl index: " + impl.getIndex());
515+ }
516+
517+ /**
518+ * Returns the <code>SyncProvider</code> instance identified by <i>providerID</i>.
519+ *
520+ * @param providerID the unique identifier of the provider
521+ * @return a <code>SyncProvider</code> implementation
522+ * @throws SyncFactoryException If the SyncProvider cannot be found,
523+ * the providerID is {@code null}, or
524+ * some error was encountered when trying to invoke this provider.
525+ */
526+ public static SyncProvider getInstance(String providerID)
527+ throws SyncFactoryException {
528+
529+ if(providerID == null) {
530+ throw new SyncFactoryException("The providerID cannot be null");
531+ }
532+
533+ initMapIfNecessary(); // populate HashTable
534+ initJNDIContext(); // check JNDI context for any additional bindings
535+
536+ ProviderImpl impl = (ProviderImpl) implementations.get(providerID);
537+
538+ if (impl == null) {
539+ // Requested SyncProvider is unavailable. Return default provider.
540+ return new com.sun.rowset.providers.RIOptimisticProvider();
541+ }
542+
543+ // Attempt to invoke classname from registered SyncProvider list
544+ Class c = null;
545+ try {
546+ ClassLoader cl = Thread.currentThread().getContextClassLoader();
547+
548+ /**
549+ * The SyncProvider implementation of the user will be in
550+ * the classpath. We need to find the ClassLoader which loads
551+ * this SyncFactory and try to laod the SyncProvider class from
552+ * there.
553+ **/
554+ c = Class.forName(providerID, true, cl);
555+
556+ if (c != null) {
557+ return (SyncProvider) c.newInstance();
558+ } else {
559+ return new com.sun.rowset.providers.RIOptimisticProvider();
560+ }
561+
562+ } catch (IllegalAccessException e) {
563+ throw new SyncFactoryException("IllegalAccessException: " + e.getMessage());
564+ } catch (InstantiationException e) {
565+ throw new SyncFactoryException("InstantiationException: " + e.getMessage());
566+ } catch (ClassNotFoundException e) {
567+ throw new SyncFactoryException("ClassNotFoundException: " + e.getMessage());
568+ }
569+ }
570+
571+ /**
572+ * Returns an Enumeration of currently registered synchronization
573+ * providers. A <code>RowSet</code> implementation may use any provider in
574+ * the enumeration as its <code>SyncProvider</code> object.
575+ * <p>
576+ * At a minimum, the reference synchronization provider allowing
577+ * RowSet content data to be stored using a JDBC driver should be
578+ * possible.
579+ *
580+ * @return Enumeration A enumeration of available synchronization
581+ * providers that are registered with this Factory
582+ */
583+ public static Enumeration<SyncProvider> getRegisteredProviders()
584+ throws SyncFactoryException {
585+ initMapIfNecessary();
586+ // return a collection of classnames
587+ // of type SyncProvider
588+ return implementations.elements();
589+ }
590+
591+ /**
592+ * Sets the logging object to be used by the <code>SyncProvider</code>
593+ * implementation provided by the <code>SyncFactory</code>. All
594+ * <code>SyncProvider</code> implementations can log their events to
595+ * this object and the application can retrieve a handle to this
596+ * object using the <code>getLogger</code> method.
597+ * <p>
598+ * This method checks to see that there is an {@code SQLPermission}
599+ * object which grants the permission {@code setSyncFactory}
600+ * before allowing the method to succeed. If a
601+ * {@code SecurityManager} exists and its
602+ * {@code checkPermission} method denies calling {@code setLogger},
603+ * this method throws a
604+ * {@code java.lang.SecurityException}.
605+ *
606+ * @param logger A Logger object instance
607+ * @throws java.lang.SecurityException if a security manager exists and its
608+ * {@code checkPermission} method denies calling {@code setLogger}
609+ * @throws NullPointerException if the logger is null
610+ * @see SecurityManager#checkPermission
611+ */
612+ public static void setLogger(Logger logger) {
613+
614+ SecurityManager sec = System.getSecurityManager();
615+ if (sec != null) {
616+ sec.checkPermission(SET_SYNCFACTORY_PERMISSION);
617+ }
618+
619+ if(logger == null){
620+ throw new NullPointerException("You must provide a Logger");
621+ }
622+ rsLogger = logger;
623+ }
624+
625+ /**
626+ * Sets the logging object that is used by <code>SyncProvider</code>
627+ * implementations provided by the <code>SyncFactory</code> SPI. All
628+ * <code>SyncProvider</code> implementations can log their events
629+ * to this object and the application can retrieve a handle to this
630+ * object using the <code>getLogger</code> method.
631+ * <p>
632+ * This method checks to see that there is an {@code SQLPermission}
633+ * object which grants the permission {@code setSyncFactory}
634+ * before allowing the method to succeed. If a
635+ * {@code SecurityManager} exists and its
636+ * {@code checkPermission} method denies calling {@code setLogger},
637+ * this method throws a
638+ * {@code java.lang.SecurityException}.
639+ *
640+ * @param logger a Logger object instance
641+ * @param level a Level object instance indicating the degree of logging
642+ * required
643+ * @throws java.lang.SecurityException if a security manager exists and its
644+ * {@code checkPermission} method denies calling {@code setLogger}
645+ * @throws java.util.logging.LoggingPermission if a security manager exists and its
646+ * {@code checkPermission} method denies calling {@code setLevel}
647+ * @throws NullPointerException if the logger is null
648+ * @see SecurityManager#checkPermission
649+ * @see LoggingPermission
650+ */
651+ public static void setLogger(Logger logger, Level level) {
652+ // singleton
653+ SecurityManager sec = System.getSecurityManager();
654+ if (sec != null) {
655+ sec.checkPermission(SET_SYNCFACTORY_PERMISSION);
656+ }
657+
658+ if(logger == null){
659+ throw new NullPointerException("You must provide a Logger");
660+ }
661+ logger.setLevel(level);
662+ rsLogger = logger;
663+ }
664+
665+ /**
666+ * Returns the logging object for applications to retrieve
667+ * synchronization events posted by SyncProvider implementations.
668+ *
669+ * @throws SyncFactoryException if no logging object has been set.
670+ */
671+ public static Logger getLogger() throws SyncFactoryException {
672+
673+ Logger result = rsLogger;
674+ // only one logger per session
675+ if (result == null) {
676+ throw new SyncFactoryException("(SyncFactory) : No logger has been set");
677+ }
678+
679+ return result;
680+ }
681+
682+ /**
683+ * Sets the initial JNDI context from which SyncProvider implementations
684+ * can be retrieved from a JNDI namespace
685+ * <p>
686+ * This method checks to see that there is an {@code SQLPermission}
687+ * object which grants the permission {@code setSyncFactory}
688+ * before allowing the method to succeed. If a
689+ * {@code SecurityManager} exists and its
690+ * {@code checkPermission} method denies calling {@code setJNDIContext},
691+ * this method throws a
692+ * {@code java.lang.SecurityException}.
693+ *
694+ * @param ctx a valid JNDI context
695+ * @throws SyncFactoryException if the supplied JNDI context is null
696+ * @throws java.lang.SecurityException if a security manager exists and its
697+ * {@code checkPermission} method denies calling {@code setJNDIContext}
698+ * @see SecurityManager#checkPermission
699+ */
700+ public static synchronized void setJNDIContext(javax.naming.Context ctx)
701+ throws SyncFactoryException {
702+ SecurityManager sec = System.getSecurityManager();
703+ if (sec != null) {
704+ sec.checkPermission(SET_SYNCFACTORY_PERMISSION);
705+ }
706+ if (ctx == null) {
707+ throw new SyncFactoryException("Invalid JNDI context supplied");
708+ }
709+ ic = ctx;
710+ }
711+
712+ /**
713+ * Controls JNDI context initialization.
714+ *
715+ * @throws SyncFactoryException if an error occurs parsing the JNDI context
716+ */
717+ private static synchronized void initJNDIContext() throws SyncFactoryException {
718+
719+ if ((ic != null) && (lazyJNDICtxRefresh == false)) {
720+ try {
721+ parseProperties(parseJNDIContext());
722+ lazyJNDICtxRefresh = true; // touch JNDI namespace once.
723+ } catch (NamingException e) {
724+ e.printStackTrace();
725+ throw new SyncFactoryException("SPI: NamingException: " + e.getExplanation());
726+ } catch (Exception e) {
727+ e.printStackTrace();
728+ throw new SyncFactoryException("SPI: Exception: " + e.getMessage());
729+ }
730+ }
731+ }
732+ /**
733+ * Internal switch indicating whether the JNDI namespace should be re-read.
734+ */
735+ private static boolean lazyJNDICtxRefresh = false;
736+
737+ /**
738+ * Parses the set JNDI Context and passes bindings to the enumerateBindings
739+ * method when complete.
740+ */
741+ private static Properties parseJNDIContext() throws NamingException {
742+
743+ NamingEnumeration bindings = ic.listBindings("");
744+ Properties properties = new Properties();
745+
746+ // Hunt one level below context for available SyncProvider objects
747+ enumerateBindings(bindings, properties);
748+
749+ return properties;
750+ }
751+
752+ /**
753+ * Scans each binding on JNDI context and determines if any binding is an
754+ * instance of SyncProvider, if so, add this to the registry and continue to
755+ * scan the current context using a re-entrant call to this method until all
756+ * bindings have been enumerated.
757+ */
758+ private static void enumerateBindings(NamingEnumeration bindings,
759+ Properties properties) throws NamingException {
760+
761+ boolean syncProviderObj = false; // move to parameters ?
762+
763+ try {
764+ Binding bd = null;
765+ Object elementObj = null;
766+ String element = null;
767+ while (bindings.hasMore()) {
768+ bd = (Binding) bindings.next();
769+ element = bd.getName();
770+ elementObj = bd.getObject();
771+
772+ if (!(ic.lookup(element) instanceof Context)) {
773+ // skip directories/sub-contexts
774+ if (ic.lookup(element) instanceof SyncProvider) {
775+ syncProviderObj = true;
776+ }
777+ }
778+
779+ if (syncProviderObj) {
780+ SyncProvider sync = (SyncProvider) elementObj;
781+ properties.put(SyncFactory.ROWSET_SYNC_PROVIDER,
782+ sync.getProviderID());
783+ syncProviderObj = false; // reset
784+ }
785+
786+ }
787+ } catch (javax.naming.NotContextException e) {
788+ bindings.next();
789+ // Re-entrant call into method
790+ enumerateBindings(bindings, properties);
791+ }
792+ }
793+
794+ /**
795+ * Lazy initialization Holder class used by {@code getSyncFactory}
796+ */
797+ private static class SyncFactoryHolder {
798+ static final SyncFactory factory = new SyncFactory();
799+ }
800+}
801+
802+/**
803+ * Internal class that defines the lazy reference construct for each registered
804+ * SyncProvider implementation.
805+ */
806+class ProviderImpl extends SyncProvider {
807+
808+ private String className = null;
809+ private String vendorName = null;
810+ private String ver = null;
811+ private int index;
812+
813+ public void setClassname(String classname) {
814+ className = classname;
815+ }
816+
817+ public String getClassname() {
818+ return className;
819+ }
820+
821+ public void setVendor(String vendor) {
822+ vendorName = vendor;
823+ }
824+
825+ public String getVendor() {
826+ return vendorName;
827+ }
828+
829+ public void setVersion(String providerVer) {
830+ ver = providerVer;
831+ }
832+
833+ public String getVersion() {
834+ return ver;
835+ }
836+
837+ public void setIndex(int i) {
838+ index = i;
839+ }
840+
841+ public int getIndex() {
842+ return index;
843+ }
844+
845+ public int getDataSourceLock() throws SyncProviderException {
846+
847+ int dsLock = 0;
848+ try {
849+ dsLock = SyncFactory.getInstance(className).getDataSourceLock();
850+ } catch (SyncFactoryException sfEx) {
851+
852+ throw new SyncProviderException(sfEx.getMessage());
853+ }
854+
855+ return dsLock;
856+ }
857+
858+ public int getProviderGrade() {
859+
860+ int grade = 0;
861+
862+ try {
863+ grade = SyncFactory.getInstance(className).getProviderGrade();
864+ } catch (SyncFactoryException sfEx) {
865+ //
866+ }
867+
868+ return grade;
869+ }
870+
871+ public String getProviderID() {
872+ return className;
873+ }
874+
875+ /*
876+ public javax.sql.RowSetInternal getRowSetInternal() {
877+ try
878+ {
879+ return SyncFactory.getInstance(className).getRowSetInternal();
880+ } catch(SyncFactoryException sfEx) {
881+ //
882+ }
883+ }
884+ */
885+ public javax.sql.RowSetReader getRowSetReader() {
886+
887+ RowSetReader rsReader = null;
888+
889+ try {
890+ rsReader = SyncFactory.getInstance(className).getRowSetReader();
891+ } catch (SyncFactoryException sfEx) {
892+ //
893+ }
894+
895+ return rsReader;
896+
897+ }
898+
899+ public javax.sql.RowSetWriter getRowSetWriter() {
900+
901+ RowSetWriter rsWriter = null;
902+ try {
903+ rsWriter = SyncFactory.getInstance(className).getRowSetWriter();
904+ } catch (SyncFactoryException sfEx) {
905+ //
906+ }
907+
908+ return rsWriter;
909+ }
910+
911+ public void setDataSourceLock(int param)
912+ throws SyncProviderException {
913+
914+ try {
915+ SyncFactory.getInstance(className).setDataSourceLock(param);
916+ } catch (SyncFactoryException sfEx) {
917+
918+ throw new SyncProviderException(sfEx.getMessage());
919+ }
920+ }
921+
922+ public int supportsUpdatableView() {
923+
924+ int view = 0;
925+
926+ try {
927+ view = SyncFactory.getInstance(className).supportsUpdatableView();
928+ } catch (SyncFactoryException sfEx) {
929+ //
930+ }
931+
932+ return view;
933+ }
934+}
java/pkg/javax/sql/rowset/spi/SyncFactoryException.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncFactoryException.java+58−0
@@ -0,0 +1,58 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.spi;
27+
28+import java.sql.SQLException;
29+
30+/**
31+ * Indicates an error with <code>SyncFactory</code> mechanism. A disconnected
32+ * RowSet implementation cannot be used without a <code>SyncProvider</code>
33+ * being successfully instantiated
34+ *
35+ * @author Jonathan Bruce
36+ * @see javax.sql.rowset.spi.SyncFactory
37+ * @see javax.sql.rowset.spi.SyncFactoryException
38+ */
39+public class SyncFactoryException extends java.sql.SQLException {
40+
41+ /**
42+ * Creates new <code>SyncFactoryException</code> without detail message.
43+ */
44+ public SyncFactoryException() {
45+ }
46+
47+ /**
48+ * Constructs an <code>SyncFactoryException</code> with the specified
49+ * detail message.
50+ *
51+ * @param msg the detail message.
52+ */
53+ public SyncFactoryException(String msg) {
54+ super(msg);
55+ }
56+
57+ static final long serialVersionUID = -4354595476433200352L;
58+}
java/pkg/javax/sql/rowset/spi/SyncProvider.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncProvider.java+430−0
@@ -0,0 +1,430 @@
1+/*
2+ * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.spi;
27+
28+import javax.sql.*;
29+
30+/**
31+ * The synchronization mechanism that provides reader/writer capabilities for
32+ * disconnected <code>RowSet</code> objects.
33+ * A <code>SyncProvider</code> implementation is a class that extends the
34+ * <code>SyncProvider</code> abstract class.
35+ * <P>
36+ * A <code>SyncProvider</code> implementation is
37+ * identified by a unique ID, which is its fully qualified class name.
38+ * This name must be registered with the
39+ * <code>SyncFactory</code> SPI, thus making the implementation available to
40+ * all <code>RowSet</code> implementations.
41+ * The factory mechanism in the reference implementation uses this name to instantiate
42+ * the implementation, which can then provide a <code>RowSet</code> object with its
43+ * reader (a <code>javax.sql.RowSetReader</code> object) and its writer (a
44+ * <code>javax.sql.RowSetWriter</code> object).
45+ * <P>
46+ * The Jdbc <code>RowSet</code> Implementations specification provides two
47+ * reference implementations of the <code>SyncProvider</code> abstract class:
48+ * <code>RIOptimisticProvider</code> and <code>RIXMLProvider</code>.
49+ * The <code>RIOptimisticProvider</code> can set any <code>RowSet</code>
50+ * implementation with a <code>RowSetReader</code> object and a
51+ * <code>RowSetWriter</code> object. However, only the <code>RIXMLProvider</code>
52+ * implementation can set an <code>XmlReader</code> object and an
53+ * <code>XmlWriter</code> object. A <code>WebRowSet</code> object uses the
54+ * <code>XmlReader</code> object to read data in XML format to populate itself with that
55+ * data. It uses the <code>XmlWriter</code> object to write itself to a stream or
56+ * <code>java.io.Writer</code> object in XML format.
57+ * <P>
58+ * <h3>1.0 Naming Convention for Implementations</h3>
59+ * As a guide to naming <code>SyncProvider</code>
60+ * implementations, the following should be noted:
61+ * <UL>
62+ * <li>The name for a <code>SyncProvider</code> implementation
63+ * is its fully qualified class name.
64+ * <li>It is recommended that vendors supply a
65+ * <code>SyncProvider</code> implementation in a package named <code>providers</code>.
66+ * </UL>
67+ * <p>
68+ * For instance, if a vendor named Fred, Inc. offered a
69+ * <code>SyncProvider</code> implementation, you could have the following:
70+ * <PRE>
71+ * Vendor name: Fred, Inc.
72+ * Domain name of vendor: com.fred
73+ * Package name: com.fred.providers
74+ * SyncProvider implementation class name: HighAvailabilityProvider
75+ *
76+ * Fully qualified class name of SyncProvider implementation:
77+ * com.fred.providers.HighAvailabilityProvider
78+ * </PRE>
79+ * <P>
80+ * The following line of code uses the fully qualified name to register
81+ * this implementation with the <code>SyncFactory</code> static instance.
82+ * <PRE>
83+ * SyncFactory.registerProvider(
84+ * "com.fred.providers.HighAvailabilityProvider");
85+ * </PRE>
86+ * <P>
87+ * The default <code>SyncProvider</code> object provided with the reference
88+ * implementation uses the following name:
89+ * <pre>
90+ * com.sun.rowset.providers.RIOptimisticProvider
91+ * </pre>
92+ * <p>
93+ * A vendor can register a <code>SyncProvider</code> implementation class name
94+ * with Oracle Corporation by sending email to jdbc@sun.com.
95+ * Oracle will maintain a database listing the
96+ * available <code>SyncProvider</code> implementations for use with compliant
97+ * <code>RowSet</code> implementations. This database will be similar to the
98+ * one already maintained to list available JDBC drivers.
99+ * <P>
100+ * Vendors should refer to the reference implementation synchronization
101+ * providers for additional guidance on how to implement a new
102+ * <code>SyncProvider</code> implementation.
103+ *
104+ * <h3>2.0 How a <code>RowSet</code> Object Gets Its Provider</h3>
105+ *
106+ * A disconnected <code>Rowset</code> object may get access to a
107+ * <code>SyncProvider</code> object in one of the following two ways:
108+ * <UL>
109+ * <LI>Using a constructor<BR>
110+ * <PRE>
111+ * CachedRowSet crs = new CachedRowSet(
112+ * "com.fred.providers.HighAvailabilitySyncProvider");
113+ * </PRE>
114+ * <LI>Using the <code>setSyncProvider</code> method
115+ * <PRE>
116+ * CachedRowSet crs = new CachedRowSet();
117+ * crs.setSyncProvider("com.fred.providers.HighAvailabilitySyncProvider");
118+ * </PRE>
119+
120+ * </UL>
121+ * <p>
122+ * By default, the reference implementations of the <code>RowSet</code> synchronization
123+ * providers are always available to the Java platform.
124+ * If no other pluggable synchronization providers have been correctly
125+ * registered, the <code>SyncFactory</code> will automatically generate
126+ * an instance of the default <code>SyncProvider</code> reference implementation.
127+ * Thus, in the preceding code fragment, if no implementation named
128+ * <code>com.fred.providers.HighAvailabilitySyncProvider</code> has been
129+ * registered with the <code>SyncFactory</code> instance, <i>crs</i> will be
130+ * assigned the default provider in the reference implementation, which is
131+ * <code>com.sun.rowset.providers.RIOptimisticProvider</code>.
132+ * <p>
133+ * <h3>3.0 Violations and Synchronization Issues</h3>
134+ * If an update between a disconnected <code>RowSet</code> object
135+ * and a data source violates
136+ * the original query or the underlying data source constraints, this will
137+ * result in undefined behavior for all disconnected <code>RowSet</code> implementations
138+ * and their designated <code>SyncProvider</code> implementations.
139+ * Not defining the behavior when such violations occur offers greater flexibility
140+ * for a <code>SyncProvider</code>
141+ * implementation to determine its own best course of action.
142+ * <p>
143+ * A <code>SyncProvider</code> implementation
144+ * may choose to implement a specific handler to
145+ * handle a subset of query violations.
146+ * However if an original query violation or a more general data source constraint
147+ * violation is not handled by the <code>SyncProvider</code> implementation,
148+ * all <code>SyncProvider</code>
149+ * objects must throw a <code>SyncProviderException</code>.
150+ * <p>
151+ * <h3>4.0 Updatable SQL VIEWs</h3>
152+ * It is possible for any disconnected or connected <code>RowSet</code> object to be populated
153+ * from an SQL query that is formulated originally from an SQL <code>VIEW</code>.
154+ * While in many cases it is possible for an update to be performed to an
155+ * underlying view, such an update requires additional metadata, which may vary.
156+ * The <code>SyncProvider</code> class provides two constants to indicate whether
157+ * an implementation supports updating an SQL <code>VIEW</code>.
158+ * <ul>
159+ * <li><code><b>NONUPDATABLE_VIEW_SYNC</b></code> - Indicates that a <code>SyncProvider</code>
160+ * implementation does not support synchronization with an SQL <code>VIEW</code> as the
161+ * underlying source of data for the <code>RowSet</code> object.
162+ * <li><code><b>UPDATABLE_VIEW_SYNC</b></code> - Indicates that a
163+ * <code>SyncProvider</code> implementation
164+ * supports synchronization with an SQL <code>VIEW</code> as the underlying source
165+ * of data.
166+ * </ul>
167+ * <P>
168+ * The default is for a <code>RowSet</code> object not to be updatable if it was
169+ * populated with data from an SQL <code>VIEW</code>.
170+ * <P>
171+ * <h3>5.0 <code>SyncProvider</code> Constants</h3>
172+ * The <code>SyncProvider</code> class provides three sets of constants that
173+ * are used as return values or parameters for <code>SyncProvider</code> methods.
174+ * <code>SyncProvider</code> objects may be implemented to perform synchronization
175+ * between a <code>RowSet</code> object and its underlying data source with varying
176+ * degrees of of care. The first group of constants indicate how synchronization
177+ * is handled. For example, <code>GRADE_NONE</code> indicates that a
178+ * <code>SyncProvider</code> object will not take any care to see what data is
179+ * valid and will simply write the <code>RowSet</code> data to the data source.
180+ * <code>GRADE_MODIFIED_AT_COMMIT</code> indicates that the provider will check
181+ * only modified data for validity. Other grades check all data for validity
182+ * or set locks when data is modified or loaded.
183+ * <OL>
184+ * <LI>Constants to indicate the synchronization grade of a
185+ * <code>SyncProvider</code> object
186+ * <UL>
187+ * <LI>SyncProvider.GRADE_NONE
188+ * <LI>SyncProvider.GRADE_MODIFIED_AT_COMMIT
189+ * <LI>SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
190+ * <LI>SyncProvider.GRADE_LOCK_WHEN_MODIFIED
191+ * <LI>SyncProvider.GRADE_LOCK_WHEN_LOADED
192+ * </UL>
193+ * <LI>Constants to indicate what locks are set on the data source
194+ * <UL>
195+ * <LI>SyncProvider.DATASOURCE_NO_LOCK
196+ * <LI>SyncProvider.DATASOURCE_ROW_LOCK
197+ * <LI>SyncProvider.DATASOURCE_TABLE_LOCK
198+ * <LI>SyncProvider.DATASOURCE_DB_LOCK
199+ * </UL>
200+ * <LI>Constants to indicate whether a <code>SyncProvider</code> object can
201+ * perform updates to an SQL <code>VIEW</code> <BR>
202+ * These constants are explained in the preceding section (4.0).
203+ * <UL>
204+ * <LI>SyncProvider.UPDATABLE_VIEW_SYNC
205+ * <LI>SyncProvider.NONUPDATABLE_VIEW_SYNC
206+ * </UL>
207+ * </OL>
208+ *
209+ * @author Jonathan Bruce
210+ * @see javax.sql.rowset.spi.SyncFactory
211+ * @see javax.sql.rowset.spi.SyncFactoryException
212+ */
213+public abstract class SyncProvider {
214+
215+ /**
216+ * Creates a default <code>SyncProvider</code> object.
217+ */
218+ public SyncProvider() {
219+ }
220+
221+ /**
222+ * Returns the unique identifier for this <code>SyncProvider</code> object.
223+ *
224+ * @return a <code>String</code> object with the fully qualified class name of
225+ * this <code>SyncProvider</code> object
226+ */
227+ public abstract String getProviderID();
228+
229+ /**
230+ * Returns a <code>javax.sql.RowSetReader</code> object, which can be used to
231+ * populate a <code>RowSet</code> object with data.
232+ *
233+ * @return a <code>javax.sql.RowSetReader</code> object
234+ */
235+ public abstract RowSetReader getRowSetReader();
236+
237+ /**
238+ * Returns a <code>javax.sql.RowSetWriter</code> object, which can be
239+ * used to write a <code>RowSet</code> object's data back to the
240+ * underlying data source.
241+ *
242+ * @return a <code>javax.sql.RowSetWriter</code> object
243+ */
244+ public abstract RowSetWriter getRowSetWriter();
245+
246+ /**
247+ * Returns a constant indicating the
248+ * grade of synchronization a <code>RowSet</code> object can expect from
249+ * this <code>SyncProvider</code> object.
250+ *
251+ * @return an int that is one of the following constants:
252+ * SyncProvider.GRADE_NONE,
253+ * SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT,
254+ * SyncProvider.GRADE_CHECK_ALL_AT_COMMIT,
255+ * SyncProvider.GRADE_LOCK_WHEN_MODIFIED,
256+ * SyncProvider.GRADE_LOCK_WHEN_LOADED
257+ */
258+ public abstract int getProviderGrade();
259+
260+
261+ /**
262+ * Sets a lock on the underlying data source at the level indicated by
263+ * <i>datasource_lock</i>. This should cause the
264+ * <code>SyncProvider</code> to adjust its behavior by increasing or
265+ * decreasing the level of optimism it provides for a successful
266+ * synchronization.
267+ *
268+ * @param datasource_lock one of the following constants indicating the severity
269+ * level of data source lock required:
270+ * <pre>
271+ * SyncProvider.DATASOURCE_NO_LOCK,
272+ * SyncProvider.DATASOURCE_ROW_LOCK,
273+ * SyncProvider.DATASOURCE_TABLE_LOCK,
274+ * SyncProvider.DATASOURCE_DB_LOCK,
275+ * </pre>
276+ * @throws SyncProviderException if an unsupported data source locking level
277+ * is set.
278+ * @see #getDataSourceLock
279+ */
280+ public abstract void setDataSourceLock(int datasource_lock)
281+ throws SyncProviderException;
282+
283+ /**
284+ * Returns the current data source lock severity level active in this
285+ * <code>SyncProvider</code> implementation.
286+ *
287+ * @return a constant indicating the current level of data source lock
288+ * active in this <code>SyncProvider</code> object;
289+ * one of the following:
290+ * <pre>
291+ * SyncProvider.DATASOURCE_NO_LOCK,
292+ * SyncProvider.DATASOURCE_ROW_LOCK,
293+ * SyncProvider.DATASOURCE_TABLE_LOCK,
294+ * SyncProvider.DATASOURCE_DB_LOCK
295+ * </pre>
296+ * @throws SyncProviderExceptiom if an error occurs determining the data
297+ * source locking level.
298+ * @see #setDataSourceLock
299+
300+ */
301+ public abstract int getDataSourceLock()
302+ throws SyncProviderException;
303+
304+ /**
305+ * Returns whether this <code>SyncProvider</code> implementation
306+ * can perform synchronization between a <code>RowSet</code> object
307+ * and the SQL <code>VIEW</code> in the data source from which
308+ * the <code>RowSet</code> object got its data.
309+ *
310+ * @return an <code>int</code> saying whether this <code>SyncProvider</code>
311+ * object supports updating an SQL <code>VIEW</code>; one of the
312+ * following:
313+ * SyncProvider.UPDATABLE_VIEW_SYNC,
314+ * SyncProvider.NONUPDATABLE_VIEW_SYNC
315+ */
316+ public abstract int supportsUpdatableView();
317+
318+ /**
319+ * Returns the release version of this <code>SyncProvider</code> instance.
320+ *
321+ * @return a <code>String</code> detailing the release version of the
322+ * <code>SyncProvider</code> implementation
323+ */
324+ public abstract String getVersion();
325+
326+ /**
327+ * Returns the vendor name of this <code>SyncProvider</code> instance
328+ *
329+ * @return a <code>String</code> detailing the vendor name of this
330+ * <code>SyncProvider</code> implementation
331+ */
332+ public abstract String getVendor();
333+
334+ /*
335+ * Standard description of synchronization grades that a SyncProvider
336+ * could provide.
337+ */
338+
339+ /**
340+ * Indicates that no synchronization with the originating data source is
341+ * provided. A <code>SyncProvider</code>
342+ * implementation returning this grade will simply attempt to write
343+ * updates in the <code>RowSet</code> object to the underlying data
344+ * source without checking the validity of any data.
345+ *
346+ */
347+ public static final int GRADE_NONE = 1;
348+
349+ /**
350+ * Indicates a low level optimistic synchronization grade with
351+ * respect to the originating data source.
352+ *
353+ * A <code>SyncProvider</code> implementation
354+ * returning this grade will check only rows that have changed.
355+ *
356+ */
357+ public static final int GRADE_CHECK_MODIFIED_AT_COMMIT = 2;
358+
359+ /**
360+ * Indicates a high level optimistic synchronization grade with
361+ * respect to the originating data source.
362+ *
363+ * A <code>SyncProvider</code> implementation
364+ * returning this grade will check all rows, including rows that have not
365+ * changed.
366+ */
367+ public static final int GRADE_CHECK_ALL_AT_COMMIT = 3;
368+
369+ /**
370+ * Indicates a pessimistic synchronization grade with
371+ * respect to the originating data source.
372+ *
373+ * A <code>SyncProvider</code>
374+ * implementation returning this grade will lock the row in the originating
375+ * data source.
376+ */
377+ public static final int GRADE_LOCK_WHEN_MODIFIED = 4;
378+
379+ /**
380+ * Indicates the most pessimistic synchronization grade with
381+ * respect to the originating
382+ * data source. A <code>SyncProvider</code>
383+ * implementation returning this grade will lock the entire view and/or
384+ * table affected by the original statement used to populate a
385+ * <code>RowSet</code> object.
386+ */
387+ public static final int GRADE_LOCK_WHEN_LOADED = 5;
388+
389+ /**
390+ * Indicates that no locks remain on the originating data source. This is the default
391+ * lock setting for all <code>SyncProvider</code> implementations unless
392+ * otherwise directed by a <code>RowSet</code> object.
393+ */
394+ public static final int DATASOURCE_NO_LOCK = 1;
395+
396+ /**
397+ * Indicates that a lock is placed on the rows that are touched by the original
398+ * SQL statement used to populate the <code>RowSet</code> object
399+ * that is using this <code>SyncProvider</code> object.
400+ */
401+ public static final int DATASOURCE_ROW_LOCK = 2;
402+
403+ /**
404+ * Indicates that a lock is placed on all tables that are touched by the original
405+ * SQL statement used to populate the <code>RowSet</code> object
406+ * that is using this <code>SyncProvider</code> object.
407+ */
408+ public static final int DATASOURCE_TABLE_LOCK = 3;
409+
410+ /**
411+ * Indicates that a lock is placed on the entire data source that is the source of
412+ * data for the <code>RowSet</code> object
413+ * that is using this <code>SyncProvider</code> object.
414+ */
415+ public static final int DATASOURCE_DB_LOCK = 4;
416+
417+ /**
418+ * Indicates that a <code>SyncProvider</code> implementation
419+ * supports synchronization between a <code>RowSet</code> object and
420+ * the SQL <code>VIEW</code> used to populate it.
421+ */
422+ public static final int UPDATABLE_VIEW_SYNC = 5;
423+
424+ /**
425+ * Indicates that a <code>SyncProvider</code> implementation
426+ * does <B>not</B> support synchronization between a <code>RowSet</code>
427+ * object and the SQL <code>VIEW</code> used to populate it.
428+ */
429+ public static final int NONUPDATABLE_VIEW_SYNC = 6;
430+}
java/pkg/javax/sql/rowset/spi/SyncProviderException.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncProviderException.java+164−0
@@ -0,0 +1,164 @@
1+/*
2+ * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.spi;
27+
28+import java.sql.SQLException;
29+import javax.sql.rowset.*;
30+
31+/**
32+ * Indicates an error with the <code>SyncProvider</code> mechanism. This exception
33+ * is created by a <code>SyncProvider</code> abstract class extension if it
34+ * encounters violations in reading from or writing to the originating data source.
35+ * <P>
36+ * If it is implemented to do so, the <code>SyncProvider</code> object may also create a
37+ * <code>SyncResolver</code> object and either initialize the <code>SyncProviderException</code>
38+ * object with it at construction time or set it with the <code>SyncProvider</code> object at
39+ * a later time.
40+ * <P>
41+ * The method <code>acceptChanges</code> will throw this exception after the writer
42+ * has finished checking for conflicts and has found one or more conflicts. An
43+ * application may catch a <code>SyncProviderException</code> object and call its
44+ * <code>getSyncResolver</code> method to get its <code>SyncResolver</code> object.
45+ * See the code fragment in the interface comment for
46+ * <a href="SyncResolver.html"><code>SyncResolver</code></a> for an example.
47+ * This <code>SyncResolver</code> object will mirror the <code>RowSet</code>
48+ * object that generated the exception, except that it will contain only the values
49+ * from the data source that are in conflict. All other values in the <code>SyncResolver</code>
50+ * object will be <code>null</code>.
51+ * <P>
52+ * The <code>SyncResolver</code> object may be used to examine and resolve
53+ * each conflict in a row and then go to the next row with a conflict to
54+ * repeat the procedure.
55+ * <P>
56+ * A <code>SyncProviderException</code> object may or may not contain a description of the
57+ * condition causing the exception. The inherited method <code>getMessage</code> may be
58+ * called to retrieve the description if there is one.
59+ *
60+ * @author Jonathan Bruce
61+ * @see javax.sql.rowset.spi.SyncFactory
62+ * @see javax.sql.rowset.spi.SyncResolver
63+ * @see javax.sql.rowset.spi.SyncFactoryException
64+ */
65+public class SyncProviderException extends java.sql.SQLException {
66+
67+ /**
68+ * The instance of <code>javax.sql.rowset.spi.SyncResolver</code> that
69+ * this <code>SyncProviderException</code> object will return when its
70+ * <code>getSyncResolver</code> method is called.
71+ */
72+ private SyncResolver syncResolver = null;
73+
74+ /**
75+ * Creates a new <code>SyncProviderException</code> object without a detail message.
76+ */
77+ public SyncProviderException() {
78+ super();
79+ }
80+
81+ /**
82+ * Constructs a <code>SyncProviderException</code> object with the specified
83+ * detail message.
84+ *
85+ * @param msg the detail message
86+ */
87+ public SyncProviderException(String msg) {
88+ super(msg);
89+ }
90+
91+ /**
92+ * Constructs a <code>SyncProviderException</code> object with the specified
93+ * <code>SyncResolver</code> instance.
94+ *
95+ * @param syncResolver the <code>SyncResolver</code> instance used to
96+ * to process the synchronization conflicts
97+ * @throws IllegalArgumentException if the <code>SyncResolver</code> object
98+ * is <code>null</code>.
99+ */
100+ public SyncProviderException(SyncResolver syncResolver) {
101+ if (syncResolver == null) {
102+ throw new IllegalArgumentException("Cannot instantiate a SyncProviderException " +
103+ "with a null SyncResolver object");
104+ } else {
105+ this.syncResolver = syncResolver;
106+ }
107+ }
108+
109+ /**
110+ * Retrieves the <code>SyncResolver</code> object that has been set for
111+ * this <code>SyncProviderException</code> object, or
112+ * if none has been set, an instance of the default <code>SyncResolver</code>
113+ * implementation included in the reference implementation.
114+ * <P>
115+ * If a <code>SyncProviderException</code> object is thrown, an application
116+ * may use this method to generate a <code>SyncResolver</code> object
117+ * with which to resolve the conflict or conflicts that caused the
118+ * exception to be thrown.
119+ *
120+ * @return the <code>SyncResolver</code> object set for this
121+ * <code>SyncProviderException</code> object or, if none has
122+ * been set, an instance of the default <code>SyncResolver</code>
123+ * implementation. In addition, the default <code>SyncResolver</code>
124+ * implementation is also returned if the <code>SyncResolver()</code> or
125+ * <code>SyncResolver(String)</code> constructors are used to instantiate
126+ * the <code>SyncResolver</code> instance.
127+ */
128+ public SyncResolver getSyncResolver() {
129+ if (syncResolver != null) {
130+ return syncResolver;
131+ } else {
132+ try {
133+ syncResolver = new com.sun.rowset.internal.SyncResolverImpl();
134+ } catch (SQLException sqle) {
135+ }
136+ return syncResolver;
137+ }
138+ }
139+
140+ /**
141+ * Sets the <code>SyncResolver</code> object for this
142+ * <code>SyncProviderException</code> object to the one supplied.
143+ * If the argument supplied is <code>null</code>, a call to the method
144+ * <code>getSyncResolver</code> will return the default reference
145+ * implementation of the <code>SyncResolver</code> interface.
146+ *
147+ * @param syncResolver the <code>SyncResolver</code> object to be set;
148+ * cannot be <code>null</code>
149+ * @throws IllegalArgumentException if the <code>SyncResolver</code> object
150+ * is <code>null</code>.
151+ * @see #getSyncResolver
152+ */
153+ public void setSyncResolver(SyncResolver syncResolver) {
154+ if (syncResolver == null) {
155+ throw new IllegalArgumentException("Cannot set a null SyncResolver " +
156+ "object");
157+ } else {
158+ this.syncResolver = syncResolver;
159+ }
160+ }
161+
162+ static final long serialVersionUID = -939908523620640692L;
163+
164+}
java/pkg/javax/sql/rowset/spi/SyncResolver.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/SyncResolver.java+372−0
@@ -0,0 +1,372 @@
1+/*
2+ * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package javax.sql.rowset.spi;
27+
28+import javax.sql.RowSet;
29+import java.sql.SQLException;
30+
31+/**
32+ * Defines a framework that allows applications to use a manual decision tree
33+ * to decide what should be done when a synchronization conflict occurs.
34+ * Although it is not mandatory for
35+ * applications to resolve synchronization conflicts manually, this
36+ * framework provides the means to delegate to the application when conflicts
37+ * arise.
38+ * <p>
39+ * Note that a conflict is a situation where the <code>RowSet</code> object's original
40+ * values for a row do not match the values in the data source, which indicates that
41+ * the data source row has been modified since the last synchronization. Note also that
42+ * a <code>RowSet</code> object's original values are the values it had just prior to the
43+ * the last synchronization, which are not necessarily its initial values.
44+ * <p>
45+ *
46+ * <H2>Description of a <code>SyncResolver</code> Object</H2>
47+ *
48+ * A <code>SyncResolver</code> object is a specialized <code>RowSet</code> object
49+ * that implements the <code>SyncResolver</code> interface.
50+ * It <b>may</b> operate as either a connected <code>RowSet</code> object (an
51+ * implementation of the <code>JdbcRowSet</code> interface) or a connected
52+ * <code>RowSet</code> object (an implementation of the
53+ * <code>CachedRowSet</code> interface or one of its subinterfaces). For information
54+ * on the subinterfaces, see the
55+ * <a href="../package-summary.html"><code>javax.sql.rowset</code></a> package
56+ * description. The reference implementation for <code>SyncResolver</code> implements
57+ * the <code>CachedRowSet</code> interface, but other implementations
58+ * may choose to implement the <code>JdbcRowSet</code> interface to satisfy
59+ * particular needs.
60+ * <P>
61+ * After an application has attempted to synchronize a <code>RowSet</code> object with
62+ * the data source (by calling the <code>CachedRowSet</code>
63+ * method <code>acceptChanges</code>), and one or more conflicts have been found,
64+ * a rowset's <code>SyncProvider</code> object creates an instance of
65+ * <code>SyncResolver</code>. This new <code>SyncResolver</code> object has
66+ * the same number of rows and columns as the
67+ * <code>RowSet</code> object that was attempting the synchronization. The
68+ * <code>SyncResolver</code> object contains the values from the data source that caused
69+ * the conflict(s) and <code>null</code> for all other values.
70+ * In addition, it contains information about each conflict.
71+ * <P>
72+ *
73+ * <H2>Getting and Using a <code>SyncResolver</code> Object</H2>
74+ *
75+ * When the method <code>acceptChanges</code> encounters conflicts, the
76+ * <code>SyncProvider</code> object creates a <code>SyncProviderException</code>
77+ * object and sets it with the new <code>SyncResolver</code> object. The method
78+ * <code>acceptChanges</code> will throw this exception, which
79+ * the application can then catch and use to retrieve the
80+ * <code>SyncResolver</code> object it contains. The following code snippet uses the
81+ * <code>SyncProviderException</code> method <code>getSyncResolver</code> to get
82+ * the <code>SyncResolver</code> object <i>resolver</i>.
83+ * <PRE>
84+ * } catch (SyncProviderException spe) {
85+ * SyncResolver resolver = spe.getSyncResolver();
86+ * ...
87+ * }
88+ * </PRE>
89+ * <P>
90+ * With <i>resolver</i> in hand, an application can use it to get the information
91+ * it contains about the conflict or conflicts. A <code>SyncResolver</code> object
92+ * such as <i>resolver</i> keeps
93+ * track of the conflicts for each row in which there is a conflict. It also places a
94+ * lock on the table or tables affected by the rowset's command so that no more
95+ * conflicts can occur while the current conflicts are being resolved.
96+ * <P>
97+ * The following kinds of information can be obtained from a <code>SyncResolver</code>
98+ * object:
99+ * <P>
100+ * <LI>What operation was being attempted when a conflict occurred<BR>
101+ * The <code>SyncProvider</code> interface defines four constants
102+ * describing states that may occur. Three
103+ * constants describe the type of operation (update, delete, or insert) that a
104+ * <code>RowSet</code> object was attempting to perform when a conflict was discovered,
105+ * and the fourth indicates that there is no conflict.
106+ * These constants are the possible return values when a <code>SyncResolver</code> object
107+ * calls the method <code>getStatus</code>.
108+ * <PRE>
109+ * int operation = resolver.getStatus();
110+ * </PRE>
111+ * <P>
112+ * <LI>The value in the data source that caused a conflict<BR>
113+ * A conflict exists when a value that a <code>RowSet</code> object has changed
114+ * and is attempting to write to the data source
115+ * has also been changed in the data source since the last synchronization. An
116+ * application can call the <code>SyncResolver</code> method
117+ * <code>getConflictValue</code > to retrieve the
118+ * value in the data source that is the cause of the conflict because the values in a
119+ * <code>SyncResolver</code> object are the conflict values from the data source.
120+ * <PRE>
121+ * java.lang.Object conflictValue = resolver.getConflictValue(2);
122+ * </PRE>
123+ * Note that the column in <i>resolver</i> can be designated by the column number,
124+ * as is done in the preceding line of code, or by the column name.
125+ * </UL>
126+ * <P>
127+ * With the information retrieved from the methods <code>getStatus</code> and
128+ * <code>getConflictValue</code>, the application may make a determination as to
129+ * which value should be persisted in the data source. The application then calls the
130+ * <code>SyncResolver</code> method <code>setResolvedValue</code>, which sets the value
131+ * to be persisted in the <code>RowSet</code> object and also in the data source.
132+ * <PRE>
133+ * resolver.setResolvedValue("DEPT", 8390426);
134+ * </PRE>
135+ * In the preceding line of code,
136+ * the column name designates the column in the <code>RowSet</code> object
137+ * that is to be set with the given value. The column number can also be used to
138+ * designate the column.
139+ * <P>
140+ * An application calls the method <code>setResolvedValue</code> after it has
141+ * resolved all of the conflicts in the current conflict row and repeats this process
142+ * for each conflict row in the <code>SyncResolver</code> object.
143+ * <P>
144+ *
145+ * <H2>Navigating a <code>SyncResolver</code> Object</H2>
146+ *
147+ * Because a <code>SyncResolver</code> object is a <code>RowSet</code> object, an
148+ * application can use all of the <code>RowSet</code> methods for moving the cursor
149+ * to navigate a <code>SyncResolver</code> object. For example, an application can
150+ * use the <code>RowSet</code> method <code>next</code> to get to each row and then
151+ * call the <code>SyncResolver</code> method <code>getStatus</code> to see if the row
152+ * contains a conflict. In a row with one or more conflicts, the application can
153+ * iterate through the columns to find any non-null values, which will be the values
154+ * from the data source that are in conflict.
155+ * <P>
156+ * To make it easier to navigate a <code>SyncResolver</code> object, especially when
157+ * there are large numbers of rows with no conflicts, the <code>SyncResolver</code>
158+ * interface defines the methods <code>nextConflict</code> and
159+ * <code>previousConflict</code>, which move only to rows
160+ * that contain at least one conflict value. Then an application can call the
161+ * <code>SyncResolver</code> method <code>getConflictValue</code>, supplying it
162+ * with the column number, to get the conflict value itself. The code fragment in the
163+ * next section gives an example.
164+ *
165+ * <H2>Code Example</H2>
166+ *
167+ * The following code fragment demonstrates how a disconnected <code>RowSet</code>
168+ * object <i>crs</i> might attempt to synchronize itself with the
169+ * underlying data source and then resolve the conflicts. In the <code>try</code>
170+ * block, <i>crs</i> calls the method <code>acceptChanges</code>, passing it the
171+ * <code>Connection</code> object <i>con</i>. If there are no conflicts, the
172+ * changes in <i>crs</i> are simply written to the data source. However, if there
173+ * is a conflict, the method <code>acceptChanges</code> throws a
174+ * <code>SyncProviderException</code> object, and the
175+ * <code>catch</code> block takes effect. In this example, which
176+ * illustrates one of the many ways a <code>SyncResolver</code> object can be used,
177+ * the <code>SyncResolver</code> method <code>nextConflict</code> is used in a
178+ * <code>while</code> loop. The loop will end when <code>nextConflict</code> returns
179+ * <code>false</code>, which will occur when there are no more conflict rows in the
180+ * <code>SyncResolver</code> object <i>resolver</i>. In This particular code fragment,
181+ * <i>resolver</i> looks for rows that have update conflicts (rows with the status
182+ * <code>SyncResolver.UPDATE_ROW_CONFLICT</code>), and the rest of this code fragment
183+ * executes only for rows where conflicts occurred because <i>crs</i> was attempting an
184+ * update.
185+ * <P>
186+ * After the cursor for <i>resolver</i> has moved to the next conflict row that
187+ * has an update conflict, the method <code>getRow</code> indicates the number of the
188+ * current row, and
189+ * the cursor for the <code>CachedRowSet</code> object <i>crs</i> is moved to
190+ * the comparable row in <i>crs</i>. By iterating
191+ * through the columns of that row in both <i>resolver</i> and <i>crs</i>, the conflicting
192+ * values can be retrieved and compared to decide which one should be persisted. In this
193+ * code fragment, the value in <i>crs</i> is the one set as the resolved value, which means
194+ * that it will be used to overwrite the conflict value in the data source.
195+ *
196+ * <PRE>

176 more lines aren’t shown here.

java/pkg/javax/sql/rowset/spi/TransactionalWriter.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/TransactionalWriter.java+83−0

This diff is large: its 84 lines aren’t shown here.

java/pkg/javax/sql/rowset/spi/XmlReader.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/XmlReader.java+74−0

This diff is large: its 75 lines aren’t shown here.

java/pkg/javax/sql/rowset/spi/XmlWriter.class+0−0

Binary file not shown.

java/pkg/javax/sql/rowset/spi/XmlWriter.java+74−0

This diff is large: its 75 lines aren’t shown here.

java/pkg/javax/sql/rowset/spi/mkfile+15−0

This diff is large: its 16 lines aren’t shown here.

java/pkg/javax/sql/rowset/spi/package.html+510−0

This diff is large: its 511 lines aren’t shown here.

java/pkg/javax/sql/rowset/sqlxml.xsd+162−0

This diff is large: its 163 lines aren’t shown here.

java/pkg/javax/sql/rowset/webrowset.xsd+160−0

This diff is large: its 161 lines aren’t shown here.