Package org.opengis.cite.iso19142.util

# Class WFSClient

java.lang.Object
org.opengis.cite.iso19142.util.WFSClient

public class WFSClient extends Object
A WFS 2.0 client component.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected jakarta.ws.rs.client.Client`
  `client`
  `protected List<QName>`
  `featureTypes`
  The list of feature types recognized by the SUT.
  `protected Set<ProtocolBinding>`
  `globalBindings`
  The set of message bindings broadly implemented by the SUT.
  `protected Document`
  `wfsMetadata`
  A Document that describes the service under test.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `WFSClient()`
  Default client constructor.
  `WFSClient(Document wfsMetadata)`
  Constructs a client that is aware of the capabilities of a WFS implementation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `jakarta.ws.rs.core.Response`
  `deleteFeature(Document reqEntity, String id, QName typeName)`
  Submits a request to delete a feature.
  `Document`
  `deleteFeatures(Map<String,QName> features, ProtocolBinding binding)`
  Submits a request to delete a collection of features specified by identifier and type name.
  `int`
  `deleteStoredQuery(String queryId)`
  Submits a request to delete a stored query.
  `(package private) Document`
  `executeTransaction(Document request, ProtocolBinding binding)`
  Executes a WFS transaction.
  `ProtocolBinding`
  `getAnyTransactionBinding()`
  Returns a protocol binding suitable for transaction requests.
  `Document`
  `getCapabilities()`
  Retrieves a complete representation of the capabilities document from the WFS implementation described by the service metadata.
  `jakarta.ws.rs.client.Client`
  `getClient()`
  Returns the underlying JAX-RS client.
  `jakarta.ws.rs.core.Response`
  `getFeature(Source reqEntity, ProtocolBinding binding)`
  Submits a GetFeature request.
  `Document`
  `getFeatureByType(QName typeName, int count, ProtocolBinding binding)`
  Retrieves feature representations by type name.
  `jakarta.ws.rs.core.Response`
  `GetFeatureVersion(ResourceId rid, QName typeName)`
  Submits a request to retrieve one or more feature versions as specified by the given resource identifier.
  `Document`
  `getServiceDescription()`
  Returns the WFS service description set for this client.
  `Document`
  `insert(List<Element> features, ProtocolBinding binding)`
  Submits a request to insert a collection of GML feature instances.
  `Document`
  `invokeStoredQuery(String queryId, Map<String,Object> params)`
  Invokes a stored query using any supported protocol binding (request encoding).
  `List<String>`
  `listStoredQueries()`
  Requests a list of stored queries.
  `(package private) Document`
  `retrieveXMLResponseEntity(Document request, ProtocolBinding binding)`
  Submits the given request entity and returns the response entity as a DOM Document.
  `void`
  `setServiceDescription(InputStream srvMetadata)`
  Sets the service description obtained using the given InputStream.
  `jakarta.ws.rs.core.Response`
  `submitRequest(Source entity, ProtocolBinding binding, URI endpoint)`
  Submits an HTTP request message.
  `jakarta.ws.rs.core.Response`
  `submitRequest(Document reqEntity, ProtocolBinding binding)`
  Submits a request using the specified message binding and the content of the given XML request entity.
  `Document`
  `updateFeature(String id, QName featureType, Map<String,Object> properties)`
  Submits a request to update a feature using the POST protocol binding.
  `Document`
  `updateFeature(Document req, String id, QName featureType, Map<String,Object> properties, ProtocolBinding binding)`
  Submits a request to update a feature.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### client

    protected jakarta.ws.rs.client.Client client

  - ### wfsMetadata

    protected Document wfsMetadata
    A Document that describes the service under test.

  - ### globalBindings

    protected Set<ProtocolBinding> globalBindings
    The set of message bindings broadly implemented by the SUT.

  - ### featureTypes

    protected List<QName> featureTypes
    The list of feature types recognized by the SUT.

- ## Constructor Details

  - ### WFSClient

    public WFSClient()
    Default client constructor. The client is configured to consume SOAP message entities. The request and response may be logged to a default JDK logger (in the namespace "com.sun.jersey.api.client"). TODO

  - ### WFSClient

    public WFSClient(Document wfsMetadata)
    Constructs a client that is aware of the capabilities of a WFS implementation.
    Parameters:
      `wfsMetadata` - A service description (e.g. WFS capabilities document).

- ## Method Details

  - ### getServiceDescription

    public Document getServiceDescription()
    Returns the WFS service description set for this client.
    Returns:
      A WFS capabilities document (wfs:WFS_Capabilities).

  - ### getClient

    public jakarta.ws.rs.client.Client getClient()
    Returns the underlying JAX-RS client.
    Returns:
      A JAX-RS client component.

  - ### setServiceDescription

    public void setServiceDescription(InputStream srvMetadata) throws SAXException, IOException
    Sets the service description obtained using the given InputStream. The standard description is an XML representation of a WFS capabilities document.
    Parameters:
      `srvMetadata` - An InputStream supplying the service metadata.
    Throws:
      `SAXException` - If any I/O errors occur.
      `IOException` - If any parsing errors occur.

  - ### invokeStoredQuery

    public Document invokeStoredQuery(String queryId, Map<String,Object> params)
    Invokes a stored query using any supported protocol binding (request encoding).
    Parameters:
      `queryId` - A stored query identifier.
      `params` - A collection of query parameters distinguished by name (may be empty, e.g. Collections.<String, Object>.emptyMap() ).
    Returns:
      A Document representing the XML response entity, or `null` if the response doesn't contain one.

  - ### getFeatureByType

    public Document getFeatureByType(QName typeName, int count, ProtocolBinding binding)
    Retrieves feature representations by type name.
    Parameters:
      `typeName` - A QName denoting the feature type.
      `count` - The maximum number of features to fetch (> 0). If count < 1, the default value (10) applies.
      `binding` - The ProtocolBinding to use for this request; if `null` a global binding will be used.
    Returns:
      A Document representing the XML response entity, or `null` if the response doesn't contain one.

  - ### getFeature

    public jakarta.ws.rs.core.Response getFeature(Source reqEntity, ProtocolBinding binding)
    Submits a GetFeature request.
    Parameters:
      `reqEntity` - A Source representing the content of the request entity; if necessary it will be transformed into the query component of a GET request.
      `binding` - The HTTP method binding to use.
    Returns:
      A client response context.

  - ### deleteFeatures

    public Document deleteFeatures(Map<String,QName> features, ProtocolBinding binding)
    Submits a request to delete a collection of features specified by identifier and type name.
    Parameters:
      `features` - A Map containing entries that specify a feature by identifier (gml:id attribute value) and type name (QName).
      `binding` - The ProtocolBinding to use.
    Returns:
      A Document representing the XML response entity, or `null` if the response doesn't contain one.

  - ### deleteFeature

    public jakarta.ws.rs.core.Response deleteFeature(Document reqEntity, String id, QName typeName)
    Submits a request to delete a feature. A wfs:Delete element is appended to the given transaction request entity.
    Parameters:
      `reqEntity` - A WFS transaction request entity (wfs:Transaction).
      `id` - A feature identifier.
      `typeName` - The type name of the feature.
    Returns:
      A representation of the HTTP response.

  - ### GetFeatureVersion

    public jakarta.ws.rs.core.Response GetFeatureVersion(ResourceId rid, QName typeName)
    Submits a request to retrieve one or more feature versions as specified by the given resource identifier.
    Parameters:
      `rid` - A resource identifier that selects members of the version chain to which this identified version belongs.
      `typeName` - The name of a feature type.
    Returns:
      The (JAX-RS) client response message.

  - ### insert

    public Document insert(List<Element> features, ProtocolBinding binding)
    Submits a request to insert a collection of GML feature instances.
    Parameters:
      `features` - A List<Element> containing one or more feature representations.
      `binding` - The ProtocolBinding to use.
    Returns:
      A Document representing the XML response entity, or `null` if the response doesn't contain one.

  - ### updateFeature

    public Document updateFeature(String id, QName featureType, Map<String,Object> properties)
    Submits a request to update a feature using the POST protocol binding.
    Parameters:
      `id` - A feature identifier.
      `featureType` - The qualified name of the feature type.
      `properties` - A Map containing the feature properties to be updated.
    Returns:
      A Document representing the XML response entity.
    See Also:
      - `updateFeature(Document, String, QName, Map, ProtocolBinding)`

  - ### updateFeature

    public Document updateFeature(Document req, String id, QName featureType, Map<String,Object> properties, ProtocolBinding binding)
    Submits a request to update a feature.
    Parameters:
      `req` - An empty wfs:Transaction request entity.
      `id` - The GML identifier of the feature to be updated (gml:id attribute).
      `featureType` - The type of the feature instance.
      `properties` - A Map containing the feature properties to be updated (replaced). Each entry consists of a value reference (an XPath expression) and a value object. The value may be a Node representing a complex property value; otherwise it is treated as a simple value by calling the object's toString() method.
      `binding` - The ProtocolBinding to use.
    Returns:
      A Document representing the XML response entity, or `null` if the response doesn't contain one.

  - ### submitRequest

    public jakarta.ws.rs.core.Response submitRequest(Source entity, ProtocolBinding binding, URI endpoint)
    Submits an HTTP request message. For GET requests the XML request entity is serialized to its corresponding KVP string format and added to the query component of the Request-URI. For SOAP requests that adhere to the "Request-Response" message exchange pattern, the outbound message entity is a SOAP envelope containing the standard XML request in the body.
    Parameters:
      `entity` - An XML representation of the request entity.
      `binding` - The `ProtocolBinding` to use.
      `endpoint` - The service endpoint.
    Returns:
      A Response object representing the response message.

  - ### submitRequest

    public jakarta.ws.rs.core.Response submitRequest(Document reqEntity, ProtocolBinding binding)
    Submits a request using the specified message binding and the content of the given XML request entity.
    Parameters:
      `reqEntity` - A DOM Document representing the content of the request message.
      `binding` - The ProtocolBinding to use; may be `ProtocolBinding.ANY` if any supported binding can be used.
    Returns:
      A Response object representing the response message.

  - ### getCapabilities

    public Document getCapabilities()
    Retrieves a complete representation of the capabilities document from the WFS implementation described by the service metadata. The `acceptVersions` parameter is omitted, so the response shall reflect the latest version supported by the SUT.
    Returns:
      A Document containing the response to a GetCapabilities request, or `null` if one could not be obtained.

  - ### getAnyTransactionBinding

    public ProtocolBinding getAnyTransactionBinding()
    Returns a protocol binding suitable for transaction requests. Any binding advertised in the service capabilities document is returned.
    Returns:
      A supported ProtocolBinding instance (POST or SOAP).

  - ### executeTransaction

    Document executeTransaction(Document request, ProtocolBinding binding)
    Executes a WFS transaction.
    Parameters:
      `request` - A Document node representing a wfs:Transaction request entity.
      `binding` - The ProtocolBinding to use
    Returns:
      A Document node representing the response entity.

  - ### retrieveXMLResponseEntity

    Document retrieveXMLResponseEntity(Document request, ProtocolBinding binding)
    Submits the given request entity and returns the response entity as a DOM Document.
    Parameters:
      `request` - An XML representation of the request entity; the actual request depends on the message binding in use.
      `binding` - The ProtocolBinding to use (GET, POST, or SOAP).
    Returns:
      A DOM Document containing the response entity, or `null` if the request failed or the message body could not be parsed.

  - ### deleteStoredQuery

    public int deleteStoredQuery(String queryId)
    Submits a request to delete a stored query.
    Parameters:
      `queryId` - A URI value that identifies the query to be dropped.
    Returns:
      The HTTP status code.

  - ### listStoredQueries

    public List<String> listStoredQueries()
    Requests a list of stored queries.
    Returns:
      A list of query identifiers.