DescriptionDocument (opensearchlibrary 1.7.0-SNAPSHOT API)

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

All Methods Instance Methods Concrete 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()
```

Class DescriptionDocument

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DescriptionDocument

Method Detail

getNSPrefix

getNSUrl

getShortName

getLongName

getDescription

getContact

getDeveloper

getAttribution

getSyndicationRight

canRequest

canSendToEndUsers

canSendToClients

hasAdultContent

getTags

hasLangRestriction

isLanguageSupported

getSupportedLanguages

isInputEncodingSupported

getDefaultInputEncoding

getSupportedInputEncodings

isOutputEncodingSupported

getDefaultOutputEncoding

getSupportedOutputEncodings

getImageURI

getImageURI

getSupportedMimeTypes

getUniqueTemplates

getQueryBuilders

getExampleQueryBuilders

getNSPrefixToURIMappings

getURIToPrefixMappings