jdbcdocumentcollection.java

MG4J (Managing Gigabytes for Java) is a free full-text search engine for large document collections

package it.unimi.dsi.mg4j.document;

/*		 
 * MG4J: Managing Gigabytes for Java
 *
 * Copyright (C) 2005-2007 Sebastiano Vigna 
 *
 *  This library is free software; you can redistribute it and/or modify it
 *  under the terms of the GNU Lesser General Public License as published by the Free
 *  Software Foundation; either version 2.1 of the License, or (at your option)
 *  any later version.
 *
 *  This library 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 Lesser General Public License
 *  for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 *
 */

import it.unimi.dsi.fastutil.ints.Int2IntMap;
import it.unimi.dsi.fastutil.ints.Int2IntOpenHashMap;
import it.unimi.dsi.fastutil.ints.IntArrayList;
import it.unimi.dsi.fastutil.io.BinIO;
import it.unimi.dsi.fastutil.objects.Reference2ObjectArrayMap;
import it.unimi.dsi.fastutil.objects.Reference2ObjectMap;
import it.unimi.dsi.io.MultipleInputStream;
import it.unimi.dsi.io.NullInputStream;
import it.unimi.dsi.lang.MutableString;
import it.unimi.dsi.mg4j.document.PropertyBasedDocumentFactory.MetadataKeys;
import it.unimi.dsi.mg4j.util.MG4JClassParser;

import java.io.IOException;
import java.io.InputStream;
import java.io.ObjectInputStream;
import java.io.Serializable;
import java.lang.reflect.InvocationTargetException;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.sql.Statement;

import com.martiansoftware.jsap.FlaggedOption;
import com.martiansoftware.jsap.JSAP;
import com.martiansoftware.jsap.JSAPException;
import com.martiansoftware.jsap.JSAPResult;
import com.martiansoftware.jsap.Parameter;
import com.martiansoftware.jsap.SimpleJSAP;
import com.martiansoftware.jsap.UnflaggedOption;

/** A {@link it.unimi.dsi.mg4j.document.DocumentCollection} corresponding to
 *  the result of a query in a relational database.
 * 
 * <p>An instance of this class is based on a query. The query should produce two
 * fixed columns: the first, named <samp>id</samp>, must be an increasing integer
 * which act as an identifier (i.e., as a key); the second, named <samp>title</samp>, must be a text field and will 
 * be used as a title. The remaining columns will be indexed, and the name of the corresponding
 * field will be the name of the column (use judiciously <samp>AS</samp>).
 *
 * <p>In complex queries, the specification <samp>id</samp> for the first column
 * could be ambiguous; in that case, you can provide an alternate (and hopefully more precise) specification.
 * 
 * <p>At construction time, the query is executed, obtaining a bijection between
 * the values of the identifier and document indices. The bijection is exposed by the
 * methods {@link #id2doc(int)} and {@link #doc2id(int)}. The class tolerates
 * additions to the database (and they will be skipped), but deletions will cause errors.
 * 
 * <P>This class provides a main method with a flexible syntax that serialises
 * a query into a document collection.
 */
public class JdbcDocumentCollection extends AbstractDocumentCollection implements Serializable {

	private static final long serialVersionUID = 1L;
	/** The map from database identifiers to documents. */
	final protected Int2IntMap id2doc;
	/** The map (as an array) from documents to database identifiers. */
	final protected int[] doc2id;
	/** The URI pointing at the database. */
	final protected String dbUri;
	/** Optionally, the driver. */
	@SuppressWarnings("unchecked")
	transient Class jdbcDriver;
	/** Optionally, the driver name. */
	final String jdbcDriverName;
	/** The factory to be used by this collection. */
	final protected DocumentFactory factory;
	/** The query generating the collection (without the <samp>SELECT</samp> keyword). */
	final protected String select;
	/** The spec for the id field; by default it is <samp>id</samp>, but in complex query it could be ambiguous. */
	final protected String idSpec;
	/** The <samp>WHERE</samp> part of the query generating 
	 * the collection (without the <samp>WHERE</samp> keyword), or <code>null</code>. */
	final protected String where;
	
	/** Creates a document collection based on the result set of an SQL query using <samp>id</samp> as id specifier.
	 * 
	 * <p><strong>Beware.</strong> This class is not guaranteed to work if the database is
	 * deleted or modified after creation!
	 * 
	 * @param dbUri a JDBC URI pointing at the database.
	 * @param jdbcDriverName the name of a JDBC driver, or <code>null</code> if you do not want to load a driver.
	 * @param select the SQL query generating the collection (without the <samp>SELECT</samp> keyword), except for the <samp>WHERE</samp> part.
	 * @param where the <samp>WHERE</samp> part (without the <samp>WHERE</samp> keyword) of the SQL query generating the collection, or <code>null</code>.
	 * @param factory the factory that will be used to create documents.
	 */
	public JdbcDocumentCollection( final String dbUri, final String jdbcDriverName, final String select, final String where, final DocumentFactory factory ) throws SQLException, ClassNotFoundException {
		this( dbUri, jdbcDriverName, select, "id", where, factory );
	}

	/** Creates a document collection based on the result set of an SQL query.
	 * 
	 * <p><strong>Beware.</strong> This class is not guaranteed to work if the database is
	 * deleted or modified after creation!
	 * 
	 * @param dbUri a JDBC URI pointing at the database.
	 * @param jdbcDriverName the name of a JDBC driver, or <code>null</code> if you do not want to load a driver.
	 * @param select the SQL query generating the collection (without the <samp>SELECT</samp> keyword), except for the <samp>WHERE</samp> part.
	 * @param idSpec the complete SQL spec for the <samp>id</samp> (necessary for complex queries with multiple tables).
	 * @param where the <samp>WHERE</samp> part (without the <samp>WHERE</samp> keyword) of the SQL query generating the collection, or <code>null</code>.
	 * @param factory the factory that will be used to create documents.
	 */
	public JdbcDocumentCollection( final String dbUri, final String jdbcDriverName, final String select, final String idSpec, final String where, final DocumentFactory factory ) throws SQLException, ClassNotFoundException {
		this.dbUri = dbUri;
		this.jdbcDriverName = jdbcDriverName;
		this.select = select;
		this.idSpec = idSpec;
		this.where = where;
		this.factory = factory;
		
		initDriver();
		Connection connection = DriverManager.getConnection( dbUri );
		Statement s = connection.createStatement();
		ResultSet rs = s.executeQuery( buildQuery( null ) );
		
		id2doc = new Int2IntOpenHashMap();
		id2doc.defaultReturnValue( -1 );
		final IntArrayList ids = new IntArrayList();
		int id;
		for( int i = 0; rs.next(); i++ ) {
			id = rs.getInt( 1 );
			ids.add( id );
			id2doc.put( i, id );
		}
		
		doc2id = ids.toIntArray();
	}

	public JdbcDocumentCollection copy() {
		try {
			return new JdbcDocumentCollection( dbUri, jdbcDriverName, select, idSpec, where, factory.copy() );
		}
		catch ( Exception e ) {
			throw new RuntimeException( e );
		}
	}
	
	/** Creates a complete query using instance data and possibly an additional <samp>WHERE</samp> clause.
	 * 
	 * @param additionalWhere an additional condition for the <samp>WHERE</samp> clause.
	 * @return a complete query based on instance data and <code>additionalWhere</code>,
	 */
	
	private String buildQuery( final String additionalWhere ) {
		final MutableString query = new MutableString();
		query.append( "SELECT " ).append( select );
		if ( where == null && additionalWhere != null ) query.append( " WHERE (" ).append( additionalWhere ).append( ")" );
		if ( where != null && additionalWhere == null ) query.append( " WHERE (" ).append( where ).append( ")" );
		if ( where != null && additionalWhere != null ) query.append( " WHERE (" ).append( where ).append( ") AND (" ).append( additionalWhere ).append( ")" ); 
		query.append( " ORDER BY 1" );
		return query.toString();
	}
	
	private void initDriver() throws ClassNotFoundException {
		jdbcDriver = jdbcDriverName != null ? Class.forName( jdbcDriverName ) : null;
	}
	
	public DocumentFactory factory() {
		return factory;
	}
	
	public int size() {
		return doc2id.length;
	}