Derby Embedded JSR 169 Functional Spec
-
2005/02/10 – djd@debrunners.com
Fix package name of DataSource implementation.
- Initial
Version: 2004/12/09 – djd@debrunners.com
Summary
- Add
support for Derby running in J2ME/CDC/Foundation platform
- JDBC
API defined by JDBC Optional Package for CDC/Foundation Profile (JSR 169).
Database Features
Embedded (derby.jar), sysinfo, dblook, and ij
(derbytools.jar) will be modified to work under JSR169 on J2ME/CDC/Foundation
(Foundation).
These features will not be modified to work on Foundation:
- Derby
Network server (could be a separate project)
- Encrypted
Databases (no support for JCE classes in Foundation)
The support for JSR169 and Foundation will be built into the
existing Jar files, derby.jar and derbytools.jar. A single set of jars for all
platforms is preferable from an ease of use point of view. While it may be
thought that a separate smaller jar would be better for a J2ME platform, the
actual savings in jar file size is not significant, since the majority of the
Derby code is from the SQL language area, which will be (almost) fully
supported in JSR169.
Databases created under JSR 169 will be portable to J2SE
platforms.
Non-encrypted databases created under J2SE platforms will be
portable to J2ME platforms, though they may contain SQL elements that are not
supported in Derby on Foundation, see SQL section.
JDBC
JSR 169 provides a sub-set of the JDBC 3.0 specification for
the Foundation platform.
Derby will support the subset of its JDBC 3.0 support as
specified by JSR 169.
Some specific points to note are:
- Derby’s
JSR169 implementation of javax.sql.DataSource will be org.apache.derby.jdbc.EmbeddedSimpleDataSource
- This
is the only way to obtain a Connection with Derby with JSR169. [Note
DriverManager and Driver and not part of JSR169]
- This
DataSource implementation will support all the properties supported by org.apache.derby.jdbc.EmbeddedDataSource.
- Note
EmbeddedDataSource cannot be used in JSR169 as it is
defined to implement classes in javax.naming packages, which are not
part of Foundation.
- This
DataSource implementation may also be used in JDBC 2.0 and JDBC 3.0
environments.
- DECIMAL
data types will be supported but since the platform does not support java.math.BigDecimal
applications must get and set DECIMAL values using alternate JDBC getXXX
and setXXX methods. Any alternate getXXX/setXXX method that works against
a DECIMAL type with JDBC 2.0/3.0
will work in JSR169. Typically this will be get getString() and
setString().
SQL
SQL language remains unchanged when running in JSR169 with
these exceptions:
- DECIMAL
type will be supported, even though java.math.BigDecimal is not supported
on Foundation (see JDBC section).
- Java
Routines (procedures and functions):
- Routines
of type CONTAINS SQL, READS SQL DATA or MODIFIES SQL DATA will not be
supported, i.e. those that contain server-side JDBC. The standard api (jdbc:default:connection)
to obtain a Connection can not be supported in JSR169 since it uses
java.sql.DriverManager. Note that this standard JDBC URL is from the SQL
standard and not JDBC.
This may be a runtime error at the time the routine trys to obtain a
connection using jdbc:default:connection.
- The
DECIMAL type will be type mappable to java.lang.String for method
resolution instead of java.math.BigDecimal.
Tools
Sysinfo will be modified to display addition information
(Derby JRE Level) that indicates the JRE level that Derby understands the
running JVM to be, which will be one of:
- J2SE
1.3 – JDBC 2.0
- J2SE
1.4 – JDBC 3.0
- J2SE
1.4.2 - JDBC 3.0
- J2SE
5.0 – JDBC 3.0
- J2ME/CDC/Foundation
– JSR169
Builds
In order to build derby additional jars will need to be
downloaded:
- J2ME/CDC/Foundation
profile jars – possibly could be optional, used to ensure Derby classes
intended to run on Foundation only reference Foundation classes.
- JSR169
jar – Needed to compile concrete Derby java.sql.ResultSet
implementation (and maybe other JSR169 classes) for JSR 169.
Testing
I will run all tests under java/testing against Derby in
JSR169 on IBM’s WCTME 5.7 with the exception of:
- Network
Server Tests
- Encryption
Tests
- Java
tests that use java.math.BigDecimal
- Tests
that use or create routines that call server-side JDBC.
References