modules/sql/src/main/java/java/sql/SQLData.java

/* 
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package java.sql;

/**
 * An interface for the custom mapping of an SQL <i>User Defined Type</i> (UDT)
 * to a Java class. The Java class object is added to the connection's type map
 * paired with the SQL name of the corresponding UDT.
 * <p>
 * Usually within an implementation of {@code SQLData}, there is a corresponding
 * field for every attribute of an SQL type, but only one field, if the type is
 * SQL {@code DISTINCT}. When the UDT is returned within a {@code ResultSet}, it
 * is accessed with the {@link ResultSet#getObject} method and is returned as an
 * object which is an instance of the class defined by the {@code SQLData}
 * mapping. The application can use this object just like any other Java object
 * and can store changes back into the database using the
 * {@link PreparedStatement#setObject} method which performs the reverse mapping
 * into the SQL {@code UDT}.
 * <p>
 * Normally the implementation of a custom mapping is generated by
 * a tool requiring the name of the SQL {@code UDT}, the name
 * of the class which it is going to be mapped to, and the field names to which
 * the UDT attributes are mapped. The tool can then implement the {@code
 * SQLData}, {@code readSQL}, and {@code writeSQL} methods. {@code readSQL} reads
 * attributes from an {@code SQLInput} object, and {@code writeSQL} writes them.
 * This is done via {@code SQLInput} and {@code SQLOutput} method calls
 * respectively.
 * <p>
 * Ordinarily an application would not call {@code SQLData} methods directly.
 * Similarly {@code SQLInput} and {@code SQLOutput} methods are not usually
 * called directly.
 */
public interface SQLData {

    /**
     * Gets the SQL name of the <i>User Defined Type</i> (UDT) that this object
     * represents. This method, usually invoked by the JDBC driver, retrieves
     * the name of the UDT instance associated with this {@code SQLData} object.
     * 
     * @return a string with UDT type name for this object mapping, passed to
     *         {@code readSQL} when the object was created.
     * @throws SQLException
     *             if a database error occurs.
     */
    public String getSQLTypeName() throws SQLException;

    /**
     * Reads data from the database into this object. This method follows these
     * steps:
     * <p>
     * <ul>
     * <li>Utilize the passed input stream to read the attributes or entries of
     * the SQL type</li>
     * <li>This is carried out by reading each entry from the input stream,
     * ordered as they are in the SQL definition.</li>
     * <li>Assign the data to the appropriate fields or elements. This is done
     * by calling the relevant reader method for the type involved (e.g. {@code
     * SQLInput.readString}, {@code SQLInputreadBigDecimal}). If the type is
     * distinct, then read its only data entry. For structured types, read every
     * entry.</li>
     * </ul>
     * <p>
     * The supplied input stream is typically initialized by the calling JDBC
     * driver with the type map before {@code readSQL} is called.
     *
     * @param stream
     *            the {@code SQLInput} stream from which the type map data is
     *            read for the custom mapping.
     * @param typeName
     *            the SQL type name for the type which is being mapped.
     * @throws SQLException
     *             if a database error occurs.
     * @see SQLInput
     */
    public void readSQL(SQLInput stream, String typeName) throws SQLException;

    /**
     * Writes the object to a supplied {@code SQLOutput} data stream, writing it
     * out as an SQL value to the data source.
     * <p>
     * This method follows the following steps:
     * <ul>
     * <li>Write each attribute of the SQL type to the output stream.</li>
     * <li>Write each item by calling a method on the output stream, in the
     * order they appear in the SQL definition of the type. Use the appropriate
     * {@code SQLOutput} methods (e.g. {@code writeInt}, {@code writeString}).
     * Write a single data element for a distinct type. For a structured type,
     * write a value for each attribute of the the SQL type.</li>
     * </ul>
     * 
     * @param stream
     *            the {@code SQLOutput} stream to use to write out the data for
     *            the custom mapping.
     * @throws SQLException
     *             if a database error occurs.
     * @see SQLOutput
     */
    public void writeSQL(SQLOutput stream) throws SQLException;
}