org.gcube.opensearch.opensearchlibrary
Class DescriptionDocument

java.lang.Object
  extended by org.gcube.opensearch.opensearchlibrary.DescriptionDocument

public class DescriptionDocument
extends java.lang.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
DescriptionDocument(org.w3c.dom.Document descriptionDocument, URLElementFactory urlFactory, QueryElementFactory queryFactory)
          Creates a new DescriptionDocument instance
 
Method Summary
 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
 java.lang.String getAttribution()
          Returns the String contained in the Attribution element of the description document
 java.lang.String getContact()
          Returns the String contained in the Contact element of the description document
 java.lang.String getDefaultInputEncoding()
          Returns the default input encoding of the OpenSearch specification
 java.lang.String getDefaultOutputEncoding()
          Returns the default output encoding of the OpenSearch specification
 java.lang.String getDescription()
          Returns the String contained in the Description element of the description document
 java.lang.String getDeveloper()
          Returns the String contained in the Developer element of the description document
 java.util.List<QueryBuilder> getExampleQueryBuilders(java.lang.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.
 java.net.URI getImageURI()
          Retrieves the URI of the image that appears in the first Image element of this description document
 java.net.URI getImageURI(java.lang.String MIMEType)
          Retrieves the URI of the image with a specific MIME type appearing first in an Image element of this description document
 java.lang.String getLongName()
          Returns the String contained in the LongName element of the description document
 java.lang.String getNSPrefix(java.lang.String NSUrl)
          Retrieves the namespace prefix associated with a namespace URI in the description document
 java.util.Map<java.lang.String,java.lang.String> getNSPrefixToURIMappings()
           
 java.lang.String getNSUrl(java.lang.String NSPrefix)
          Retrieves the namespace URI associated with a namespace prefix in the description document
 java.util.List<QueryBuilder> getQueryBuilders(java.lang.String rel, java.lang.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
 java.lang.String getShortName()
          Returns the String contained in the ShortName element of the description document
 java.util.List<java.lang.String> getSupportedInputEncodings()
          Retrieves a list of all input encodings supported by e OpenSearch provider corresponding to this description document
 java.util.List<java.lang.String> getSupportedLanguages()
          Retrieves a list of all languages supported by the OpenSearch provider corresponding to this description document
 java.util.List<java.lang.String> getSupportedMimeTypes(java.lang.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"
 java.util.List<java.lang.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
 java.util.List<java.lang.String> getTags()
          Retrieves a list of all the tags contained in the description document which identify and categorize the search content
 java.util.Map<java.lang.String,java.util.List<java.lang.String>> getUniqueTemplates()
          Returns all parameter-wise unique templates contained in this description document
 java.util.Map<java.lang.String,java.lang.String> getURIToPrefixMappings()
           
 java.lang.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(java.lang.String encoding)
          Determines whether a specific input encoding is supported by the OpenSearch provider corresponding to this description document
 boolean isLanguageSupported(java.lang.String lang)
          Determines whether a specific language is supported by the OpenSearch provider corresponding to this description document
 boolean isOutputEncodingSupported(java.lang.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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DescriptionDocument

public DescriptionDocument(org.w3c.dom.Document descriptionDocument,
                           URLElementFactory urlFactory,
                           QueryElementFactory queryFactory)
                    throws java.lang.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:
java.lang.Exception - In case of an error, description document validity related or otherwise.
Method Detail

getNSPrefix

public java.lang.String getNSPrefix(java.lang.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 java.lang.String getNSUrl(java.lang.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 java.lang.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 java.lang.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 java.lang.String getDescription()
Returns the String contained in the Description element of the description document

Returns:
The Description value

getContact

public java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.util.List<java.lang.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(java.lang.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 java.util.List<java.lang.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(java.lang.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 java.lang.String getDefaultInputEncoding()
Returns the default input encoding of the OpenSearch specification

Returns:
the default input encoding

getSupportedInputEncodings

public java.util.List<java.lang.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(java.lang.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 java.lang.String getDefaultOutputEncoding()
Returns the default output encoding of the OpenSearch specification

Returns:
the default output encoding

getSupportedOutputEncodings

public java.util.List<java.lang.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 java.net.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 java.net.URI getImageURI(java.lang.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 java.util.List<java.lang.String> getSupportedMimeTypes(java.lang.String rel)
                                                       throws java.lang.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:
java.lang.Exception - If an error has occurred

getUniqueTemplates

public java.util.Map<java.lang.String,java.util.List<java.lang.String>> getUniqueTemplates()
                                                                                    throws java.lang.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:
java.lang.Exception - If the URL elements of the description document are not initialized, or in case of other errors

getQueryBuilders

public java.util.List<QueryBuilder> getQueryBuilders(java.lang.String rel,
                                                     java.lang.String MIMEType)
                                              throws java.lang.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:
java.lang.Exception - If the URL elements contained in the desription document are not initialized or in case of other errors

getExampleQueryBuilders

public java.util.List<QueryBuilder> getExampleQueryBuilders(java.lang.String MIMEType)
                                                     throws java.lang.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:
java.lang.Exception - If the URL elements contained in the desription document are not initialized or in case of other errors

getNSPrefixToURIMappings

public java.util.Map<java.lang.String,java.lang.String> getNSPrefixToURIMappings()

getURIToPrefixMappings

public java.util.Map<java.lang.String,java.lang.String> getURIToPrefixMappings()