[jira] Commented: (DERBY-942) Add JDBC4 Ease of Development Support

["Rick Hillegas (JIRA)" <de...@db.apache.org>]

    [ http://issues.apache.org/jira/browse/DERBY-942?page=comments#action_12366225 ] 

Rick Hillegas commented on DERBY-942:
-------------------------------------

Here are sections 20.1 and 20.2 of the JDBC 4 spec:

179
20.1 Overview
The JDBC Ease of Development features are intended to:
■ Make it easier to execute SQL queries which return a single result set; execute
SQL Data Manipulation Language (DML) statements that return a row count or
that return nothing.
■ This reduces the amount of code required to execute queries that normally
would be executed using the Statement.executeQuery and
Statement.executeUpdate methods.
■ Simplify the developer experience for users who want to access, navigate and
modify their data as rows and columns.
■ Provide a means for more strongly typed data.
■ Process the returned data in a connected or disconnected environment.
■ Leverage the new features added to J2SE 5.0 such as generics and annotations.
The JDBC Ease of Development features are not intended to:
■ Be used as an Object-Relational Mapping (ORM) Technology. Developers who
need the features found in an ORM Technology should consider using the Java
Persistence API.
■ Address more complex JDBC application needs such as processing multiple result
sets.
180 JDBC 4.0 Specification • October 2005
20.1.1 JDBC Annotations
JDBC Annotations assist developer by reducing the amount of code that must be
written when using the JDBC APIs. The annotations will be used in combination
with Query interfaces and DataSet objects to simplify the access and processing of
data that is returned as a single SQL result set.
TABLE 20-1 lists the annotations provided in JDBC 4.0.
20.1.2 Query Interface
A Query interface defines a set of methods that are decorated with JDBC
annotations. These annotations describe the SQL queries and SQL update statements
to be invoked by a given method. A Query interface must be a subinterface of the
BaseQuery interface. The interface must also specify how the data returned for a
SQL query should be bound to a DataSet.
TABLE 20-1 JDBC Annotations
Annotation Description
AutoGeneratedKeys Defines the fields within a DataSet
representing the columns that are to be
returned for auto-generated keys
ResultColumn Maps a field within a DataSet to a specific
column in a SQL ResultSet
Select Associates a SQL Select statement with a
method in a Query Interface
Update Associates a SQL statement that may return
an update count, with a method in a Query
Interface
Chapter 20 Ease of Development 181
20.1.3 BaseQuery Interface
The BaseQuery interface must be the superinterface for all Query interfaces. This
interface defines methods for closing a concrete implementation of a Query interface
and for determining if an instance of a Query object has been closed.
20.1.4 DataSet interface
The DataSet interface is a subinterface of java.util.List and provides a type
safe view of the data returned from the execution of a SQL query. A DataSet
interface is a parameterized type. The parameter type is a data class describing the
columns for the rows that are returned from a method on a Query interface
decorated by the Select annotation.
A DataSet may operate in a connected or disconnected mode. When used in a
connected mode, the DataSet is normally implemented as a ResultSet. A
disconnected DataSet is normally implemented as a CachedRowSet.
A DataSet object allows for the iteration through the rows that were returned using
the java.util.Iterator API. A DataSet object allows user to iterate through
the rows that were returned using the java.util.Iterator API.
20.1.5 User-Defined Class
A user-defined class is used to represent the type parameter for a DataSet. The
class defines the fields that represent the columns returned from an underlying data
store. The user-defined class may be specified in two ways: as a structure or as a
JavaBeansTM component. The user-defined class must be created with an access
modifier of public.
Note - Throughout the rest of this chapter, this "user-defined class" will be referred
to as data class.
When the data class is used as a simple structure, it consists of public fields whose
names match the columns in the data returned from a data source.
public class Person {
public String firstName;
public String lastName;
}
CODE EXAMPLE 20-1 data class as a structure
182 JDBC 4.0 Specification • October 2005
The data class can also be represented as a JavaBeansTM component, providing setters
and getters, that match the column names in the returned data to access the fields.
public class Person {
private String firstName;
private String lastName;
public String getFirstName() { return firstName;}
public String getLastName() { return lastName;}
public void setFirstName(String fName) { firstName= fName;}
public void setLastName(String lName) { lastName=lName;}
}
CODE EXAMPLE 20-2 data class as a JavaBean
20.1.6 QueryObjectGenerator Interface
The QueryObjectGenerator interface may be implemented by JDBC drivers. A
QueryObjectGenerator is used to process JDBC annotations and to provide the
mapping between DataSet objects and the resulting data returned by a method
decorated with a Select annotation. The interface also contains the method
createQueryObject that returns an instance of a Query interface.
The method DatabaseMetaData.providesQueryObjectGenerator may be
used to determine whether a JDBC driver provides a QueryObjectGenerator
implementation.
An implementation of QueryObjectGenerator is provided by Java SE 6.
20.2 Creating an instance of a Query interface
This section describes how to create a concrete implementation of a Query interface.
The database table that will be used in the example was created by the following
DDL:
create table mammal(firstName varchar(20), lastName varchar(20), int
age, int weight, description varchar(50), longDescription
varchar(254), int key1, int key2);
Chapter 20 Ease of Development 183
CODE EXAMPLE 20-3 DDL used to create the mammal table
20.2.1 Creating a Query Interface
The following section will provide an example of creating a Query interface.
Prior to creating a Query interface, developers should create any needed data classes
that will be supplied as a type parameter for a DataSet. Please refer to the
DataSet section for additional details.
public class Mammal {
public String firstName;
public String lastName;
public int age;
public int weight;
public String description;
}
CODE EXAMPLE 20-4 Mammal data class
The methods of the Query interface are decorated with Select and Update
annotations. Methods decorated by Select annotations will return instances of
DataSet<T>.
interface MyQueries extends BaseQuery {
@Select(sql="SELECT lastName, description FROM mammal")
DataSet<Mammal> getAllMammals();
@Update(sql="delete from mammals")
int deleteAllMammals();
}
CODE EXAMPLE 20-5 A sample Query interface
20.2.2 Concrete Query Interface implementation
A concrete implementation of a Query interface can be created by invoking either
the Connection.createQueryObject or DataSource.createQueryObject
method passing a Query interface as its parameter.
Connection con = DriverManager.getConnection(url, props);
MyQueries myQueries = con.createQueryObject(MyQueries.class);
CODE EXAMPLE 20-6 Creating an instance of a SQL Interface
20.2.2.1 Connection.createQueryObject and
DataSource.createQueryObject methods
JDBC drivers must implement the createQueryObject method on the
Connection and DataSource interface. If the JDBC driver does not provide its
own implementation of a QueryObjectGenerator, it must invoke the default
QueryObjectGenerator implementation provided by Java SE 6.
When DataSource.createQueryObject is used for creating a Query object
instance, a Connection will be obtained from the DataSource and used when
executing a method on the Query interface. The QueryObjectGenerator
implementation will be responsible for closing the Connection.
If Connection.createQueryObject is used for creating a Query object instance,
the application is responsible for closing the connection..
20.2.2.2 Invoking Query Interface Methods
Once you have created an implementation of the Query interface, you may invoke
any of the methods that are defined by the interface.
DataSet<Mammal> mammalRows = myQueries.getAllMammals();
CODE EXAMPLE 20-7 invoking a method on the Query interface
20.2.2.3 Closing a Query Object
An application must explictly close a Query object by calling the close method.
The close method will close any connected DataSets created from the Query
object, thereby releasing any external resources and making it available for garbage
collection.

> Add JDBC4 Ease of Development Support
> -------------------------------------
>
>          Key: DERBY-942
>          URL: http://issues.apache.org/jira/browse/DERBY-942
>      Project: Derby
>         Type: New Feature
>   Components: JDBC
>     Reporter: Rick Hillegas
>     Assignee: Anurag Shekhar
>      Fix For: 10.2.0.0

>
> As described in the JDBC 4 spec, sections 20.1, 20.2, and 3.1.
> The Ease of Development extensions provide a way to create tabular DataSets from queries and tuple signatures. The jdk ships with a factory for creating these DataSets, which is a class which implements the QueryObjectGenerator interface. A database can write its own custom QueryObjectGenerator, or just ship with the default, jdk-shipped version. For this task, we will simply wire the default jdk-shipped factory into the appropriate methods: Connection.createQueryObject() and DataSource.createQueryObject().

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
   http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
   http://www.atlassian.com/software/jira