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 import java.util.Map;
21 
22 /**
23  * This interface represents an SQL Ref - a data object containing a cursor
24  * or pointer to a result table.
25  * <p>
26  * The data structure identified by an instance of Ref is held in the
27  * database, so the data is not necessarily read and converted
28  * into a Java object until {@code getObject} is called. However, if
29  * the database supports the {@code Ref} type, it is not typically
30  * necessary to get the underlying object before using it in a method call -
31  * the {@code Ref} object can be used in place of the data structure.
32  * <p>
33  * A {@code Ref} object is stored into the database using the
34  * {@link PreparedStatement#setRef(int, Ref)} method.
35  */
36 public interface Ref {
37 
38     /**
39      * Gets the fully-qualified SQL name of the SQL structured type that this
40      * {@code Ref} references.
41      *
42      * @return the fully qualified name of the SQL structured type.
43      * @throws SQLException
44      *             if there is a database error.
45      */
getBaseTypeName()46     public String getBaseTypeName() throws SQLException;
47 
48     /**
49      * Gets the SQL structured type instance referenced by this {@code Ref}.
50      *
51      * @return a Java object whose type is defined by the mapping for the SQL
52      *         structured type.
53      * @throws SQLException
54      *             if there is a database error.
55      */
getObject()56     public Object getObject() throws SQLException;
57 
58     /**
59      * Returns the associated object and uses the relevant mapping to convert it
60      * to a Java type.
61      *
62      * @param map
63      *            the mapping for type conversion.
64      * @return a Java object whose type is defined by the mapping for the SQL
65      *         structured type.
66      * @throws SQLException
67      *             if there is a database error.
68      */
getObject(Map<String, Class<?>> map)69     public Object getObject(Map<String, Class<?>> map) throws SQLException;
70 
71     /**
72      * Sets the value of the structured type that this {@code Ref} references to
73      * a supplied object.
74      *
75      * @param value
76      *            the {@code Object} representing the new SQL structured type
77      *            that this {@code Ref} references.
78      * @throws SQLException
79      *             if there is a database error.
80      */
setObject(Object value)81     public void setObject(Object value) throws SQLException;
82 }
83