Metacat

/**

 *  '$RCSfile$'

 *  Copyright: 2010 Regents of the University of California and the

 *             National Center for Ecological Analysis and Synthesis

 *

 *   '$Author: jones $'

 *     '$Date: 2010-02-03 17:58:12 -0900 (Wed, 03 Feb 2010) $'

 * '$Revision: 5211 $'

 *

 * 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.

 *

 * You should have received a copy of the GNU 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

 */

package edu.ucsb.nceas.metacat;

import java.sql.PreparedStatement;

import java.sql.ResultSet;

import java.sql.SQLException;

import org.apache.log4j.Logger;

import edu.ucsb.nceas.metacat.database.DBConnection;

import edu.ucsb.nceas.metacat.database.DBConnectionPool;

import edu.ucsb.nceas.metacat.util.DocumentUtil;

/**

 * Manage the relationship between Metacat local identifiers (LocalIDs) that are

 * codified as the (docid, rev) pair with globally uniqe string identifiers

 * (GUIDs) that are opaque strings.  This class provides methods to manage these

 * identifiers, and to search for and look up LocalIDs based on their GUID and

 * vice versa. IdentifierManager is a singleton.

 * 

 * @author Matthew Jones

 */

public class IdentifierManager {

    public static final String TYPE_SYSTEM_METADATA = "systemmetadata";

    public static final String TYPE_IDENTIFIER = "identifier";

    /**

     * The single instance of the manager that is always returned.

     */

    private static IdentifierManager self = null;

    private Logger logMetacat = Logger.getLogger(EventLog.class);

    /**

     * A private constructor that initializes the class when getInstance() is

     * called.

     */

    private IdentifierManager()

    {

    }

    /**

     * Return the single instance of the manager after initializing it if it

     * wasn't previously initialized.

     * 

     * @return the single IdentifierManager instance

     */

    public static IdentifierManager getInstance()

    {

        if (self == null) {

            self = new IdentifierManager();

        }

        return self;

    }

    /**

     * Lookup a GUID from the database, and return the associated LocalID. If

     * the identifier is not found, throw an exception.

     * 

     * @param guid the global identifier to look up

     * @return String containing the corresponding LocalId

     * @throws McdbDocNotFoundException if the identifier is not found

     */

    public String getLocalId(String guid) throws McdbDocNotFoundException

    {

        return this.getId(guid, TYPE_IDENTIFIER);

    }

    /**

     * Determine if an identifier exists already, returning true if so.

     * 

     * @param guid the global identifier to look up

     * @return boolean true if the identifier exists

     */

    public boolean identifierExists(String guid)

    {

        boolean idExists = false;

        try {

            String id = getLocalId(guid);

            if (id != null) {

                idExists = true;

            }

        } catch (McdbDocNotFoundException e) {

            idExists = false;

        }

        return idExists;

    }

    /**

     * Create a mapping between two identifiers, one representing an 

     * unconstrained, globally unique string (guid), and one a localId 

     * in the Metacat docid format (scope.id.revision). 

     * This mapping allows one to find the global id (guid) from the localId.

     * 

     * @param guid the global string identifier to be mapped

     * @param localId the local identifier to be mapped

     */

    public void createMapping(String guid, String localId)

    {   

        createGenericMapping(guid, localId, TYPE_IDENTIFIER);

    }

    /**

     * Given a global identifier (guid), create a suitable local identifier that

     * follows Metacat's docid semantics and format (scope.id.rev), and create

     * a mapping between these two identifiers.  This effectively reserves both

     * the global and the local identifier, as they will now be present in the

     * identifier mapping table.  If the incoming guid has the syntax of a

     * Metacat docid (scope.id.rev), then simply use it.

     * 

     * @param guid the global string identifier

     * @param rev the revision number to be used in the localId

     * @return String containing the localId to be used for Metacat operations

     */

    public String generateLocalId(String guid, int rev) 

    {

        String localId = "";

        boolean conformsToDocidFormat = false;

        // Check if the guid passed in is already in docid (scope.id.rev) format

        try {

            AccessionNumber acc = new AccessionNumber(guid, "NONE");

            if (new Integer(acc.getRev()).intValue() > 0) {

                conformsToDocidFormat = true;

            }

        } catch (NumberFormatException e) {

            // No action needed, simply detecting invalid AccessionNumbers

        } catch (AccessionNumberException e) {

            // No action needed, simply detecting invalid AccessionNumbers

        } catch (SQLException e) {

            // No action needed, simply detecting invalid AccessionNumbers

        }

        if (conformsToDocidFormat) {

            // if it conforms, use it for both guid and localId

            localId = guid;

        } else {

            // if not, then generate a new unique localId

            localId = DocumentUtil.generateDocumentId(rev);

        }

        // Register this new pair in the identifier mapping table

        createMapping(guid, localId);

        return localId;

    }

    /**

     * given a local identifer, look up the guid.  Throw McdbDocNotFoundException

     * if the docid, rev is not found in the identifiers table

     *

     * @param docid the docid to look up

     * @param rev the revision of the docid to look up

     * @return String containing the mapped guid

     * @throws McdbDocNotFoundException if the docid, rev is not found

     */

    public String getGUID(String docid, int rev)

      throws McdbDocNotFoundException

    {

        String query = "select guid from identifier where docid = ? and rev = ?";

        String guid = null;

        DBConnection dbConn = null;

        int serialNumber = -1;

        try {

            // Get a database connection from the pool

            dbConn = DBConnectionPool.getDBConnection("Identifier.getGUID");

            serialNumber = dbConn.getCheckOutSerialNumber();

            // Execute the insert statement

            PreparedStatement stmt = dbConn.prepareStatement(query);

            stmt.setString(1, docid);

            stmt.setInt(2, rev);

            ResultSet rs = stmt.executeQuery();

            if (rs.next()) {

                guid = rs.getString(1);

            } else {

                throw new McdbDocNotFoundException("Document not found:" + guid);

            }

            stmt.close();

        } catch (SQLException e) {

            logMetacat.error("Error while looking up the guid: " 

                    + e.getMessage());

        } finally {

            // Return database connection to the pool

            DBConnectionPool.returnDBConnection(dbConn, serialNumber);

        }

        return guid;

    }

    /**

     * insert a system metadata id for a local id

     * 

     * @param guid the id to insert

     * @param localId the systemMetadata object to get the local id for

     */

    public void createSystemMetadataMapping(String guid, String localId)

    {

        createGenericMapping(guid, localId, TYPE_SYSTEM_METADATA);

    }

    /**

     * return the localId of a system metadata document based on its guid

     */

    public String getSystemMetadataId(String guid)

      throws McdbDocNotFoundException

    {

      return this.getId(guid, TYPE_SYSTEM_METADATA);

    }

    /**

     * return a localId based on a guid.  The type can either be 'identifier' 

     * to get an id from the identifier table or 'systemmetadata' to get

     * the identifier from the systemidentifier table

     */

    private String getId(String guid, String type)

      throws McdbDocNotFoundException

    {

      if(!type.equals(TYPE_IDENTIFIER) &&

        !type.equals(TYPE_SYSTEM_METADATA))

      {

        throw new RuntimeException("cannot lookup the identifier for type " + type +

          ".  Please choose 'identifier' or 'systemmetadata'.");

      }

      String db_guid = "";

      String docid = "";

      int rev = 0;

      String query = "select guid, docid, rev from " + type + " where guid = ?";

      DBConnection dbConn = null;

      int serialNumber = -1;

      try {

          // Get a database connection from the pool

          dbConn = DBConnectionPool.getDBConnection("Identifier.getLocalId");

          serialNumber = dbConn.getCheckOutSerialNumber();

          // Execute the insert statement

          PreparedStatement stmt = dbConn.prepareStatement(query);

          stmt.setString(1, guid);

          ResultSet rs = stmt.executeQuery();

          if (rs.next()) {

              db_guid = rs.getString(1);

              docid = rs.getString(2);

              rev = rs.getInt(3);

              assert(db_guid.equals(guid));

          } else {

              throw new McdbDocNotFoundException("Document not found:" + guid);

          }

          stmt.close();

      } catch (SQLException e) {

          logMetacat.error("Error while looking up the local identifier: " 

                  + e.getMessage());

      } finally {

          // Return database connection to the pool

          DBConnectionPool.returnDBConnection(dbConn, serialNumber);

      }

      return docid + "." + rev;

    }

    private void createGenericMapping(String guid, String localId, String type)

    {

        if(!type.equals(TYPE_IDENTIFIER) &&

        !type.equals(TYPE_SYSTEM_METADATA))

        {

          throw new RuntimeException("Cannot create mapping for type " + type +

            ".  Please choose 'identifier' or 'systemmetadata'.");

        }

        int serialNumber = -1;

        DBConnection dbConn = null;

        try {

            // Parse the localId into scope and rev parts

            AccessionNumber acc = new AccessionNumber(localId, "NOACTION");

            String docid = acc.getDocid();

            int rev = (new Integer(acc.getRev()).intValue());

            // Get a database connection from the pool

            dbConn = 

                DBConnectionPool.getDBConnection("Identifier.createMapping");

            serialNumber = dbConn.getCheckOutSerialNumber();

            // Execute the insert statement

            String query = "insert into " + type + " (guid, docid, rev) values (?, ?, ?)";            

            PreparedStatement stmt = dbConn.prepareStatement(query);

            stmt.setString(1, guid);

            stmt.setString(2, docid);

            stmt.setInt(3, rev);

            int rows = stmt.executeUpdate();

            stmt.close();

        } catch (SQLException e) {

            logMetacat.error("SQL error while creating a mapping to the system metadata identifier: " 

                    + e.getMessage());

        } catch (NumberFormatException e) {

            logMetacat.error("NumberFormat error while creating a mapping to the system metadata identifier: " 

                    + e.getMessage());

        } catch (AccessionNumberException e) {

            logMetacat.error("AccessionNumber error while creating a mapping to the system metadata identifier: " 

                    + e.getMessage());

        } finally {

            // Return database connection to the pool

            DBConnectionPool.returnDBConnection(dbConn, serialNumber);

        }

    }

}