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.
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.
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.
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.