1 /* 2 * @(#)Ref.java 1.27 04/05/05 3 * 4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.sql; 9 10 /** 11 * The mapping in the Java programming language of an SQL <code>REF</code> 12 * value, which is a reference to an SQL structured type value in the database. 13 * <P> 14 * SQL <code>REF</code> values are stored in a table that contains 15 * instances of a referenceable SQL structured type, and each <code>REF</code> 16 * value is a unique identifier for one instance in that table. 17 * An SQL <code>REF</code> value may be used in place of the 18 * SQL structured type it references, either as a column value in a 19 * table or an attribute value in a structured type. 20 * <P> 21 * Because an SQL <code>REF</code> value is a logical pointer to an 22 * SQL structured type, a <code>Ref</code> object is by default also a logical 23 * pointer. Thus, retrieving an SQL <code>REF</code> value as 24 * a <code>Ref</code> object does not materialize 25 * the attributes of the structured type on the client. 26 * <P> 27 * A <code>Ref</code> object can be stored in the database using the 28 * <code>PreparedStatement.setRef</code> method. 29 * 30 * @see Struct 31 * @since 1.2 32 */ 33 public interface Ref { 34 35 /** 36 * Retrieves the fully-qualified SQL name of the SQL structured type that 37 * this <code>Ref</code> object references. 38 * 39 * @return the fully-qualified SQL name of the referenced SQL structured type 40 * @exception SQLException if a database access error occurs 41 * @since 1.2 42 */ 43 String getBaseTypeName() throws SQLException; 44 45 /** 46 * Retrieves the referenced object and maps it to a Java type 47 * using the given type map. 48 * 49 * @param map a <code>java.util.Map</code> object that contains 50 * the mapping to use (the fully-qualified name of the SQL 51 * structured type being referenced and the class object for 52 * <code>SQLData</code> implementation to which the SQL 53 * structured type will be mapped) 54 * @return a Java <code>Object</code> that is the custom mapping for 55 * the SQL structured type to which this <code>Ref</code> 56 * object refers 57 * @exception SQLException if a database access error occurs 58 * @since 1.4 59 * @see #setObject 60 */ 61 Object getObject(java.util.Map<String,Class<?>> map) throws SQLException; 62 63 64 /** 65 * Retrieves the SQL structured type instance referenced by 66 * this <code>Ref</code> object. If the connection's type map has an entry 67 * for the structured type, the instance will be custom mapped to 68 * the Java class indicated in the type map. Otherwise, the 69 * structured type instance will be mapped to a <code>Struct</code> object. 70 * 71 * @return a Java <code>Object</code> that is the mapping for 72 * the SQL structured type to which this <code>Ref</code> 73 * object refers 74 * @exception SQLException if a database access error occurs 75 * @since 1.4 76 * @see #setObject 77 */ 78 Object getObject() throws SQLException; 79 80 /** 81 * Sets the structured type value that this <code>Ref</code> 82 * object references to the given instance of <code>Object</code>. 83 * The driver converts this to an SQL structured type when it 84 * sends it to the database. 85 * 86 * @param value an <code>Object</code> representing the SQL 87 * structured type instance that this 88 * <code>Ref</code> object will reference 89 * @exception SQLException if a database access error occurs 90 * @since 1.4 91 * @see #getObject() 92 * @see #getObject(Map) 93 * @see PreparedStatement#setObject(int, Object) 94 * @see CallableStatement#setObject(String, Object) 95 */ 96 void setObject(Object value) throws SQLException; 97 98 } 99 100 101