//  Copyright (c) 2002, G. KLYNE
//  All rights reserved.
//
//  Redistribution and use in source and binary forms, with or without
//  modification, are permitted provided that the following conditions
//  are met:
//  1. Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
//  2. Redistributions in binary form must reproduce the above copyright
//     notice, this list of conditions and the following disclaimer in the
//     documentation and/or other materials provided with the distribution.
//  3. The name of the author may not be used to endorse or promote products
//     derived from this software without specific prior written permission.
//
//  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
//  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
//  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
//  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
//  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
//  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
//  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
//  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
//  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
//  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
//  $Author: graham $
//  $Date: 2002/05/16 13:19:01 $
//  $Source: /file/cvsdev/PythonN3/N3JenaRdb.java,v $
//  $Id: N3JenaRdb.java,v 1.2 2002/05/16 13:19:01 graham Exp $
//
//-------+---------+---------+---------+---------+---------+---------+---------+
//       1         2         3         4         5         6         7         8

// package org.ninebynine.PyJena ;
// package N3JenaRdb ;

import com.hp.hpl.mesa.rdf.jena.model.Model ;

import com.hp.hpl.mesa.rdf.jena.rdb.ModelRDB ;
import com.hp.hpl.mesa.rdf.jena.rdb.IDBConnection ;
import com.hp.hpl.mesa.rdf.jena.rdb.DBConnection ;
import com.hp.hpl.mesa.rdf.jena.rdb.IRDBDriver ;
import com.hp.hpl.mesa.rdf.jena.rdb.DriverGenericGeneric ;

/**
 * N3JenaRdb is a thin wrapper for the Jena ModelRdb class, to handle the
 * awkward aspects of Java interfacing to Python.  This class aims to provide
 * a clean, simple interface to Jena from Python.
 * <p>
 * It may be that this class has very little to do - it is designed in to the
 * Python/Jena interface as a safety net for catching things that don't
 * work across the language boundary.
 *
 * @author Graham Klyne
 *
 */

public class N3JenaRdb
    {
    /**
     *  Knowledge base name string
     */
    String m_KBName = null ;

    /**
     *  Knowledge database type string
     */
    String m_DBType = null ;

    /**
     *  Error diagnostic, or null
     */
    String m_Error = null ;

    /**
     * Reference to database connection used for RDB-based model, or null.
     * (Not sure if we need to keep this value around:
     * can be dropped if it proves pointless.)
     *
     * @see ModelRDB.getStore
     */
    IDBConnection m_DBCon = null ;

    /**
     * Reference to Jena model implementation used
     */
    Model m_Model = null ;

    /**
     *  Create a new database-hosted Model object,
     *  using an existing database for the purpose.
     *  <p>
     *  NOTE: the database must be created before calling this method,
     *  but it may be empty.
     *
     * @param   dbtype  is the type of database used to hold the RDF model;
     *                  e.g. "Mysql" (see Jena RDB notes for more details).
     * @param   dburl   is the JDBC URL of the database to be accessed;
     *                  e.g. jdbc:mysql://luggage.atuin.ninebynine.org/SemaFor
     * @param   dbuser  is the username to use for accessing the database.
     * @param   dbpass  is the password to use for accessing the database.
     */
    public N3JenaRdb
      ( String dbtype, String dburl, String dbuser, String dbpass )
        {
        m_KBName = dburl ;
        m_DBCon  = new DBConnection( dburl, dbuser, dbpass ) ;
        m_DBType = dbtype ;
        m_Model  = null ;
        m_Error  = null ;
        try
            {
            IRDBDriver driver = m_DBCon.getDriver( "Generic", m_DBType ) ;
            /** @todo change this when Jena RDB method added to IRDBDriver */
            ((DriverGenericGeneric)driver).loadDatabaseDriver() ;
            m_Model = new ModelRDB( m_DBCon ) ;
            }
        catch ( com.hp.hpl.mesa.rdf.jena.rdb.RDFRDBException e )
            {
            m_Model  = null ;
            m_Error  = e.toString() ;
            }
        return ;
        }

    /**
     *  Format the database with a new, empty RDF model, if it is
     *  not already formatted.
     *
     * @return  the newly created Jena Model instance, or null
     *          if the operation fails.
     */
    public Model format()
        {
        if ( m_Model != null ) m_Model.close() ;
        try
            {
            m_Model = ModelRDB.create( m_DBCon, "Generic", m_DBType ) ;
            }
        catch ( com.hp.hpl.mesa.rdf.jena.rdb.RDFRDBException e )
            {
            m_Model  = null ;
            m_Error  = e.toString() ;
            }
        return m_Model ;
        }

    /**
     *  Close model store base and release any resources.
     */
    public void close()
        {
        if ( m_Model != null ) m_Model.close() ;
        m_Model = null ;
        m_DBCon = null ;
        return ;
        }

    /**
     *  Return the underlying Jena model object.
     *
     * @return  An instance of the Jena Model type.
     */
    public Model getModel()
        {
        return m_Model ;
        }

    /**
     *  Return the current error diagnostic string
     *
     * @return  A string describing the current error condition,
     *          or null if there is none.
     */
    public String getError()
        {
        return m_Error ;
        }

    /**
     *  Return the string representation of the knowledge base.
     *
     * @return  a string representing the knowledge base.
     */
    public String toString()
        {
        return "N3JenaRdb(" + m_KBName + ")" ;
        }

    }   // End of N3JenaRdb

//-------+---------+---------+---------+---------+---------+---------+---------+
//  $Log: N3JenaRdb.java,v $
//  Revision 1.2  2002/05/16 13:19:01  graham
//  Fix use of Jena ModelDB.create() method.
//  (db is initialized only if not already present.)
//
//  Revision 1.1  2002/05/15 17:21:13  graham
//  N3ModelJenaRdb.py, with supporting code,
//  works with a Jena RDB model store.
//  Tested against a MySQL server.
//
//