org.deegree.ogcwebservices.csw.discovery
Class GetRecords

java.lang.Object
  org.deegree.ogcwebservices.AbstractOGCWebServiceRequest
      org.deegree.ogcwebservices.csw.AbstractCSWRequest
          org.deegree.ogcwebservices.csw.discovery.GetRecords

All Implemented Interfaces:

Serializable, OGCWebServiceRequest

public class GetRecords
extends AbstractCSWRequest

Class representation of a GetRecords request.

The primary means of resource discovery in the general model are the two operations search and present. In the HTTP protocol binding these are combined in the form of the mandatory GetRecords operation, which does a search.

Parameters specific to the GetRecords -request (omitting REQUEST, SERVICE and VERSION):

Name	Occurences	Function
NAMESPACE	0|1	The NAMESPACE parameter is included in the KVP encoding to allow clients to bind any namespace prefixes that might be used for qualified names specified in other parameters. For example, the typeName parameter may include qualified names of the form namespace prefix:name. The value of the NAMESPACE parameter is a comma separated list of character strings of the form [namespace prefix:] namespace url. Not including the name namespace prefix binds the specified URL to the default namespace. As in XML, only one default namespace may be bound. This parameter is not required for the XML encoding since XML includes a mechanism for binding namespace prefixes.
resultType	0|1 (default: RESULTS)	The resultType parameter may have the values HITS, RESULTS or VALIDATE and is used to indicate whether the catalogue service returns the full result set, the number of hits the query found or validates the request. If the resultType parameter is set to HITS, the catalogue service shall return an empty <GetRecordsResponse> element with the numberOfRecordsMatched attribute set to indicate the number of hits. The other attributes may be set to zero or not specified at all if they are optional. If the resultType parameter is set to HITS, then the values for the parameters outputFormat and outputSchema (if specified) shall be ignored since no actual records will be returned. If the resultType parameter is set to RESULTS, the catalogue service should generate a complete response with the <GetRecordsResponse> element containing the result set for the request. If the resultType parameter is set to VALIDATE, the catalogue service shall validate the request and return an empty <GetRecordsResponse>. All mandatory attributes may be given a value of zero and all optional attributes may be omitted. If the request does not validate then a service exception shall be raised as describe in Subclause 10.3.2.3.
outputFormat	0|1 (default: text/xml)	The outputFormat parameter is used to control the format of the output that is generated in response to a GetRecords request. Its value must be a MIME type. The default value, "text/xml", means that the output shall be an XML document. All registries shall at least support XML as an output format. Other output formats may be supported and may include output formats such as TEXT (MIME type text/plain), or HTML (MIME type text/html). The list of output formats that a CSW instance provides must be advertised in the Capabilities document. In the case where the output format is text/xml, the CSW must generate an XML document that validates against a schema document that is specified in the output document via the xsi:schemaLocation attribute defined in XML.
outputSchema	0|1 (default: OGCCORE)	The outputSchema parameter is used to indicate the schema of the output that is generated in response to a GetRecords request. The default value for this parameter shall be OGCCORE indicating that the schema for the core returnable properties (as defined in subclause 6.3.3) shall be used. Application profiles may define additional values for outputSchema and may redefine the default value but all profiles must support the value OGCCORE. Examples values for the outputSchema parameter might be FGDC, or ISO19119, ISO19139 or ANZLIC. The list of supported output schemas must be advertised in the capabilities document.
startPosition	0|1 (default: 1)	The startPosition paramater is used to indicate at which record position the catalogue should start generating output. The default value is 1 meaning it starts at the first record in the result set.
maxRecords	0|1 (default: 10)	The maxRecords parameter is used to define the maximum number of records that should be returned from the result set of a query. If it is not specified, then 10 records shall be returned. If its value is set to zero, then the behavior is indentical to setting "resultType=HITS" as described above.
typeName	1	The typeName parameter is a list of record type names that define a set of metadata record element names which will be constrained in the predicate of the query. In addition, all or some of the these names may be specified in the query to define which metadata record elements the query should present in the response to the GetRecords operation.
ElementSetName / ElementName	* (default: 10)	The ElementName parameter is used to specify one or more metadata record elements that the query should present in the response to the a GetRecords operation. Well known sets of element may be named, in which case the ElementSetName parameter may be used (e.g.brief, summary or full). If neither parameter is specified, then a CSW shall present all metadata record elements. As mentioned above, if the outputFormat parameter is set to text/xml, then the response to the GetRecords operation shall validate against a schema document that is referenced in the response using the xmlns attributes. If the set of metadata record elements that the client specifies in the query in insufficient to generate a valid XML response document, a CSW may augment the list of elements presented to the client in order to be able to generate a valid document. Thus a client application should expect to receive more than the requested elements if the output format is set to XML.
CONSTRAINTLANGUAGE / Constraint	0|1	Each request encoding (XML and KVP) has a specific mechanism for specifying the predicate language that will be used to constrain a query. In the XML encoding, the element <Constraint> is used to define the query predicate. The root element of the content of the <Constraint> element defines the predicate language that is being used. Two possible root elements are <ogc:Filter> for the OGC XML filter encoding, and <csw:CqlText> for a common query language string. An example predicate specification in the XML encoding is: <Constraint> <CqlText>prop1!=10</CqlText> </Constraint> In the KVP encoding, the parameter CONSTRAINTLANGUAGE is used to specify the predicate language being used. The Constraint parameter is used to specify the actual predicate. For example, to specify a CQL predicate, the following parameters would be set in the KVP encoding: ...CONSTRAINTLANGUAGE=CQL_TEXT&CONSTRAINT="prop1!=10"...
SortBy	0|1	The result set may be sorted by specifying one or more metadata record elements upon which to sort. In KVP encoding, the SORTBY parameter is used to specify the list of sort elements. The value for the SORTBY parameter is a comma-separated list of metadata record element names upon which to sort the result set. The format for each element in the list shall be either element name:A indicating that the element values should be sorted in ascending order or element name:D indicating that the element values should be sorted in descending order. For XML encoded requests, the <ogc:SortBy> element is used to specify a list of sort metadata record elements. The attribute sortOrder is used to specify the sort order for each element. Valid values for the sortOrder attribute are ASC indicating an ascending sort and DESC indicating a descending sort.
DistributedSearch / hopCount	0|1 (default: FALSE)	The DistributedSearch parameter may be used to indicate that the query should be distributed. The default query behaviour, if the DistributedSearch parameter is set to FALSE (or is not specified at all), is to execute the query on the local server. In the XML encoding, if the <DistributedSearch> element is not specified then the query is executed on the local server. The hopCount parameter controls the distributed query behaviour by limiting the maximum number of message hops before the search is terminated. Each catalogue decrements this value by one when the request is received and does not propagate the request if the hopCount=0.
ResponseHandler	0|1	The ResponseHandler parameter is a flag that indicates how the GetRecords operation should be processed by a CSW. If the parameter is not present, then the GetRecords operation is processed synchronously meaning that the client sends the GetRecords request to a CSW and waits to receive a valid response or exception message. The CSW immediately processes the GetRecords request while the client waits for a response. The problem with this mode of operation is that the client may timeout waiting for the CSW to process the request. If the ResponseHandler parameter is present, the GetRecords operation is processed asynchronously. In this case, the CSW responds immediately to a client's request with an acknowledgment message that tells the client that the request has been received and validated, and notification of completion will be sent to the URI specified as the value of the ResponseHandler parameter.

Version:

$Revision: 18436 $, $Revision: 18436 $, $Date: 2009-07-13 10:45:11 +0200 (Mo, 13. Jul 2009) $

Author:

Markus Schneider , Andreas Poth , Torsten Friebe , Markus Schneider , last edited by: $Author: lbuesching $

See Also:

Serialized Form

Nested Class Summary

static class

GetRecords.RESULT_TYPE The RESULT_TYPE a simple enum which defines some result values of a GetRecord.

Field Summary

protected static int	DEFAULT_HOPCOUNT
protected static int	DEFAULT_MAX_RECORDS
protected static String	DEFAULT_OUTPUTFORMAT
protected static String	DEFAULT_OUTPUTSCHEMA
protected static String	DEFAULT_OUTPUTSCHEMA_202
protected static int	DEFAULT_STARTPOSITION
protected static String	DEFAULT_VERSION
static String	RESULT_TYPE_STRING_HITS defining HITS as String
static String	RESULT_TYPE_STRING_RESULTS defining RESULTS as String
static String	RESULT_TYPE_STRING_VALIDATE defining VALIDATE as String

Constructor Summary

GetRecords(String id, String version, Map<String,String> vendorSpecificParameters, Map<String,URI> namespace, GetRecords.RESULT_TYPE resultType, String outputFormat, String outputSchema, int startPosition, int maxRecords, int hopCount, URI responseHandler, Query query)
Creates a new GetRecords instance.

Method Summary

static GetRecords	create(Map<String,String> kvp) Creates a new GetRecords instance from the values stored in the submitted Map.
static GetRecords	create(String id, Element root) creates a GetRecords request from the XML fragment passed.
int	getHopCount() returns <= 0 if no distributed search shall be performed. otherwise the recursion depht is returned.
int	getMaxRecords()
Map<String,URI>	getNamespace() Used to specify a namespace and its prefix.
String	getOutputFormat() Value is Mime type;The only value that must be supported is text/xml.
String	getOutputSchema() The outputSchema parameter is used to indicate the schema of the output that is generated in response to a GetRecords request.
Query	getQuery()
URI	getResponseHandler()
GetRecords.RESULT_TYPE	getResultType() The resultType parameter may have the values HITS, RESULTS or VALIDATE and is used to indicate whether the catalogue service returns the full result set, the number of hits the query found or validates the request.
String	getResultTypeAsString() The resultType parameter may have the values HITS, RESULTS or VALIDATE and is used to indicate whether the catalogue service returns the full result set, the number of hits the query found or validates the request.
int	getStartPosition()
void	setQuery(Query query)
void	setResultType(GetRecords.RESULT_TYPE resultType) sets the resultType of a request.

Methods inherited from class org.deegree.ogcwebservices.csw.AbstractCSWRequest

getNSMappings, getServiceName

Methods inherited from class org.deegree.ogcwebservices.AbstractOGCWebServiceRequest

getId, getParam, getParamAsInt, getParamValues, getRequestParameter, getRequiredParam, getVendorSpecificParameter, getVendorSpecificParameters, getVersion, toString

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_OUTPUTFORMAT

protected static final String DEFAULT_OUTPUTFORMAT

See Also:

Constant Field Values

DEFAULT_OUTPUTSCHEMA

protected static final String DEFAULT_OUTPUTSCHEMA

See Also:

Constant Field Values

DEFAULT_OUTPUTSCHEMA_202

protected static final String DEFAULT_OUTPUTSCHEMA_202

See Also:

Constant Field Values

DEFAULT_STARTPOSITION

protected static final int DEFAULT_STARTPOSITION

See Also:

Constant Field Values

DEFAULT_MAX_RECORDS

protected static final int DEFAULT_MAX_RECORDS

See Also:

Constant Field Values

DEFAULT_HOPCOUNT

protected static final int DEFAULT_HOPCOUNT

See Also:

Constant Field Values

DEFAULT_VERSION

protected static final String DEFAULT_VERSION

See Also:

Constant Field Values

RESULT_TYPE_STRING_HITS

public static String RESULT_TYPE_STRING_HITS

defining HITS as String

RESULT_TYPE_STRING_VALIDATE

public static String RESULT_TYPE_STRING_VALIDATE

defining VALIDATE as String

RESULT_TYPE_STRING_RESULTS

public static String RESULT_TYPE_STRING_RESULTS

defining RESULTS as String

Constructor Detail

GetRecords

public GetRecords(String id,
                  String version,
                  Map<String,String> vendorSpecificParameters,
                  Map<String,URI> namespace,
                  GetRecords.RESULT_TYPE resultType,
                  String outputFormat,
                  String outputSchema,
                  int startPosition,
                  int maxRecords,
                  int hopCount,
                  URI responseHandler,
                  Query query)

Creates a new GetRecords instance.

Parameters:

id -

version -

vendorSpecificParameters -

namespace -

resultType -

outputFormat -

outputSchema -

startPosition -

maxRecords -

hopCount -

responseHandler -

query -

Method Detail

create

public static GetRecords create(String id,
                                Element root)
                         throws MissingParameterValueException,
                                InvalidParameterValueException,
                                OGCWebServiceException

creates a GetRecords request from the XML fragment passed. The passed element must be valid against the OGC CSW 2.0 GetRecords schema. TODO respect namespaces (use QualifiedNames) for type names

Parameters:

id - unique ID of the request

root - root element of the GetRecors request

Returns:

a GetRecords instance with given id and parsed values from the root element

Throws:

MissingParameterValueException - if a required parameter was not set

InvalidParameterValueException - if a parameter is invalid

OGCWebServiceException - if something went wrong while creating the Request

create

public static GetRecords create(Map<String,String> kvp)
                         throws InvalidParameterValueException,
                                MissingParameterValueException,
                                OperationNotSupportedException

Creates a new GetRecords instance from the values stored in the submitted Map. Keys (parameter names) in the Map must be uppercase.

Parameters:

kvp - Map containing the parameters

Returns:

a GetRecords instance with given id and values from the kvp

Throws:

InvalidParameterValueException

MissingParameterValueException

OperationNotSupportedException - if an CQL_TEXT constrain is requested

To do:

evaluate vendorSpecificParameter

getNamespace

public Map<String,URI> getNamespace()

Used to specify a namespace and its prefix. Format must be [ :] . If the prefix is not specified then this is the default namespace

Zero or one (Optional) ; Include value for each distinct namespace used by all qualified names in the request. If not included, all qualified names are in default namespace

The NAMESPACE parameter is included in the KVP encoding to allow clients to bind any namespace prefixes that might be used for qualified names specified in other parameters. For example, the typeName parameter may include qualified names of the form namespace prefix:name.

The value of the NAMESPACE parameter is separated list of character strings of the form [namespace prefix:]namespace url. Not including the name namespace prefix binds the specified URL to the default namespace. As in XML, only one default namespace may be bound.

Returns:

the mapped namespaces or null if all qualified names are in default namespace.

getResultType

public GetRecords.RESULT_TYPE getResultType()

The resultType parameter may have the values HITS, RESULTS or VALIDATE and is used to indicate whether the catalogue service returns the full result set, the number of hits the query found or validates the request.

If the resultType parameter is set to HITS, the catalogue service shall return an empty <GetRecordsResponse>element with the numberOfRecordsMatched attribute set to indicate the number of hits. The other attributes may be set to zero or not specified at all if they are optional.

If the resultType parameter is set to HITS, then the values for the parameters outputFormat and outputSchema (if specified) shall be ignored since no actual records will be returned

If the resultType parameter is set to RESULTS, the catalogue service should generate a complete response with the <GetRecordsResponse>element containing the result set for the request

If the resultType parameter is set to VALIDATE, the catalogue service shall validate the request and return an empty <GetRecordsResponse>. All mandatory attributes may be given a value of zero and all optional attributes may be omitted. If the request does not validate then a service exception shall be raised

Returns:

one of HITS, RESULTS or VALIDATE

getResultTypeAsString

public String getResultTypeAsString()

The resultType parameter may have the values HITS, RESULTS or VALIDATE and is used to indicate whether the catalogue service returns the full result set, the number of hits the query found or validates the request.

If the resultType parameter is set to HITS, the catalogue service shall return an empty <GetRecordsResponse>element with the numberOfRecordsMatched attribute set to indicate the number of hits. The other attributes may be set to zero or not specified at all if they are optional.

If the resultType parameter is set to HITS, then the values for the parameters outputFormat and outputSchema (if specified) shall be ignored since no actual records will be returned

If the resultType parameter is set to RESULTS, the catalogue service should generate a complete response with the <GetRecordsResponse>element containing the result set for the request

If the resultType parameter is set to VALIDATE, the catalogue service shall validate the request and return an empty <GetRecordsResponse>. All mandatory attributes may be given a value of zero and all optional attributes may be omitted. If the request does not validate then a service exception shall be raised

Returns:

the resulttype as a String, one of "HITS", "VALIDATE" or "RESULTS"

setResultType

public void setResultType(GetRecords.RESULT_TYPE resultType)

sets the resultType of a request. This may be useful to perform a request first with resultType = HITS to determine the total number of records matching a query and afterwards performing the same request with resultType = RESULTS (and maxRecords < number of matched records).

Parameters:

resultType -

getHopCount

public int getHopCount()

returns <= 0 if no distributed search shall be performed. otherwise the recursion depht is returned.

The hopCount parameter controls the distributed query behaviour by limiting the maximum number of message hops before the search is terminated. Each catalogue decrements this value by one when the request is received and does not propagate the request if the hopCount=0

Returns:

<= 0 if no distributed search shall be performed. otherwise the recursion depht is returned.

getOutputFormat

public String getOutputFormat()

Value is Mime type;The only value that must be supported is text/xml. Other suppored values may include text/html and text/plain

The outputFormat parameter is used to control the format of the output that is generated in response to a GetRecords request. Its value must be a MIME type. The default value, "text/xml", means that the output shall be an XML document. All registries shall at least support XML as an output format. Other output formats may be supported and may include output formats such as TEXT (MIME type text/plain), or HTML (MIME type text/html). The list of output formats that a CSW instance provides must be advertised in the Capabilities document

In the case where the output format is text/xml, the CSW must generate an XML document that validates against a schema document that is specified in the output document via the xsi:schemaLocation attribute defined in XML

Returns:

Value is a Mime type

getOutputSchema

public String getOutputSchema()

The outputSchema parameter is used to indicate the schema of the output that is generated in response to a GetRecords request. The default value for this parameter shall be OGCCORE indicating that the schema for the core returnable properties shall be used. Application profiles may define additional values for outputSchema and may redefine the default value but all profiles must support the value OGCCORE

Examples values for the outputSchema parameter might be FGDC, or ISO19119, ISO19139 or ANZLIC. The list of supported output schemas must be advertised in the capabilities document

Returns:

The default value for this parameter shall be OGCCORE

getStartPosition

public int getStartPosition()

Returns:

the number of the first returned dataset. Zero or one (Optional)Default value is 1. If startPosition > the number of datasets satisfying the constraint, no dataset will be returned

getMaxRecords

public int getMaxRecords()

Returns:

The maxRecords parameter. It is used to define the maximum number of records that should be returned from the result set of a query. If it is not specified, then 10 records shall be returned. If its value is set to zero, then the behavior is indentical to setting "resultType=HITS"

getResponseHandler

public URI getResponseHandler()

Returns:

the location of a response adress to which an asynchronous result may be sent.

getQuery

public Query getQuery()

Returns:

the query object.

setQuery

public void setQuery(Query query)

Parameters:

query -

See Also:

getQuery()