BibRefSupport (biojava-legacy 1.9.3 API)

```
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

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ATTR_FORMAT` A vocabulary name, or a part of a vocabulary name.
`static String`	`ATTR_PROPERTIES` A part of a vocabulary name.
`static String`	`ATTR_SCOPE` A vocabulary name, or a part of a vocabulary name.
`static String`	`ENTRY_PROPERTIES` A vocabulary name.
`static String`	`GENERIC_PROVIDER` A name of a provider type.
`static String`	`INIT_PROP_LOG` A property name ("log").
`static String`	`INIT_PROP_SUPPORT` A property name ("bibrefsupport").
`static String`	`JOURNAL_ABBREV` A vocabulary name.
`static String`	`JOURNAL_TITLES` A vocabulary name.
`static String`	`LANGUAGES` A vocabulary name.
`static String`	`PROVIDER_ORGANISATION` A name of a provider type.
`static String`	`PROVIDER_PERSON` A name of a provider type.
`static String`	`PROVIDER_SERVICE` A name of a provider type.
`static String`	`REPOSITORY_SUBSETS` A vocabulary name.
`static String`	`RESOURCE_TYPES` A vocabulary name.
`static String`	`ROLE_ATTR_QUERYABLE` A role of an attribute.
`static String`	`ROLE_ATTR_RETRIEVABLE` A role of an attribute.
`static String`	`SUBJECT_HEADINGS` A vocabulary name.
`static String`	`TYPE_ARTICLE` A name of a bibliographic resource type.
`static String`	`TYPE_BOOK` A name of a bibliographic resource type.
`static String`	`TYPE_BOOK_ARTICLE` A name of a bibliographic resource type.
`static String`	`TYPE_JOURNAL_ARTICLE` A name of a bibliographic resource type.
`static String`	`TYPE_PATENT` A name of a bibliographic resource type.
`static String`	`TYPE_PROCEEDING` A name of a bibliographic resource type.
`static String`	`TYPE_TECH_REPORT` A name of a bibliographic resource type.
`static String`	`TYPE_THESIS` A name of a bibliographic resource type.
`static String`	`TYPE_WEB_RESOURCE` A name of a bibliographic resource type.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and 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(String repositorySubset)` It returns all supported searching and sorting criteria in the given repository subset.
`CandyVocabulary`	`getSupportedValues(String resourceType, 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, Hashtable properties)` It merges all given collections together.

- Field Detail
  - RESOURCE_TYPES
```
static final String RESOURCE_TYPES
```
    A vocabulary name. The vocabulary contains stringified names of all citation types stored in the repository. The names of types that are explicitly defined by this interface should be equal to the constant strings for types (such as TYPE_BOOK).
    
    See Also:
    
    Constant Field Values
  - REPOSITORY_SUBSETS
```
static final String REPOSITORY_SUBSETS
```
    A vocabulary name. Some bibliographic repositories consist of several databases. Their list can be provided by this vocabulary.
    
    See Also:
    
    Constant Field Values
  - SUBJECT_HEADINGS
```
static final String SUBJECT_HEADINGS
```
    A vocabulary name. The vocabulary contains available subject headings.
    
    See Also:
    
    Constant Field Values
  - LANGUAGES
```
static final String LANGUAGES
```
    A vocabulary name. The vocabulary contains available languages used in BibRef.language and BiblioDescription.language.
    
    See Also:
    
    Constant Field Values
  - JOURNAL_TITLES
```
static final String JOURNAL_TITLES
```
    A vocabulary name. The vocabulary contains journal titles as used in BiblioJournal.name.
    
    See Also:
    
    Constant Field Values
  - JOURNAL_ABBREV
```
static final String JOURNAL_ABBREV
```
    A vocabulary name. The vocabulary contains journal abbreviations as used in BiblioJournal.abbreviation.
    
    See Also:
    
    Constant Field Values
  - ENTRY_PROPERTIES
```
static final String ENTRY_PROPERTIES
```
    A vocabulary name. The vocabulary contains names of properties that characterize a citation as a repository/database record.
    
    See Also:
    
    Constant Field Values
  - TYPE_BOOK
```
static final String TYPE_BOOK
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_ARTICLE
```
static final String TYPE_ARTICLE
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_BOOK_ARTICLE
```
static final String TYPE_BOOK_ARTICLE
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_JOURNAL_ARTICLE
```
static final String TYPE_JOURNAL_ARTICLE
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_PATENT
```
static final String TYPE_PATENT
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_THESIS
```
static final String TYPE_THESIS
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_PROCEEDING
```
static final String TYPE_PROCEEDING
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_TECH_REPORT
```
static final String TYPE_TECH_REPORT
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - TYPE_WEB_RESOURCE
```
static final String TYPE_WEB_RESOURCE
```
    A name of a bibliographic resource type.
    
    See Also:
    
    Constant Field Values
  - PROVIDER_PERSON
```
static final String PROVIDER_PERSON
```
    A name of a provider type.
    
    See Also:
    
    Constant Field Values
  - PROVIDER_ORGANISATION
```
static final String PROVIDER_ORGANISATION
```
    A name of a provider type.
    
    See Also:
    
    Constant Field Values
  - PROVIDER_SERVICE
```
static final String PROVIDER_SERVICE
```
    A name of a provider type.
    
    See Also:
    
    Constant Field Values
  - GENERIC_PROVIDER
```
static final String GENERIC_PROVIDER
```
    A name of a provider type.
    
    See Also:
    
    Constant Field Values
  - ATTR_PROPERTIES
```
static final String ATTR_PROPERTIES
```
    A part of a vocabulary name. It is usually coupled together with a bibliographic resource type to give a full vocabulary name. For example: JournalArticle/ATTR_PROPERTIES.
    
    The vocabulary contains property names for the given resource type as defined in BibRef.properties.
    
    See Also:
    
    Constant Field Values
  - ATTR_SCOPE
```
static final String ATTR_SCOPE
```
    A vocabulary name, or a part of a vocabulary name. The vocabulary contains all allowed keys in BiblioScope.properties.
    
    See Also:
    
    Constant Field Values
  - ATTR_FORMAT
```
static final String ATTR_FORMAT
```
    A vocabulary name, or a part of a vocabulary name. The vocabulary contains all allowed keys in BibRef.format.
    
    See Also:
    
    Constant Field Values
  - ROLE_ATTR_QUERYABLE
```
static final String ROLE_ATTR_QUERYABLE
```
    A role of an attribute.
    
    The introspection mechanism (provided by using controlled vocabularies) allows to find what attributes are available in the repository. The attributes which can be used in query methods should be identified by putting this constant into their vocabulary entry (somewhere in the description field).
    
    See Also:
    
    Constant Field Values
  - ROLE_ATTR_RETRIEVABLE
```
static final String ROLE_ATTR_RETRIEVABLE
```
    A role of an attribute.
    
    The introspection mechanism (provided by using controlled vocabularies) allows to find what attributes are available in the repository. The attributes which can be used in retrieval methods should be identified by putting this constant into their vocabulary entry (somewhere in the description field).
    
    See Also:
    
    Constant Field Values
  - INIT_PROP_LOG
```
static final String INIT_PROP_LOG
```
    A property name ("log").
    
    Used for passing an instance dealing with logging.
    
    See Also:
    
    Constant Field Values
  - INIT_PROP_SUPPORT
```
static final String INIT_PROP_SUPPORT
```
    A property name ("bibrefsupport").
    
    Used for passing an instance of a class implementing this interface. It is recommended to pass this property, for example, in the constructor of an implementation of the BibRefQuery interace}.
    
    See Also:
    
    Constant Field Values
- 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(String resourceType,
                                   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
  - getSupportedCriteria
```
BiblioCriterion[] getSupportedCriteria()
                                throws BibRefException
```
    It returns all supported searching and sorting criteria for the whole bibliographic repository.
    
    Returns:
    
    available criteria
    
    Throws:
    
    BibRefException - if something bad happened
    
    See Also:
    
    getSupportedCriteria for a repository subset
  - getSupportedCriteria
```
BiblioCriterion[] getSupportedCriteria(String repositorySubset)
                                throws BibRefException
```
    It returns all supported searching and sorting criteria in the given repository subset.
    
    Parameters:
    
    repositorySubset - a name of a repository subset as used in BiblioEntryStatus.repositorySubset, and as (possibly) defined in the controlled vocabulary REPOSITORY_SUBSETS
    
    Returns:
    
    available criteria
    
    Throws:
    
    BibRefException - if there is no such repository subset, or something else wrong happened
    
    See Also:
    
    getSupportedCriteria regardless of repository subsets
  - union
```
BibRefQuery union(BibRefQuery[] collections,
                  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)

Interface BibRefSupport

The implementation is advised to used the following constructor

Field Summary

Method Summary

Field Detail

RESOURCE_TYPES

REPOSITORY_SUBSETS

SUBJECT_HEADINGS

LANGUAGES

JOURNAL_TITLES

JOURNAL_ABBREV

ENTRY_PROPERTIES

TYPE_BOOK

TYPE_ARTICLE

TYPE_BOOK_ARTICLE

TYPE_JOURNAL_ARTICLE

TYPE_PATENT

TYPE_THESIS

TYPE_PROCEEDING

TYPE_TECH_REPORT

TYPE_WEB_RESOURCE

PROVIDER_PERSON

PROVIDER_ORGANISATION

PROVIDER_SERVICE

GENERIC_PROVIDER

ATTR_PROPERTIES

ATTR_SCOPE

ATTR_FORMAT

ROLE_ATTR_QUERYABLE

ROLE_ATTR_RETRIEVABLE

INIT_PROP_LOG

INIT_PROP_SUPPORT

Method Detail

connect

isReady

disconnect

getVocabularyFinder

getSupportedValues

getSupportedCriteria

getSupportedCriteria

union