project.biota.biotaInterface
Class BiotaRequestHandler

java.lang.Object
  project.biota.biotaInterface.BiotaRequestHandler

Direct Known Subclasses:

BiotaDefaultHandler, BiotaServerRequestHandler, BiotaWebRequestHandler

public abstract class BiotaRequestHandler

extends Object

BiotaRequestHandler is an abstract class extended by classes that wish to handle requests for a particular type of resources. For example, class BiotaServerRequestHandler extends this class to handle DiGIR requests for resources served via a 4D Server, while class BiotaWebRequestHandler extends this class to handle DiGIR requests for resources served via a Biota onboard Web Server.

This class provides the commom functionality of all DiGIR query handlers, such as processing the query arguments and building responses.

Author:

Kimmy Lin

See Also:

BiotaDefaultHandler, BiotaServerRequestHandler, BiotaWebRequestHandler

Field Summary

protected Namespace	conceptualSchemaNamespace The JDOM Namespace for the conceptual schema used in the DiGIR request.
protected String	conceptualSchemaURI The URI for the conceptual schema used in the DiGIR request.
protected SimpleDateFormat	formatter Format a Java date to conform the XML schema dateTime data type.
protected String	left_index A parameter indicates the left-hand side argument in a binary logical relationship like "and".
protected static Logger	logger The Apache log4j Logger object for this class.
protected int	maxDepth The maximum depth of the query structure.
protected int	maxlevel A parameter indicates the level of the query structure.
protected DiGIRRequestParser	requestParser The DiGIRRequestParser that parses the request.
protected Set	requiredConcepts A set of schema concepts required to build the DiGIR response.
protected Map	requiredTablesFields Maps database tables to a set of fields in that table that are mapped to the schema concepts.
protected Element	responseRecords The JDOM Element that holds the records for the DiGIR response.
protected String	right_index A parameter indicates the right-hand side argument in a binary logical relationship like "and".
protected ResourceObject	rscObject An object that holds all the information for the requested resource.

Constructor Summary

BiotaRequestHandler(DiGIRRequestParser parser)
Constructs a BiotaRequestHandler to handle a DiGIR request.

Method Summary

protected Element	addRecordConceptElem(RecordConcept recordConcept, Object fieldsValues) Constructs a JDOM element for each record concept and checks whether the it is a complex concept that contains a sequence of schema/complex concept.
protected abstract void	buildDiGIRResult(String filterString) Makes database queries and processes the response returned by the database to build the records for the DiGIR response.
Element	buildResult() Returns a JDOM element of the records for the DiGIR response.
protected void	createInventoryResponseElem(Map resultMap) Creates all the "record" JDOM element for a DiGIR response to a inventory request.
protected void	findRequiredTablesFields() Finds the database tables/fields that are required to build the DiGIR response.
protected abstract String	getConceptValue(String conceptName, Object fieldsValues) Constructs the value for a schema concept from the fieldsValues object.
protected String	getQueryString(String filter) Processes the string representation of the DiGIR request filter contents to a string that has the depth info of the structure, and replaces the schema concept to whatever database tables/fields that concept maps to.
protected String	parseValue(project.biota.resource.Field field, String value) Extracts the value from a string for a field that needs parsing using the separator(parseSymbol) and position(pos) specified for that field in the resource's configuaration file.
protected abstract void	updateResourceMetadata(ResourceObject rscObj) Updates the metadata for the resource specified by the ResourceObject object.

Methods inherited from class java.lang.Object

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

Field Detail

requestParser

protected DiGIRRequestParser requestParser

The DiGIRRequestParser that parses the request.

responseRecords

protected Element responseRecords

The JDOM Element that holds the records for the DiGIR response.

maxlevel

protected int maxlevel

A parameter indicates the level of the query structure.

maxDepth

protected int maxDepth

The maximum depth of the query structure.

left_index

protected String left_index

A parameter indicates the left-hand side argument in a binary logical relationship like "and".

right_index

protected String right_index

A parameter indicates the right-hand side argument in a binary logical relationship like "and".

conceptualSchemaURI

protected String conceptualSchemaURI

The URI for the conceptual schema used in the DiGIR request.

conceptualSchemaNamespace

protected Namespace conceptualSchemaNamespace

The JDOM Namespace for the conceptual schema used in the DiGIR request.

rscObject

protected ResourceObject rscObject

An object that holds all the information for the requested resource.

requiredConcepts

protected Set requiredConcepts

A set of schema concepts required to build the DiGIR response.

requiredTablesFields

protected Map requiredTablesFields

Maps database tables to a set of fields in that table that are mapped to the schema concepts.

formatter

protected SimpleDateFormat formatter

Format a Java date to conform the XML schema dateTime data type.

logger

protected static Logger logger

The Apache log4j Logger object for this class.

Constructor Detail

BiotaRequestHandler

public BiotaRequestHandler(DiGIRRequestParser parser)

Constructs a BiotaRequestHandler to handle a DiGIR request.

Parameters:

parser - the DiGIRRequestParser that parses the DiGIR request

Method Detail

buildResult

public Element buildResult()

Returns a JDOM element of the records for the DiGIR response. This method collects all the schema concepts required to build the response, finds the database tables/fields that mapped to these concepts, and then calls buildDiGIRResult() method to build a JDOM element that contains the query result.

Returns:

a JDOM element of the DiGIR response

See Also:

buildDiGIRResult(String)

buildDiGIRResult

protected abstract void buildDiGIRResult(String filterString)

Makes database queries and processes the response returned by the database to build the records for the DiGIR response.

Subclasses of BiotaRequestHandler need to implement this method. Different types of resources require different codes to make the database connection. For example, a resource hosted in a 4D Server requires a JDBC conncetion while a resource hosted in a Biota onboard Web Server reqireds a HTTP connection.

Parameters:

filterString - the string representation of the filter in the DiGIR request

updateResourceMetadata

protected abstract void updateResourceMetadata(ResourceObject rscObj)

Updates the metadata for the resource specified by the ResourceObject object.

Subclasses of BiotaRequestHandler need to implement this method to query the resource about its total number of records and the date the resource is last updated and call ResourceObject.setNumberOfRecords() method and ResourceObject.setDateLastUpdated() on the ResourceObject object that represents the requested resource.

Parameters:

rscObj - the ResourceObject object that represents a resource

See Also:

ResourceObject.setNumberOfRecords(int), ResourceObject.setDateLastUpdated(String)

getConceptValue

protected abstract String getConceptValue(String conceptName,
                                          Object fieldsValues)

Constructs the value for a schema concept from the fieldsValues object. Subclasses of BiotaRequestHandler need to implement this method to extract value from a collection of database field values returned from the resource. This method needs to implement ways to build the concept value from multiple database fields or to call parseValue() method when a field needs parsing.

Parameters:

conceptName - the name for the schema concept

fieldsValues - a collection of field values for one record

Returns:

the value for the schema concept for a record

See Also:

parseValue(Field, String)

getQueryString

protected String getQueryString(String filter)

Processes the string representation of the DiGIR request filter contents to a string that has the depth info of the structure, and replaces the schema concept to whatever database tables/fields that concept maps to. Each field is identified by [table_name]field_name. For example, the following string

((Concpet_A EQUALS Value_A AND Concept_B EQUALS Value_B ) OR Concept_C NOTEQUALS Value_C)

will be processed to

0a( 1a( 2a([field_A_table]field_A=value_A)2a or 2b([field_B_table]field_B=value_B)2b )1a or 1b([field_C_table]field_C=value_C)1b )0a

It returns an empty string if the content of the DiGIR filter is empty.

Returns:

a string representation of the DiGIR filter contents with depth information

findRequiredTablesFields

protected void findRequiredTablesFields()

Finds the database tables/fields that are required to build the DiGIR response. It finds the mappped tables/fields of each required concept and stored them in a Map, mapping table names to a set of fields required from that table.

parseValue

protected String parseValue(project.biota.resource.Field field,
                            String value)

Extracts the value from a string for a field that needs parsing using the separator(parseSymbol) and position(pos) specified for that field in the resource's configuaration file. If the field doesn't need parsing, it returns the original passed-in value. It returns an empty string if the following is true:

position >= (value.split(separator)).length

Parameters:

field - the Field that needs parsing

value - the string that contains the value for the field

Returns:

the parsed value of the field

addRecordConceptElem

protected Element addRecordConceptElem(RecordConcept recordConcept,
                                       Object fieldsValues)

Constructs a JDOM element for each record concept and checks whether the it is a complex concept that contains a sequence of schema/complex concept. If so, it recursively calls itself to build the content for all of its children concepts. If not, it's a simple schema concept and this method simply calls getConceptValue() method to find the value for that concept. It then checks check whether the value is null. If so, it sets the xsi:nil attribute of that concept element to "true".

Parameters:

recordConcept - a concept specified by the record schema in the DiGIR request

fieldsValues - a collection of field values for one record

Returns:

a JDOM element for this record concept

See Also:

getConceptValue(String, Object)

createInventoryResponseElem

protected void createInventoryResponseElem(Map resultMap)

Creates all the "record" JDOM element for a DiGIR response to a inventory request.

Parameters:

resultMap - a Java Map object mapping each concept value to its count