How a GetFeature request works

This documentation is no longer maintained. Please see the new GeoServer documentation at http://docs.geoserver.org

How a Get Feature Requests Works

This page will describe how a getFeature() request works in Geoserver. It will also show you how to set up Eclipse and use the debugger to run through a getFeature() request yourself.

There are three bodies to a getFeature() request:

  1. DataSet
  2. Request
  3. Response

DataSet

A dataset is the data that will be read by the getFeature() request. It is what makes up our maps.

Here is an example of a PostGIS database (or a shapefile) with the following data in it:

tiger_ny=# select state_name,state_abbr,persons::int4,families::int4,houshold::int4,male::int4,
           female::int4, geometrytype(the_geom) as the_geom from states_postgis;
  state_name   | state_abbr | persons  | families | houshold |  male   | female  |   the_geom
---------------+------------+----------+----------+----------+---------+---------+--------------
 Iowa          | IA         |  2776755 |   740819 |  1064325 | 1344802 | 1431953 | MULTIPOLYGON ...
 Massachusetts | MA         |  6016425 |  1514746 |  2247110 | 2888745 | 3127680 | MULTIPOLYGON ...
 Nebraska      | NE         |  1578385 |   415427 |   602363 |  769439 |  808946 | MULTIPOLYGON ...
 New York      | NY         | 18235907 |  4548344 |  6746555 | 8739138 | 9496769 | MULTIPOLYGON ...

 Pennsylvania  | PA         | 11881643 |  3155989 |  4495966 | 5694265 | 6187378 | MULTIPOLYGON ...
 Connecticut   | CT         |  3287116 |   864493 |  1230479 | 1592873 | 1694243 | MULTIPOLYGON ...
 Rhode Island  | RI         |  1003464 |   258886 |   377977 |  481496 |  521968 | MULTIPOLYGON ...
 New Jersey    | NJ         |  7484736 |  1962314 |  2687478 | 3622220 | 3862516 | MULTIPOLYGON ...
 Indiana       | IN         |  5544159 |  1480351 |  2065355 | 2688281 | 2855878 | MULTIPOLYGON ...
 Nevada        | NV         |  1201833 |   307400 |   466297 |  611880 |  589953 | MULTIPOLYGON ...
...
In Reality

Geoserver ships with a USA states shapefile that has all the above data in it. It also contains more columns than the above, but I've simplified it for easier reading. You can put the Geoserver "states" shapefile in PostGIS, using the shp2pgsql program that comes with PostGIS, and use a PostGIS datastore instead.

NOTE: This discussion is pretty much the same for any datastore (ie. with oracle, shapefiles, DB2, SDE, etc...).

In the above example of the data, a Feature is one of the rows. For example

Iowa          | IA         |  2776755 |   740819 |  1064325 | 1344802 | 1431953 | MULTIPOLYGON ...

is a Feature.

A getFeature request will be targetted at the data and will bring back Features in the form of GML.

Request

A request can be sent to Geoserver as a GET or a POST, both are handled similarly.

The getFeature process keeps the distinction between a GET and POST until it hits the FeatureRequest object: org.vfny.geoserver.wfs.requests.FeatureRequest. Once you hit FeatureRequest, the code isn't forked and the request works from one spot, execute(). Read on for more details.

GET and POST

Here is an example HTTP GET request

http://localhost:8080/geoserver/wfs?
request=getfeature&
service=wfs&
version=1.0.0&
typename=states&
filter=<ogc:Filter
xmlns:ogc="http://ogc.org" xmlns:gml="http://www.opengis.net/gml">
<ogc:BBOX>
<ogc:PropertyName>the_geom</ogc:PropertyName>
<gml:Box srsName="http://www.opengis.net/gml/srs/epsg.xml">
<gml:coordinates>-73.99312376470733,40.76203427979042 -73.9239210030026,40.80129519821393</gml:coordinates>
</gml:Box>
</ogc:BBOX>
</ogc:Filter>
Try it

If you have Geoserver set up locally on port 8080, you can enter the above URL and Geoserver will process it.

Try it with this link

 

Here is an example HTTP XML POST request

http://localhost:8080/geoserver/wfs

<wfs:GetFeature service="WFS" version="1.0.0"
  outputFormat="GML2"
  xmlns:topp="http://www.openplans.org/topp"
  xmlns:wfs="http://www.opengis.net/wfs"
  xmlns:ogc="http://www.opengis.net/ogc"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/wfs
                      http://schemas.opengis.net/wfs/1.0.0/WFS-basic.xsd">
  <wfs:Query typeName="topp:states">
    <ogc:Filter>
      <ogc:BBOX>
        <ogc:PropertyName>the_geom</ogc:PropertyName>
        <gml:Box srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">
           <gml:coordinates>
               -73.99312376470733,40.76203427979042 -73.9239210030026,40.80129519821393
           </gml:coordinates>
        </gml:Box>
      </ogc:BBOX>
   </ogc:Filter>
  </wfs:Query>
</wfs:GetFeature>

Exploring the HTTP GET request URL

There are 6 parts to the URL:

  1. The server address - _http://localhost:8080/geoserver/wfs_
  2. The request type - request=getfeature
  3. The service type - service=wfs
  4. The version - version=1.0.0
  5. The type name, also known as the data you are querying - typename=states
  6. The filter used to select exactly what you want from the type

The server address points to where your Geoserver instance is running. In this example, on the local machine on port 8080.

The request type is the command that you are sending to the server. In this case the URL is asking "get me some features". There are other commands that can be sent:

  • GetFeature (the case we are analyzing)
  • Transaction
  • LockFeature
  • GetFeatureWithLock
  • GetFeatureInfo
  • GetCapabilities

Service type tells the server what service mode you want. Here we want [WFS]. Another possible service is [WMS].

Version number of what?

The type name is the FeatureType that you are querying, also known as the data. In our example, a shapefile that contains US states.

The filter is a restriction on our query. It pretty much says "restrict my query to only features in this bounding box". There are many filters you can use, but we will not explore them in this tutorial. Here is the sleep inducing OGC Filter specification if you really want to learn more.

How Geoserver interperets the request

Here is the overview of the program flow, in a bit of an abstract view.

Entry Point

When the request comes in, the servlet container (ie. jetty or tomcat) will send the request to the WfsDispatcher. This is the entry point for Geoserver to process the results.

You can set up where this entry point is by changing your web.xml file. Located in %GEOSERVER_HOME%/server/geoserver/WEB-INF

Here is the part of the xml file that we want:

<servlet-name>WfsDispatcher</servlet-name>
    <servlet-class>org.vfny.geoserver.wfs.servlets.WfsDispatcher</servlet-class>
  </servlet>
...
 <servlet-mapping>
    <servlet-name>WfsDispatcher</servlet-name>
    <url-pattern>/wfs/*</url-pattern>
  </servlet-mapping>

This says that any request to "wfs/*" will get routed to the org.vfny.geoserver.wfs.servlets.WfsDispatcher servlet. Since both our requests (GET and POST) are to "http://localhost:8080/geoserver/wfs", the servlet container (ie. jetty or tomcat) will send the request to the WfsDispatcher.

WFS Dispatcher

There are two main methods in WfsDispatcher.java (located in org.vfny.geoserver.wfs.servlets):

public void doPost(HttpServletRequest request, HttpServletResponse response)
        throws ServletException, IOException

public void doGet(HttpServletRequest request, HttpServletResponse response)
        throws ServletException, IOException

If you send an HTTP POST request, doPost gets called. If you send an HTTP GET request, doGet gets called. Get it?

POST
Since one cannot read the POST portion of a HTTP request more than once, a copy of the request is written to disk. This is done in WfsDispatcher.doPost().

NOTE: This is somewhat inefficient, but we originally done this way because very large feature insert requests can be very large. Holding the request in memory would not be scalable. A better (and faster) solution would be to have a simple class that would either hold a small request in memory or, if the request is large, write it to disk.

DispatcherXMLReader will then use SAX to parse the XML. It looks at the first tag in the XML request (see DispatchHandler) and can determine the request type from that. In our case (see above), its "<wfs:GetFeature>" so we know this is a Dispatcher.GET_FEATURE_REQUEST request.

GET
This case is very easy - it just looks at the request url for the "request=GetFeature". You can see that in WfsDispatcher.doGet() and DispatcherKvpReader.

NOTE: "Kvp" means "Key-Value Pair". For the clause "request=GetFeature", the Key is "request" and the value is "GetFeature".

Whether it was an HTTP GET or POST, the WfsDispatcher will create an appropriate servelet. Remember the 6 different request types: GetFeature, Transaction, LockFeature, GetFeatureWithLock, GetFeatureInfo, GetCapabilities? For 'GetFeature' it will create a Feature servelet: org.vfny.geoserver.wfs.servlets.Feature

The GET or POST request information is then passed to that servelet, along with a response object that the servelet will populate. The response will be described later in the response section.

Note

You might be wondering why a request goes through the (WFS) Dispatcher and then through a second (GetFeature) servlet.

If you look at the web.xml (the file the servlet container uses for configuration), you'll see these lines:

<servlet>
    <servlet-name>GetFeature</servlet-name>
    <servlet-class>org.vfny.geoserver.wfs.servlets.Feature</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>GetFeature</servlet-name>
    <url-pattern>/wfs/GetFeature/*</url-pattern>
  </servlet-mapping>

This means you can actually send your GetFeature request directly to the GetFeature servlet instead indirectly through the WFS dispatcher. Most people (and software) find it easier to just send all your requests to one URL instead of each request to a specific servlet. Geoserver lets you do either.

http://localhost:8080/geoserver/wfs/GetFeature

The diagram below shows where the distinction between GET and POST ends:

Not every object or class in the above diagram recognizes the difference, web.xml for example, but it is more to show the life of the GET and POST distinction.

Feature Servelet

The next stage of the getFeature request creates a FeatureRequest object and populates it with the query information.

Depending on whether a GET or a POST was used, different parsers are selected.

The two parsers are GetFeatureKvpReader, for HTTP GET, and GetFeatureXMLReader, for HTTP POST. These will then create the FeatureRequest object.

The FeatureRequest object will then head over to the feature type that was specified in the URL, in this example "states", and query the data.

Response

Added by dblasby, last edited by Mike Pumphrey on Jul 23, 2008  (view change)

Comments ( Hide )

Jody Garnett says:

Rock on Dave - really nice level of detail. In the vwfs documentation there are some UML process diagrams that go through some of these issues. You may want to grab the diagrams.

Aug 16, 2005 14:49 ( Permalink )
View • Attachments (7) • Info