1. /*
  2. * @(#)SQLData.java 1.14 00/02/02
  3. *
  4. * Copyright 1998-2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package java.sql;
  11. /**
  12. * The interface used for the custom mapping of SQL user-defined types.
  13. * This interface must be implemented by any Java class that is
  14. * registered in a type mapping. It is expected that this interface
  15. * will normally be implemented by a tool. The methods in this interface
  16. * are called by the driver and are never called by a programmer
  17. * directly.
  18. * @since 1.2
  19. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  20. * 2.0 API</a>
  21. */
  22. public interface SQLData {
  23. /**
  24. * Returns the fully-qualified
  25. * name of the SQL user-defined type that this object represents.
  26. * This method is called by the JDBC driver to get the name of the
  27. * UDT instance that is being mapped to this instance of
  28. * <code>SQLData</code>.
  29. *
  30. * @return the type name that was passed to the method <code>readSql</code>
  31. * when this object was constructed and populated
  32. * @exception SQLException if there is a database access error
  33. * @since 1.2
  34. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  35. * 2.0 API</a>
  36. */
  37. String getSQLTypeName() throws SQLException;
  38. /**
  39. * Populates this object with data read from the database.
  40. * The implementation of the method must follow this protocol:
  41. * <UL>
  42. * <LI>It must read each of the attributes or elements of the SQL
  43. * type from the given input stream. This is done
  44. * by calling a method of the input stream to read each
  45. * item, in the order that they appear in the SQL definition
  46. * of the type.
  47. * <LI>The method <code>readSQL</code> then
  48. * assigns the data to appropriate fields or
  49. * elements (of this or other objects).
  50. * Specifically, it must call the appropriate <code>SQLInput.readXXX</code>
  51. * method(s) to do the following:
  52. * for a distinct type, read its single data element;
  53. * for a structured type, read a value for each attribute of the SQL type.
  54. * </UL>
  55. * The JDBC driver initializes the input stream with a type map
  56. * before calling this method, which is used by the appropriate
  57. * <code>SQLInput.readXXX</code> method on the stream.
  58. *
  59. * @param stream the <code>SQLInput</code> object from which to read the data for
  60. * the value that is being custom mapped
  61. * @param typeName the SQL type name of the value on the data stream
  62. * @exception SQLException if there is a database access error
  63. * @see SQLInput
  64. */
  65. void readSQL (SQLInput stream, String typeName) throws SQLException;
  66. /**
  67. * Writes this object to the given SQL data stream, converting it back to
  68. * its SQL value in the data source.
  69. * The implementation of the method must follow this protocol:<BR>
  70. * It must write each of the attributes of the SQL type
  71. * to the given output stream. This is done by calling a
  72. * method of the output stream to write each item, in the order that
  73. * they appear in the SQL definition of the type.
  74. * Specifically, it must call the appropriate <code>SQLOutput.writeXXX</code>
  75. * method(s) to do the following:
  76. * for a Distinct Type, write its single data element;
  77. * for a Structured Type, write a value for each attribute of the SQL type.
  78. *
  79. * @param stream the <code>SQLOutput</code> object to which to write the data for
  80. * the value that was custom mapped
  81. * @exception SQLException if there is a database access error
  82. * @see SQLOutput
  83. * @since 1.2
  84. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  85. * 2.0 API</a>
  86. */
  87. void writeSQL (SQLOutput stream) throws SQLException;
  88. }