1. /*
  2. * @(#)Driver.java 1.18 00/02/02
  3. *
  4. * Copyright 1996-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 that every driver class must implement.
  13. * <P>The Java SQL framework allows for multiple database drivers.
  14. *
  15. * <P>Each driver should supply a class that implements
  16. * the Driver interface.
  17. *
  18. * <P>The DriverManager will try to load as many drivers as it can
  19. * find and then for any given connection request, it will ask each
  20. * driver in turn to try to connect to the target URL.
  21. *
  22. * <P>It is strongly recommended that each Driver class should be
  23. * small and standalone so that the Driver class can be loaded and
  24. * queried without bringing in vast quantities of supporting code.
  25. *
  26. * <P>When a Driver class is loaded, it should create an instance of
  27. * itself and register it with the DriverManager. This means that a
  28. * user can load and register a driver by calling
  29. * <pre>
  30. * <code>Class.forName("foo.bah.Driver")</code>
  31. * </pre>
  32. *
  33. * @see DriverManager
  34. * @see Connection
  35. */
  36. public interface Driver {
  37. /**
  38. * Attempts to make a database connection to the given URL.
  39. * The driver should return "null" if it realizes it is the wrong kind
  40. * of driver to connect to the given URL. This will be common, as when
  41. * the JDBC driver manager is asked to connect to a given URL it passes
  42. * the URL to each loaded driver in turn.
  43. *
  44. * <P>The driver should raise a SQLException if it is the right
  45. * driver to connect to the given URL, but has trouble connecting to
  46. * the database.
  47. *
  48. * <P>The java.util.Properties argument can be used to passed arbitrary
  49. * string tag/value pairs as connection arguments.
  50. * Normally at least "user" and "password" properties should be
  51. * included in the Properties.
  52. *
  53. * @param url the URL of the database to which to connect
  54. * @param info a list of arbitrary string tag/value pairs as
  55. * connection arguments. Normally at least a "user" and
  56. * "password" property should be included.
  57. * @return a <code>Connection</code> object that represents a
  58. * connection to the URL
  59. * @exception SQLException if a database access error occurs
  60. */
  61. Connection connect(String url, java.util.Properties info)
  62. throws SQLException;
  63. /**
  64. * Returns true if the driver thinks that it can open a connection
  65. * to the given URL. Typically drivers will return true if they
  66. * understand the subprotocol specified in the URL and false if
  67. * they don't.
  68. *
  69. * @param url the URL of the database
  70. * @return true if this driver can connect to the given URL
  71. * @exception SQLException if a database access error occurs
  72. */
  73. boolean acceptsURL(String url) throws SQLException;
  74. /**
  75. * Gets information about the possible properties for this driver.
  76. * <p>The getPropertyInfo method is intended to allow a generic GUI tool to
  77. * discover what properties it should prompt a human for in order to get
  78. * enough information to connect to a database. Note that depending on
  79. * the values the human has supplied so far, additional values may become
  80. * necessary, so it may be necessary to iterate though several calls
  81. * to getPropertyInfo.
  82. *
  83. * @param url the URL of the database to which to connect
  84. * @param info a proposed list of tag/value pairs that will be sent on
  85. * connect open
  86. * @return an array of DriverPropertyInfo objects describing possible
  87. * properties. This array may be an empty array if no properties
  88. * are required.
  89. * @exception SQLException if a database access error occurs
  90. */
  91. DriverPropertyInfo[] getPropertyInfo(String url, java.util.Properties info)
  92. throws SQLException;
  93. /**
  94. * Gets the driver's major version number. Initially this should be 1.
  95. * @return this driver's major version number
  96. */
  97. int getMajorVersion();
  98. /**
  99. * Gets the driver's minor version number. Initially this should be 0.
  100. * @return this driver's minor version number
  101. */
  102. int getMinorVersion();
  103. /**
  104. * Reports whether this driver is a genuine JDBC
  105. * COMPLIANT<sup><font size=-2>TM</font></sup> driver.
  106. * A driver may only report true here if it passes the JDBC compliance
  107. * tests; otherwise it is required to return false.
  108. *
  109. * JDBC compliance requires full support for the JDBC API and full support
  110. * for SQL 92 Entry Level. It is expected that JDBC compliant drivers will
  111. * be available for all the major commercial databases.
  112. *
  113. * This method is not intended to encourage the development of non-JDBC
  114. * compliant drivers, but is a recognition of the fact that some vendors
  115. * are interested in using the JDBC API and framework for lightweight
  116. * databases that do not support full database functionality, or for
  117. * special databases such as document information retrieval where a SQL
  118. * implementation may not be feasible.
  119. */
  120. boolean jdbcCompliant();
  121. }