edu.ucsb.nceas.metacat

## Class IdentifierManager

- java.lang.Object
- - edu.ucsb.nceas.metacat.IdentifierManager

-     public class IdentifierManager
      extends java.lang.Object

  Manage the relationship between Metacat local identifiers (LocalIDs) that are codified as the (docid, rev) pair with globally unique 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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TYPE_IDENTIFIER`
    `static java.lang.String` | `TYPE_SYSTEM_METADATA`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.List<org.dataone.service.types.v1.Permission>` | `convertPermission(int permission)`
    `int` | `convertPermission(org.dataone.service.types.v1.Permission permission)`
    `void` | `createMapping(java.lang.String guid, java.lang.String localId)` create a mapping in the identifier table
    `boolean` | `deleteSystemMetadata(java.lang.String guid)`
    `boolean` | `existsInIdentifierTable(org.dataone.service.types.v1.Identifier pid)` Determine if the given pid exists on the identifier table.
    `boolean` | `existsInXmlLRevisionTable(java.lang.String docid, int rev)` IF the given localId exists on the xml_revisions table
    `java.lang.String` | `generateLocalId(java.lang.String guid, int rev)`
    `java.lang.String` | `generateLocalId(java.lang.String guid, int rev, boolean isSystemMetadata)` 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.
    `org.dataone.service.types.v1.AccessPolicy` | `getAccessPolicy(java.lang.String guid)` Lookup access policy from Metacat
    `java.util.List<java.lang.String>` | `getAllLocalIds()` return a listing of all local ids in the object store
    `java.util.List<java.lang.String>` | `getAllPidsInChain(java.lang.String sid)` Get all pids in the series chain
    `java.util.List<java.lang.String>` | `getAllSystemMetadataGUIDs()` return a listing of all guids in the object store
    `java.lang.String` | `getGUID(java.lang.String docid, int rev)` given a local identifer, look up the guid.
    `java.util.List<java.lang.String>` | `getGUIDs(java.lang.String formatId, java.lang.String nodeId, java.lang.String scheme)` Get the list of identifiers which system metadata matches the given format id and original member node id and guid or series id start with the scheme (doi for example).
    `org.dataone.service.types.v1.Identifier` | `getHeadPID(org.dataone.service.types.v1.Identifier sid)` Get the pid of the head (current) version of objects match the specified sid.
    `static IdentifierManager` | `getInstance()` Return the single instance of the manager after initializing it if it wasn't previously initialized.
    `java.util.Date` | `getLastModifiedDate()` returns a list of system metadata-only guids since the given date
    `int` | `getLatestRevForLocalId(java.lang.String localId)` return the newest rev for a given localId
    `java.lang.String` | `getLocalId(java.lang.String guid)` Lookup a localId given the GUID.
    `java.util.List<java.lang.String>` | `getLocalIdsWithNoSystemMetadata(boolean includeRevisions, int serverLocation)` return all local ids in the object store that do not have associated system metadata
    `java.lang.String` | `getObjectFilePath(java.lang.String localId, boolean isScienceMetadata)` Get the the file path for the given object local id
    `org.dataone.service.types.v2.SystemMetadata` | `getSystemMetadata(java.lang.String guid)` return a hash of all of the info that is in the systemmetadata table
    `java.util.List<java.lang.String>` | `getUpdatedSystemMetadataIds(java.util.Date since)` returns a list of system metadata-only guids since the given date
    `boolean` | `identifierExists(java.lang.String guid)` Determine if an identifier exists already, returning true if so.
    `void` | `insertOrUpdateSystemMetadata(org.dataone.service.types.v2.SystemMetadata sysmeta)` creates a system metadata mapping and adds additional fields from sysmeta to the table for quick searching.
    `boolean` | `mappingExists(java.lang.String guid)` Determine if an identifier mapping exists already, returning true if so.
    `boolean` | `objectFileExists(java.lang.String localId, boolean isScienceMetadata)` Determine if the object file exist for the given localId.
    `org.dataone.service.types.v1.ObjectList` | `querySystemMetadata(java.util.Date startTime, java.util.Date endTime, org.dataone.service.types.v1.ObjectFormatIdentifier objectFormatId, org.dataone.service.types.v1.NodeReference nodeId, int start, int count, org.dataone.service.types.v1.Identifier identifier, boolean isSID)` query the systemmetadata table based on the given parameters
    `void` | `removeMapping(java.lang.String guid, java.lang.String localId)` remove a mapping in the identifier table
    `boolean` | `systemMetadataPIDExists(org.dataone.service.types.v1.Identifier pid)` Determine if the specified identifier object exists or not.
    `boolean` | `systemMetadataPIDExists(java.lang.String guid)`
    `boolean` | `systemMetadataSIDExists(org.dataone.service.types.v1.Identifier sid)` Check if the specified sid object exists on the serial id field on the system metadata table
    `boolean` | `systemMetadataSIDExists(java.lang.String sid)` Check if the specified sid exists on the serial id field on the system metadata table
    `void` | `updateAuthoritativeMemberNodeId(java.lang.String existingMemberNodeId, java.lang.String newMemberNodeId)`
    `void` | `updateMapping(java.lang.String guid, java.lang.String localId)` update a mapping
    `void` | `updateSystemMetadata(org.dataone.service.types.v2.SystemMetadata sm, DBConnection dbConn)` Insert the system metadata fields into the db

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TYPE_SYSTEM_METADATA

          public static final java.lang.String TYPE_SYSTEM_METADATA

      See Also:
        Constant Field Values

    - #### TYPE_IDENTIFIER

          public static final java.lang.String TYPE_IDENTIFIER

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getInstance

          public static IdentifierManager getInstance()

      Return the single instance of the manager after initializing it if it wasn't previously initialized.
      Returns:
        the single IdentifierManager instance

    - #### getSystemMetadata

          public org.dataone.service.types.v2.SystemMetadata getSystemMetadata(java.lang.String guid)
                                                                        throws McdbDocNotFoundException

      return a hash of all of the info that is in the systemmetadata table
      Parameters:
        `guid` -
      Returns:
      Throws:
        `McdbDocNotFoundException`

    - #### getLatestRevForLocalId

          public int getLatestRevForLocalId(java.lang.String localId)
                                     throws McdbDocNotFoundException

      return the newest rev for a given localId
      Parameters:
        `localId` -
      Returns:
      Throws:
        `McdbDocNotFoundException`

    - #### getLocalIdsWithNoSystemMetadata

          public java.util.List<java.lang.String> getLocalIdsWithNoSystemMetadata(boolean includeRevisions,
                                                                                  int serverLocation)

      return all local ids in the object store that do not have associated system metadata

    - #### getAllLocalIds

          public java.util.List<java.lang.String> getAllLocalIds()

      return a listing of all local ids in the object store
      Returns:
        a list of all local ids in metacat

    - #### getAllSystemMetadataGUIDs

          public java.util.List<java.lang.String> getAllSystemMetadataGUIDs()

      return a listing of all guids in the object store
      Returns:
        a list of all GUIDs in metacat

    - #### getAllPidsInChain

          public java.util.List<java.lang.String> getAllPidsInChain(java.lang.String sid)
                                                             throws java.sql.SQLException

      Get all pids in the series chain
      Parameters:
        `sid` - the id of the series chain
      Returns:
        a list of pid in the chain
      Throws:
        `java.sql.SQLException`

    - #### getUpdatedSystemMetadataIds

          public java.util.List<java.lang.String> getUpdatedSystemMetadataIds(java.util.Date since)
                                                                       throws java.lang.Exception

      returns a list of system metadata-only guids since the given date
      Returns:
        a list of system ids in metacat that do not correspond to objects TODO: need to check which server they are on
      Throws:
        `java.lang.Exception`

    - #### getLastModifiedDate

          public java.util.Date getLastModifiedDate()
                                             throws java.lang.Exception

      returns a list of system metadata-only guids since the given date
      Returns:
        a list of system ids in metacat that do not correspond to objects TODO: need to check which server they are on
      Throws:
        `java.lang.Exception`

    - #### identifierExists

          public boolean identifierExists(java.lang.String guid)
                                   throws java.sql.SQLException

      Determine if an identifier exists already, returning true if so. NOTE: looks in the identifier and system metadata table for a match (in that order) Can return true for both PIDs and SIDs.
      Parameters:
        `guid` - the global identifier to look up
      Returns:
        boolean true if the identifier exists
      Throws:
        `java.sql.SQLException`

    - #### mappingExists

          public boolean mappingExists(java.lang.String guid)
                                throws java.sql.SQLException

      Determine if an identifier mapping exists already, returning true if so.
      Parameters:
        `guid` - the global identifier to look up
      Returns:
        boolean true if the identifier exists
      Throws:
        `java.sql.SQLException`

    - #### generateLocalId

          public java.lang.String generateLocalId(java.lang.String guid,
                                                  int rev)

      Parameters:
        `guid` -
        `rev` -
      Returns:

    - #### generateLocalId

          public java.lang.String generateLocalId(java.lang.String guid,
                                                  int rev,
                                                  boolean isSystemMetadata)

      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. REMOVED feature: If the incoming guid has the syntax of a Metacat docid (scope.id.rev), then simply use it. WHY: because "test.1.001" becomes "test.1.1" which is not correct for DataONE identifier use (those revision numbers are just chartacters and should not be interpreted)
      Parameters:
        `guid` - the global string identifier
        `rev` - the revision number to be used in the localId
      Returns:
        String containing the localId to be used for Metacat operations

    - #### getGUID

          public java.lang.String getGUID(java.lang.String docid,
                                          int rev)
                                   throws McdbDocNotFoundException

      given a local identifer, look up the guid. Throw McdbDocNotFoundException if the docid, rev is not found in the identifiers or systemmetadata tables
      Parameters:
        `docid` - the docid to look up
        `rev` - the revision of the docid to look up
      Returns:
        String containing the mapped guid
      Throws:
        `McdbDocNotFoundException` - if the docid, rev is not found

    - #### getGUIDs

          public java.util.List<java.lang.String> getGUIDs(java.lang.String formatId,
                                                           java.lang.String nodeId,
                                                           java.lang.String scheme)

      Get the list of identifiers which system metadata matches the given format id and original member node id and guid or series id start with the scheme (doi for example).
      Parameters:
        `formatId` - the format id of the identifier must match the given formatId.
        `nodeId` - the original member node of the identifier must match the given nodeId.
        `scheme` - the guid or series id must start with the given scheme (doi for exampe)
      Returns:
        the list of identifier string. An empty list will be returned if nothing was found.

    - #### getHeadPID

          public org.dataone.service.types.v1.Identifier getHeadPID(org.dataone.service.types.v1.Identifier sid)
                                                             throws java.sql.SQLException

      Get the pid of the head (current) version of objects match the specified sid. 1. locate all candidate chain-ends for S1: determined by: seriesId == S1 AND (obsoletedBy == null OR obsoletedBy.seriesId != S1) // these are the type1 and type2 ends If obsoletedBy is missing, we generally consider it a type 2 end except: there is another object in the chain (has the same series id) that obsoletes the missing object. 2. if only 1 candidate chain-end, return it as the HEAD 3. otherwise return the one in the chain with the latest dateUploaded value. However, we find that dateUpload doesn't refect the obsoletes information (espically on the cn), so we will check osoletes information as well. https://redmine.dataone.org/issues/7624
      Parameters:
        `sid` - specified sid which should match.
      Returns:
        the pid of the head version. The null will be returned if there is no pid found.
      Throws:
        `java.sql.SQLException`

    - #### systemMetadataSIDExists

          public boolean systemMetadataSIDExists(org.dataone.service.types.v1.Identifier sid)
                                          throws java.sql.SQLException

      Check if the specified sid object exists on the serial id field on the system metadata table
      Parameters:
        `sid` -
      Returns:
        true if it exists; false otherwise.
      Throws:
        `java.sql.SQLException`

    - #### systemMetadataSIDExists

          public boolean systemMetadataSIDExists(java.lang.String sid)
                                          throws java.sql.SQLException

      Check if the specified sid exists on the serial id field on the system metadata table
      Parameters:
        `id` -
      Returns:
        true if it exists; false otherwise.
      Throws:
        `java.sql.SQLException`

    - #### systemMetadataPIDExists

          public boolean systemMetadataPIDExists(org.dataone.service.types.v1.Identifier pid)
                                          throws java.sql.SQLException

      Determine if the specified identifier object exists or not.
      Parameters:
        `pid` - - the specified identifier
      Returns:
        true if it is exists.
      Throws:
        `java.sql.SQLException`
        `java.lang.NullPointerException`

    - #### systemMetadataPIDExists

          public boolean systemMetadataPIDExists(java.lang.String guid)
                                          throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### insertOrUpdateSystemMetadata

          public void insertOrUpdateSystemMetadata(org.dataone.service.types.v2.SystemMetadata sysmeta)
                                            throws McdbDocNotFoundException,
                                                   java.sql.SQLException,
                                                   org.dataone.service.exceptions.InvalidSystemMetadata

      creates a system metadata mapping and adds additional fields from sysmeta to the table for quick searching.
      Parameters:
        `guid` - the id to insert
        `localId` - the systemMetadata object to get the local id for
      Throws:
        `McdbDocNotFoundException`
        `java.sql.SQLException`
        `org.dataone.service.exceptions.InvalidSystemMetadata`

    - #### updateMapping

          public void updateMapping(java.lang.String guid,
                                    java.lang.String localId)

      update a mapping
      Parameters:
        `guid` -
        `localId` -

    - #### updateSystemMetadata

          public void updateSystemMetadata(org.dataone.service.types.v2.SystemMetadata sm,
                                           DBConnection dbConn)
                                    throws McdbDocNotFoundException,
                                           java.sql.SQLException,
                                           org.dataone.service.exceptions.InvalidSystemMetadata,
                                           AccessException

      Insert the system metadata fields into the db
      Parameters:
        `sm` -
      Throws:
        `McdbDocNotFoundException`
        `java.sql.SQLException`
        `org.dataone.service.exceptions.InvalidSystemMetadata`
        `AccessException`

    - #### getAccessPolicy

          public org.dataone.service.types.v1.AccessPolicy getAccessPolicy(java.lang.String guid)
                                                                    throws McdbDocNotFoundException,
                                                                           AccessException

      Lookup access policy from Metacat
      Parameters:
        `guid` -
      Returns:
      Throws:
        `McdbDocNotFoundException`
        `AccessException`

    - #### convertPermission

          public int convertPermission(org.dataone.service.types.v1.Permission permission)

    - #### convertPermission

          public java.util.List<org.dataone.service.types.v1.Permission> convertPermission(int permission)

    - #### getLocalId

          public java.lang.String getLocalId(java.lang.String guid)
                                      throws McdbDocNotFoundException,
                                             java.sql.SQLException

      Lookup a localId given the GUID. If the identifier is not found, throw an exception.
      Parameters:
        `guid` - the global identifier to look up
      Returns:
        String containing the corresponding LocalId
      Throws:
        `McdbDocNotFoundException` - if the identifier is not found
        `java.sql.SQLException`

    - #### querySystemMetadata

          public org.dataone.service.types.v1.ObjectList querySystemMetadata(java.util.Date startTime,
                                                                             java.util.Date endTime,
                                                                             org.dataone.service.types.v1.ObjectFormatIdentifier objectFormatId,
                                                                             org.dataone.service.types.v1.NodeReference nodeId,
                                                                             int start,
                                                                             int count,
                                                                             org.dataone.service.types.v1.Identifier identifier,
                                                                             boolean isSID)
                                                                      throws java.sql.SQLException,
                                                                             edu.ucsb.nceas.utilities.PropertyNotFoundException,
                                                                             ServiceException

      query the systemmetadata table based on the given parameters
      Parameters:
        `startTime` -
        `endTime` -
        `objectFormat` -
        `nodeId` -
        `start` -
        `count` -
      Returns:
        ObjectList
      Throws:
        `java.sql.SQLException`
        `ServiceException`
        `edu.ucsb.nceas.utilities.PropertyNotFoundException`

    - #### createMapping

          public void createMapping(java.lang.String guid,
                                    java.lang.String localId)

      create a mapping in the identifier table
      Parameters:
        `guid` -
        `localId` -

    - #### removeMapping

          public void removeMapping(java.lang.String guid,
                                    java.lang.String localId)

      remove a mapping in the identifier table
      Parameters:
        `guid` -
        `localId` -

    - #### deleteSystemMetadata

          public boolean deleteSystemMetadata(java.lang.String guid)

    - #### updateAuthoritativeMemberNodeId

          public void updateAuthoritativeMemberNodeId(java.lang.String existingMemberNodeId,
                                                      java.lang.String newMemberNodeId)

    - #### objectFileExists

          public boolean objectFileExists(java.lang.String localId,
                                          boolean isScienceMetadata)
                                   throws edu.ucsb.nceas.utilities.PropertyNotFoundException

      Determine if the object file exist for the given localId.
      Parameters:
        `localId` -
        `isScienceMetadata` -
      Returns:
      Throws:
        `edu.ucsb.nceas.utilities.PropertyNotFoundException`

    - #### getObjectFilePath

          public java.lang.String getObjectFilePath(java.lang.String localId,
                                                    boolean isScienceMetadata)
                                             throws edu.ucsb.nceas.utilities.PropertyNotFoundException

      Get the the file path for the given object local id
      Parameters:
        `localId` -
        `isScienceMetadata` -
      Returns:
      Throws:
        `edu.ucsb.nceas.utilities.PropertyNotFoundException`

    - #### existsInXmlLRevisionTable

          public boolean existsInXmlLRevisionTable(java.lang.String docid,
                                                   int rev)
                                            throws java.sql.SQLException

      IF the given localId exists on the xml_revisions table
      Parameters:
        `localId` -
      Returns:
      Throws:
        `java.sql.SQLException`

    - #### existsInIdentifierTable

          public boolean existsInIdentifierTable(org.dataone.service.types.v1.Identifier pid)
                                          throws java.sql.SQLException

      Determine if the given pid exists on the identifier table.
      Parameters:
        `pid` - must be a PID
      Returns:
        true if it exists; false otherwise.
      Throws:
        `java.sql.SQLException`

Copyright © 2023 Regents of the University of California. All Rights Reserved.