Module org.apache.derby.tools
Package org.apache.derby.jdbc

## Class BasicEmbeddedDataSource40

- java.lang.Object
- - org.apache.derby.jdbc.BasicEmbeddedDataSource40

- All Implemented Interfaces:
    `Serializable`, `Wrapper`, `CommonDataSource`, `DataSource`, `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
  Direct Known Subclasses:
    `BasicEmbeddedConnectionPoolDataSource40`, `BasicEmbeddedXADataSource40`, `org.apache.derby.jdbc.ReferenceableDataSource`

      public class BasicEmbeddedDataSource40
      extends Object
      implements DataSource, Serializable, org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface

  This data source is suitable for an application using embedded Derby, running on Java 8 Compact Profile 2 or higher.

  BasicEmbeddedDataSource40 is similar to EmbeddedDataSource, but does not support JNDI naming, i.e. it does not implement `javax.naming.Referenceable`.

  The standard attributes provided are, cf. e.g. table 9.1 in the JDBC 4.2 specification.
  - databaseName
  - dataSourceName
  - description
  - password
  - user
  These standard attributes are not supported:
  - networkProtocol
  - portNumber
  - roleName
  - serverName
  The embedded Derby driver also supports these attributes:
  - loginTimeout
  @see javax.sql.CommonDataSource set/get
  - logWriter
  @see javax.sql.CommonDataSource set/get
  - createDatabase
  - connectionAttributes
  - shutdownDatabase
  - attributesAsPassword
  See the specific Derby DataSource implementation for details on their meaning.

  See also the JDBC specifications for more details.
  See Also:
    `EmbeddedDataSource`, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BasicEmbeddedDataSource40()` | Constructs a basic embedded data source.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object other)` |
    `boolean` | `getAttributesAsPassword()` | Return the value of the `attributesAsPassword` property, cf.
    `Connection` | `getConnection()` | Attempt to establish a database connection.
    `Connection` | `getConnection​(String username, String password)` | Attempt to establish a database connection with the given username and password.
    `Connection` | `getConnection​(String username, String password, boolean requestPassword)` | Get a user connection: minion method.
    `String` | `getConnectionAttributes()` |
    `String` | `getCreateDatabase()` |
    `String` | `getDatabaseName()` |
    `String` | `getDataSourceName()` |
    `String` | `getDescription()` |
    `int` | `getLoginTimeout()` | Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.
    `PrintWriter` | `getLogWriter()` | Get the log writer for this data source.
    `Logger` | `getParentLogger()` |
    `String` | `getPassword()` |
    `String` | `getShutdownDatabase()` |
    `String` | `getUser()` |
    `int` | `hashCode()` |
    `boolean` | `isWrapperFor​(Class<?> interFace)` | Returns false unless `interFace` is implemented.
    `void` | `setAttributesAsPassword​(boolean attributesAsPassword)` | Set `attributeAsPassword` property to enable passing connection request attributes in the password argument of `getConnection(String,String)`.
    `void` | `setConnectionAttributes​(String prop)` | Set this property to pass in more Derby specific connection URL attributes.
    `void` | `setCreateDatabase​(String create)` | Set this property to create a new database.
    `void` | `setDatabaseName​(String databaseName)` | Set the database name.
    `void` | `setDataSourceName​(String dsn)` | Set the data source name.
    `void` | `setDescription​(String desc)` | Set the data source descripton.
    `void` | `setLoginTimeout​(int seconds)` | Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
    `void` | `setLogWriter​(PrintWriter out)` | Set the log writer for this data source.
    `void` | `setPassword​(String password)` | Set the `password` property for the data source.
    `void` | `setShutdownDatabase​(String shutdown)` | Set this property if you wish to shutdown the database identified by `databaseName`.
    `void` | `setUser​(String user)` | Set the `user` property for the data source.
    `<T> T` | `unwrap​(Class<T> iface)` | Returns `this` if this class implements the specified interface.

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface javax.sql.CommonDataSource

      `createShardingKeyBuilder`

    - ### Methods inherited from interface javax.sql.DataSource

      `createConnectionBuilder`

- - ### Constructor Detail

    - #### BasicEmbeddedDataSource40

          public BasicEmbeddedDataSource40()

      Constructs a basic embedded data source. See the class Javadoc.

  - ### Method Detail

    - #### setDatabaseName

          public void setDatabaseName​(String databaseName)

      Set the database name. Setting this property is mandatory. If a database named wombat at g:/db needs to be accessed, database name should be set to "g:/db/wombat". The database will be booted if it is not already running in the system.
      Specified by:
        `setDatabaseName` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `databaseName` - the name of the database

    - #### getDatabaseName

          public String getDatabaseName()

      Specified by:
        `getDatabaseName` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        the database name set by `setDatabaseName(java.lang.String)`.

    - #### setDataSourceName

          public void setDataSourceName​(String dsn)

      Set the data source name. The property is not mandatory. It is used for informational purposes only.
      Specified by:
        `setDataSourceName` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `dsn` - the name of the data source

    - #### getDataSourceName

          public String getDataSourceName()

      Specified by:
        `getDataSourceName` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        data source name as set in `setDataSourceName(java.lang.String)`.

    - #### setDescription

          public void setDescription​(String desc)

      Set the data source descripton. This property is not mandatory. It is used for informational purposes only.
      Specified by:
        `setDescription` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `desc` - the description of the data source

    - #### getDescription

          public String getDescription()

      Specified by:
        `getDescription` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        the description as set in `setDescription(java.lang.String)`.

    - #### setUser

          public void setUser​(String user)

      Set the `user` property for the data source.

      This is user name for any data source `getConnection()` call that takes no arguments.
      Specified by:
        `setUser` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `user` - The user

    - #### getUser

          public String getUser()

      Specified by:
        `getUser` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        the user name as set by `setUser(java.lang.String)`.

    - #### setPassword

          public void setPassword​(String password)

      Set the `password` property for the data source.

      This is user's password for any data source `getConnection()` call that takes no arguments.
      Specified by:
        `setPassword` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `password` - The password in plain text

    - #### getPassword

          public String getPassword()

      Specified by:
        `getPassword` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        the password as set in `setPassword(java.lang.String)`.

    - #### getLoginTimeout

          public int getLoginTimeout()
                              throws SQLException

      Gets the maximum time in seconds that this data source can wait while attempting to connect to a database. A value of zero means that the timeout is the default system timeout if there is one; otherwise it means that there is no timeout. When a data source object is created, the login timeout is initially zero. See `setLoginTimeout(int)`.
      Specified by:
        `getLoginTimeout` in interface `CommonDataSource`
      Specified by:
        `getLoginTimeout` in interface `DataSource`
      Returns:
        the data source login time limit
      Throws:
        `SQLException` - if a database access error occurs.

    - #### setLoginTimeout

          public void setLoginTimeout​(int seconds)
                               throws SQLException

      Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise it specifies that there is no timeout. When a data source object is created, the login timeout is initially zero.

      Derby currently ignores this property.
      Specified by:
        `setLoginTimeout` in interface `CommonDataSource`
      Specified by:
        `setLoginTimeout` in interface `DataSource`
      Parameters:
        `seconds` - the data source login time limit
      Throws:
        `SQLException` - if a database access error occurs.

    - #### getLogWriter

          public PrintWriter getLogWriter()
                                   throws SQLException

      Get the log writer for this data source.

      The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the `java.sql.Drivermanager` class. When a data source object is created the log writer is initially null, in other words, logging is disabled.
      Specified by:
        `getLogWriter` in interface `CommonDataSource`
      Specified by:
        `getLogWriter` in interface `DataSource`
      Returns:
        the log writer for this data source, null if disabled
      Throws:
        `SQLException` - if a database-access error occurs.

    - #### setLogWriter

          public void setLogWriter​(PrintWriter out)
                            throws SQLException

      Set the log writer for this data source.

      The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the `java.sql.Drivermanager` class. When a data source object is created the log writer is initially null, in other words, logging is disabled.
      Specified by:
        `setLogWriter` in interface `CommonDataSource`
      Specified by:
        `setLogWriter` in interface `DataSource`
      Parameters:
        `out` - the new log writer; to disable, set to null
      Throws:
        `SQLException` - if a database-access error occurs.

    - #### setCreateDatabase

          public void setCreateDatabase​(String create)

      Set this property to create a new database. If this property is not set, the database (identified by `databaseName`) is assumed to be already existing.
      Specified by:
        `setCreateDatabase` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `create` - if set to the string `"create"`, this data source will try to create a new database of databaseName, or boot the database if one by that name already exists.

    - #### getCreateDatabase

          public String getCreateDatabase()

      Specified by:
        `getCreateDatabase` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        The string `"create"` if create is set, or `null` if not

    - #### setConnectionAttributes

          public void setConnectionAttributes​(String prop)

      Set this property to pass in more Derby specific connection URL attributes.
      Any attributes that can be set using a property of this DataSource implementation (e.g user, password) should not be set in connection attributes. Conflicting settings in connection attributes and properties of the DataSource will lead to unexpected behaviour.
      Specified by:
        `setConnectionAttributes` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `prop` - set to the list of Derby connection attributes separated by semi-colons. E.g., to specify an encryption bootPassword of "x8hhk2adf", and set upgrade to true, do the following:

                 ds.setConnectionAttributes("bootPassword=x8hhk2adf;upgrade=true");

        See the Derby documentation for complete list.

    - #### getConnectionAttributes

          public String getConnectionAttributes()

      Specified by:
        `getConnectionAttributes` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        the Derby specific connection URL attributes, see `setConnectionAttributes(java.lang.String)`.

    - #### setShutdownDatabase

          public void setShutdownDatabase​(String shutdown)

      Set this property if you wish to shutdown the database identified by `databaseName`.
      Specified by:
        `setShutdownDatabase` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `shutdown` - if set to the string `"shutdown"`, this data source will shutdown the database if it is running.

    - #### getShutdownDatabase

          public String getShutdownDatabase()

      Specified by:
        `getShutdownDatabase` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        the string `"shutdown"` if shutdown is set, or null if not, cf. `setShutdownDatabase(java.lang.String)`.

    - #### setAttributesAsPassword

          public void setAttributesAsPassword​(boolean attributesAsPassword)

      Set `attributeAsPassword` property to enable passing connection request attributes in the password argument of `getConnection(String,String)`. If the property is set to `true` then the `password` argument of the `getConnection(String, String)` method call is taken to be a list of connection attributes with the same format as the `connectionAttributes` property.
      Specified by:
        `setAttributesAsPassword` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `attributesAsPassword` - Use `true` to encode password argument as a set of connection attributes in a connection request.

    - #### getAttributesAsPassword

          public boolean getAttributesAsPassword()

      Return the value of the `attributesAsPassword` property, cf. `setAttributesAsPassword(boolean)`.
      Specified by:
        `getAttributesAsPassword` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Returns:
        the value

    - #### equals

          public boolean equals​(Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### getConnection

          public Connection getConnection()
                                   throws SQLException

      Attempt to establish a database connection.
      Specified by:
        `getConnection` in interface `DataSource`
      Returns:
        a Connection to the database
      Throws:
        `SQLException` - if a database-access error occurs.

    - #### getConnection

          public Connection getConnection​(String username,
                                          String password)
                                   throws SQLException

      Attempt to establish a database connection with the given username and password. If the `attributeAsPassword` property is set to true then the password argument is taken to be a list of connection attributes with the same format as the `connectionAttributes` property.
      Specified by:
        `getConnection` in interface `DataSource`
      Parameters:
        `username` - the database user on whose behalf the Connection is being made
        `password` - the user's password
      Returns:
        a Connection to the database
      Throws:
        `SQLException` - if a database-access error occurs.

    - #### getConnection

          public final Connection getConnection​(String username,
                                                String password,
                                                boolean requestPassword)
                                         throws SQLException

      Get a user connection: minion method.
      Specified by:
        `getConnection` in interface `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`
      Parameters:
        `username` - the user name
        `password` - the password
        `requestPassword` - `true` if the password came from the getConnection() call with user and password arguments..
      Returns:
        user connection
      Throws:
        `SQLException`

    - #### isWrapperFor

          public boolean isWrapperFor​(Class<?> interFace)
                               throws SQLException

      Returns false unless `interFace` is implemented.
      Specified by:
        `isWrapperFor` in interface `Wrapper`
      Parameters:
        `interFace` - a class defining an interface
      Returns:
        `true` if this implements the interface or directly or indirectly wraps an object that does
      Throws:
        `SQLException` - if an error occurs while determining whether this is a wrapper for an object with the given interface

    - #### unwrap

          public <T> T unwrap​(Class<T> iface)
                       throws SQLException

      Returns `this` if this class implements the specified interface.
      Specified by:
        `unwrap` in interface `Wrapper`
      Parameters:
        `iface` - a class defining an interface
      Returns:
        an object that implements the interface
      Throws:
        `SQLException` - if no object is found that implements the interface

    - #### getParentLogger

          public Logger getParentLogger()
                                 throws SQLFeatureNotSupportedException

      Specified by:
        `getParentLogger` in interface `CommonDataSource`
      Throws:
        `SQLFeatureNotSupportedException`