org.gcube.opensearch.opensearchlibrary

Class DescriptionDocument

java.lang.Object

org.gcube.opensearch.opensearchlibrary.DescriptionDocument

public class DescriptionDocument
extends Object

This is the central class of the OpenSearch library, providing functionality related to OpenSearch description documents. A client who intends to use the library for the purpose of submitting queries to OpenSearch-enabled providers should first instantiate this class. On instantiation, a pre-parsed Document object is checked for validity as an OpenSearch description document. If the document is found valid, various operations such as the retrieval of QueryBuilder objects ,which can be used in order to submit queries, and the querying of a number of description document related properties are exposed to the client.

Author:

gerasimos.farantatos

Constructor Summary

Constructors

Constructor and Description
DescriptionDocument(Document descriptionDocument, URLElementFactory urlFactory, QueryElementFactory queryFactory) Creates a new DescriptionDocument instance

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canRequest() Determines whether the client may request search results from the OpenSearch provider corresponding to this description document
boolean	canSendToClients() Determines whether the client may send the search results obtained from the OpenSearch provider corresponding to this description document to other search clients
boolean	canSendToEndUsers() Determines whether the client may display the search results obtained from the OpenSearch provider corresponding to this description document to end users
String	getAttribution() Returns the String contained in the Attribution element of the description document
String	getContact() Returns the String contained in the Contact element of the description document
String	getDefaultInputEncoding() Returns the default input encoding of the OpenSearch specification
String	getDefaultOutputEncoding() Returns the default output encoding of the OpenSearch specification
String	getDescription() Returns the String contained in the Description element of the description document
String	getDeveloper() Returns the String contained in the Developer element of the description document
List<QueryBuilder>	getExampleQueryBuilders(String MIMEType) Retrieves a list of all QueryBuilder objects that can be used to send example queries as described in the Query elements of this description document.
URI	getImageURI() Retrieves the URI of the image that appears in the first Image element of this description document
URI	getImageURI(String MIMEType) Retrieves the URI of the image with a specific MIME type appearing first in an Image element of this description document
String	getLongName() Returns the String contained in the LongName element of the description document
String	getNSPrefix(String NSUrl) Retrieves the namespace prefix associated with a namespace URI in the description document
Map<String,String>	getNSPrefixToURIMappings()
String	getNSUrl(String NSPrefix) Retrieves the namespace URI associated with a namespace prefix in the description document
List<QueryBuilder>	getQueryBuilders(String rel, String MIMEType) Retrieves a list of QueryBuilder objects that can be used to construct queries for resources related to a specific role and which return results of a given MIME type
String	getShortName() Returns the String contained in the ShortName element of the description document
List<String>	getSupportedInputEncodings() Retrieves a list of all input encodings supported by e OpenSearch provider corresponding to this description document
List<String>	getSupportedLanguages() Retrieves a list of all languages supported by the OpenSearch provider corresponding to this description document
List<String>	getSupportedMimeTypes(String rel) Retrieves a list of MIME types supported for constructing queries for a specific role Standard OpenSearch Url rel values are: "results", "suggestion", "self" and "collection"
List<String>	getSupportedOutputEncodings() Retrieves a list of all output encodings supported by e OpenSearch provider corresponding to this description document
SyndicationRight	getSyndicationRight() Returns the SyndicationRight value contained in the SyndicationRight element of the description document
List<String>	getTags() Retrieves a list of all the tags contained in the description document which identify and categorize the search content
Map<String,List<String>>	getUniqueTemplates() Returns all parameter-wise unique templates contained in this description document
Map<String,String>	getURIToPrefixMappings()
Boolean	hasAdultContent() Determines whether the search results obtained from the OpenSearch provider corresponding to this description document may contain material intended only for adults
boolean	hasLangRestriction() Determines whether the description document limits the search to a set of supported languages
boolean	isInputEncodingSupported(String encoding) Determines whether a specific input encoding is supported by the OpenSearch provider corresponding to this description document
boolean	isLanguageSupported(String lang) Determines whether a specific language is supported by the OpenSearch provider corresponding to this description document
boolean	isOutputEncodingSupported(String encoding) Determines whether a specific output encoding is supported by the OpenSearch provider corresponding to this description document

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DescriptionDocument

public DescriptionDocument(Document descriptionDocument,
                   URLElementFactory urlFactory,
                   QueryElementFactory queryFactory)
                    throws Exception

Creates a new DescriptionDocument instance

Parameters:

descriptionDocument - A Document corresponding to the XML document that is to be processed as a description document

urlFactory - The factory that will be used to construct URLElements in order to process URL elements contained in the description document

queryFactory - The factory that will be used to construct QueryElements in order to process Query elements contained in the description document

Throws:

Exception - In case of an error, description document validity related or otherwise.

Method Detail

getNSPrefix

public String getNSPrefix(String NSUrl)

Retrieves the namespace prefix associated with a namespace URI in the description document

Parameters:

NSUrl - The namespace URI

Returns:

The prefix of the namespace. Null is returned if the namespace URI is not present in the description document

getNSUrl

public String getNSUrl(String NSPrefix)

Retrieves the namespace URI associated with a namespace prefix in the description document

Parameters:

NSPrefix - The prefix of the namespace

Returns:

The URI of the namespace. Null is returned if the namespace prefix is not present in the description document

getShortName

public String getShortName()

Returns the String contained in the ShortName element of the description document

Returns:

The ShortName String or null if the description document does not contain such an element

getLongName

public String getLongName()

Returns the String contained in the LongName element of the description document

Returns:

The LongName String or null if the description document does not contain such an element

getDescription

public String getDescription()

Returns the String contained in the Description element of the description document

Returns:

The Description value

getContact

public String getContact()

Returns the String contained in the Contact element of the description document

Returns:

The Contact String or null if the description document does not contain such an element

getDeveloper

public String getDeveloper()

Returns the String contained in the Developer element of the description document

Returns:

The Developer String or null if the description document does not contain such an element

getAttribution

public String getAttribution()

Returns the String contained in the Attribution element of the description document

Returns:

The Attribution String or null if the description document does not contain such an element

getSyndicationRight

public SyndicationRight getSyndicationRight()

Returns the SyndicationRight value contained in the SyndicationRight element of the description document

Returns:

The SyndicationRight of the description document or null if such an element is absent

canRequest

public boolean canRequest()

Determines whether the client may request search results from the OpenSearch provider corresponding to this description document

Returns:

true if the client may request search results, false otherwise

canSendToEndUsers

public boolean canSendToEndUsers()

Determines whether the client may display the search results obtained from the OpenSearch provider corresponding to this description document to end users

Returns:

true if the client may display the search results to end users, false otherwise

canSendToClients

public boolean canSendToClients()

Determines whether the client may send the search results obtained from the OpenSearch provider corresponding to this description document to other search clients

Returns:

true if the client may send the search results to other search clients, false otherwise

hasAdultContent

public Boolean hasAdultContent()

Determines whether the search results obtained from the OpenSearch provider corresponding to this description document may contain material intended only for adults

Returns:

true if the search results may contain material intended only for adults, false otherwise

getTags

public List<String> getTags()

Retrieves a list of all the tags contained in the description document which identify and categorize the search content

Returns:

A list containing all the tags contained in the description document. Null is returned if no tags are specified in the description document

hasLangRestriction

public boolean hasLangRestriction()

Determines whether the description document limits the search to a set of supported languages

Returns:

true if the search must be limited to the languages supported by the provider, false if queries for an arbitrary language are supported

isLanguageSupported

public boolean isLanguageSupported(String lang)

Determines whether a specific language is supported by the OpenSearch provider corresponding to this description document

Parameters:

lang - The language to check support for

Returns:

true if the language is supported, false otherwise

getSupportedLanguages

public List<String> getSupportedLanguages()

Retrieves a list of all languages supported by the OpenSearch provider corresponding to this description document

Returns:

A list of all supported languages

isInputEncodingSupported

public boolean isInputEncodingSupported(String encoding)

Determines whether a specific input encoding is supported by the OpenSearch provider corresponding to this description document

Parameters:

encoding - The input encoding to check support for

Returns:

true if the input encoding is supported, false otherwise

getDefaultInputEncoding

public String getDefaultInputEncoding()

Returns the default input encoding of the OpenSearch specification

Returns:

the default input encoding

getSupportedInputEncodings

public List<String> getSupportedInputEncodings()

Retrieves a list of all input encodings supported by e OpenSearch provider corresponding to this description document

Returns:

A list of all supported input encodings

isOutputEncodingSupported

public boolean isOutputEncodingSupported(String encoding)

Determines whether a specific output encoding is supported by the OpenSearch provider corresponding to this description document

Parameters:

encoding - The output encoding to check support for

Returns:

true if the output encoding is supported, false otherwise

getDefaultOutputEncoding

public String getDefaultOutputEncoding()

Returns the default output encoding of the OpenSearch specification

Returns:

the default output encoding

getSupportedOutputEncodings

public List<String> getSupportedOutputEncodings()

Retrieves a list of all output encodings supported by e OpenSearch provider corresponding to this description document

Returns:

A list of all supported output encodings

getImageURI

public URI getImageURI()

Retrieves the URI of the image that appears in the first Image element of this description document

Returns:

The URI of the image

getImageURI

public URI getImageURI(String MIMEType)

Retrieves the URI of the image with a specific MIME type appearing first in an Image element of this description document

Parameters:

MIMEType - The MIME type of the image to be retrieved

Returns:

The URI of the image with the given MIME type

getSupportedMimeTypes

public List<String> getSupportedMimeTypes(String rel)
                                   throws Exception

Retrieves a list of MIME types supported for constructing queries for a specific role Standard OpenSearch Url rel values are: "results", "suggestion", "self" and "collection"

Parameters:

rel - The role of the resource to be queried

Returns:

A list of all MIME types supported for querying the resource associated with the given role

Throws:

Exception - If an error has occurred

getUniqueTemplates

public Map<String,List<String>> getUniqueTemplates()
                                            throws Exception

Returns all parameter-wise unique templates contained in this description document

Returns:

An association of the MIME types corresponding to the templates with the unique templates themselves

Throws:

Exception - If the URL elements of the description document are not initialized, or in case of other errors

getQueryBuilders

public List<QueryBuilder> getQueryBuilders(String rel,
                                  String MIMEType)
                                    throws Exception

Retrieves a list of QueryBuilder objects that can be used to construct queries for resources related to a specific role and which return results of a given MIME type

Parameters:

rel - The role of the resource to be queried, e.g. "results"

MIMEType - The MIME type of the results that the provider should return

Returns:

A list of all QueryBuilders that satisfy the criteria passed as arguments. If none are found, an empty list is returned.

Throws:

Exception - If the URL elements contained in the desription document are not initialized or in case of other errors

getExampleQueryBuilders

public List<QueryBuilder> getExampleQueryBuilders(String MIMEType)
                                           throws Exception

Retrieves a list of all QueryBuilder objects that can be used to send example queries as described in the Query elements of this description document. The result type of the queries constructed by these QueryBuilders will match the MIME type given as argument.

Parameters:

MIMEType - The MIME type which the results obtained from queries issued using the QueryBuilders returned should have

Returns:

A list of QueryBuilder objects that can be used to issue the requested example queries

Throws:

Exception - If the URL elements contained in the desription document are not initialized or in case of other errors

getNSPrefixToURIMappings

public Map<String,String> getNSPrefixToURIMappings()

getURIToPrefixMappings

public Map<String,String> getURIToPrefixMappings()