Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| deegree 2.4 (2010/11/11 10:47 build-27-official)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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: 25619 $, $Revision: 25619 $, $Date: 2010-08-02 08:17:24 +0200 (Mo, 02. Aug 2010) $
Author:
  Markus Schneider , Andreas Poth , Torsten Friebe , Markus Schneider , last edited by: $Author: apoth $
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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| deegree 2.4 (2010/11/11 10:47 build-27-official)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

an open source project founded by lat/lon, Bonn, Germany.
For more information visit: http://www.deegree.org