1 package com.atlassian.refapp.api;
2
3 import javax.sql.DataSource;
4 import java.sql.Connection;
5 import java.sql.SQLException;
6 import java.util.Optional;
7
8 /**
9 * Provides a database connection for use by core and plugins.
10 * <p>
11 * An H2 server (internal) database will be provided, unless the user specifies an external database via system properties:
12 * <p>
13 * <code>refapp.jdbc.external</code> set this to true to use an external database
14 * <code>refapp.jdbc.driver.class.name</code> {@link java.sql.Driver} implementation to use
15 * <code>refapp.jdbc.app.url</code> mandatory jdbc url
16 * <code>refapp.jdbc.app.schema</code> optional jdbc schema - don't specify if you don't use a schema e.g. mysql, however must still be specified for all other databases; don't rely on the default schema
17 * <code>refapp.jdbc.app.user</code> mandatory jdbc user
18 * <code>refapp.jdbc.app.pass</code> mandatory jdbc password
19 * <code>refapp.jdbc.app.val.query</code> optional validation query for drivers that don't support {@link Connection#isValid(int)}
20 */
21 public interface ConnectionProvider {
22
23 /**
24 * Provides a connection from a pool.
25 * <p>
26 * Users may close the connection.
27 * Users may create transactions within the connection.
28 *
29 * @return valid connection
30 * @throws java.sql.SQLException on any failure to provide connection
31 */
32 Connection connection() throws SQLException;
33
34 /**
35 * Provides the {@link DataSource} used to source any database connections
36 *
37 * @return valid DataSource
38 * @since 3.2
39 */
40 DataSource dataSource();
41
42 /**
43 * Returns the configured schema name (if any)
44 *
45 * @return schema name, if there is one
46 * @since 3.2
47 */
48 Optional<String> schema();
49
50 /**
51 * Returns the configured database driver class name
52 *
53 * @return fully qualified driver class name
54 * @since 3.2
55 */
56 String driverClassName();
57 }