| /* | |
| * 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. | |
| * </p> | |
| * | |
| * @since Android 1.0 | |
| */ | |
| 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. | |
| * @since Android 1.0 | |
| */ | |
| 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> | |
| * <p> | |
| * The supplied input stream is typically initialized by the calling JDBC | |
| * driver with the type map before {@code readSQL} is called. | |
| * </p> | |
| * | |
| * @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 | |
| * @since Android 1.0 | |
| */ | |
| 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> | |
| * </p> | |
| * | |
| * @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 | |
| * @since Android 1.0 | |
| */ | |
| public void writeSQL(SQLOutput stream) throws SQLException; | |
| } |