Interface BibRefSupport


  • public interface BibRefSupport

    This interface defines supporting utilities for working with bibliographic repositories.

    The fundamental part of this interface deals with the controlled vocabularies. However, the BibRefSupport interface is here just a gateway to other Java interfaces defined in a separate package org.biojava.utils.candy.

    The controlled vocabularies are used in order to find names of all available attributes of the given bibliographic repository, to find all possible values of some attributes, and to specify availability of the ordering and searching criteria. Here belong methods getVocabularyFinder, getSupportedValues, and getSupportedCriteria.

    The other raison d'etre for the BibRefSupport interface is to have a place where some common constants can be put in. The constants specify common vocabulary names (examples are RESOURCE_TYPES or JOURNAL_TITLES, explicitly defined bibliographic resource types (for example, TYPE_BOOK or TYPE_ARTICLE), and few other things.

    And finally, there are some methods allowing to improve an efficient access to the supporting resources by calling explicitly connect and disconnect.

    It was an intention to separate completely methods dealing with bibliographic repositories (as defined in interface BibRefQuery) and methods helping with other things (as defined here). This box of bricks approach helps to use different communication protocols for bibliographic and supporting repositories. For example, the performance can be sometimes improved when the client loads separately all controlled vocabularies and use them locally while the access to the bibliographic repository is still remote.

    The implementation is advised to used the following constructor

        public NameOfAnImplementation (String[] args, Hashtable props) {...}
    
    where both args and props contain implementation specific parameters and properties. However, some properties are more probable to be used - the suggested names for them are defined also in this interface (e.g. INIT_PROP_LOG).

    The use of this constructor makes easier to load dynamically different supporting implementations.

    Since:
    1.3
    Version:
    $Id$
    Author:
    Martin Senger, Matthew Pocock
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void connect()
      It creates a connection to an object providing the supporting utilities, or/and it makes all necessary initialization steps needed for further communication.
      void disconnect()
      It closes connection with a utility object.
      BiblioCriterion[] getSupportedCriteria()
      It returns all supported searching and sorting criteria for the whole bibliographic repository.
      BiblioCriterion[] getSupportedCriteria​(java.lang.String repositorySubset)
      It returns all supported searching and sorting criteria in the given repository subset.
      CandyVocabulary getSupportedValues​(java.lang.String resourceType, java.lang.String attrName)
      It returns a controlled vocabulary containing all possible values of the attribute given in attrName in the context given in resourceType.
      CandyFinder getVocabularyFinder()
      It returns an object representing a central place where all controlled vocabularies can be received from and shared by all users.
      boolean isReady()
      It checks if a utility object is available.
      BibRefQuery union​(BibRefQuery[] collections, java.util.Hashtable properties)
      It merges all given collections together.
    • Method Detail

      • connect

        void connect()
              throws BibRefException

        It creates a connection to an object providing the supporting utilities, or/and it makes all necessary initialization steps needed for further communication.

        However, there should be no need to call this method explicitly, the other methods should do it automatically before they need to use any supporting utility.

        Throws:
        BibRefException - if the connection/initialization cannot be established
      • isReady

        boolean isReady()
        It checks if a utility object is available. The semantic of availabledepends on the implementation.
        Returns:
        true if it is ready
      • disconnect

        void disconnect()
        It closes connection with a utility object. Implementations may choose to use this method for freeing resources.
      • getVocabularyFinder

        CandyFinder getVocabularyFinder()
                                 throws BibRefException

        It returns an object representing a central place where all controlled vocabularies can be received from and shared by all users.

        The controlled vocabularies are used for finding names of all available attributes of the given bibliographic repository, for finding all possible values of some attributes, and for specifying availability of the ordering and searching criteria.

        Returns:
        an instance implementing CandyFinder interface
        Throws:
        BibRefException - if the vocabulary finder cannot be found
      • getSupportedValues

        CandyVocabulary getSupportedValues​(java.lang.String resourceType,
                                           java.lang.String attrName)
                                    throws BibRefException

        It returns a controlled vocabulary containing all possible values of the attribute given in attrName in the context given in resourceType. It is up to the implementation to define the context.

        Specifically, for attrName equals to ATTR_PROPERTIES it returns a vocabulary containing attribute names available for the given citation type.

        Parameters:
        resourceType - is usually a name of a citation type (e.g. "Book", "JournalArticle"), see TYPE_BOOK, etc., but can define other contexts as well (e.g. "Person" as defined by constant PROVIDER_PERSON)
        attrName - a name of an attribute whose values should be available from the returned vocabulary
        Returns:
        a controlled vocabulary
        Throws:
        BibRefException - if there is no such vocabulary available, or something else wrong happened
      • union

        BibRefQuery union​(BibRefQuery[] collections,
                          java.util.Hashtable properties)
                   throws BibRefException

        It merges all given collections together. The result should eliminate redundancy - which usually means removing the same citations.

        The merging process can be influenced by specifying some properties (but they are not defined by this interface, they depend on the implementation).

        Note that the merging is independent on the repository, or repositories where the collections come from. The main raison d'etre is actually to allow to merge collections from different repositories. But it opens the question what to do with the resulting collection (how to query it, for example, if it is a "virtual" collection). So it can be quite difficult to implement this method :-(.

        Parameters:
        collections - to be merged together
        properties - define features how to do merging
        Returns:
        a merged collection
        Throws:
        BibRefException - if merging failed (which may also happen when any of the collection is too large)