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
FieldsModifier and TypeFieldDescriptionstatic final String
A vocabulary name, or a part of a vocabulary name.static final String
A part of a vocabulary name.static final String
A vocabulary name, or a part of a vocabulary name.static final String
A vocabulary name.static final String
A name of a provider type.static final String
A property name ("log").static final String
A property name ("bibrefsupport").static final String
A vocabulary name.static final String
A vocabulary name.static final String
A vocabulary name.static final String
A name of a provider type.static final String
A name of a provider type.static final String
A name of a provider type.static final String
A vocabulary name.static final String
A vocabulary name.static final String
A role of an attribute.static final String
A role of an attribute.static final String
A vocabulary name.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type.static final String
A name of a bibliographic resource type. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
It closes connection with a utility object.It returns all supported searching and sorting criteria for the whole bibliographic repository.getSupportedCriteria
(String repositorySubset) It returns all supported searching and sorting criteria in the given repository subset.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.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.union
(BibRefQuery[] collections, Hashtable properties) It merges all given collections together.
-
Field Details
-
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 asTYPE_BOOK
).- See Also:
-
REPOSITORY_SUBSETS
A vocabulary name. Some bibliographic repositories consist ofseveral databases
. Their list can be provided by this vocabulary.- See Also:
-
SUBJECT_HEADINGS
A vocabulary name. The vocabulary contains availablesubject headings
.- See Also:
-
LANGUAGES
A vocabulary name. The vocabulary contains available languages used inBibRef.language
andBiblioDescription.language
.- See Also:
-
JOURNAL_TITLES
A vocabulary name. The vocabulary contains journal titles as used inBiblioJournal.name
.- See Also:
-
JOURNAL_ABBREV
A vocabulary name. The vocabulary contains journal abbreviations as used inBiblioJournal.abbreviation
.- See Also:
-
ENTRY_PROPERTIES
A vocabulary name. The vocabulary contains names of properties that characterize a citation as arepository/database record
.- See Also:
-
TYPE_BOOK
A name of a bibliographic resource type.- See Also:
-
TYPE_ARTICLE
A name of a bibliographic resource type.- See Also:
-
TYPE_BOOK_ARTICLE
A name of a bibliographic resource type.- See Also:
-
TYPE_JOURNAL_ARTICLE
A name of a bibliographic resource type.- See Also:
-
TYPE_PATENT
A name of a bibliographic resource type.- See Also:
-
TYPE_THESIS
A name of a bibliographic resource type.- See Also:
-
TYPE_PROCEEDING
A name of a bibliographic resource type.- See Also:
-
TYPE_TECH_REPORT
A name of a bibliographic resource type.- See Also:
-
TYPE_WEB_RESOURCE
A name of a bibliographic resource type.- See Also:
-
PROVIDER_PERSON
A name of a provider type.- See Also:
-
PROVIDER_ORGANISATION
A name of a provider type.- See Also:
-
PROVIDER_SERVICE
A name of a provider type.- See Also:
-
GENERIC_PROVIDER
A name of a provider type.- See Also:
-
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:
-
ATTR_SCOPE
A vocabulary name, or a part of a vocabulary name. The vocabulary contains all allowed keys inBiblioScope.properties
.- See Also:
-
ATTR_FORMAT
A vocabulary name, or a part of a vocabulary name. The vocabulary contains all allowed keys inBibRef.format
.- See Also:
-
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:
-
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:
-
INIT_PROP_LOG
A property name ("log").
Used for passing an instance dealing with logging.
- See Also:
-
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:
-
-
Method Details
-
connect
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
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
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"), seeTYPE_BOOK
, etc., but can define other contexts as well (e.g. "Person" as defined by constantPROVIDER_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
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
It returns all supported searching and sorting criteria in the given repository subset.
- Parameters:
repositorySubset
- a name of a repository subset as used inBiblioEntryStatus.repositorySubset
, and as (possibly) defined in the controlled vocabularyREPOSITORY_SUBSETS
- Returns:
- available criteria
- Throws:
BibRefException
- if there is no such repository subset, or something else wrong happened- See Also:
-
union
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 togetherproperties
- 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)
-