1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.sql; 19 20 /** 21 * An interface for the custom mapping of an SQL <i>User Defined Type</i> (UDT) 22 * to a Java class. The Java class object is added to the connection's type map 23 * paired with the SQL name of the corresponding UDT. 24 * <p> 25 * Usually within an implementation of {@code SQLData}, there is a corresponding 26 * field for every attribute of an SQL type, but only one field, if the type is 27 * SQL {@code DISTINCT}. When the UDT is returned within a {@code ResultSet}, it 28 * is accessed with the {@link ResultSet#getObject} method and is returned as an 29 * object which is an instance of the class defined by the {@code SQLData} 30 * mapping. The application can use this object just like any other Java object 31 * and can store changes back into the database using the 32 * {@link PreparedStatement#setObject} method which performs the reverse mapping 33 * into the SQL {@code UDT}. 34 * <p> 35 * Normally the implementation of a custom mapping is generated by 36 * a tool requiring the name of the SQL {@code UDT}, the name 37 * of the class which it is going to be mapped to, and the field names to which 38 * the UDT attributes are mapped. The tool can then implement the {@code 39 * SQLData}, {@code readSQL}, and {@code writeSQL} methods. {@code readSQL} reads 40 * attributes from an {@code SQLInput} object, and {@code writeSQL} writes them. 41 * This is done via {@code SQLInput} and {@code SQLOutput} method calls 42 * respectively. 43 * <p> 44 * Ordinarily an application would not call {@code SQLData} methods directly. 45 * Similarly {@code SQLInput} and {@code SQLOutput} methods are not usually 46 * called directly. 47 */ 48 public interface SQLData { 49 50 /** 51 * Gets the SQL name of the <i>User Defined Type</i> (UDT) that this object 52 * represents. This method, usually invoked by the JDBC driver, retrieves 53 * the name of the UDT instance associated with this {@code SQLData} object. 54 * 55 * @return a string with UDT type name for this object mapping, passed to 56 * {@code readSQL} when the object was created. 57 * @throws SQLException 58 * if a database error occurs. 59 */ getSQLTypeName()60 public String getSQLTypeName() throws SQLException; 61 62 /** 63 * Reads data from the database into this object. This method follows these 64 * steps: 65 * <p> 66 * <ul> 67 * <li>Utilize the passed input stream to read the attributes or entries of 68 * the SQL type</li> 69 * <li>This is carried out by reading each entry from the input stream, 70 * ordered as they are in the SQL definition.</li> 71 * <li>Assign the data to the appropriate fields or elements. This is done 72 * by calling the relevant reader method for the type involved (e.g. {@code 73 * SQLInput.readString}, {@code SQLInputreadBigDecimal}). If the type is 74 * distinct, then read its only data entry. For structured types, read every 75 * entry.</li> 76 * </ul> 77 * <p> 78 * The supplied input stream is typically initialized by the calling JDBC 79 * driver with the type map before {@code readSQL} is called. 80 * 81 * @param stream 82 * the {@code SQLInput} stream from which the type map data is 83 * read for the custom mapping. 84 * @param typeName 85 * the SQL type name for the type which is being mapped. 86 * @throws SQLException 87 * if a database error occurs. 88 * @see SQLInput 89 */ readSQL(SQLInput stream, String typeName)90 public void readSQL(SQLInput stream, String typeName) throws SQLException; 91 92 /** 93 * Writes the object to a supplied {@code SQLOutput} data stream, writing it 94 * out as an SQL value to the data source. 95 * <p> 96 * This method follows the following steps: 97 * <ul> 98 * <li>Write each attribute of the SQL type to the output stream.</li> 99 * <li>Write each item by calling a method on the output stream, in the 100 * order they appear in the SQL definition of the type. Use the appropriate 101 * {@code SQLOutput} methods (e.g. {@code writeInt}, {@code writeString}). 102 * Write a single data element for a distinct type. For a structured type, 103 * write a value for each attribute of the the SQL type.</li> 104 * </ul> 105 * 106 * @param stream 107 * the {@code SQLOutput} stream to use to write out the data for 108 * the custom mapping. 109 * @throws SQLException 110 * if a database error occurs. 111 * @see SQLOutput 112 */ writeSQL(SQLOutput stream)113 public void writeSQL(SQLOutput stream) throws SQLException; 114 } 115