com.ibatis.sqlmap.client.SqlMapClient Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ibatis-sqlmap
There is a newer version: 3.0-beta-10
/*
 *  Copyright 2004 Clinton Begin
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.ibatis.sqlmap.client;

import java.sql.Connection;

/**
 * A thread safe client for working with your SQL Maps (Start Here).  This interface inherits transaction control
 * and execution methods from the SqlMapTransactionManager and SqlMapExecutor interfaces.
 * 
 * The SqlMapClient is the central class for working with SQL Maps.  This class will allow you
 * to run mapped statements (select, insert, update, delete etc.), and also demarcate
 * transactions and work with batches.  Once you have an SqlMapClient instance, everything
 * you need to work with SQL Maps is easily available.
 * 

 * The SqlMapClient can either
 * be worked with directly as a multi-threaded client (internal session management), or you can get a single threaded
 * session and work with that.  There may be a slight performance increase if you explicitly
 * get a session (using the openSession() method), as it saves the SqlMapClient from having
 * to manage threads contexts.  But for most cases it won't make much of a difference, so
 * choose whichever paradigm suits your needs or preferences.
 * 

 * An SqlMapClient instance can be safely made static or applied as a Singleton.
 * Generally it's a good idea to make a simple configuration class that will configure the
 * instance (using SqlMapClientBuilder) and provide access to it.
 * 

 * The following example will demonstrate the use of SqlMapClient.
 * 
 * 
 * //
 * // autocommit simple query --these are just examples...not patterns
 * //
 * 
 * Employee emp = (Employee) sqlMap.queryForObject("getEmployee", new Integer(1));
 * 
 * //
 * // transaction --these are just examples...not patterns
 * //
 * 
 * try {
 *   sqlMap.startTransaction()
 *   Employee emp2 = new Employee();
 *   // ...set emp2 data
 *   Integer generatedKey = (Integer) sqlMap.insert ("insertEmployee", emp2);
 *   emp2.setFavouriteColour ("green");
 *   sqlMap.update("updateEmployee", emp2);
 *   sqlMap.commitTransaction();
 * } finally {
 *   sqlMap.endTransaction();
 * }
 * 
 * //
 * // session --these are just examples...not patterns
 * //
 * 
 * try {
 *   SqlMapSession session = sqlMap.openSession()
 *   session.startTransaction()
 *   Employee emp2 = new Employee();
 *   // ...set emp2 data
 *   Integer generatedKey = (Integer) session.insert ("insertEmployee", emp2);
 *   emp2.setFavouriteColour ("green");
 *   session.update("updateEmployee", emp2);
 *   session.commitTransaction();
 * } finally {
 *   try {
 *     session.endTransaction();
 *   } finally {
 *     session.close();
 *   }
 *   // Generally your session scope would be in a wider context and therefore the
 *   // ugly nested finally block above would not be there.  Realize that sessions
 *   // MUST be closed if explicitly opened (via openSession()).
 * }
 * 
 * //
 * // batch --these are just examples...not patterns
 * //
 * 
 * try {
 *   sqlMap.startTransaction()
 *   List list = (Employee) sqlMap.queryForList("getFiredEmployees", null);
 *   sqlMap.startBatch ();
 *   for (int i=0, n=list.size(); i < n; i++) {
 *     sqlMap.delete ("deleteEmployee", list.get(i));
 *   }
 *   sqlMap.executeBatch();
 *   sqlMap.commitTransaction();
 * } finally {
 *   sqlMap.endTransaction();
 * }
 * 
 *
 * @see SqlMapClientBuilder
 * @see SqlMapSession
 * @see SqlMapExecutor
 */
public interface SqlMapClient extends SqlMapExecutor, SqlMapTransactionManager {

  /**
   * Returns a single threaded SqlMapSession implementation for use by
   * one user.  Remember though, that SqlMapClient itself is a thread safe SqlMapSession
   * implementation, so you can also just work directly with it.  If you do get a session
   * explicitly using this method be sure to close it!  You can close a session using
   * the sqlMapSession.close() method.
   * 
   *
   * @return An SqlMapSession instance.
   */
  public SqlMapSession openSession();

  /**
   * Returns a single threaded SqlMapSession implementation for use by
   * one user.  Remember though, that SqlMapClient itself is a thread safe SqlMapSession
   * implementation, so you can also just work directly with it.  If you do get a session
   * explicitly using this method be sure to close it!  You can close a session using
   * the SqlMapSession.close() method.
   * 

   * This particular implementation takes a user provided connection as a parameter.  This
   * connection will be used for executing statements, and therefore overrides any
   * configured datasources.  Using this approach allows the developer to easily use an externally
   * supplied connection for executing statements.
   * 

   * Important: Using a user supplied connection basically sidesteps the datasource
   * so you are responsible for appropriately handling your connection lifecycle (i.e. closing).
   * Here's a (very) simple example (throws SQLException):
   * 
   * try {
   *   Connection connection = dataSource.getConnection();
   *   SqlMapSession session = sqlMap.openSession(connection);
   *   // do work
   *   connection.commit();
   * } catch (SQLException e) {
   *     try {
   *       if (connection != null) commit.rollback();
   *     } catch (SQLException ignored) {
   *       // generally ignored
   *     }
   *     throw e;  // rethrow the exception
   * } finally {
   *   try {
   *     if (connection != null) connection.close();
   *   } catch (SQLException ignored) {
   *     // generally ignored
   *   }
   * }
   * 
   * 
   * @param conn - the connection to use for the session
   *
   * @return An SqlMapSession instance.
   */
  public SqlMapSession openSession(Connection conn);

  /**
   * TODO : Deprecated and will be removed.
   *
   * @return A session (DEPRECATED)
   * @deprecated Use openSession() instead.  THIS METHOD WILL BE REMOVED BEFORE
   *             FINAL RELEASE.
   */
  public SqlMapSession getSession();

  /**
   * Flushes all data caches.
   */
  public void flushDataCache();

  /**
   * Flushes the data cache that matches the cache model ID provided. 
   * cacheId should include the namespace, even when 
   * useStatementNamespaces="false".
   *
   * @param cacheId The cache model to flush
   */
  public void flushDataCache(String cacheId);

  /**
   * Returns a generated implementation of a cusom mapper class as specified by the method
   * parameter.  The generated implementation will run mapped statements by matching the method
   * name to the statement name.  The mapped statement elements determine how the statement is
   * run as per the following:
   * 
   *   <insert> -- insert()
   *   
<update> -- update()
   *   
<delete> -- delete()
   *   
<select> -- queryForObject, queryForList or queryForMap, as determined by signature (see below)
   *   
<procedure> -- determined by method name (see below)
   * 
   *
   * How select statements are run is determined by the method signature,
   * as per the following:
   * 
   *    Object methodName (Object param) -- queryForObject
   *   
 List methodName (Object param [, int skip, int max | , int pageSize]) -- queryForList
   *   
 Map methodName (Object param, String keyProp [,valueProp]) -- queryForMap
   * 
   *
   * How stored procedures are run is determined by the method name,
   * as per the following:
   * 
   *    insertXxxxx -- insert()
   *   
 createXxxxx -- insert()
   *   
 updateXxxxx -- update()
   *   
 saveXxxxx -- update()
   *   
 deleteXxxxx -- delete()
   *   
 removeXxxxx -- delete()
   *   
 selectXxxxx -- queryForXxxxxx() determined by method signature as above
   *   
 queryXxxxx -- queryForXxxxxx() determined by method signature as above
   *   
 fetchXxxxx -- queryForXxxxxx() determined by method signature as above
   *   
 getXxxxx -- queryForXxxxxx() determined by method signature as above
   * 
   *
   * @param iface The interface that contains methods representing the mapped statements contained.
   * @return An instance of iface that can be used to call mapped statements directly in a typesafe
   * manner.
   */
  //public Object getMapper(Class iface);
}