/*
* File : ConnectionBeanProvider.java
* Created : 21-oct-2003 18:18
* By : fbusquets
*
* JClic - Authoring and playing system for educational activities
*
* Copyright (C) 2000 - 2005 Francesc Busquets & Departament
* d'Educacio de la Generalitat de Catalunya
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details (see the LICENSE file).
*/
package edu.xtec.util.db;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.util.HashMap;
import java.util.Map;
/**
* Classes that extended this abstract class provide {@link edu.xtec.util.db.ConnectionBean}
* objects to clients. It also provides a static method to create ConnectionBeanProvider objects
* based on different parameters, and stores a map containing all the created
* objects, in order to reuse them between different instances or applications
* sharing the same JVM.
* @author Francesc Busquets (fbusquets@xtec.cat)
* @version 13.09.16
*/
public abstract class ConnectionBeanProvider {
/** Tag used in properties to identify the JDBC driver used in the connections
* to the database.
*/
public static final String DB_DRIVER="dbDriver";
/** Tag used in properties to identify the server used in connections */
public static final String DB_SERVER="dbServer";
/** Tag used in properties to identify the login name used in connections. */
public static final String DB_LOGIN="dbLogin";
/** Tag used in properties to identify the password used in connections. */
public static final String DB_PASSWORD="dbPassword";
/**
* Tag used in properties to determine if the {@link edu.xtec.util.db.ConnectionBean}
* objects created must store and reuse {@link java.sql.PreparedStatement} objects.
*/
public static final String MAP_STATEMENTS="dbMapStatements";
/** Tag used for <I>true</I> */
public static final String TRUE = "true";
/** Tag used for <I>false</I> */
public static final String FALSE="false";
/**
* Name of the JDBC driver used in Connection objects
*/
protected String dbDriver;
/**
* Name of the JDBC url used in Connection objects
*/
protected String dbServer;
/** Name of the user used in Connection objects. */
protected String dbLogin;
/**
* Password used in JDBC Connection objects.
*/
protected String dbPassword;
/**
* When true, the {@link edu.xtec.util.db.ConnectionBean} objects created will store and reuse
* prepared statements.
*/
protected boolean mapStatements;
private int useCount;
private static Map<String, ConnectionBeanProvider> cbProviders;
/**
* Main initialization function. Must be called immediatelly after constructor by
* getConnectionBeanProvider functions.
* @param map Collection of key - value pairs that must specify the driver, url, login and
* password of the just created ConnectionBeanProvider.
* @throws Exception Throwed if dbDriver does not contain a valid driver name, or if it can't be
* instantiated.
*/
protected void setUp(Map<String, String> map) throws Exception{
dbDriver = getValue(map, DB_DRIVER, null);
dbServer = getValue(map, DB_SERVER, null);
dbLogin = getValue(map, DB_LOGIN, null);
dbPassword = getValue(map, DB_PASSWORD, null);
mapStatements = !FALSE.equals(getValue(map, MAP_STATEMENTS, TRUE));
useCount=0;
}
/** This is the main function that all ConnectionbeanProvider objects must
* implement.<P>
* <B>Important:</B> You must ever call FreeConnectionBean after the use of the ConnectionBean
* object. Typical inmplementation use a try - catch - finally statement block in
* order to ensure that all ConnectionBean objects will be properly disposed after
* use.<P>
* Example:<P>
* <PRE>
* ConectionBeanProvider cbp;
* java.util.Properties prop=new Java.util.Properties();
* // ...
* // ... fill-up properties with values for dbDriver, dbServer, dbLogin, etc.
* // ...
* cbp=ConnectionBeanProvider.getConnectionBeanProvider(map);
* ConnectionBean cb=cbp.getConnectionBean();
* try {
* // ... use of the ConnectionBean object
* } catch(Exception ex){
* // ... process possible exceptions done while database access
* } finally {
* // Very important: free the ConnectionBean object:
* cbp.freeConnectionBean(cb);
* }
* </PRE>
* @return A ready-to-use ConnectionBean. Remember to return it by calling
* FreeConnectionBean.
*/
public abstract ConnectionBean getConnectionBean();
/** This method must be called when the obtained ConnectionBean is no longer needed,
* usualy inside the <I>finally</I> block of a <I>try - catch</I> statement.
* @param conn The ConnectionBean object to be disposed
* @return A descriptive String, useful only for debug purposes.
*/
public abstract String freeConnectionBean(ConnectionBean conn);
/**
* This method will be called before finalization. Implementations of
* <CODE>ConnectionBeanProvider</CODE> must perform cleanup operations on all opened
* connections.
*/
protected abstract void destroy();
/**
* Provides information about the current state of this <CODE>ConnectionBeanProvider</CODE>.
* @return Information string, formatted in HTML.
*/
public String getInfo(){
StringBuilder sb=new StringBuilder();
sb.append(DB_DRIVER).append(": ").append(dbDriver).append("<br>\n");
sb.append(DB_SERVER).append(": ").append(dbServer).append("<br>\n");
sb.append(DB_LOGIN).append(": ").append(dbLogin).append("<br>\n");
sb.append(MAP_STATEMENTS).append(": ").append(mapStatements).append("<br>\n");
sb.append("Use count:").append(useCount).append("<br>\n");
return sb.substring(0);
}
/**
* Provides information about all the <CODE>ConnectionBeanProvider</CODE> objects currently
* existing.
* @return Information string, formatted in HTML.
*/
public static String getGlobalInfo(){
StringBuilder sb=new StringBuilder();
if(cbProviders==null)
cbProviders=new HashMap<String, ConnectionBeanProvider>(2);
sb.append("<b>").append(cbProviders.size()).append(" ConnectionBeanProviders created</b><br>\n");
for(String key : cbProviders.keySet()){
ConnectionBeanProvider cbp=cbProviders.get(key);
sb.append("<hr>\n");
sb.append(cbp.getInfo());
}
return sb.substring(0);
}
/**
* Method used to build a ConnectionBeanProvider. The current
* implementations returns a {@link edu.xtec.util.db.SingleConnectionBeanProvider} if <CODE>mapStatements</CODE>
* is <I>false</I>. Otherwise, it checks the value of <CODE>dbDriverName</CODE> to return a
* {@link PooledConnectionBeanProvider} or a {@link
* edu.xtec.util.db.JNDIConnectionBeanProvider}.
* @param pooled Determines the type of ConnectionbeanProvider to be created: pooled or simple.
* @param dbDriver Name of the JDBC driver to be used. When this param is "JNDI", a
* {@link edu.xtec.util.db.JNDIConnectionBeanProvider} will be created.
* @param dbServer Path to the JDBC source or JNDI datasource to be used.
* @param dbLogin User name to be used in JDB connections.
* @param dbPassword Password to be used in JDBC connections.
* @param mapStatements When <i>true</i>, the created {@link edu.xtec.util.db.ConnectionBean}
* objects will reuse PreparedStatements.
* @throws Exception If something goes wrong.
* @return The ConnectionBean object.
*/
public static ConnectionBeanProvider getConnectionBeanProvider(boolean pooled,
String dbDriver, String dbServer, String dbLogin, String dbPassword,
boolean mapStatements) throws Exception{
Map<String, String> map=new HashMap<String, String>();
map.put(DB_DRIVER, dbDriver);
map.put(DB_SERVER, dbServer);
map.put(DB_LOGIN, dbLogin);
map.put(DB_PASSWORD, dbPassword);
map.put(MAP_STATEMENTS, mapStatements ? TRUE : FALSE);
return getConnectionBeanProvider(pooled, map);
}
/**
* This method calls the many-params version of getConnectionBeanProvider(),
* extracting the needed parameters from the map.
* @param map Collection containing all the key - value pairs needed to create the
* ConnectionBeanProvider object.
* @param pooled Determines the type of <CODE>ConnectionbeanProvider</CODE> to be created: <I>pooled</I> or <I>simple</I>.
* @throws Exception If something goes wrong.
* @return The requested ConnectionBeanProvider object.
*/
public static ConnectionBeanProvider getConnectionBeanProvider(boolean pooled, Map<String, String> map) throws Exception{
ConnectionBeanProvider result=null;
String staticDbDriver=map.get(DB_DRIVER);
String staticDbServer=map.get(DB_SERVER);
String staticDbLogin=map.get(DB_LOGIN);
StringBuilder kb=new StringBuilder();
kb.append(staticDbDriver).append("@");
kb.append(staticDbServer).append("@");
kb.append(staticDbLogin).append("@");
kb.append(pooled ? "POOLED" : "DIRECT");
String ks=kb.substring(0);
if(cbProviders==null)
cbProviders=new HashMap<String, ConnectionBeanProvider>(2);
else
result = cbProviders.get(ks);
/*
Iterator it=cbProviders.keySet().iterator();
while(it.hasNext()){
Object o=it.next();
if(o!=null && o.equals(ks)){
result=(ConnectionBeanProvider)cbProviders.get(o);
break;
}
}
*/
if(result==null){
if(JNDIConnectionBeanProvider.JNDI.equals(staticDbDriver))
result=new JNDIConnectionBeanProvider();
else if(pooled)
result=new PooledConnectionBeanProvider();
else
result=new SingleConnectionBeanProvider();
result.setUp(map);
cbProviders.put(ks, result);
}
result.useCount++;
result.readDBSettings(map);
return result;
}
/** Use this method when a ConectionbeanProvider is no longer needed.
* ConnectionBeanProvider objects are stored into a static collection, so they can
* be reused when multiple classes (or multiple instances of the same class) need
* them. The ConnectionBeanProvider object will be destroyed only when a internal
* counter decreases to zero.
* @param cbp The ConnectionBeanProvider to be released.
*/
public static void freeConnectionBeanProvider(ConnectionBeanProvider cbp){
if(cbp!=null && cbProviders!=null){
for (String s : cbProviders.keySet()) {
ConnectionBeanProvider o=cbProviders.get(s);
if(o!=null && o.equals(cbp) && --cbp.useCount<=0){
cbp.destroy();
cbProviders.remove(s);
break;
}
}
}
}
/**
* Useful method used to retrieve a value from a Map using a default value when not
* found, or when found with <I>null</I> value.
* @param map The map where to search for
* @param key The key to be searched
* @param defaultValue Value returned when not found or null
* @return The String associated with the specified key, or the defaultValue if not found.
*/
protected String getValue(Map<String, String> map, String key, String defaultValue){
String result=map.get(key);
if(result==null || result.trim().length()==0)
result=defaultValue;
return result;
}
/**
* Key for the name of the database table that contains key-value pairs of settings
*/
public static final String SETTINGS_TABLE_KEY="SETTINGS_TABLE";
/**
* Default name for the settings table
*/
public static final String DEFAULT_SETTINGS_TABLE = "SETTINGS";
/**
* All the settings with this value will be read from the database
*/
public static final String READ_FROM_DATABASE="READ_FROM_DATABASE";
/**
* This function looks inside a map for entries with the value "READ_FROM_DATABASE".
* All settings with this text will be replaced with the value stored in a
* table names "SETTINGS" (or with the name specified in the map with the key
* "SETTINGS_TABLE"). This table must contain at least two fields: "SETTING_KEY"
* and "SETTING_VALUE".
* @param map The map to be processed
* @throws Exception If the database is not accessible.
*/
public void readDBSettings(Map<String, String> map) throws Exception{
Exception exception=null;
String settingsTable=getValue(map, SETTINGS_TABLE_KEY, DEFAULT_SETTINGS_TABLE);
if(settingsTable!=null && map.containsValue(READ_FROM_DATABASE)){
edu.xtec.util.db.ConnectionBean con=null;
PreparedStatement stmt=null;
ResultSet rs=null;
try{
con=getConnectionBean();
String sql= "SELECT SETTING_VALUE"+
" FROM "+settingsTable+
" WHERE SETTING_KEY=?";
stmt=con.getPreparedStatement(sql);
for (String key : map.keySet()) {
String value=map.get(key);
if(READ_FROM_DATABASE.equals(value)){
stmt.setString(1, key);
rs=stmt.executeQuery();
if(rs.next()){
value=rs.getString(1);
map.put(key, value);
}
}
}
} catch(Exception ex) {
exception=ex;
} finally {
if(rs!=null)
rs.close();
if(stmt!=null && con!=null)
con.closeStatement(stmt);
if(con!=null)
freeConnectionBean(con);
}
}
if(exception!=null)
throw exception;
}
}