org.jscience.bibliography
Interface BibRefQuery


public interface BibRefQuery

An interface defining functionality of a BibRefCollection (which is a main entry point to the queryied bibliographic repositories).

A BibRefQuery represents a collection of Bibliographic references, and can be used for refining the collection by asking queries, and/or to retrive the contents of the collection.

The implementations are 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 either in this interface or in the "sister" interface BibRefSupport.

See Also:
BibRef

Field Summary
static java.lang.String PROP_CRITERIONS
          A property name ("criterions") specifying a list of searching and ordering criteria names.
static java.lang.String PROP_EXCLUDED_ATTRS
          A property name ("excluded") specifyies a list of attribute names.
 
Method Summary
 void connect()
          Make a connection to a repository, or/and make initialization steps needed for further communication.
 void connect(byte[] collectionId)
          Make a connection to a repository, or/and make initialization steps needed for further communication, and make the collection described by 'collectionId' the current collection.
 void destroy()
          Free all resources related to this collection.
 void disconnect()
          Disconnect from the repository.
 BibRefQuery find(java.lang.String[] keywords, java.lang.String[] attrs, java.util.Hashtable properties)
          Query the current collection and return another collection which is a subset of the current collection containing results of the specified query.
 BibRefQuery findByAuthor(BiblioProvider author, java.util.Hashtable properties)
          Query the current collection and return another collection which is a subset of the current collection containing results of the specified query.
 BibRef findById(java.lang.String bibRefId)
          Query the current collection to find a citation with the given ID.
 BibRef findById(java.lang.String bibRefId, java.lang.String[] onlyAttrs)
          Query the current collection to find a citation with the given ID.
 java.lang.String findByIdAsXML(java.lang.String bibRefId)
          Query the current collection to find a citation with the given ID, and return it in an XML format.
 BibRef[] getAllBibRefs()
          Return all citations from the current collection.
 BibRef[] getAllBibRefs(java.lang.String[] onlyAttrs)
          Return all citations from the current collection.
 java.io.InputStream getAllBibRefsAsXML()
          Return all citations from the current collection as an XML stream.
 java.lang.String[] getAllIDs()
          Return only IDs of all citations in the current collection.
 java.lang.String getBibRefAsXML(BibRef bibRef)
          Return an XML representation of the given citation.
 int getBibRefCount()
          Return the number of citation in the current collection.
 java.util.Enumeration getBibRefs()
          Return an enumeration of all citations from the current collection.
 java.util.Enumeration getBibRefs(java.lang.String[] onlyAttrs)
          Return an enumeration of all citations from the current collection.
 java.util.Enumeration getBibRefsAsXML()
          Return an enumeration of all citations from the current collection.
 byte[] getCollectionId()
          Return an identification of the current collection.
 boolean isReady()
          Check if the repository is available.
 BibRefQuery query(java.lang.String query, java.util.Hashtable properties)
          Query the current collection and return another collection which is a subset of the current collection containing results of the specified query.
 BibRefQuery sort(java.lang.String[] orderedBy, java.util.Hashtable properties)
          Sort the current collection and return another collection which is a sorted copy of the current collection.
 

Field Detail

PROP_EXCLUDED_ATTRS

static final java.lang.String PROP_EXCLUDED_ATTRS
A property name ("excluded") specifyies a list of attribute names. The list is used to define attributes which are not returned in the resulting citations. The type is String[].

See Also:
find(java.lang.String[], java.lang.String[], java.util.Hashtable), query(java.lang.String, java.util.Hashtable), Constant Field Values

PROP_CRITERIONS

static final java.lang.String PROP_CRITERIONS
A property name ("criterions") specifying a list of searching and ordering criteria names. The type is String[].

See Also:
find(java.lang.String[], java.lang.String[], java.util.Hashtable), query(java.lang.String, java.util.Hashtable), Constant Field Values
Method Detail

getCollectionId

byte[] getCollectionId()
Return an identification of the current collection.

At the beginning, the identification usually contain a bibliographic repository name or its contents description. But later, usually after connect() or after the first query, the identification may contain information rich enough to be able to re-create the whole collection (e.g. it can contain IDs of all records in the given collection).

An implementation is not required to provide a persistent collection identification. However, if it does provide, it should also be able to accept the same identifier in the connect() method, and to use it to re-create the same collection.

Returns:
an identification of the current collection (may be null)

connect

void connect()
             throws BQSException
Make a connection to a repository, or/and make initialization steps needed for further communication.

However, there should be no need to call this explicitly, the other methods should do it automatically when they need something from the repository.

Throws:
BQSException - if the connection cannot be established

connect

void connect(byte[] collectionId)
             throws BQSException
Make a connection to a repository, or/and make initialization steps needed for further communication, and make the collection described by 'collectionId' the current collection.

Parameters:
collectionId - a (usually persistent) token allowing to re-create a collection; the parameter is the same as an identifier returned earlier by method getCollectionId()
Throws:
BQSException - if the connection cannot be established, or if the collection with the given ID cannot be re-created.

isReady

boolean isReady()
Check if the repository is available. The semantic of availabledepends on the implementation.

Returns:
DOCUMENT ME!

disconnect

void disconnect()
Disconnect from the repository. Implementations may choose to use this method for freeing resources needed to acces the repository.


find

BibRefQuery find(java.lang.String[] keywords,
                 java.lang.String[] attrs,
                 java.util.Hashtable properties)
                 throws BQSException
Query the current collection and return another collection which is a subset of the current collection containing results of the specified query. Search for the keywords in the specified attributes - try to find citations having all the keywords somewhere in the given attributes.

The query result can be influenced by the additional properties:

Parameters:
keywords - keyword or phrases that are being looked for
attrs - attributes names that should be searched
properties - specify attributes excluded from the results and requested criteria for the query
Returns:
a new queryable collection
Throws:
BQSException - if query failed (which can have many reasons :-))
See Also:
query(java.lang.String, java.util.Hashtable)

query

BibRefQuery query(java.lang.String query,
                  java.util.Hashtable properties)
                  throws BQSException
Query the current collection and return another collection which is a subset of the current collection containing results of the specified query. For searching use a specific query language which is not defined by this interface but must be defined by the implementation.

The query result can be influenced by the additional properties:

Parameters:
query - an expression in a query language
properties - specify attributes excluded from the results and requested criteria for the query
Returns:
a new queryable collection
Throws:
BQSException - if query failed (which can have many reasons :-))
See Also:
find(java.lang.String[], java.lang.String[], java.util.Hashtable)

findByAuthor

BibRefQuery findByAuthor(BiblioProvider author,
                         java.util.Hashtable properties)
                         throws BQSException
Query the current collection and return another collection which is a subset of the current collection containing results of the specified query. Search only for non-empty attributes in the given author.

The query result can be influenced by the additional properties:

Parameters:
author - specifies one or more attributes that are being search for; for example, a search for citations written by authors with surname "Doe" will use 'author' object filled only with attribute 'surname'
properties - specify attributes excluded from the results and requested criteria for the query
Returns:
a new queryable collection
Throws:
BQSException - if query failed (which can have many reasons :-))
See Also:
find(java.lang.String[], java.lang.String[], java.util.Hashtable)

findById

BibRef findById(java.lang.String bibRefId)
                throws BQSException
Query the current collection to find a citation with the given ID.

Parameters:
bibRefId - an identifier of a citation that is being looked for
Returns:
a found bibliographic reference (citation)
Throws:
BQSException - if such citation was not found (or something else bad happened)
See Also:
findById(String,String[])

findById

BibRef findById(java.lang.String bibRefId,
                java.lang.String[] onlyAttrs)
                throws BQSException
Query the current collection to find a citation with the given ID.

The returned citation will contain at least attributes whose names are specified by the parameter onlyAttrs. It is meant to provide more lightweight citation. The implementation may provide more attributes than specified in onlyAttrs (e.g. it may be always good to include an attribute representing a unique identifier of this citation even if it is not asked for).

Note that one can ask only for attributes that are available in the current collection. If the collection was already created without some attributes (using property PROP_EXCLUDED_ATTRS, e.g in method find(java.lang.String[], java.lang.String[], java.util.Hashtable)) one cannot expect to get them even if they are asked for by the parameter onlyAttrs.

Parameters:
bibRefId - an identifier of a citation that is being looked for
onlyAttrs - DOCUMENT ME!
Returns:
a found bibliographic reference (citation)
Throws:
BQSException - if such citation was not found (or something else bad happened)
See Also:
findById(String)

findByIdAsXML

java.lang.String findByIdAsXML(java.lang.String bibRefId)
                               throws BQSException
Query the current collection to find a citation with the given ID, and return it in an XML format.

Parameters:
bibRefId - an identifier of a citation that is being looked for
Returns:
a found bibliographic reference (citation)
Throws:
BQSException - if such citation was not found (or something else bad happened)

getBibRefCount

int getBibRefCount()
                   throws BQSException
Return the number of citation in the current collection.

Returns:
the size of this collection
Throws:
BQSException - if a connection with the repository is broken

sort

BibRefQuery sort(java.lang.String[] orderedBy,
                 java.util.Hashtable properties)
                 throws BQSException
Sort the current collection and return another collection which is a sorted copy of the current collection.

The sorting result can be influenced by an additional property PROP_CRITERIONS (of type String[]) containing a list of sorting criteria names. The caller specifies here what criteria she wishes, and this method can change this property and return here the criteria really used for sorting.

Parameters:
orderedBy - a list of attributenames that the collection should be sorted by
properties - DOCUMENT ME!
Returns:
a sorted collection
Throws:
BQSException - if sorting failed (which may also happen when the collection is too large)

getAllBibRefs

BibRef[] getAllBibRefs()
                       throws BQSException
Return all citations from the current collection. Some attributes may be missing (empty) if the property PROP_EXCLUDED_ATTRS was used for creating the current collection.

Returns:
all citations
Throws:
BQSException - if the collection is too large, or if the connection to the repository is broken
See Also:
getAllBibRefs(String[]), find(java.lang.String[], java.lang.String[], java.util.Hashtable), query(java.lang.String, java.util.Hashtable), findByAuthor(org.jscience.bibliography.BiblioProvider, java.util.Hashtable)

getAllBibRefs

BibRef[] getAllBibRefs(java.lang.String[] onlyAttrs)
                       throws BQSException
Return all citations from the current collection. The returned citations will contain at least attributes whose names are specified by the parameter onlyAttrs. It is meant to provide more lightweight citations. The implementation may provide more attributes than specified in onlyAttrs (e.g. it may be always good to include an attribute representing a unique identifier of a citation even if it is not asked for).

Note that one can ask only for attributes that are available in the current collection. If the collection was already created without some attributes (using property PROP_EXCLUDED_ATTRS, e.g in method find(java.lang.String[], java.lang.String[], java.util.Hashtable)) one cannot expect to get them even if they are asked for by the parameter onlyAttrs.

Parameters:
onlyAttrs - DOCUMENT ME!
Returns:
all citations
Throws:
BQSException - if the collection is too large, or if the connection to the repository is broken
See Also:
getAllBibRefs(), query(java.lang.String, java.util.Hashtable), findByAuthor(org.jscience.bibliography.BiblioProvider, java.util.Hashtable)

getAllIDs

java.lang.String[] getAllIDs()
                             throws BQSException
Return only IDs of all citations in the current collection.

Returns:
a list of all identifiers
Throws:
BQSException - if the collection is too large, or if the connection to the repository is broken

getBibRefs

java.util.Enumeration getBibRefs()
                                 throws BQSException
Return an enumeration of all citations from the current collection. The type of elements in the enumeration is BibRef. Some attributes may be missing (empty) if the property PROP_EXCLUDED_ATTRS was used for creating the current collection.

Returns:
an iterator over all citations
Throws:
BQSException - if the connection to the repository is broken
See Also:
getAllBibRefs(), getBibRefs(String[])

getBibRefs

java.util.Enumeration getBibRefs(java.lang.String[] onlyAttrs)
                                 throws BQSException
Return an enumeration of all citations from the current collection. The type of elements in the enumeration is BibRef.

The citations available through the enumeration will contain at least attributes whose names are specified by the parameter onlyAttrs. It is meant to provide more lightweight citations. The implementation may provide more attributes than specified in onlyAttrs (e.g. it may be always good to include an attribute representing a unique identifier of a citation even if it is not asked for).

Note that one can ask only for attributes that are available in the current collection. If the collection was already created without some attributes (using property PROP_EXCLUDED_ATTRS, e.g in method find(java.lang.String[], java.lang.String[], java.util.Hashtable)) one cannot expect to get them even if they are asked for by the parameter onlyAttrs.

Parameters:
onlyAttrs - DOCUMENT ME!
Returns:
an iterator over all citations
Throws:
BQSException - if the connection to the repository is broken
See Also:
getAllBibRefs(), getBibRefs()

getAllBibRefsAsXML

java.io.InputStream getAllBibRefsAsXML()
                                       throws BQSException
Return all citations from the current collection as an XML stream. Some attributes may be missing (empty) if the property PROP_EXCLUDED_ATTRS was used for creating the current collection.

Returns:
an XML data stream containing all citations from the current collection
Throws:
BQSException - if the collection is too large, or if the connection to the repository is broken
See Also:
getAllBibRefs()

getBibRefsAsXML

java.util.Enumeration getBibRefsAsXML()
                                      throws BQSException
Return an enumeration of all citations from the current collection. The type of elements in the enumeration is String. Each element represent one citation as an XML string. Some attributes may be missing (empty) if the property PROP_EXCLUDED_ATTRS was used for creating the current collection.

Note that it is not the same as with getAllBibRefsAsXML() where the return type is an InputStream (and not the String).

Returns:
an iterator over all citations
Throws:
BQSException - if the connection to the repository is broken
See Also:
getBibRefs(), getAllBibRefsAsXML()

getBibRefAsXML

java.lang.String getBibRefAsXML(BibRef bibRef)
                                throws BQSException
Return an XML representation of the given citation. The XML format depends on the repository where the citation comes from.

Parameters:
bibRef - a citation being converted into an XML format
Returns:
an XML data about 'bibRef' citation
Throws:
BQSException - if the implementation needs it :-)

destroy

void destroy()
             throws BQSException
Free all resources related to this collection.

Throws:
BQSException - if the connection to the repository is broken