1. /*
  2. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  3. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4. */
  5. package javax.sql;
  6. import java.sql.Connection;
  7. import java.sql.SQLException;
  8. /**
  9. * <p>A DataSource object is a factory for Connection objects. An
  10. * object that implements the DataSource interface will typically be
  11. * registered with a JNDI service provider. A JDBC driver that is
  12. * accessed via the DataSource API does not automatically register
  13. * itself with the DriverManager.
  14. */
  15. public interface DataSource {
  16. /**
  17. * <p>Attempt to establish a database connection.
  18. *
  19. * @return a Connection to the database
  20. * @exception SQLException if a database-access error occurs.
  21. */
  22. Connection getConnection() throws SQLException;
  23. /**
  24. * <p>Attempt to establish a database connection.
  25. *
  26. * @param user the database user on whose behalf the Connection is
  27. * being made
  28. * @param password the user's password
  29. * @return a Connection to the database
  30. * @exception SQLException if a database-access error occurs.
  31. */
  32. Connection getConnection(String username, String password)
  33. throws SQLException;
  34. /**
  35. * <p>Get the log writer for this data source.
  36. *
  37. * <p>The log writer is a character output stream to which all logging
  38. * and tracing messages for this data source object instance will be
  39. * printed. This includes messages printed by the methods of this
  40. * object, messages printed by methods of other objects manufactured
  41. * by this object, and so on. Messages printed to a data source
  42. * specific log writer are not printed to the log writer associated
  43. * with the java.sql.Drivermanager class. When a DataSource object is
  44. * created the log writer is initially null, in other words, logging
  45. * is disabled.
  46. *
  47. * @return the log writer for this data source, null if disabled
  48. * @exception SQLException if a database-access error occurs.
  49. */
  50. java.io.PrintWriter getLogWriter() throws SQLException;
  51. /**
  52. * <p>Set the log writer for this data source.
  53. *
  54. * <p>The log writer is a character output stream to which all logging
  55. * and tracing messages for this data source object instance will be
  56. * printed. This includes messages printed by the methods of this
  57. * object, messages printed by methods of other objects manufactured
  58. * by this object, and so on. Messages printed to a data source
  59. * specific log writer are not printed to the log writer associated
  60. * with the java.sql.Drivermanager class. When a DataSource object is
  61. * created the log writer is initially null, in other words, logging
  62. * is disabled.
  63. *
  64. * @param out the new log writer; to disable, set to null
  65. * @exception SQLException if a database-access error occurs.
  66. */
  67. void setLogWriter(java.io.PrintWriter out) throws SQLException;
  68. /**
  69. * <p>Sets the maximum time in seconds that this data source will wait
  70. * while attempting to connect to a database. A value of zero
  71. * specifies that the timeout is the default system timeout
  72. * if there is one; otherwise it specifies that there is no timeout.
  73. * When a DataSource object is created the login timeout is
  74. * initially zero.
  75. *
  76. * @param seconds the data source login time limit
  77. * @exception SQLException if a database access error occurs.
  78. */
  79. void setLoginTimeout(int seconds) throws SQLException;
  80. /**
  81. * Gets the maximum time in seconds that this data source can wait
  82. * while attempting to connect to a database. A value of zero
  83. * means that the timeout is the default system timeout
  84. * if there is one; otherwise it means that there is no timeout.
  85. * When a DataSource object is created the login timeout is
  86. * initially zero.
  87. *
  88. * @return the data source login time limit
  89. * @exception SQLException if a database access error occurs.
  90. */
  91. int getLoginTimeout() throws SQLException;
  92. }