project.biota.digir
Class DiGIRRequestParser

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      project.biota.digir.DiGIRRequestParser

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler

public class DiGIRRequestParser

extends DefaultHandler

DiGIRRequestParser parses a DiGIR request and saves the info later needed in constructing a DiGIR response.

Author:

Jacob Asiedu, Kimmy Lin

Constructor Summary

DiGIRRequestParser(InputSource source)
Constructs a DiGIRRequestParser object to parse the DiGIR request in the InputSource object.

Method Summary

void	addDiagnostics(String severity, int errorConst, String msg) Adds a diagnoistic element to the DiGIR response.
protected void	addRecordConcept(RecordConcept concept) Adds a RecordConcept object to the list of record concepts specified in the DiGIR request.
void	characters(char[] ch, int start, int length) Receives notification of character data inside an element.
void	endDocument() Receives notification of the end of the document to take any specific actions at the end of a document.
void	endElement(String namespaceURI, String localName, String qName) Receives notification of the end of an element.
void	endPrefixMapping(String prefix) Receives notification of the end of a Namespace mapping.
void	error(SAXParseException e) Receives notification of a recoverable parser error.
void	fatalError(SAXParseException e) Reports a fatal XML parsing error.
String	getClientIP() Gets the IP address string of the client that makes the HTTP request to the servlet.
String	getConceptualSchemaName() Returns the conceptual schema namespace identifier used in this DiGIR request.
String	getConceptualSchemaURI() Returns the conceptual schema URI string used in this DiGIR request.
boolean	getCount() Returns the boolean value of the "count" element specified in this DiGIR request.
Map	getDiagnostics() Returns a map mapping error level strings to a list of DiGIRProvError objects.
int	getErrorCode() Returns the error code.
String	getFilterString() Gets the string representation of this DiGIR request filter contents from the DiGIRRequestParser.
String	getInventoryClause() Gets the schema concept to be used to construct a DiGIR response to an inventory request.
int	getLimit() Returns the "limit" attribute specified in the "records" element of the request.
List	getRecordConcepts() Returns a list of concepts requested via a schema location or a sequence of elements specified in the "structure" element of the DiGIR search request.
String	getRequestDestinationText() Gets the the text associated with the "destination" element of a DiGIR request.
String	getRequestedResource() Returns the name of the resource requested in this DiGIR request.
String	getRequestSourceText() Gets the the text associated with the "source" element of a DiGIR request.
String	getRequestType() Gets the type of this DiGIR request.
Set	getRequiredConcepts() Returns a set of schema concept names required to build the DiGIR response.
String	getSourceResource() Gets the resource attribute of the "source" element of a DiGIR request.
String	getSourceURL() Gets the URL string of the client that makes the HTTP request to the servlet.
int	getStart() Returns the start attribute specified in the "records" element of the request.
boolean	hasErrorDiagnose() Checks whether there is an error diagnostic already.
void	ignorableWhitespace(char[] ch, int start, int length) Receives notification of ignorable whitespace in element content.
void	init() Initializes the SAX parser.
void	processingInstruction(String instruction, String data) Receives notification of a processing instruction.
void	setClientIP(String ip) Sets the IP address string of the client that makes the HTTP request to the servlet.
void	setDocumentLocator(Locator locator) Receive a Locator object for document events.
void	setSourceURL(String urlString) Sets the URL string of the client that makes the HTTP request to the servlet.
void	skippedEntity(String name) Receives notification of a skipped entity.
void	startDocument() Receives notification of the beginning of the document to take any specific actions at the beginning of a document.
void	startElement(String namespaceURI, String localName, String qName, Attributes atts) Receives notification of the start of an element.
void	startParsing(InputSource source) Starts parsing the DiGIR request.
void	startPrefixMapping(String prefix, String uri) Receives notification of the start of a Namespace mapping.
void	warning(SAXParseException e) Receives notification of a parser warning.

Methods inherited from class org.xml.sax.helpers.DefaultHandler

notationDecl, resolveEntity, unparsedEntityDecl

Methods inherited from class java.lang.Object

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

Constructor Detail

DiGIRRequestParser

public DiGIRRequestParser(InputSource source)

Constructs a DiGIRRequestParser object to parse the DiGIR request in the InputSource object.

Parameters:

source - the InputSource object of the xml entity

Method Detail

init

public void init()

Initializes the SAX parser.

startParsing

public void startParsing(InputSource source)

Starts parsing the DiGIR request.

Parameters:

source - the InputSource object of the xml entity

startDocument

public void startDocument()
                   throws SAXException

Receives notification of the beginning of the document to take any specific actions at the beginning of a document.

Throws:

SAXException - any SAX exception, possibly wrapping another exception

endDocument

public void endDocument()
                 throws SAXException

Receives notification of the end of the document to take any specific actions at the end of a document.

Throws:

SAXException - any SAX exception, possibly wrapping another exception

setDocumentLocator

public void setDocumentLocator(Locator locator)

Receive a Locator object for document events.

Parameters:

locator - the locator for all SAX document events

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException

Receives notification of the start of an element.

Parameters:

namespaceURI - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified name (with prefix), or the empty string if qualified names are not available

atts - the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object

Throws:

SAXException - any SAX exception, possibly wrapping another exception

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

Receives notification of character data inside an element.

Parameters:

ch - the characters

start - the start position in the character array

length - the number of characters to use from the character array

Throws:

SAXException - any SAX exception, possibly wrapping another exception

endElement

public void endElement(String namespaceURI,
                       String localName,
                       String qName)
                throws SAXException

Receives notification of the end of an element.

Parameters:

namespaceURI - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName - the local name (without prefix), or the empty string if Namespace processing is not being performed

qName - the qualified name (with prefix), or the empty string if qualified names are not available

Throws:

SAXException - any SAX exception, possibly wrapping another exception

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

Receives notification of ignorable whitespace in element content. Does nothing.

Parameters:

ch - the whitespace characters

start - the start position in the character array

length - the number of characters to use from the character array

Throws:

SAXException - any SAX exception, possibly wrapping another exception

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

Receives notification of the start of a Namespace mapping. Does nothing.

Parameters:

prefix - the Namespace prefix being declared

uri - the Namespace URI mapped to the prefix

Throws:

SAXException - any SAX exception, possibly wrapping another exception

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Receives notification of the end of a Namespace mapping. Does nothing.

Parameters:

prefix - the Namespace prefix being declared

Throws:

SAXException - any SAX exception, possibly wrapping another exception

processingInstruction

public void processingInstruction(String instruction,
                                  String data)
                           throws SAXException

Receives notification of a processing instruction. Does nothing.

Parameters:

instruction - the processing instruction target

data - the processing instruction data, or null if none is supplied

Throws:

SAXException - any SAX exception, possibly wrapping another exception

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Receives notification of a skipped entity. Does nothing.

Parameters:

name - the name of the skipped entity

Throws:

SAXException - any SAX exception, possibly wrapping another exception

error

public void error(SAXParseException e)
           throws SAXException

Receives notification of a recoverable parser error.

Parameters:

e - the error information encoded as an SAXParseException

Throws:

SAXException - any SAX exception, possibly wrapping another exception

warning

public void warning(SAXParseException e)
             throws SAXException

Receives notification of a parser warning.

Parameters:

e - the warning information encoded as an SAXParseException

Throws:

SAXException - any SAX exception, possibly wrapping another exception

fatalError

public void fatalError(SAXParseException e)
                throws SAXException

Reports a fatal XML parsing error.

Parameters:

e - the warning information encoded as an SAXParseException

Throws:

SAXException - any SAX exception, possibly wrapping another exception

setSourceURL

public void setSourceURL(String urlString)

Sets the URL string of the client that makes the HTTP request to the servlet.

Parameters:

urlString - the URL string of the servlet client

getSourceURL

public String getSourceURL()

Gets the URL string of the client that makes the HTTP request to the servlet.

Returns:

the URL string of the servlet client

setClientIP

public void setClientIP(String ip)

Sets the IP address string of the client that makes the HTTP request to the servlet.

Parameters:

ip - the IP address string of the servlet client

getClientIP

public String getClientIP()

Gets the IP address string of the client that makes the HTTP request to the servlet.

Returns:

the IP address string of the servlet client

getInventoryClause

public String getInventoryClause()

Gets the schema concept to be used to construct a DiGIR response to an inventory request. If the request doesn't specify one, it will return the default inventory concept for the specified resource.

Returns:

the concept used to construct a inventory response

getSourceResource

public String getSourceResource()

Gets the resource attribute of the "source" element of a DiGIR request.

Returns:

the resource attribute of the "source" element

getRequestSourceText

public String getRequestSourceText()

Gets the the text associated with the "source" element of a DiGIR request.

Returns:

the text of the "source" element

getRequestDestinationText

public String getRequestDestinationText()

Gets the the text associated with the "destination" element of a DiGIR request.

Returns:

the text of the "destination" element

getRequestType

public String getRequestType()

Gets the type of this DiGIR request. It can only be one of the following:
search, metadata, or inventory

Returns:

the type of this DiGIR request

getStart

public int getStart()

Returns the start attribute specified in the "records" element of the request. The DiGIR response will display the result starting from this record number. It defaults to "0" if not specified in the request.

Returns:

an int specified in the "start" attribute of the "records" element

getLimit

public int getLimit()

Returns the "limit" attribute specified in the "records" element of the request. The DiGIR response will display this amount of records if the number of the records is greater than this number. If the number of the records is less than this number, the DiGIR response will display all the records. It defaults to "10" if not specified in the request.

Returns:

an int specified in the "limit" attribute of the "records" element

getCount

public boolean getCount()

Returns the boolean value of the "count" element specified in this DiGIR request. If the value is false, the reponse will not include the "MATCH_COUNT" as a "diagnostic" element.

Returns:

the boolean value of the "count" element in the request

getFilterString

public String getFilterString()

Gets the string representation of this DiGIR request filter contents from the DiGIRRequestParser. It returns an empty string if the content of the DiGIR fitler is empty.

The string uses parentheses to represent the structure of the DiGIR filter. e.g.

( ( concpet_A EQUALS value_A AND concept_B EQUALS value_B ) OR concept_C NOTEQUALS value_C )

Returns:

a string representation of the DiGIR filter contents

getErrorCode

public int getErrorCode()

Returns the error code. This method is usually code to check whether an error has occurred while parsing the DiGIR request. An error has occurred if (getErrorCode() != DiGIRProvError.OK) is true.

Returns:

the DiGIRRequestParser's error code

See Also:

DiGIRProvError

getRequestedResource

public String getRequestedResource()

Returns the name of the resource requested in this DiGIR request.

Returns:

the name of the requested resource

getDiagnostics

public Map getDiagnostics()

Returns a map mapping error level strings to a list of DiGIRProvError objects. The error levels are the same as the severities defined in the DiGIR schema, debug, info, warn, error, and fatal. Each DiGIRProvError holds the provider's error code, the string representation of the error code, and the error message for each error occurred while processing this DiGIR request.

Returns:

a map from error levels to list of DiGIRProvError objects

getConceptualSchemaURI

public String getConceptualSchemaURI()

Returns the conceptual schema URI string used in this DiGIR request.

Returns:

the conceptual schema namespace URI string used in this DiGIR request

getConceptualSchemaName

public String getConceptualSchemaName()

Returns the conceptual schema namespace identifier used in this DiGIR request.

Returns:

the conceptual schema namespace identifier used in this DiGIR request

getRequiredConcepts

public Set getRequiredConcepts()

Returns a set of schema concept names required to build the DiGIR response. This method parses the record schema specified in the schemaLocation attribute of the "structure" if one exists and saves each schema concepts required to build the DiGIR response. This method also builds a java.util.List of RecordConcept object in order to later present the DiGIR response in the same order and structure specified in the record schema.

If it fails to parse the schema specified in the request, it uses the default record schema for the requested resource.

Returns:

a java.util.Set of names of the required schema concepts

getRecordConcepts

public List getRecordConcepts()

Returns a list of concepts requested via a schema location or a sequence of elements specified in the "structure" element of the DiGIR search request. Each concept is represented by a RecordConcept object that might be a simple schema concept or a complex concept that contains a sequence of simple/complex concepts. A java.util.List is used to keep the order of the concepts as requested.

This method calls getRequiredConcepts() to build the list of record concepts as well as the set of required schema concepts if they are not already found.

Returns:

a java.util.List of RecordConcept objects representing the required concepts

See Also:

getRequiredConcepts()

addRecordConcept

protected void addRecordConcept(RecordConcept concept)

Adds a RecordConcept object to the list of record concepts specified in the DiGIR request. It also adds the name of the required schema concept for that record concept to the set of schema concepts required to map to the database fields.

Parameters:

concept - the RecordConcept object representing a record concept

addDiagnostics

public void addDiagnostics(String severity,
                           int errorConst,
                           String msg)

Adds a diagnoistic element to the DiGIR response. Calling this method with parameters like the following

addDiagnostics("error", DiGIRProvError.RESOURCE_FAILURE, "SOMETHING WRONG");

results in a "diagnostic" element like the following

<diagnostic code="RESOURCE_FAILURE" severity="error">SOMETHING WRONG</diagnostic>

in the DiGIR response.

Parameters:

severity - the severity of the message, could be debug, info, warn, error, or fatal.

errorConst - the error constants defined by DiGIRProvError

msg - the error message

See Also:

DiGIRProvError

hasErrorDiagnose

public boolean hasErrorDiagnose()

Checks whether there is an error diagnostic already. If so, the DiGIRProcessor will not go on to build the "diagnostic" element for the severity level "info" such as "MATCH_COUNT" or "END_OF_RECORD", which don't have realistic meanings if an error occurred in the process.

Returns:

true if there is an error diagnostic.