001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: /**
021: * An interface for the custom mapping of an SQL User Defined Type (UDT) to a
022: * Java Class. The Java Class object will be added to the Connection's type map
023: * with the SQL Name of the UDT which it maps.
024: * <p>
025: * Usually within an implementation of SQLData, there is a corresponding field
026: * for every attribute of an SQL type, or only one field if the type is SQL
027: * DISTINCT. When the UDT is returned within a ResultSet, it is accessed with
028: * the ResultSet.getObject method and is returned as an Object which is an
029: * instance of the class defined by the SQLData mapping. The application can use
030: * this object just like any other Java object and can store changes back into
031: * the database using the PreparedStatement.setObject method which performs the
032: * reverse mapping into the SQL UDT.
033: * <p>
034: * It is standard for an implementation for a custom mapping to be generated by
035: * a tool. The tool usually requires the name of the SQL UDT, the name of the
036: * class which it is going to be mapped to, and the field names to which the UDT
037: * attributes will be mapped. The tool can then implement the SQLData readSQL
038: * and writeSQL methods. readSQL reads attributes from an SQLInput object, and
039: * writeSQL writes them. This is done via SQLInput and SQLOutput method calls
040: * respectively
041: * <p>
042: * Ordinarily a programmer would not call SQLData methods directly. Similarly
043: * SQLInput and SQLOutput methods are not usually called directly.
044: */
045: public interface SQLData {
046:
047: /**
048: * Gets the SQL name of the User Defined Type (UDT) that this object
049: * represents. This method, usually invoked by the JDBC driver, retrieves
050: * the name of the UDT instance associated with this SQLData object.
051: *
052: * @return a string with UDT type name for this object mapping, passed to
053: * readSQL when the object was created
054: * @throws SQLException
055: * if a database error occurs
056: */
057: public String getSQLTypeName() throws SQLException;
058:
059: /**
060: * Reads data from the database into this object. This method follows these
061: * steps:
062: * <ul>
063: * <li>Utilize the passed input stream to read the attributes or entries of
064: * the SQL type</li>
065: * <li>This is carried out by reading each entry from the input stream,
066: * ordered as the are the SQL definition.</li>
067: * <li>Assign the data to the appropriate fields or elements. This is done
068: * by calling the relevant reader method for the type involved (eg.
069: * SQLInput.readString, SQLInputreadBigDecimal). If the type is distinct,
070: * then read its only data entry. For structured types, read every entry.</li>
071: * </ul>
072: * The supplied input stream is typically initialized by the calling JDBC
073: * driver with the type map before readSQL is called.
074: *
075: * @param stream
076: * the SQLInput stream from which the type map data is read for
077: * the custom mapping
078: * @param typeName
079: * the SQL Type name for the type which is being mapped
080: * @throws SQLException
081: * if a database error occurs
082: */
083: public void readSQL(SQLInput stream, String typeName)
084: throws SQLException;
085:
086: /**
087: * Writes the object to a supplied SQLOutput data stream, writing it out as
088: * an SQL value to the data source.
089: * <p>
090: * This method follows the following steps:
091: * <ul>
092: * <li>Write each attribute of the SQL type to the output stream.</li>
093: * <li>Write each item by calling a method on the output stream, in the
094: * order they appear in the SQL definition of the type. Use the appropriate
095: * SQLOutput methods (eg. writeInt, writeString). Write a single data
096: * element for a Distinct type. For a Structured type, write a value for
097: * each attribute of the the SQL type.</li>
098: * </ul>
099: *
100: * @param stream
101: * the SQLOutput stream to use to write out the data for the
102: * custom mapping
103: * @throws SQLException
104: * if a database error occurs
105: */
106: public void writeSQL(SQLOutput stream) throws SQLException;
107: }
|