com.scooterframework.orm.sqldataexpress.service
Interface SqlService

All Superinterfaces:
SqlServiceGeneric, SqlServiceSpecific, SqlServiceTransactionManager
All Known Implementing Classes:
SqlServiceImpl

public interface SqlService
extends SqlServiceGeneric, SqlServiceSpecific, SqlServiceTransactionManager

SqlService interface specified services that are called by clients.

A SqlService instance is a thread-safe service object. Only one such instance is needed for an application. The SqlService object has a TransactionManager object. The TransactionManager object is responsible for managing the transaction associated with the current thread. This transaction instance can be automatically started if it has not been started externally.

You cannot start a new transaction when the current transaction is still active. In other words, you have to end a transaction, either through commitTransaction() or through rollbackTransaction(), before you can call beginTransaction(). Therefore, you should use beginTransaction() in the client code, not in service methods.

If you expect your service methods or utility methods which may be invoked by other methods or transactions, you should use implicit transaction in the service or utility methods. See Example 5 below for details.

If a transaction is not started, a default implicit transaction will be started when any service method is called. The type of default transaction is specified in property file. If the type is not specified, JdbcTransaction will be used as default.

If a transaction has already started, no implicit transaction will be started.

 Examples:
 
 Example 1: Start a new transaction explicitly
 
      SqlService sqlSvc = SqlServiceConfig.getSqlService();
      try{
          sqlSvc.beginTransaction();//start transaction explicitly
          
          sqlSvc.update(..);
          sqlSvc.update(..);
          
          sqlSvc.commitTransaction();
      }
      catch (Exception ex) {
          sqlSvc.rollbackTransaction();
      }
      finally {
          sqlSvc.releaseResources();
      }
 
 
 Example 2: Start a new transaction explicitly by using TransactionManager
 
      TransactionManager tm =  TransactionManagerUtil.getTransactionManager();
      try{
          tm.beginTransaction();//start transaction explicitly
          
          sqlSvc.update(..);
          sqlSvc.update(..);
          
          tm.commitTransaction();
      }
      catch (Exception ex) {
          tm.rollbackTransaction();
      }
      finally {
          tm.releaseResources();
      }
 
 
 Example 3: Start a new transaction explicitly by using UserTransaction
 
      UserTransaction utx = ...;
      try{
          utx.beginTransaction();//start transaction explicitly
          
          sqlSvc.update(..);
          sqlSvc.update(..);
          
          utx.commitTransaction();
      }
      catch (Exception ex) {
          utx.rollbackTransaction();
      }
 
 
 Example 4: Start a new transaction automatically when a service method is called
 
      sqlSvc.update(..); //automatically start a transaction. 
      sqlSvc.insert(..); //automatically start another transaction. 
 
 
 Example 5: Start a new implicit transaction by using ImplicitTransactionManager
  //We use implicit transaction here because we expect transfer() 
  //be used in other transaction context.
        public void transfer(...) {
      ImplicitTransactionManager itm = TransactionManagerUtil.getImplicitTransactionManager();
      try{
          itm.beginTransactionImplicit();//start transaction implicitly
          
          sqlSvc.withdraw(..);
          sqlSvc.deposit(..);
          
          itm.commitTransactionImplicit();
      }
      catch (Exception ex) {
          itm.rollbackTransactionImplicit();
      }
      finally {
          itm.releaseResourcesImplicit();
      }
  }
 


Method Summary
 
Methods inherited from interface com.scooterframework.orm.sqldataexpress.service.SqlServiceGeneric
execute, execute, execute, execute, execute, retrieveMasterDetails
 
Methods inherited from interface com.scooterframework.orm.sqldataexpress.service.SqlServiceSpecific
delete, insert, retrieveRow, retrieveRows, retrieveRows, retrieveRows, update
 
Methods inherited from interface com.scooterframework.orm.sqldataexpress.service.SqlServiceTransactionManager
beginTransaction, beginTransaction, commitTransaction, releaseResources, rollbackTransaction