7.4.1. Basic functionality

7.4.1.1. WFS operations

The OGC WFS 2.0 interface defines eleven operations that can be invoked by a client. A WFS server is not required to offer all operations to conform to the standard but may support a subset only. The following table lists all WFS 2.0 operations and marks those supported by the 3D City Database WFS.

Table 7.8 Overview of supported WFS 2.0 operations
Operation
Description
Supported
GetCapabilities
The GetCapabilities operation generates a service metadata document describing the WFS service provided by a server.
X
DescribeFeatureType
The DescribeFeatureType operation returns a schema description of the CityGML feature types offered by the WFS instance.
X
GetFeature
The GetFeature operation returns a selection of CityGML features from the 3D City Database using a query expression.
X
GetPropertyValue
The GetPropertyValue operation allows the value of a feature property or part of the value of a complex feature property to be retrieved from the 3D City Database for a set of features identified using a query expression.
X
ListStoredQueries
The ListStoredQueries operation lists the stored queries available at the server.
X
DescribeStoredQuery
The DescribeStoredQueries operation provides detailed metadata about each stored query expression that the server offers.
X
CreateStoredQuery
A stored query may be created using the CreateStoredQuery operation.
X
DropStoredQuery
The DropStoredQuery operation allows previously created stored queries to be dropped from the system.
X
Transaction
The Transaction operation is used to describe data transformation operations (i.e., insert, update, replace, delete) to be applied to CityGML feature instances under the control of the web feature service.
LockFeature
The LockFeature operation is used to expose a long-term feature locking mechanism to ensure consistency in data manipulation operations (e.g., update or delete).
GetFeatureWithLock
The GetFeatureWithLock operation is functionally similar to the GetFeature operation except that in response to a GetFeatureWithLock operation, the WFS shall also lock the features in the result set.

7.4.1.2. Service URL

The service URL or service endpoint is the location where the 3D City Database WFS can be accessed by a client application over a local network or the internet. This URL is typically composed as follows:

http[s]://[host][:port]/[context_path]/wfs

The actual URL depends on the servlet container and your network configuration. Please ask your network administrator for the protocol (typically http or https), the host name and the port of the server. The context path is typically added to the URL by the servlet container. Please refer to the documentation of your servlet container for more information. The last component wfs of the URL identifies the service and makes sure that requests are routed to the WFS service implementation.

Note

For Apache Tomcat, the name of the WFS WAR file will be used as context path in the service URL. For example, if the WAR file is named citydb-wfs.war, then the service URL will be http[s]://[host][:port]/citydb-wfs/wfs. To pick a different context path, simply rename the WAR file or change Tomcat’s default behavior.

7.4.1.3. Service bindings

A service binding refers to the communication protocol that shall be used for exchanging request and response messages between a WFS server and a client. The WFS 2.0 interface standard defines HTTP GET, HTTP POST and SOAP over HTTP POST as possible service bindings for WFS 2.0 implementations.

The 3D City Database WFS implements both the HTTP POST and the HTTP GET conformance class. Therefore, a client can choose to send a request either XML-encoded using the HTTP method POST (using text/xml as content type) or KVP-encoded (key-value-pair) using the HTTP method GET. Use the config.xml to determine which method the WFS server should support (see Section 7.3.3).

Note

The WFS specification does not define a KVP encoding for all operations. These operations must therefore be XML-encoded and sent to the server through HTTP POST. Also note that the XML content of POST messages sent to the server must be well-formed and valid with respect to the WFS 2.0 XML Schema

The following table summarizes the operations and the supported service binding as offered by the 3D City Database WFS.

Table 7.9 Service bindings for the supported WFS 2.0 operations.
Operation
Service Binding
GetCapabilities
XML over HTTP POST and KVP over HTTP GET
DescribeFeatureType
XML over HTTP POST and KVP over HTTP GET
GetFeature
XML over HTTP POST and KVP over HTTP GET
GetPropertyValue
XML over HTTP POST and KVP over HTTP GET
ListStoredQueries
XML over HTTP POST and KVP over HTTP GET
DescribeStoredQuery
XML over HTTP POST and KVP over HTTP GET
CreateStoredQuery
XML over HTTP POST
DropStoredQuery
XML over HTTP POST and KVP over HTTP GET

7.4.1.4. CityGML feature types

The 3D City Database WFS supports all CityGML top-level feature types, and corresponding feature instances will be sent to the client upon request. If you just want to advertise a subset of the CityGML feature types, you can restrict the feature types in the config.xml settings (cf. Section 7.3.2). In addition to the predefined CityGML feature types, the WFS can also support feature types defined in a CityGML ADE. This requires a corresponding ADE extension to be installed for the WFS and to be registered with the 3DCityDB instance (cf. Section 7.2).

The supported CityGML feature types together with their official XML namespaces (CityGML version 2.0 and 1.0) and recommended prefixes are listed in the table below.

Table 7.10 Supported CityGML top-level feature types with XML namespaces and prefixes.
Feature type
XML namespace
XML prefix
Building
bldg
Bridge
brid
Tunnel
tun
TransportationComplex
tran
Road
tran
Track
tran
Road
tran
Square
tren
Railway
tran
CityFurniture
frn
LandUse
luse
WaterBody
wtr
PlantCover
veg
SolitaryVegetationObject
veg
ReliefFeature
dem
GenericCityObject
gen
CityObjectGroup
grp

Simply declare the above namespaces in XML-encoded requests using the notation xmlns:prefix=namspace_uri and use the feature type name to request corresponding features from the WFS. If you pick a CityGML 2.0 namespace, the response will be encoded in CityGML 2.0. If you rather want the response to be encoded in CityGML 1.0, choose a CityGML 1.0 namespace instead. Remember to list the CityGML versions to be supported by the WFS in the config.xml file (see Section 7.3.2).

For KVP-encoded requests, the NAMESPACES parameter must be used to declare namespaces and their prefixes used in the request based on the format xmlns(prefix, escaped_uri).

Note

The 3DCityDB WFS automatically supports the default CityGML prefixes in KVP-encoded requests. Thus, if you pick one of the default prefixes from the list above, you do not have to use the NAMESPACES parameter.

The CityGML version that will be associated with the prefix depends on the default CityGML version in your config.xml (cf. Section 7.3.2). If you want to request a specific version instead, you can append a “1” for CityGML 1.0 and a “2” for CityGML 2.0 to the prefix. For example, use the prefix bldg2 to request features in CityGML 2.0. If you do not want to rely on these predefined prefixes, you can always use the NAMESPACES parameter instead

7.4.1.5. Exception reports

If the WFS encounters an error while parsing or processing a request, an XML document indicating that error is generated and sent to the client as exception response. Please refer to the WFS 2.0 specification for the structure and syntax of the exception response.