0N/A/*
2362N/A * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
0N/A * This code is free software; you can redistribute it and/or modify it
0N/A * under the terms of the GNU General Public License version 2 only, as
2362N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
2362N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
0N/A * This code is distributed in the hope that it will be useful, but WITHOUT
0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/A * version 2 for more details (a copy is included in the LICENSE file that
0N/A * accompanied this code).
0N/A *
0N/A * You should have received a copy of the GNU General Public License version
0N/A * 2 along with this work; if not, write to the Free Software Foundation,
0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A *
2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2362N/A * or visit www.oracle.com if you need additional information or have any
2362N/A * questions.
0N/A */
0N/A
0N/Apackage javax.sql.rowset.serial;
0N/A
0N/Aimport java.sql.*;
0N/Aimport java.io.*;
0N/Aimport java.util.Map;
0N/Aimport java.net.URL;
0N/A
0N/A
0N/A/**
0N/A * A serialized version of an <code>Array</code>
0N/A * object, which is the mapping in the Java programming language of an SQL
0N/A * <code>ARRAY</code> value.
0N/A * <P>
0N/A * The <code>SerialArray</code> class provides a constructor for creating
0N/A * a <code>SerialArray</code> instance from an <code>Array</code> object,
0N/A * methods for getting the base type and the SQL name for the base type, and
0N/A * methods for copying all or part of a <code>SerialArray</code> object.
0N/A * <P>
0N/A * Note: In order for this class to function correctly, a connection to the
0N/A * data source
0N/A * must be available in order for the SQL <code>Array</code> object to be
0N/A * materialized (have all of its elements brought to the client server)
0N/A * if necessary. At this time, logical pointers to the data in the data source,
0N/A * such as locators, are not currently supported.
0N/A */
0N/Apublic class SerialArray implements Array, Serializable, Cloneable {
0N/A
0N/A /**
0N/A * A serialized array in which each element is an <code>Object</code>
0N/A * in the Java programming language that represents an element
0N/A * in the SQL <code>ARRAY</code> value.
0N/A * @serial
0N/A */
0N/A private Object[] elements;
0N/A
0N/A /**
0N/A * The SQL type of the elements in this <code>SerialArray</code> object. The
0N/A * type is expressed as one of the constants from the class
0N/A * <code>java.sql.Types</code>.
0N/A * @serial
0N/A */
0N/A private int baseType;
0N/A
0N/A /**
0N/A * The type name used by the DBMS for the elements in the SQL <code>ARRAY</code>
0N/A * value that this <code>SerialArray</code> object represents.
0N/A * @serial
0N/A */
0N/A private String baseTypeName;
0N/A
0N/A /**
0N/A * The number of elements in this <code>SerialArray</code> object, which
0N/A * is also the number of elements in the SQL <code>ARRAY</code> value
0N/A * that this <code>SerialArray</code> object represents.
0N/A * @serial
0N/A */
0N/A private int len;
0N/A
0N/A /**
0N/A * Constructs a new <code>SerialArray</code> object from the given
0N/A * <code>Array</code> object, using the given type map for the custom
0N/A * mapping of each element when the elements are SQL UDTs.
0N/A * <P>
0N/A * This method does custom mapping if the array elements are a UDT
0N/A * and the given type map has an entry for that UDT.
0N/A * Custom mapping is recursive,
0N/A * meaning that if, for instance, an element of an SQL structured type
0N/A * is an SQL structured type that itself has an element that is an SQL
0N/A * structured type, each structured type that has a custom mapping will be
0N/A * mapped according to the given type map.
0N/A * <P>
0N/A * The new <code>SerialArray</code>
0N/A * object contains the same elements as the <code>Array</code> object
0N/A * from which it is built, except when the base type is the SQL type
0N/A * <code>STRUCT</code>, <code>ARRAY</code>, <code>BLOB</code>,
0N/A * <code>CLOB</code>, <code>DATALINK</code> or <code>JAVA_OBJECT</code>.
0N/A * In this case, each element in the new
0N/A * <code>SerialArray</code> object is the appropriate serialized form,
0N/A * that is, a <code>SerialStruct</code>, <code>SerialArray</code>,
0N/A * <code>SerialBlob</code>, <code>SerialClob</code>,
0N/A * <code>SerialDatalink</code>, or <code>SerialJavaObject</code> object.
0N/A * <P>
0N/A * Note: (1) The <code>Array</code> object from which a <code>SerialArray</code>
0N/A * object is created must have materialized the SQL <code>ARRAY</code> value's
0N/A * data on the client before it is passed to the constructor. Otherwise,
0N/A * the new <code>SerialArray</code> object will contain no data.
0N/A * <p>
0N/A * Note: (2) If the <code>Array</code> contains <code>java.sql.Types.JAVA_OBJECT</code>
0N/A * types, the <code>SerialJavaObject</code> constructor is called where checks
0N/A * are made to ensure this object is serializable.
0N/A * <p>
0N/A * Note: (3) The <code>Array</code> object supplied to this constructor cannot
0N/A * return <code>null</code> for any <code>Array.getArray()</code> methods.
0N/A * <code>SerialArray</code> cannot serialize null array values.
0N/A *
0N/A *
0N/A * @param array the <code>Array</code> object to be serialized
0N/A * @param map a <code>java.util.Map</code> object in which
0N/A * each entry consists of 1) a <code>String</code> object
0N/A * giving the fully qualified name of a UDT (an SQL structured type or
0N/A * distinct type) and 2) the
0N/A * <code>Class</code> object for the <code>SQLData</code> implementation
0N/A * that defines how the UDT is to be mapped. The <i>map</i>
0N/A * parameter does not have any effect for <code>Blob</code>,
0N/A * <code>Clob</code>, <code>DATALINK</code>, or
0N/A * <code>JAVA_OBJECT</code> types.
0N/A * @throws SerialException if an error occurs serializing the
0N/A * <code>Array</code> object
0N/A * @throws SQLException if a database access error occurs or if the
0N/A * <i>array</i> or the <i>map</i> values are <code>null</code>
0N/A */
0N/A public SerialArray(Array array, Map<String,Class<?>> map)
0N/A throws SerialException, SQLException
0N/A {
0N/A
0N/A if ((array == null) || (map == null)) {
0N/A throw new SQLException("Cannot instantiate a SerialArray " +
0N/A "object with null parameters");
0N/A }
0N/A
0N/A if ((elements = (Object[])array.getArray()) == null) {
0N/A throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
0N/A "return null value which cannot be serialized");
0N/A }
0N/A
0N/A elements = (Object[])array.getArray(map);
0N/A baseType = array.getBaseType();
0N/A baseTypeName = array.getBaseTypeName();
0N/A len = elements.length;
0N/A
0N/A switch (baseType) {
0N/A case java.sql.Types.STRUCT:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialStruct((Struct)elements[i], map);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.ARRAY:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialArray((Array)elements[i], map);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.BLOB:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialBlob((Blob)elements[i]);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.CLOB:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialClob((Clob)elements[i]);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.DATALINK:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialDatalink((URL)elements[i]);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.JAVA_OBJECT:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialJavaObject((Object)elements[i]);
0N/A }
0N/A default:
0N/A ;
0N/A }
0N/A }
0N/A
0N/A /**
0N/A * This method frees the <code>Array</code> object and releases the resources that
0N/A * it holds. The object is invalid once the <code>free</code>
0N/A * method is called.
0N/A *<p>
0N/A * After <code>free</code> has been called, any attempt to invoke a
0N/A * method other than <code>free</code> will result in a <code>SQLException</code>
0N/A * being thrown. If <code>free</code> is called multiple times, the subsequent
0N/A * calls to <code>free</code> are treated as a no-op.
0N/A *<p>
0N/A *
0N/A * @throws SQLException if an error occurs releasing
0N/A * the Array's resources
0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0N/A * this method
0N/A * @since 1.6
0N/A */
0N/A public void free() throws SQLException {
0N/A throw new SQLFeatureNotSupportedException("Feature not supported");
0N/A }
0N/A
0N/A /**
0N/A * Constructs a new <code>SerialArray</code> object from the given
0N/A * <code>Array</code> object.
0N/A * <P>
0N/A * This constructor does not do custom mapping. If the base type of the array
0N/A * is an SQL structured type and custom mapping is desired, the constructor
0N/A * <code>SerialArray(Array array, Map map)</code> should be used.
0N/A * <P>
0N/A * The new <code>SerialArray</code>
0N/A * object contains the same elements as the <code>Array</code> object
0N/A * from which it is built, except when the base type is the SQL type
0N/A * <code>BLOB</code>,
0N/A * <code>CLOB</code>, <code>DATALINK</code> or <code>JAVA_OBJECT</code>.
0N/A * In this case, each element in the new
0N/A * <code>SerialArray</code> object is the appropriate serialized form,
0N/A * that is, a <code>SerialBlob</code>, <code>SerialClob</code>,
0N/A * <code>SerialDatalink</code>, or <code>SerialJavaObject</code> object.
0N/A * <P>
0N/A * Note: (1) The <code>Array</code> object from which a <code>SerialArray</code>
0N/A * object is created must have materialized the SQL <code>ARRAY</code> value's
0N/A * data on the client before it is passed to the constructor. Otherwise,
0N/A * the new <code>SerialArray</code> object will contain no data.
0N/A * <p>
0N/A * Note: (2) The <code>Array</code> object supplied to this constructor cannot
0N/A * return <code>null</code> for any <code>Array.getArray()</code> methods.
0N/A * <code>SerialArray</code> cannot serialize <code>null</code> array values.
0N/A *
0N/A * @param array the <code>Array</code> object to be serialized
0N/A * @throws SerialException if an error occurs serializing the
0N/A * <code>Array</code> object
0N/A * @throws SQLException if a database access error occurs or the
0N/A * <i>array</i> parameter is <code>null</code>.
0N/A */
0N/A public SerialArray(Array array) throws SerialException, SQLException {
0N/A if (array == null) {
0N/A throw new SQLException("Cannot instantiate a SerialArray " +
0N/A "object with a null Array object");
0N/A }
0N/A
0N/A if ((elements = (Object[])array.getArray()) == null) {
0N/A throw new SQLException("Invalid Array object. Calls to Array.getArray() " +
0N/A "return null value which cannot be serialized");
0N/A }
0N/A
0N/A //elements = (Object[])array.getArray();
0N/A baseType = array.getBaseType();
0N/A baseTypeName = array.getBaseTypeName();
0N/A len = elements.length;
0N/A
0N/A switch (baseType) {
0N/A
0N/A case java.sql.Types.BLOB:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialBlob((Blob)elements[i]);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.CLOB:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialClob((Clob)elements[i]);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.DATALINK:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialDatalink((URL)elements[i]);
0N/A }
0N/A break;
0N/A
0N/A case java.sql.Types.JAVA_OBJECT:
0N/A for (int i = 0; i < len; i++) {
0N/A elements[i] = new SerialJavaObject((Object)elements[i]);
0N/A }
0N/A
0N/A default:
0N/A ;
0N/A }
0N/A
0N/A
0N/A }
0N/A
0N/A /**
0N/A * Returns a new array that is a copy of this <code>SerialArray</code>
0N/A * object.
0N/A *
0N/A * @return a copy of this <code>SerialArray</code> object as an
0N/A * <code>Object</code> in the Java programming language
0N/A * @throws SerialException if an error occurs retrieving a copy of
0N/A * this <code>SerialArray</code> object
0N/A */
0N/A public Object getArray() throws SerialException {
0N/A Object dst = new Object[len];
0N/A System.arraycopy((Object)elements, 0, dst, 0, len);
0N/A return dst;
0N/A }
0N/A
0N/A //[if an error occurstype map used??]
0N/A /**
0N/A * Returns a new array that is a copy of this <code>SerialArray</code>
0N/A * object, using the given type map for the custom
0N/A * mapping of each element when the elements are SQL UDTs.
0N/A * <P>
0N/A * This method does custom mapping if the array elements are a UDT
0N/A * and the given type map has an entry for that UDT.
0N/A * Custom mapping is recursive,
0N/A * meaning that if, for instance, an element of an SQL structured type
0N/A * is an SQL structured type that itself has an element that is an SQL
0N/A * structured type, each structured type that has a custom mapping will be
0N/A * mapped according to the given type map.
0N/A *
0N/A * @param map a <code>java.util.Map</code> object in which
0N/A * each entry consists of 1) a <code>String</code> object
0N/A * giving the fully qualified name of a UDT and 2) the
0N/A * <code>Class</code> object for the <code>SQLData</code> implementation
0N/A * that defines how the UDT is to be mapped
0N/A * @return a copy of this <code>SerialArray</code> object as an
0N/A * <code>Object</code> in the Java programming language
0N/A * @throws SerialException if an error occurs
0N/A */
0N/A public Object getArray(Map<String, Class<?>> map) throws SerialException {
0N/A Object dst[] = new Object[len];
0N/A System.arraycopy((Object)elements, 0, dst, 0, len);
0N/A return dst;
0N/A }
0N/A
0N/A /**
0N/A * Returns a new array that is a copy of a slice
0N/A * of this <code>SerialArray</code> object, starting with the
0N/A * element at the given index and containing the given number
0N/A * of consecutive elements.
0N/A *
0N/A * @param index the index into this <code>SerialArray</code> object
0N/A * of the first element to be copied;
0N/A * the index of the first element is <code>0</code>
0N/A * @param count the number of consecutive elements to be copied, starting
0N/A * at the given index
0N/A * @return a copy of the designated elements in this <code>SerialArray</code>
0N/A * object as an <code>Object</code> in the Java programming language
0N/A * @throws SerialException if an error occurs
0N/A */
0N/A public Object getArray(long index, int count) throws SerialException {
0N/A Object dst = new Object[count];
0N/A System.arraycopy((Object)elements, (int)index, dst, 0, count);
0N/A return dst;
0N/A }
0N/A
0N/A /**
0N/A * Returns a new array that is a copy of a slice
0N/A * of this <code>SerialArray</code> object, starting with the
0N/A * element at the given index and containing the given number
0N/A * of consecutive elements.
0N/A * <P>
0N/A * This method does custom mapping if the array elements are a UDT
0N/A * and the given type map has an entry for that UDT.
0N/A * Custom mapping is recursive,
0N/A * meaning that if, for instance, an element of an SQL structured type
0N/A * is an SQL structured type that itself has an element that is an SQL
0N/A * structured type, each structured type that has a custom mapping will be
0N/A * mapped according to the given type map.
0N/A *
0N/A * @param index the index into this <code>SerialArray</code> object
0N/A * of the first element to be copied; the index of the
0N/A * first element in the array is <code>0</code>
0N/A * @param count the number of consecutive elements to be copied, starting
0N/A * at the given index
0N/A * @param map a <code>java.util.Map</code> object in which
0N/A * each entry consists of 1) a <code>String</code> object
0N/A * giving the fully qualified name of a UDT and 2) the
0N/A * <code>Class</code> object for the <code>SQLData</code> implementation
0N/A * that defines how the UDT is to be mapped
0N/A * @return a copy of the designated elements in this <code>SerialArray</code>
0N/A * object as an <code>Object</code> in the Java programming language
0N/A * @throws SerialException if an error occurs
0N/A */
0N/A public Object getArray(long index, int count, Map<String,Class<?>> map)
0N/A throws SerialException
0N/A {
0N/A Object dst = new Object[count];
0N/A System.arraycopy((Object)elements, (int)index, dst, 0, count);
0N/A return dst;
0N/A }
0N/A
0N/A /**
0N/A * Retrieves the SQL type of the elements in this <code>SerialArray</code>
0N/A * object. The <code>int</code> returned is one of the constants in the class
0N/A * <code>java.sql.Types</code>.
0N/A *
0N/A * @return one of the constants in <code>java.sql.Types</code>, indicating
0N/A * the SQL type of the elements in this <code>SerialArray</code> object
0N/A * @throws SerialException if an error occurs
0N/A */
0N/A public int getBaseType() throws SerialException {
0N/A return baseType;
0N/A }
0N/A
0N/A /**
0N/A * Retrieves the DBMS-specific type name for the elements in this
0N/A * <code>SerialArray</code> object.
0N/A *
0N/A * @return the SQL type name used by the DBMS for the base type of this
0N/A * <code>SerialArray</code> object
0N/A * @throws SerialException if an error occurs
0N/A */
0N/A public String getBaseTypeName() throws SerialException {
0N/A return baseTypeName;
0N/A }
0N/A
0N/A /**
0N/A * Retrieves a <code>ResultSet</code> object holding the elements of
0N/A * the subarray that starts at
0N/A * index <i>index</i> and contains up to <i>count</i> successive elements.
0N/A * This method uses the connection's type map to map the elements of
0N/A * the array if the map contains
0N/A * an entry for the base type. Otherwise, the standard mapping is used.
0N/A *
0N/A * @param index the index into this <code>SerialArray</code> object
0N/A * of the first element to be copied; the index of the
0N/A * first element in the array is <code>0</code>
0N/A * @param count the number of consecutive elements to be copied, starting
0N/A * at the given index
0N/A * @return a <code>ResultSet</code> object containing the designated
0N/A * elements in this <code>SerialArray</code> object, with a
0N/A * separate row for each element
0N/A * @throws SerialException, which in turn throws an
0N/A * <code>UnsupportedOperationException</code>, if this method is called
0N/A */
0N/A public ResultSet getResultSet(long index, int count) throws SerialException {
0N/A throw new UnsupportedOperationException();
0N/A }
0N/A
0N/A /**
0N/A *
0N/A * Retrieves a <code>ResultSet</code> object that contains all of
0N/A * the elements of the SQL <code>ARRAY</code>
0N/A * value represented by this <code>SerialArray</code> object. This method uses
0N/A * the specified map for type map customizations unless the base type of the
0N/A * array does not match a user-defined type (UDT) in <i>map</i>, in
0N/A * which case it uses the
0N/A * standard mapping. This version of the method <code>getResultSet</code>
0N/A * uses either the given type map or the standard mapping; it never uses the
0N/A * type map associated with the connection.
0N/A *
0N/A * @param map a <code>java.util.Map</code> object in which
0N/A * each entry consists of 1) a <code>String</code> object
0N/A * giving the fully qualified name of a UDT and 2) the
0N/A * <code>Class</code> object for the <code>SQLData</code> implementation
0N/A * that defines how the UDT is to be mapped
0N/A * @return a <code>ResultSet</code> object containing all of the
0N/A * elements in this <code>SerialArray</code> object, with a
0N/A * separate row for each element
0N/A * @throws SerialException, which in turn throws an
0N/A * <code>UnsupportedOperationException</code>, if this method is called
0N/A */
0N/A public ResultSet getResultSet(Map<String, Class<?>> map)
0N/A throws SerialException
0N/A {
0N/A throw new UnsupportedOperationException();
0N/A }
0N/A
0N/A /**
0N/A * Retrieves a <code>ResultSet</code> object that contains all of
0N/A * the elements in the <code>ARRAY</code> value that this
0N/A * <code>SerialArray</code> object represents.
0N/A * If appropriate, the elements of the array are mapped using the connection's
0N/A * type map; otherwise, the standard mapping is used.
0N/A *
0N/A * @return a <code>ResultSet</code> object containing all of the
0N/A * elements in this <code>SerialArray</code> object, with a
0N/A * separate row for each element
0N/A * @throws SerialException if called, which in turn throws an
0N/A * <code>UnsupportedOperationException</code>, if this method is called
0N/A */
0N/A public ResultSet getResultSet() throws SerialException {
0N/A throw new UnsupportedOperationException();
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Retrieves a result set holding the elements of the subarray that starts at
0N/A * Retrieves a <code>ResultSet</code> object that contains a subarray of the
0N/A * elements in this <code>SerialArray</code> object, starting at
0N/A * index <i>index</i> and containing up to <i>count</i> successive
0N/A * elements. This method uses
0N/A * the specified map for type map customizations unless the base type of the
0N/A * array does not match a user-defined type (UDT) in <i>map</i>, in
0N/A * which case it uses the
0N/A * standard mapping. This version of the method <code>getResultSet</code> uses
0N/A * either the given type map or the standard mapping; it never uses the type
0N/A * map associated with the connection.
0N/A *
0N/A * @param index the index into this <code>SerialArray</code> object
0N/A * of the first element to be copied; the index of the
0N/A * first element in the array is <code>0</code>
0N/A * @param count the number of consecutive elements to be copied, starting
0N/A * at the given index
0N/A * @param map a <code>java.util.Map</code> object in which
0N/A * each entry consists of 1) a <code>String</code> object
0N/A * giving the fully qualified name of a UDT and 2) the
0N/A * <code>Class</code> object for the <code>SQLData</code> implementation
0N/A * that defines how the UDT is to be mapped
0N/A * @return a <code>ResultSet</code> object containing the designated
0N/A * elements in this <code>SerialArray</code> object, with a
0N/A * separate row for each element
0N/A * @throws SerialException if called, which in turn throws an
0N/A * <code>UnsupportedOperationException</code>
0N/A */
0N/A public ResultSet getResultSet(long index, int count,
0N/A Map<String,Class<?>> map)
0N/A throws SerialException
0N/A {
0N/A throw new UnsupportedOperationException();
0N/A }
0N/A
0N/A /**
0N/A * The identifier that assists in the serialization of this <code>SerialArray</code>
0N/A * object.
0N/A */
0N/A static final long serialVersionUID = -8466174297270688520L;
0N/A}