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