jdk-sandbox: comparison jdk/src/share/classes/javax/sql/rowset/serial/SerialArray.java

equal deleted inserted replaced

-:a65826af2aa4
+:701d0765f75f
 import java.sql.*;
 import java.io.*;
 import java.util.Map;
 import java.net.URL;
 import java.util.Arrays;
 /**
 * A serialized version of an <code>Array</code>
 * object, which is the mapping in the Java programming language of an SQL
 * <code>ARRAY</code> value.
 * The <code>SerialArray</code> class provides a constructor for creating
 * a <code>SerialArray</code> instance from an <code>Array</code> object,
 * methods for getting the base type and the SQL name for the base type, and
 * methods for copying all or part of a <code>SerialArray</code> object.
 * <P>
+*
 * Note: In order for this class to function correctly, a connection to the
 * data source
 * must be available in order for the SQL <code>Array</code> object to be
 * materialized (have all of its elements brought to the client server)
 * if necessary. At this time, logical pointers to the data in the data source,
 * such as locators, are not currently supported.
+*
+* <h4> Thread safety </h4>
+*
+* A SerialArray is not safe for use by multiple concurrent threads.  If a
+* SerialArray is to be used by more than one thread then access to the
+* SerialArray should be controlled by appropriate synchronization.
+*
 */
 public class SerialArray implements Array, Serializable, Cloneable {
 /**
 * A serialized array in which each element is an <code>Object</code>
 * in the Java programming language that represents an element
 * in the SQL <code>ARRAY</code> value.
 * @serial
 */
 private Object[] elements;
 /**
 * The SQL type of the elements in this <code>SerialArray</code> object.  The
 * type is expressed as one of the constants from the class
 * <code>java.sql.Types</code>.
 * @serial
 */
 private int baseType;
 /**
 * The type name used by the DBMS for the elements in the SQL <code>ARRAY</code>
 * value that this <code>SerialArray</code> object represents.
 * @serial
 */
 private String baseTypeName;
 /**
 * The number of elements in this <code>SerialArray</code> object, which
 * is also the number of elements in the SQL <code>ARRAY</code> value
 * that this <code>SerialArray</code> object represents.
 * @serial
 */
 private int len;
 /**
 * Constructs a new <code>SerialArray</code> object from the given
 * <code>Array</code> object, using the given type map for the custom
 }
 }
 }
 /**
-* This method frees the <code>Array</code> object and releases the resources that
+* This method frees the {@code SeriableArray} object and releases the
-* it holds. The object is invalid once the <code>free</code>
+* resources that it holds. The object is invalid once the {@code free}
-* method is called.
+* method is called. <p> If {@code free} is called multiple times, the
-*<p>
+* subsequent calls to {@code free} are treated as a no-op. </P>
-* After <code>free</code> has been called, any attempt to invoke a
+*
-* method other than <code>free</code> will result in a <code>SQLException</code>
+* @throws SQLException if an error occurs releasing the SerialArray's resources
-* being thrown.  If <code>free</code> is called multiple times, the subsequent
-* calls to <code>free</code> are treated as a no-op.
-*<p>
-*
-* @throws SQLException if an error occurs releasing
-* the Array's resources
-* @exception SQLFeatureNotSupportedException if the JDBC driver does not support
-* this method
 * @since 1.6
 */
 public void free() throws SQLException {
-throw new SQLFeatureNotSupportedException("Feature not supported");
+if (elements != null) {
+elements = null;
+baseTypeName= null;
+}
 }
 /**
 * Constructs a new <code>SerialArray</code> object from the given
 * <code>Array</code> object.
 }
 }
 /**
 * Returns a new array that is a copy of this <code>SerialArray</code>
 * object.
 *
 * @return a copy of this <code>SerialArray</code> object as an
 *         <code>Object</code> in the Java programming language
-* @throws SerialException if an error occurs retrieving a copy of
+* @throws SerialException if an error occurs;
-*         this <code>SerialArray</code> object
+* if {@code free} had previously been called on this object
 */
 public Object getArray() throws SerialException {
+isValid();
 Object dst = new Object[len];
 System.arraycopy((Object)elements, 0, dst, 0, len);
 return dst;
 }
 //[if an error occurstype map used??]
 /**
 * Returns a new array that is a copy of this <code>SerialArray</code>
 * object, using the given type map for the custom
 * mapping of each element when the elements are SQL UDTs.
 * <P>
 * This method does custom mapping if the array elements are a UDT
 * and the given type map has an entry for that UDT.
 * Custom mapping is recursive,
 * meaning that if, for instance, an element of an SQL structured type
 * is an SQL structured type that itself has an element that is an SQL
 * structured type, each structured type that has a custom mapping will be
 * mapped according to the given type map.
 *
 * @param map a <code>java.util.Map</code> object in which
 *        each entry consists of 1) a <code>String</code> object
 *        giving the fully qualified name of a UDT and 2) the
 *        <code>Class</code> object for the <code>SQLData</code> implementation
 *        that defines how the UDT is to be mapped
 * @return a copy of this <code>SerialArray</code> object as an
 *         <code>Object</code> in the Java programming language
-* @throws SerialException if an error occurs
+* @throws SerialException if an error occurs;
-*/
+* if {@code free} had previously been called on this object
+*/
 public Object getArray(Map<String, Class<?>> map) throws SerialException {
+isValid();
 Object dst[] = new Object[len];
 System.arraycopy((Object)elements, 0, dst, 0, len);
 return dst;
 }
 /**
 * Returns a new array that is a copy of a slice
 * of this <code>SerialArray</code> object, starting with the
 * element at the given index and containing the given number
 * of consecutive elements.
 *
 * @param index the index into this <code>SerialArray</code> object
 *              of the first element to be copied;
 *              the index of the first element is <code>0</code>
 * @param count the number of consecutive elements to be copied, starting
 *              at the given index
 * @return a copy of the designated elements in this <code>SerialArray</code>
 *         object as an <code>Object</code> in the Java programming language
-* @throws SerialException if an error occurs
+* @throws SerialException if an error occurs;
-*/
+* if {@code free} had previously been called on this object
+*/
 public Object getArray(long index, int count) throws SerialException {
+isValid();
 Object dst = new Object[count];
 System.arraycopy((Object)elements, (int)index, dst, 0, count);
 return dst;
 }
 /**
 * Returns a new array that is a copy of a slice
 * of this <code>SerialArray</code> object, starting with the
 * element at the given index and containing the given number
 * of consecutive elements.
 * <P>
 * This method does custom mapping if the array elements are a UDT
 * and the given type map has an entry for that UDT.
 * Custom mapping is recursive,
 * meaning that if, for instance, an element of an SQL structured type
 * is an SQL structured type that itself has an element that is an SQL
 * structured type, each structured type that has a custom mapping will be
 * mapped according to the given type map.
 *
 * @param index the index into this <code>SerialArray</code> object
 *              of the first element to be copied; the index of the
 *              first element in the array is <code>0</code>
 * @param count the number of consecutive elements to be copied, starting
 *              at the given index
 * @param map a <code>java.util.Map</code> object in which
 *        each entry consists of 1) a <code>String</code> object
 *        giving the fully qualified name of a UDT and 2) the
 *        <code>Class</code> object for the <code>SQLData</code> implementation
 *        that defines how the UDT is to be mapped
 * @return a copy of the designated elements in this <code>SerialArray</code>
 *         object as an <code>Object</code> in the Java programming language
-* @throws SerialException if an error occurs
+* @throws SerialException if an error occurs;
-*/
+* if {@code free} had previously been called on this object
+*/
 public Object getArray(long index, int count, Map<String,Class<?>> map)
 throws SerialException
 {
+isValid();
 Object dst = new Object[count];
 System.arraycopy((Object)elements, (int)index, dst, 0, count);
 return dst;
 }
 /**
 * Retrieves the SQL type of the elements in this <code>SerialArray</code>
 * object.  The <code>int</code> returned is one of the constants in the class
 * <code>java.sql.Types</code>.
 *
 * @return one of the constants in <code>java.sql.Types</code>, indicating
 *         the SQL type of the elements in this <code>SerialArray</code> object
-* @throws SerialException if an error occurs
+* @throws SerialException if an error occurs;
-*/
+* if {@code free} had previously been called on this object
+*/
 public int getBaseType() throws SerialException {
+isValid();
 return baseType;
 }
 /**
 * Retrieves the DBMS-specific type name for the elements in this
 * <code>SerialArray</code> object.
 *
 * @return the SQL type name used by the DBMS for the base type of this
 *         <code>SerialArray</code> object
-* @throws SerialException if an error occurs
+* @throws SerialException if an error occurs;
-*/
+* if {@code free} had previously been called on this object
+*/
 public String getBaseTypeName() throws SerialException {
+isValid();
 return baseTypeName;
 }
 /**
 * Retrieves a <code>ResultSet</code> object holding the elements of
 * @param count the number of consecutive elements to be copied, starting
 *         at the given index
 * @return a <code>ResultSet</code> object containing the designated
 *         elements in this <code>SerialArray</code> object, with a
 *         separate row for each element
-* @throws SerialException, which in turn throws an
+* @throws SerialException if called with the cause set to
-*         <code>UnsupportedOperationException</code>, if this method is called
+*         {@code UnsupportedOperationException}
 */
 public ResultSet getResultSet(long index, int count) throws SerialException {
-throw new UnsupportedOperationException();
+SerialException se = new SerialException();
+se.initCause(new UnsupportedOperationException());
+throw  se;
 }
 /**
 *
 * Retrieves a <code>ResultSet</code> object that contains all of
 *        <code>Class</code> object for the <code>SQLData</code> implementation
 *        that defines how the UDT is to be mapped
 * @return a <code>ResultSet</code> object containing all of the
 *         elements in this <code>SerialArray</code> object, with a
 *         separate row for each element
-* @throws SerialException, which in turn throws an
+* @throws SerialException if called with the cause set to
-*         <code>UnsupportedOperationException</code>, if this method is called
+*         {@code UnsupportedOperationException}
 */
 public ResultSet getResultSet(Map<String, Class<?>> map)
 throws SerialException
 {
-throw new UnsupportedOperationException();
+SerialException se = new SerialException();
+se.initCause(new UnsupportedOperationException());
+throw  se;
 }
 /**
 * Retrieves a <code>ResultSet</code> object that contains all of
 * the elements in the <code>ARRAY</code> value that this
 * type map; otherwise, the standard mapping is used.
 *
 * @return a <code>ResultSet</code> object containing all of the
 *         elements in this <code>SerialArray</code> object, with a
 *         separate row for each element
-* @throws SerialException if called, which in turn throws an
+* @throws SerialException if called with the cause set to
-*         <code>UnsupportedOperationException</code>, if this method is called
+*         {@code UnsupportedOperationException}
 */
 public ResultSet getResultSet() throws SerialException {
-throw new UnsupportedOperationException();
+SerialException se = new SerialException();
+se.initCause(new UnsupportedOperationException());
+throw  se;
 }
 /**
 * Retrieves a result set holding the elements of the subarray that starts at
 *        <code>Class</code> object for the <code>SQLData</code> implementation
 *        that defines how the UDT is to be mapped
 * @return a <code>ResultSet</code> object containing the designated
 *         elements in this <code>SerialArray</code> object, with a
 *         separate row for each element
-* @throws SerialException if called, which in turn throws an
+* @throws SerialException if called with the cause set to
-*         <code>UnsupportedOperationException</code>
+*         {@code UnsupportedOperationException}
 */
 public ResultSet getResultSet(long index, int count,
 Map<String,Class<?>> map)
 throws SerialException
 {
-throw new UnsupportedOperationException();
+SerialException se = new SerialException();
-}
+se.initCause(new UnsupportedOperationException());
+throw  se;
+}
 /**
 * Compares this SerialArray to the specified object.  The result is {@code
 * true} if and only if the argument is not {@code null} and is a {@code
 * SerialArray} object whose elements are identical to this object's elements
 /**
 * Returns a clone of this {@code SerialArray}. The copy will contain a
 * reference to a clone of the underlying objects array, not a reference
 * to the original underlying object array of this {@code SerialArray} object.
 *
-* @return  a clone of this SerialArray
+* @return a clone of this SerialArray
 */
 public Object clone() {
 try {
 SerialArray sa = (SerialArray) super.clone();
-sa.elements = Arrays.copyOf(elements, len);
+sa.elements = (elements != null) ? Arrays.copyOf(elements, len) : null;
 return sa;
 } catch (CloneNotSupportedException ex) {
 // this shouldn't happen, since we are Cloneable
 throw new InternalError();
 }
 fields.put("baseTypeName", baseTypeName);
 s.writeFields();
 }
 /**
+* Check to see if this object had previously had its {@code free} method
+* called
+*
+* @throws SerialException
+*/
+private void isValid() throws SerialException {
+if (elements == null) {
+throw new SerialException("Error: You cannot call a method on a "
++ "SerialArray instance once free() has been called.");
+}
+}
+/**
 * The identifier that assists in the serialization of this <code>SerialArray</code>
 * object.
 */
 static final long serialVersionUID = -8466174297270688520L;
 }

changeset 14781	701d0765f75f
parent 14409	d879c92507ec
child 18564	f9db68ff2cbb