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:

• Property PROP_EXCLUDED_ATTRS is of type String[] and contains list of attributes names which should be ignored and not included in the results.
• Property PROP_CRITERIONS is also of type String[] and contains list of 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 the query.

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:

• Property PROP_EXCLUDED_ATTRS is of type String[] and contains list of attributes names which should be ignored and not included in the results.
• Property PROP_CRITERIONS is also of type String[] and contains list of 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 the query.

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:

• Property PROP_EXCLUDED_ATTRS is of type String[] and contains list of attributes names which should be ignored and not included in the results.
• Property PROP_CRITERIONS is also of type String[] and contains list of 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 the query.

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