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
18package 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 */
48public 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     */
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     */
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     */
113    public void writeSQL(SQLOutput stream) throws SQLException;
114}
115