Overview   Package  Class  Tree  Deprecated  Index  Help 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package org.apache.derby.jdbc

JDBC driver and data source implementations.

See:
          Description

Interface Summary
ClientConnectionPoolDataSourceInterface Specifies Derby extensions to the java.sqlx.ConnectionPoolDataSource.
ClientDataSourceInterface Specifies Derby extensions to the java.sqlx.DataSource API common to all Derby client driver data sources.
ClientXADataSourceInterface Specifies Derby extensions to the java.sqlx.XADataSource.
EmbeddedConnectionPoolDataSourceInterface Common interface of Derby embedded connection pooling data sources.
EmbeddedDataSourceInterface Methods that extend the API of javax.sql.DataSource common for all Derby embedded data sources.
EmbeddedXADataSourceInterface Common interface of Derby embedded XA data sources.
 

Class Summary
AutoloadedDriver This is the dummy driver which is registered with the DriverManager and which is autoloaded by JDBC4.
AutoloadedDriver40 Adds driver functionality which is only visible from JDBC 4.0 onward.
BasicClientConnectionPoolDataSource40 This datasource is suitable for client/server use of Derby, running on Java 8 Compact Profile 2 or higher.
BasicClientDataSource40 This datasource is suitable for client/server use of Derby, running on Java 8 Compact Profile 2 or higher.
BasicClientXADataSource40 This datasource is suitable for client/server use of Derby, running on Java 8 Compact Profile 2 or higher.
BasicEmbeddedConnectionPoolDataSource40 This datasource is suitable for an application using embedded Derby, running on Java 8 Compact Profile 2 or higher.
BasicEmbeddedDataSource40 This datasource is suitable for an application using embedded Derby, running on Java 8 Compact Profile 2 or higher.
BasicEmbeddedXADataSource40 This datasource is suitable for an application using embedded Derby, running on Java 8 Compact Profile 2 or higher.
ClientBaseDataSource Base class for client-side DataSource implementations.
ClientBaseDataSourceRoot Base class for client-side DataSource implementations.
ClientConnectionPoolDataSource This datasource is suitable for a client/server use of Derby, running on full Java SE 5 or 6, corresponding to JDBC 3.0 and 4.0.
ClientConnectionPoolDataSource40 This datasource is suitable for a client/server use of Derby, running on the following platforms: Java SE 7 (JDBC 4.1) and full Java SE 8 (JDBC 4.2).
ClientDataSource This datasource is suitable for a client/server use of Derby, running on full Java SE 5 or 6, corresponding to JDBC 3.0 and 4.0.
ClientDataSource40 This datasource is suitable for a client/server use of Derby, running on the following platforms: Java SE 7 (JDBC 4.1) and full Java SE 8 (JDBC 4.2).
ClientDriver The client JDBC driver (type 4) for Derby.
ClientDriver40 Adds driver functionality which is only visible from JDBC 4.0 onward.
ClientXADataSource This datasource is suitable for a client/server use of Derby, running on full Java SE 5 or 6, corresponding to JDBC 3.0 and 4.0.
ClientXADataSource40 This datasource is suitable for a client/server use of Derby, running on the following platforms: Java SE 7 (JDBC 4.1) and full Java SE 8 (JDBC 4.2).
Driver169 Driver169 - JDBC "driver" for J2ME/CDC/Foundation/JSR169, really the JDBC object factory for the JSR169 environment.
Driver20 This class extends the local JDBC driver in order to determine at JBMS boot-up if the JVM that runs us does support JDBC 2.0.
Driver20.DaemonThreadFactory Thread factory to produce daemon threads which don't block VM shutdown
Driver20.LoginCallable This code is called in a thread which puts time limits on it.
Driver30 This class extends the local20 JDBC driver in order to determine at JBMS boot-up if the JVM that runs us does support JDBC 3.0.
Driver40  
EmbeddedBaseDataSource Derby embedded data source implementation base class.
EmbeddedConnectionPoolDataSource This datasource is suitable for an application using embedded Derby, running on full Java SE 5 or 6, corresponding to JDBC 3.0 and 4.0.
EmbeddedConnectionPoolDataSource40 This datasource is suitable for an application using embedded Derby, running on the following platforms: Java SE 7 (JDBC 4.1) and full Java SE 8 (JDBC 4.2).
EmbeddedDataSource This datasource is suitable for an application using embedded Derby, running on full Java SE 5 or 6, corresponding to JDBC 3.0 and 4.0.
EmbeddedDataSource40 This datasource is suitable for an application using embedded Derby, running on the following platforms: Java SE 7 (JDBC 4.1) and full Java SE 8 (JDBC 4.2).
EmbeddedDriver The embedded JDBC driver (Type 4) for Derby.
EmbeddedSimpleDataSource This datasource is suitable for an application using embedded Derby, running on CDC/Foundation Profile 1.1.
EmbeddedXADataSource This datasource is suitable for an application using embedded Derby, running on full Java SE 5 or 6, corresponding to JDBC 3.0 and 4.0.
EmbeddedXADataSource40 This datasource is suitable for an application using embedded Derby, running on the following platforms: Java SE 7 (JDBC 4.1) and full Java SE 8 (JDBC 4.2).
EmbedPooledConnection A PooledConnection object is a connection object that provides hooks for connection pool management.
EmbedPooledConnection40 A PooledConnection object is a connection object that provides hooks for connection pool management.
EmbedXAConnection  
EmbedXAConnection40 This class implements jdbc4.0 methods of XAConnection
EmbedXAResource Implements XAResource
InternalDriver Abstract factory class and api for JDBC objects.
JDBC Simple JBDC mbean that pulls information about the JDBC driver.
ReferenceableDataSource The data source factory for Derby embedded driver data sources.
ResourceAdapterImpl  
XAStatementControl The Statement returned by an Connection returned by a XAConnection needs to float across the underlying real connections.
XATransactionState  
XATransactionState.CancelXATransactionTask The implementation of TimerTask to cancel a global transaction.
 

Package org.apache.derby.jdbc Description

JDBC driver and data source implementations.

Client/Remote driver and data sources, used to connect to the network server

Embedded driver and data sources, used when the database engine is embedded with the application.

Client/server data sources for use with Java 8 Compact Profile 2 and above:

Embedded data sources for use with Java 8 Compact Profile 2 and above:

Derby's JDBC api is defined by its entry point classes, the drivers and data source implementations and the standard JDBC api definitions of the java.sql and javax.sql classes. Derby does not provide non-standard extensions to standard JDBC classes such as Connection, to encourage portable JDBC applications.

Derby's implementation notes for JDBC

The JDBC specification is sometimes unclear or contradictory. This section covers how Derby implements some JDBC features and methods where the specification might be unclear. The JDBC specicification is in theory a single document however clarifications or additional information can also be found in the Javadoc for java.sql and javax.sql, and in the offical JDBC tutorial book.
JDBC Implementation notes by JDBC class
java.sql.Blob java.sql.Clob java.sql.Connection
java.sql.PreparedStatement java.sql.ResultSet
JDBC Implementation notes by SQL type
SQL DATE and JDBC SQL TIME and JDBC SQL TIMESTAMP and JDBC

java.sql.Blob

Clarification for getBytes(int pos, int length)

If the pos (position) argument is greater than the length of the BLOB then an exception is thrown. This matches the semantics of the SQL SUBSTR function.

Clarification for position(byte pattern, int start) and position(Blob pattern, int start)

If the pattern argument has length zero, then the value of start argument will be returned. This matches the semantics of the SQL LOCATE function.

java.sql.Clob

Clarification for getSubString(int pos, int length)

If the pos (position) argument is greater than the length of the CLOB then an exception is thrown. This matches the semantics of the SQL SUBSTR function.

Clarification for position(String searchstr, int start) and position(Clob searchstr, int start)

If the searchstr argument has length zero (the empty string), then the value of start argument will be returned. This matches the semantics of the SQL LOCATE function.

java.sql.Connection

Clarification for createStatement(), prepareStatement() and prepareCall()

CONCUR_UPDATABLE concurrency is supported for TYPE_FORWARD_ONLY and TYPE_SCROLL_INSENSITIVE ResultSet types only.

java.sql.PreparedStatement

Clarification for setAsciiStream(),setBinaryStream(),setCharacterStream()

In Derby, the stream must have the exact amount of data as the length argument, otherwise an exception with the following message 'Input Stream did not have exact amount of data as the requested length' is thrown.
[TUTORIAL3]

Stream parameter values are not re-used. [JDBC3] says in the last paragraph of 13.2.2 that parameters are re-used but nothing special about streams. However javadoc for java.sql.PreparedStatement.clearParamters() says 'In general, parameter values remain in force for repeated use of a statement'. Maybe 'in general' can be interpreted to mean 'except for streams'. Stream parameter values are not re-used and if a stream is re-used, the statement execution will fail with 'Stream has already been read and end-of-file reached and cannot be re-used.'.

java.sql.ResultSet

Extension for getXXX()

Support for data conversion using the getXXX() methods matches Table B-6 of [JDBC3] with this extension:

Clarification for deleteRow()

After deleteRow, ResultSet will be positioned right before the next row for TYPE_FORWARD_ONLY and TYPE_SCROLL_INSENSITIVE updatable ResultSets.

Clarification for updateRow()

After updateRow, ResultSet will be positioned right before the next row for TYPE_FORWARD_ONLY updatable ResultSets. The ResultSet remain on the current row for TYPE_SCROLL_INSENSITIVE updatable ResultSets.

Clarification for getAsciiStream()

getAsciiStream() is not recommended to use in Derby, because Derby handles characters as unicode internally , there is no advantage in using this method.

An ASCII character is defined as an eight bit character (range 0x00 to 0xff), see CHAR() function definition by [JDBC3] in appendix C.2.

For character types (Types.CHAR, Types.VARCHAR & Types.LONGVARCHAR), each character in the value is translated to one byte in the ASCII stream:


For binary types (Types.BINARY, Types.VARBINARY, and Types.LONGVARBINARY) getAsciiStream() returns a stream with identical contents to that returned by getBinaryStream() on the same column.

Extension for getAsciiStream()

Extension for getBinaryStream()

On Types.BLOB columns returns a stream with identical contents to that returned by getBlob().getBinaryStream() on the same column if the BLOB value is not NULL. If the BLOB value is NULL then null is returned.

Clarification for getCharacterStream()

For binary types (Types.BINARY, Types.VARBINARY, and Types.LONGVARBINARY, Types.BLOB) the value is converted to a stream of characters as though it is encoded using UTF-16BE.

Extensions for getCharacterStream()

Clarification for getString()

For binary types (Types.BINARY, Types.VARBINARY, and Types.LONGVARBINARY, Types.BLOB) getString() returns String containing a two character hexadecimal representation for every byte in a non-null value. The two characters are in the range '0' - '9' and 'a' - 'f'. For NULL values, null is returned.
Note, that this String does not match the contents of the stream returned by getAsciiStream() or getCharacterStream() on the same column.

Extensions for getString()

getUnicodeStream()

Not implemented, deprecated by [JDBC3].

Binary column example

If a binary column has been set with the Java byte array containing fours bytes, byte[] data = {0x34, 0x87, 0xc2, 0x1f} then:

Derby's SQL DATE interactions with JDBC

Derby’s SQL DATE type represents a date in the form yyyy-mm-dd with no associated time zone information.

java.sql.Date

A JDBC Date (java.sql.Date) by definition represents a point in time on a given date in a given time zone.

[JDBC3] intends that the point in time for a java.sql.Date object is 00:00 (midnight), but this is not enforced by the class.

JDBC drivers are required to return java.sql.Date objects that are normalized to 00:00 according to the required time zone.

Applications are expected to pass in java.sql.Date instances that are normalized to 00:00 (see section 18.1.1 of [TUTORIAL3]).

Conversion of a JDBC java.sql.Date to a Derby DATE value

  1. setDate() without a Calendar object or passing null for a Calendar object:

    • The yyyy-mm-dd values will be calculated from the milli-seconds value of the java.sql.Date instance using a Calendar object set to the time zone of the virtual machine.

    • This yyyy-mm-dd value will match the output of java.sql.Date.toString().

  2. setDate() with a Calendar object:

    • The yyyy-mm-dd values will be calculated from the milliseconds value of the java.sql.Date instance using the passed in Calendar.

    • The code for this is
      cal.setTimeInMillis(value.getTime());
      yyyy = cal.get(Calendar.YEAR);
      mm = cal.get(Calendar.MONTH) + 1;
      dd = cal.get(Calendar.DAY_OF_MONTH);

    • This yyyy-mm-dd value may not match the output of java.sql.Date.toString() for the value, since this method always uses the time zone of the virtual machine.

Derby does not require that the application’s java.sql.Date value is normalized to 00:00 according to the required time zone.

In both cases no time zone information is stored with the SQL DATE value.

Conversion of a Derby DATE value to a JDBC java.sql.Date

  1. getDate() without a Calendar object or passing null for a Calendar object:

    • A java.sql.Date instance is returned with a millisecond value corresponding to 00:00 on yyyy-mm-dd according to the time zone of the java virtual machine

    • The toString() method of the returned value will return ‘yyyy-mm-dd’

  2. getDate() with a Calendar object:

    • A java.sql.Date instance is returned with a millisecond value corresponding to 00:00 on yyyy-mm-dd according to the time zone of the Calendar

    • The toString() method of the returned value may not return ‘yyyy-mm-dd’, since this method always uses the time zone of the virtual machine.

Conversion of a string type to a JDBC java.sql.Date

Three different date formats are built into Derby.

  1. (ISO/JIS) yyyy-mm-dd e.g. “1980-03-21”,

  2. (IBM USA) mm/dd/yyyy e.g. “03/21/1980”, and

  3. (IBM European) dd.mm.yyyy e.g. “21.03.1980”.

If the format of the string matches one of the built in formats then a conversion to a java.sql.Date matches that of a SQL DATE value with value yyyy-mm-dd.

If the string does not match any of the built in formats Derby attempts to use the Java locale specific parser to interpret the string as a date.

Derby's SQL TIME interactions with JDBC

Derby’s SQL TIME type represents a time of day in the form hh:mm:ss with no associated time zone information.

java.sql.Time

A JDBC Time (java.sql.Time) by definition represents a point in time on an unspecified day in a given time zone.

Java.sql.Time extends java.util.date, so it includes a date. [JDBC3] intends that the date stored in a java.sql.Time be Jan 1 1970, but this is not enforced by the class.

JDBC drivers are required to return java.sql.Time objects that are normalized to Jan. 1 1970 according to the required time zone.

Applications are expected to pass in java.sql.Time instances that are normalized to Jan. 1 1970.

Conversion of a JDBC java.sql.Time to a Derby TIME value

  1. setTime() without a Calendar object or passing null for a Calendar object

  2. setTime() with a Calendar object

Derby does not require that the application’s java.sql.Time value be normalized to Jan 1 1970 according to the required time zone.

In both cases no time zone information is stored with the SQL TIME value.

Conversion of a Derby TIME value to a JDBC java.sql.Time

  1. getTime() without a Calendar object or passing null for a Calendar object

  2. getTime() with a Calendar object

Conversion of a string type to a JDBC java.sql.Time

Three different time formats are built into Derby:

  1. (ISO/EUR) hh.mm.ss e.g. “13.52.03”,

  2. (IBM USA) hh:mm [AM|PM] e.g. “1:52 PM”, and

  3. (JIS) hh:mm:ss e.g. “13:52:03”.

If the format of the string matches one of the built in formats then a conversion to a java.sql.Time matches that of a SQL TIME value with value hh:mm:ss.

If the string does not match any of the built in formats Derby attempts to use the Java locale specific parser to interpret the string as a date.

Derby's SQL TIMESTAMP interactions with JDBC

Derby’s SQL TIMESTAMP type represents a time of day in the form yyyy-mm-dd hh:mm:ss.fffffffff (nanosecond granularity) with no associated time zone information.

java.sql.Timestamp

A JDBC Timestamp (java.sql.Timestamp) by definition represents a point in time, with nanosecond resolution, in a given time zone.

Conversion of a JDBC java.sql.Timestamp to a Derby TIMESTAMP value

  1. setTimestamp() without a Calendar object or passing null for a Calendar object

    • The year, month, day, hour, minute, and second values will be calculated from the milli-seconds value of the java.sql.Timestamp instance using a Calendar object set to the time zone of the virtual machine. The nanosecond value will be calculated from the nanoseconds value of the java.sql.Timestamp.

    • The timestamp component values will match the output of java.sql.Timestamp.toString().

  2. setTime() with a Calendar object

    • The year, month, day, hour, minute, and second values will be calculated from the milliseconds value of the java.sql.Date instance using the passed in Calendar. The nanosecond value will be calculated from the nanoseconds value of the java.sql.Timestamp.

    • The code for this is
      cal.setTimeInMillis(value.getTime());
      year = cal.get(Calendar.YEAR);
      month = cal.get(Calendar.MONTH) + 1;
      day = cal.get(Calendar.DAY_OF_MONTH);
      hour = cal.get(Calendar.HOUR);
      minute = cal.get(Calendar.MINUTE);
      second = cal.get(Calendar.SECOND);
      nanos = value.getNanos();

    • This stored timestamp component value may not match the output of java.sql.Timestamp.toString() for the value, since this method always uses the time zone of the virtual machine.

Conversion of a Derby TIMESTAMP value to a JDBC java.sql.Timestamp

  1. getTimestamp() without a Calendar object or passing null for a Calendar object

    • A java.sql.Timestamp instance is returned with a nanosecond value corresponding to yyyy-mm-dd hh:mm:ss.fffffffff according to the time zone of the java virtual machine

    • The toString() method of the returned value will return ‘yyyy-mm-dd hh:mm:ss.fffffffff’.

  2. getTime() with a Calendar object

    • A java.sql.Time instance is returned with a nanosecond value corresponding to yyyy-mm-dd hh:mm:ss.fffffffff according to the time zone of the Calendar

    • The toString() method of the returned value may not return ‘yyyy-mm-dd hh:mm:ss.fffffffff’, since this method always uses the time zone of the virtual machine.

Conversion of a string type to a JDBC java.sql.Timestamp

Two different timestamp formats are built into Derby:

  1. (ISO) yyyy-mm-dd hh:mm:ss[.ffffff]e.g. “1980-10-25 13:01:23.123456”, and

  2. (IBM) yyyy-mm-dd-hh.mm.ss[.ffffff]e.g. “1980-10-25-13.01.23.123456”.

Note that only microsecond resolution is supported in converting strings to timestamps.

If the format of the string matches one of the built in formats then a conversion to a java.sql.Timestamp matches that of a SQL TIMESTAMP value with value yyyy-mm-dd hh:mm:ss.ffffff.

If the string does not match any of the built in formats Derby attempts to use the Java locale specific parser to interpret the string as a date.
Overview   Package  Class  Tree  Deprecated  Index  Help 
Built on Wed 2013-06-12 15:21:56+0000, from revision ???
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    
Apache Derby V10.10 Internals - Copyright © 2004,2013 The Apache Software Foundation. All Rights Reserved.