Telosys Data Access Layer

Data Access Layer

( “Telosys-DAL” )

Laurent Guérin / V 1.8 / 2008 – November

( for Telosys 1.0.0 and + )

Telosys framework - D.A.L. ( Laurent Guérin / ver 1.8 ) 2

Telosys-DAL : The big principles

� Telosys-DAL goals :� Provide an easy way to write and use standard “CRUD”DAOs ( for single Value Objects and Lists )

� Let the programmer see the SQL code and control all the operations

� Keep the SQL code and the “O/R mapping” in the Java classes (when the code runs, it cannot be altered by external files)

� Increase the productivity by providing � a set of classes to encapsulate all the JDBC complexity

� external tools to generate the specific Java code required to access a table

� � you don’t have to write code to create DAO and Value Objects !


Telosys-DAL : Overview

Data Access Layer

Value Objects

ConnectionManager

SqlConnection

SqlConnection

SqlConnection

SqlConnectionPool

SqlConnectionPool

SqlConnectionFactory

« SqlConnectionProvider »

AgencyVO

EmployeeVO

EmployeeVOList

« DAO »

AgencyDAO

EmployeeDAO

Application

init()

getConnection()

AgencyVOList

SQLDataSourceDataSource

Telosys

J2EE Server

dbconfig.xml


Configuration file “dbconfig.xml”

� dbconfig.xml example :<databases maxId="4" defaultId="0" >

<db id = "0"name = "MySQL - Test DB" driver = "com.mysql.jdbc.Driver" url = "jdbc:mysql://localhost:3306/test" isolationLevel = "TRANSACTION_REPEATABLE_READ" poolSize = "3" >

<property name="user" value="root" /><property name="password" value="" /><metadata catalog="" schema="" table-name-pattern=" %" table-types="TABLE VIEW" />

</db>

<db id = "1" name="DataSource MySQL" datasource="java:comp/env/jdbc/mydatasource" />

<db id = "2"name = "Oracle 10g" driver = "oracle.jdbc.OracleDriver" url = "jdbc:oracle:thin:@localhost:1521:XE"isolationLevel = "TRANSACTION_READ_COMMITTED" poolSize = “0" >

<property name="user" value="tp" /><property name="password" value="tp" /><metadata catalog="" schema="TP" table-name-pattern ="%" table-types="TABLE VIEW" />

</db>

</databases>

maxId : 0 to 100defaultId : 0 if not set or invalidid : 0 to maxIdpoolSize : . 0|1 �� factory (no pool ). > 1 �� pool

POOL [ 3 ]

Factory( no pool )

Datasource (JNDI name)


Telosys-DAL : Initialization

� Telosys-DAL stand-alone :

� Telosys-DAL with Telosys framework : � Define the dbconfig file in the telosys.properties

� Init Telosys framework, then Telosys-DAL

//--- Telosys DAL initialization with dbconfig file p ath private static final String DB_CONFIG = CONF_DIR + "dbconfig.xml" ;TelosysDAL.init( DB_CONFIG);

//--- 1) Telosys global initializationTelosys.init(..., ...);//--- 2) Telosys DAL initialization TelosysDAL.init();

DbConfFile = C:/Eclipse301/workspace/Telosys/conf/db config.xmlDbConfFile = ./dbconfig.xml


Telosys-DAL : Connections management

SqlConnectionProvider

. getConnection()

. getName()

ConnectionProvider<< interface >>

*

. init ( String dbconfigFile )

. getDefaultDatabase()

. getNumberOfDatabases()

. getConnection()

. getConnection(int base)

. getSession()

. getSession(int base)

ConnectionManager<< class >>

SqlConnectionFactory

SqlConnectionPool

SqlDataSource

javax.sql.DataSource

SqlConnection<< class >>

java.sql.Connection

<< interface >>

Pool( Vector )

getConnection :create a newconnection

getConnection :get from pool

getConnection :get from DataSource

*

1


Telosys-DAL : Connections management

� How to get a Connection :

� How to release a Connection :

if the connection comes from …� a pool � it is recycled ( in the Telosys pool )

� a factory � it is closed

� a datasource � managed by the DataSource

//--- Connection from Default DatabaseConnection c1 = ConnectionManager. getConnection() ;

//--- Connection from Database 1Connection c2 = ConnectionManager. getConnection(1) ;

Connection c1 = ConnectionManager.getConnection();c1. close() ;


DAL – V.O. ( Value Objects )

� The data exchange between the Data Access Layer and the other layers is done with “VO” ( “Value Object” ), also known as “DTO” ( “Data Transfer Object” )

� For each “VO”, 2 Java classes are required :� The VO itself

� A specific list of this type of VO (with strong type checking methods )

� Example : to managed “Employees” we need …� “EmployeeVO.java” ( the VO )

� “EmployeeVOList.java” ( the list of “EmployeeVO” )


DAL – V.O. ( Value Objects )

. getXxxx()

. setXxxx()

. isXxxx()

. toString()

EmployeeVO

. EmployeeVO add()

. add( EmployeeVO )

. insert ( index, EmployeeVO )

. replace ( index, EmployeeVO )

. remove ( index )

. remove (EmployeeVO )

. EmployeeVO get( index )

. EmployeeVO getFirst()

. EmployeeVO getNext()

EmployeeVOList

. getList()

. size()

. isEmpty()

. clear()

GenericVOList

LinkedList

List of « EmployeeVO »

Value Objectfor entity« Employee »

« Employee » example :

no inheritance

Standard « DataList » providedby Telosys

extends « GenericVOList »

Specific méthods to encapsulate the generic methods of DataList

Standard template, but no interface implementationbecause of the strongtype methods

Standard accessors, for each attribute

T e l o

s y s


DAL – D.A.O. ( Data Access Objects )

� The DAO provides methods to manipulate � A single entity : the Value Object

� A list of entity corresponding to a specific Query� The Value Objects List

� The DAO works with other classes :� 1 Value Object ( VO )

� 1 Value Objects List ( VOList )

� 0 .. N Query (providing a VOList )



� The DAO operations to manipulate a single V.O.

� load (try to load a VO using its primary key)

� save (save a VO by SQL insert or update )

� delete (delete a VO using its primary key )

� insert ( try to insert the VO )

� insertKeyGen ( insert with key generation )

� update ( try to update the VO )

� exists ( check if the VO exists in the database )



� The DAO operations to manipulate SQL Queriesand V.O. lists� createQuery ( create a SQL query to be used afterwards )

� loadList ( load a list as the result of a Query )

� saveList ( save a list by a “SQL delete” using the Query criteria & “n SQL insert” for all the items of the list)

� deleteList ( delete the list using the Query criteria )

� count ( do a “select count(*) ..” using the Query criteria )

� List elements management ( without Query ) :� updateList ( update all the items of the list )

� insertList ( insert all the items of the list )

� deleteList ( delete all the items of the list )

VOListor

List



� DAO with or without Connections ?Each operation of a DAO has 4 signatures Examples :

� dao.save( myVO ); works with the default database ID ( cf dbconfig.xml )

� dao.save( myVO, base_id );works with the given database ID ( “int” )

� dao.save( myVO, connection );works with the given standard JDBC “Connection”

� dao.save( myVO, database_session );works with the given “DatabaseSession” object( a “DatabaseSession” is a Telosys object which encapsulate a connection, useful for “Screen Managers” )

DB id

Connection



� With logical DB id ( without “Connection” )� The DAO uses the “ConnectionManager”to get a connection ( ConnectionManager.getConnection(); )

� Each insert, update or delete is commited automatically

� The connection is closed (�recycled if it belongs to a pool ) after each operation

� � The programmer never see the Connection object

� With “Connection” or “DatabaseSession”� The connection management is the programmer’s responsibility

� The DAO doesn’t commit anything

� And doesn’t close the connection

How to use D.A.O.


How to get a DAO instance

� A DAO is thread-safe => its instance can be shared an reused

� 1/ Using the default DAO constructor

� 2/ Using a DAO provider if any (since v 1.0.0)Employee bean = new Employee();DAOProvider provider = TelosysDAL.getDAOProvider(); EmployeeDAO dao ;dao = (EmployeeDAO) provider.getDAO(bean) ; // by bean instancedao = (EmployeeDAO) provider.getDAO(bean,3) ; // same but for DB 3dao = (EmployeeDAO) provider.getDAO(Employee.class) ; // by bean classdao = (EmployeeDAO) provider.getDAO(Employee.class,3) ; // same for DB 3

( the dynamic DAO registries can be defined in the files dbconfig.xml and telosys.properties )

EmployeeDAO dao = new EmployeeDAO() ;


DAO management

� DAO description :� String s = dao.describe()

� The returned string contains � the DAO Java Class

� the DAO target TABLE

� the set of SQL requests for standard operations : SELECT, INSERT, UPDATE, DELETE

� Other methods …� String dao.getTableName()

� Class dao.getEntityBeanClass()

� SqlRequests dao.getSqlRequests()

DAO & Entities (VO)


DAO : load an entity by PK

� Set the Primary Key � vo.setId(“IdValue”);

� Try to load the entity � dao.load(vo);

� SQL request :� Select … from … where …

� Return code ( int ) :� 1 – Found and loaded ( VO attributes are populated )

� 0 – Not found ( no change on the VO )


DAO : load with lock

� Lock the record with a “SELECT FOR UPDATE” :� dao.load(vo, “FOR UPDATE” );

� NB:� Database specific => any string can be used !� Use string constants !


DAO : check the existence of an entity


� Check existence � if ( dao.exists(vo) )

� boolean b = dao.exists(vo)

� SQL request :� Select count where …

� Return code ( boolean )� True : the entity exists

� False : the entity doesn’t exist


DAO : update an entity

� Set the VO attributes � vo.setId(“IdValue”);

� vo.setOther(…);

� Update � dao.update(vo);

� SQL request :� Update table set … where …

� Return code ( int )� The standard JDBC return value (the number of rows affected). � For an entity ( with a unique Key ) :

� 1 – Entity updated ( entity found and updated )

� 0 – Entity not updated ( entity not found )


DAO : insert an entity



� Insert � dao.insert(vo);

� SQL request :� Insert into … (…) values (…)


� 1 – Successful insert ( entity inserted )

� else : never happen � Exception


DAO : insert with key generation

� Set the VO attributes � vo.setAttrib1(..);

� vo.setAttrib2(..);

� Insert � Long key = dao.insertKeyGen(vo);

� Set the Key attribute in the VO instance� vo.setId( key.intValue() );

� SQL request :� Insert into … (…) values (…)

� Return code :� The generated key wrapped in a Long object( or null if none )

Key attributeis useless


DAO : delete an entity


� Delete� dao.delete(vo);

� SQL request :� Delete from … where …


� 1 – Entity deleted ( entity found and deleted )

� 0 – Entity not deleted ( entity not found )


DAO : save an entity



� Save� dao.save(vo);

� SQL requests :� Select count from … where …

� if the enity exists

� � Update

� else

� � Insert


DAO : save an entity


� Always 1 :

� entity inserted � 1 row affected

� or

� entity updated � 1 row affected


DAL – Exceptions

� TelosysException� Use a standard “try catch” block �

� What can happen ? � Duplicate key on “insert”

� Other standard JDBC exceptions :� the table has changed => the DAO is not up to date

� an integrity rule is violated

� etc…

try{

// DAO operations} catch ( TelosysException ex ){

...}

D.A.O. & Lists (VOList)


DAO and ListQueries

� A VOList is loaded by using a DAO and a ListQuery

� A ListQuery holds � 3 SQL requests with the same “WHERE” clause :

� Select … from … WHERE …

� Select count form … WHERE …

� Delete form … WHERE …

� The parameters to set in the “WHERE” clause

� Lifecycle : � 1/ created by the DAO

� 2/ customized with the specific parameters

� 3/ passed to the DAO methods to managed VOLists


DAO and ListQuery model

. setParameter(int,int)

. setParameter(int,long)

. setParameter(int,short)

. setParameter(int,Object)

. getSqlCount()

. getSqlSelect()

. getSqlDelete()

ListQuery<< interface >>

. createQuery()

. createQuery()

. createQuery()

. createQuery()

. createQueryAll()

. createQueryAll()

DAO

creates

uses

.

Criteria

.

Criterion

*

uses


DAO : Query for all the entities of a table

� How to load ALL the entities of a table//--- Create the DAOEmployeDAO dao = new EmployeDAO();//--- Create the VOListEmployeVOList list = new EmployeVOList();

//--- Define a queryListQuery query = dao. createQueryAll (); // ALL (no WHERE clause)

//--- Load the list using the querydao. loadList (query, list);

//--- Print the list sizeSystem.out.println("List size = " + list.size());//--- Print all the VO of the listIterator iter = list.iterator() ;int i = 0 ;while ( iter.hasNext() ){

System.out.println(" . " + (i++) + " : " + iter.nex t() );}

ListQuery query = dao. createQueryAll ( “order by name” );


DAO : Query with static criteria

� Query with “ static criteria ” without parameters :

� Query with “ static criteria ” with parameters :

ListQuery query = dao. createQuery ( "Matricule > 7000" ); ListQuery query = dao. createQuery ( "Matricule > 7000" ,

"order by matricule" );


ListQuery query = dao. createQuery ( "Matricule > ? and Matricule < ? " ); ListQuery query = dao. createQuery ( "Matricule > ? and Matricule < ? " ,

"order by matricule" );

query. setParameter ( 1, 100 ); // First parameter valuequery. setParameter ( 2, 200 ); // Second parameter value


Param. index :from 1 to N


DAO : Query with dynamic criteria

� Define the list of criteria :

� At request time, choose the criteria to use :

� Then, create the query :

Criterion [] SQL_CRITERIA = {

new Criterion( "nom like ?" , ParamType.STRING ), /* 1 */new Criterion( "prenom like ?" , ParamType.STRING ), /* 2 */new Criterion( "Matricule > ?" , ParamType.INTEGER ), /* 3 */new Criterion( "Matricule < ?" , ParamType.INTEGER ) /* 4 */

};Criteria crit = new Criteria (SQL_CRITERIA, "and" );

crit.doNotUse(1);crit.doNotUse(2);crit.useWithValue(3, "10");crit.useWithValue(4, "900");

ListQuery query = dao.createQuery(crit, "order by Ma tricule");


DAO & ListQuery : limitations

� A DAO works with only one table

� DAO + ListQuery can only retrieve data from a single table ( a list of VO/records load form the table )

� To retrieve data with complexes requests…� see “DataSet”


DAO : List persistence

� The DAO supports global list persistence, based on a query criteria :

� dao.deleteList( query )� Delete all the occurrences corresponding to the query criteria

� dao.saveList( query, list)� Save the new list content by removing all the existing items then inserting the new list items :

� Delete all the occurrences corresponding to the query criteria

� Insert all the occurrences of the list parameter

� NB : � be sure that there’s no risk of integrity violation when using a global “delete” for a list


DAO : List persistence

� Bulk insert/update/delete :

� dao.insertList(list)

� dao.updateList(list)

� dao.deleteList(list)

� Insert, update or delete all the elements of the given list ( VOList or standard java.util.List )

D.A.O. & Sequences


Sequence DAO

� A “Sequence DAO” is a specific type of DAO dedicated to the SEQUENCES

� It provides the standard “NEXT VAL”and “CURR VAL” operations

� Sequence DAO are available for …� Oracle

� PostgreSQL

� MySQL ( sequence simulation with tables )


Sequence DAO

� How to create and use a “Sequence DAO” …

SequenceDAO seq = new SequenceDAO( "request_id_seq" , SequenceDAO.POSTGRESQL);

//--- With the default DataBaselong val = seq.nextVal() ;

//--- With a specific DataBase IDlong val = seq.nextVal(DbId) ;

//--- With a connectionlong val = seq.nextVal(c) ;long val = seq.currVal(c) ;

//--- With a DB Sessionlong val = seq.nextVal(s) ;long val = seq.currVal(s) ;

NB : currVal � only witha connection

SequenceDAO.POSTGRESQLSequenceDAO.ORACLESequenceDAO.MYSQL


Sequence DAO

� Best practice : � create a class for each sequence

public class EmpIdSeqDAO extends SequenceDAO{

public EmpIdSeqDAO(){

super( "EmpId" , ORACLE);}

}

//--- Use an existing Sequence DAO EmpIdSeqDAO empIdSeq = new EmpIdSeqDAO();System.out.println("nextVal : " + empIdSeq.nextVal() );

DataSet


DataSet

� A “DataSet” is a set of “DataRow” ( 0..N rows )

� A “DataRow” is a set of “Object” ( 0..N cells )

� => a DataSet is like a TABLE with ROWS and COLUMNS

� A “DataSet” is “abstract” and its content can be loaded from different sources.

� The “source” of the DataSet is defined in a “DataSet definition”


DataSet

� Principle

� Step 1 : “define it” ( constructor + definition )� DataSet ds = new XXXXXX(…);

� Step 2 : “load or reload it”� ds.load()

� ds.load ( origin )

� Step 3 : “use it”

ds.load();for ( int i = 1 ; i <= ds.getRowCount() ; i++ ){

DataRow dr = ds.getDataRow(i);System.out.println(" ROW = [" + dr.toString() + "] ");String s = dr.getString(1));Date d = dr.getDate(3));int i = dr.getInt(4));

}

Origin types for SQLDataSet :- Connection- DatabaseSession- Integer ( Database Id )


DataSet : how to fetch data

for ( int i = 1 ; i <= ds.getRowCount () ; i++ ){

DataRow dr = ds.getDataRow(i);System.out.println(" dr.toString() = [" + dr.toStri ng() + "] ");String s = dr.getString(1));Date d = dr.getDate(3));int i = dr.getInt(4));

}

Iterator iter = ds.iterator ();while ( iter.hasNext() ){

DataRow dr = (DataRow)iter.next();System.out.println(" dr = [" + dr + "] ");

}

Object o = ds.getObject (2,3); // ( Row, Col )String s = ds.getString (2,3); // ( Row, Col )float f = ds.getFloat (2,3); // ( Row, Col )

if ( ds.isEmpty () )

From 1 to MAX

Row : 1 to MAXCol : 1 to MAX


DataSet : how to sort rows

ds.sort ( 2 ) ; Sort column 2ds.sort ( 2, "ASC" ) ; Sort column 2 in ascending or derds.sort ( 2, "DESC" ) ; Sort column 2 in descending order

ds.sortIgnoreCase ( 2 ) ; ds.sortIgnoreCase ( 2, "ASC" ) ; ds.sortIgnoreCase ( 2, "DESC" ) ;

if ( ds.isSorted ( 2 ) ) if ( ds.isSortedInAscendingOrder() )if ( ds.isSortedInDescendingOrder() )

� Once the DataSet is loaded, it can be sorted by column

SQLDataSet


SQLDataSet

� A “SQLDataSet” is an extension (subclass) of "DataSet"

� It can be loaded from a relational database, using a definition based on a SQL request

� The definition for a SQLDataSet is held by an instance of SQLDataSetDefinition


SQLDataSet and relational DB

� Use case 1 : Basic SQLDataSet (no parameter)//--- DataSet without SQL parametersSQLDataSetDefinition def = new SQLDataSetDefinition (

"select name, manager, agency", "from employee" , null , "order by name" );

SQLDataSetDefinition def2 = new SQLDataSetDefinition ("select name, manager, agency from employee where agency > 10 " );

//--- Set a specific Database ID def.setDatabaseId (2);

//--- Create the DataSet with the definitionSQLDataSet ds = new SQLDataSet ( def );

//--- Load the DataSet using the Database specified i n the definitionds.load() ;

//--- Examples with the load(Object) method :ds.load(new Integer(1)); // load using the given Database IDds.load(connection); // load using the given JDBC Connectionds.load(dbSession); // load using the given DatabaseSession

No parameter in criteria :no "where clause"or static "where clause"



� Use case 2 :SQLDataSet with parameters ( static criteria )

//--- DataSet with one INTEGER parameter int [] paramTypes = { ParamType.INTEGER } ; // One param ( INTEGER )

SQLDataSetDefinition def = new SQLDataSetDefinition ("select name, manager, agency", "from employee", " where agency = ? ", "order by name", paramTypes ); // Array of param types

SQLDataSetDefinition def2 = new SQLDataSetDefinition ("select name, manager, agency from employee where agency > ? ",paramTypes );

//--- Set the parameter valuesString paramValues [] = { "1" }; // Array of param value(s)

//--- Create the DataSet with the DefinitionSQLDataSet ds = new SQLDataSet ( def, paramValues );

1 .. N fixed parameters in the "where clause"



� Use case 3 : SQLDataSet with “dynamic criteria”

SQLDataSetDefinition def = new SQLDataSetDefinition ("select name, manager, agency", "from employee", null , "order by name");

//--- Define the dynamic criteria Criterion[] SQL_CRITERIA = {

new Criterion( "name like ?" , ParamType. STRING), /* 1 */new Criterion( "manager like ?" , ParamType. STRING), /* 2 */new Criterion( "agency > ?" , ParamType. INTEGER), /* 3 */new Criterion( "agency < ?" , ParamType. INTEGER) /* 4 */

};Criteria crit = new Criteria(SQL_CRITERIA, "and");//--- Set dynamically the useful criteriacrit .useWithValue(1, "ZO%");crit .doNotUse(2);crit .doNotUse(3);crit .useWithValue(4, "7000");

//--- Create the DataSet with the DefinitionSQLDataSet ds = new SQLDataSet ( def, crit );

No "where clause" ( dynamic )If "where clause", dynamic criteria will be added


SQLDataSet use cases

� DataSet are useful for …

� � Complex SQL request :the SQLDataSetDefinition support � Joins between different tables

� Additional SQL clauses :� Order by

� Group by

� …

� � Search services : complex criteria combination with “Dynamic Criteria”


Other SQLDataSet capabilities

� Use the SQLDataSet definition for "count"� int n = ds.count() ; Execute a "select count(*)" with the dataset definition criteria

� Load a "page" (a subset of the request result)� Define the number of lines per page :

� def.setLinesPerPage(100); // default = 20

� Load a page :� ds.loadPage(2);The SQL request is executed, only the expected rows are retrieved from the JDBC ResultSet

� boolean b = ds.endOfResultSet(); To know if the last row of the ResultSet has been loaded

� Retrieve the SQL request :� String sql = ds.getSqlRequest();

T H E E N D

Technology

Telosys Data Access Layer