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
20import 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 */
36public 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     */
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     */
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     */
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     */
81    public void setObject(Object value) throws SQLException;
82}
83