GeoServer User Manual

Release 1.7.4

GeoServer

April 28, 2009

Contents

Introduction 1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Getting Involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation 2.1 Installing Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Installing GeoServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 Upgrading GeoServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Started 3.1 Web Administration Interface Quickstart 3.2 Adding a Shapele . . . . . . . . . . . . . 3.3 Adding a PostGIS Table . . . . . . . . . . 3.4 Styling a Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 3 4 7 7 9 11 15 15 18 23 29 33 33 37 37 41 41 42 43 67 73 73 75 78 78 81 85 88

GeoServer Data Directory 4.1 Introduction to the Data Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Creating a New Data Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Setting the Data Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web Administration Interface 5.1 Interface basics . . . . . . 5.2 Admin menu . . . . . . . 5.3 Cong menu . . . . . . . 5.4 Demo menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Working with Data 6.1 Shapele . . . . . . . . . . . . . . . . . . 6.2 PostGIS . . . . . . . . . . . . . . . . . . 6.3 Directory . . . . . . . . . . . . . . . . . 6.4 External Web Feature Server . . . . . . 6.5 ArcSDE . . . . . . . . . . . . . . . . . . 6.6 Geographic Markup Language (GML) . 6.7 MySQL . . . . . . . . . . . . . . . . . .

6.8 6.9 6.10 6.11 6.12 7

Oracle . . . . . . . . . . . . . Oracle Next Generation . . . SQL Server . . . . . . . . . . Vector Product Format . . . . Database Connection Pooling

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. 89 . 94 . 96 . 99 . 100 103 103 105 131

Styling 7.1 Introduction to SLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 SLD Cook Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3 SLD Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Services 139 8.1 Web Feature Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 8.2 Web Map Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 8.3 Web Coverage Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Security 9.1 Accessing secured resources 9.2 Users and roles . . . . . . . . 9.3 Service-level security . . . . . 9.4 Layer-level security . . . . . 9.5 Disabling security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 153 153 154 155 157 159 159 160 161 162 165 165 165 169 191 191 201 201 202 202 204 204 207 207 207 207 207 222 222 223

10 Caching with GeoWebCache 10.1 Setup . . . . . . . . . . . 10.2 Using GeoWebCache . . 10.3 Demo page . . . . . . . 10.4 Seeding and refreshing 11 Google Earth 11.1 Overview . . 11.2 Quickstart . . 11.3 KML Styling 11.4 Tutorials . . . 11.5 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12 Running In A Production Environment 12.1 Java Considerations . . . . . . . . 12.2 Container Considerations . . . . . 12.3 Conguration Considerations . . 12.4 Data Considerations . . . . . . . . 12.5 Other Considerations . . . . . . . 13 Extensions 13.1 GeoSearch . . . 13.2 Imagemap . . . 13.3 OGR Output . 13.4 REST . . . . . . 13.5 GeoExt Styler . 13.6 WFS Versioning 14 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15 Frequently Asked Questions 225 15.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

ii

15.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 15.3 Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 15.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 16 Advanced GeoServer Conguration 227 16.1 WMS Decorations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

iii

iv

GeoServer User Manual, Release 1.7.4

GeoServer is a open source software server written in Java that allows users to share and edit geospatial data. Designed for interoperability, it publishes data from any major spatial data source using open standards. Being a community-driven project, GeoServer is developed, tested, and supported by a diverse group of individuals and organizations from around the world. GeoServer is the reference implementation of the Open Geospatial Consortium (OGC) Web Feature Service (WFS) and Web Coverage Service (WCS) standards, as well as a high performance certied compliant Web Map Service (WMS). GeoServer forms a core component of the Geospatial Web.

Contents

GeoServer User Manual, Release 1.7.4

Contents

CHAPTER 1

Introduction

Welcome to the GeoServer User Guide. This document is a comprehensive guide to all aspects of using GeoServer. Targeting all users this document covers topics from initial installation to advanced features. For those who wish to get started with GeoServer right away can skip to the Installation section. For those who want more information about just what GeoServer is and what it can do for you can continue on to the Overview section. Thanks for choosing GeoServer!

1.1 Overview
GeoServer is an open source software server written in Java that allows users to share and edit geospatial data. Designed for interoperability, it publishes data from any major spatial data source using open standards. Being a community-driven project, GeoServer is developed, tested, and supported by a diverse group of individuals and organizations from around the world. GeoServer is the reference implementation of the Open Geospatial Consortium (OGC) Web Feature Service (WFS) and Web Map Service (WMS) standards. GeoServer forms a core component of the Geospatial Web.

1.1.1 History
GeoServer was started in 2001 by The Open Planning Project (TOPP), a non-prot technology incubator based in New York. TOPP was creating a suite a tools to enable open democracy and to help make government more transparent. The rst of these was GeoServer, which came out of a recognition that a suite of tools to enable citizen involvement in government and urban planning would be greatly enhanced by the ability to share spatial data. The GeoServer founders envisioned a Geospatial Web, analogous to the World Wide Web. With the World Wide Web, one can search for and download text. With the Geospatial Web, one can search for and download spatial data. Data providers would be able to publish their data straight to this web, and users could directly access it, as opposed to the now indirect and cumbersome methods of sharing data that exist today.

GeoServer User Manual, Release 1.7.4

Those involved with GeoServer founded the Geotools project, an open source GIS Java toolkit. Through Geotools, support for Shapeles, Oracle databases, ArcSDE integration, and much more was added. Around the same time as GeoServer was founded, The OpenGIS Consortium (now the Open Geospatial Consortium) was working on the Web Feature Service standard. It species a protocol to make spatial data directly available on the web, using GML (Geographic Markup Language), an interoperable data format. A Web Map Service was also created, a protocol for creating and displaying map images created from spatial data. Other projects became interrelated. Refractions Research created PostGIS, a free and open spatial database, which enabled GeoServer to connect to a free database. Also, MetaCarta created OpenLayers, an open source browser-based map viewing utility. Together, these tools are all have enhanced the functionality of GeoServer. GeoServer can now output data to many other spatial data viewers, such as Google Earth, a popular 3-D virtual globe. In addition, GeoServer is currently working directly with Google in order to allow GeoServer data to be searchable on Google Maps. Soon a search for spatial data will be as easy as a Google search for a web page. Thus GeoServer is continuing on its mission to make spatial data more accessible to all.

1.1.2 License
GeoServer is licensed under the GNU General Public License.

1.2 Getting Involved

There are many ways that one can help out with the GeoServer project. GeoServer fully embraces an open source development model that does not see a split between user and developer, producer and consumer, but instead sees everyone as a valuable resource in a collaborative quest to build something better than any of us could alone.

1.2.1 Development
Helping to develop GeoServer is the obvious way to help out. Developers usually start with bug xes and small patches, and then move into larger contributions as they learn the system. Our developers are more than happy to help out as you learn and get acquainted, and we try our hardest to keep our code clean and well documented.

1.2.2 Documentation
One of the best and most needed ways to help out is with documentation. Our ofcial documentation is contained as part of our ofcial code repository in order to maintain a uniform look and feel to our documentation. However, we also maintain a wiki, where any and all users can post their own documentation, tips and tricks, and any other information that is useful to GeoServer. Like code contributions, if the GeoServer Project Steering Committee deems that user-contributed documentation is a valuable addition to the ofcial documentation base, it will be added.

1.2.3 Mailing lists

GeoServer maintains two email lists: GeoServer Users and GeoServer Developers. These lists are publicly available and are a great resource for those who are new to GeoServer, who need a question answered, or

Chapter 1. Introduction

GeoServer User Manual, Release 1.7.4

who are interested in contributing code. The Users list is mainly for those who have questions relating to the use of GeoServer, and the Developers list is for more code-specic and roadmap-based discussions. If you see a question asked on these lists that you know the answer to, please respond!

1.2.4 IRC
GeoServer has an IRC channel, #geoserver, on the Freenode network. GeoServer developers frequent this channel, and so it is a great way to give and receive information in real time.

1.2.5 Bug tracking

If you have a problem when working with GeoServer, then please let us know through the mailing lists. GeoServer uses JIRA , a bug tracking website, to manage code. As GeoServer is open source, everyone is encouraged to x bugs and submit patches. Even if you are not a core developer, you can still submit a patch through JIRA, and a developer will assess the patch and apply it to the code.

1.2.6 Translation
We would like GeoServer available in as many languages as possible, just as we want spatial data to be available to all. The two areas of GeoServer to translate are the text for the Web Administration Tool and this documentation. Eventually we would even like to set up GeoServer community sites in different languages, if you are interested in this please let us know.

1.2.7 Suggest improvements

If you have suggestions as to how we can make GeoServer better, we would love to hear them. You can contact us through the mailing lists or in IRC.

1.2.8 Spread the word

A further way to help out the GeoServer project is to spread the word about it. Word of mouth information sharing is more powerful than any amount spent on marketing, adn the more people who use our software, the better it will become.

1.2.9 Fund improvements

A nal way to help out is to push for GeoServer to be used in your own organization. A number of commerical organizations offer support for GeoServer, and any improvements made due to that funding will benet the entire project.

1.2. Getting Involved

GeoServer User Manual, Release 1.7.4

Chapter 1. Introduction

CHAPTER 2

Installation

GeoServer is written in Java, and requires a Java Development Kit (JDK) installed on a system in order to run. The JDK is different from a Java Runtime Evnironment (JRE), which is what is most often installed on systems. The following pages explain how to install Java, and then to install GeoServer. Specic instructions are also given for upgrading a pre-existing GeoServer instance. If a Java JDK is already installed on the system you can jump ahead to the Installing GeoServer section. Otherwise continue on to the next section, Installing Java.

2.1 Installing Java

The instructions for installing a Java Development Kit (JDK) are dependent on your operating system. Please follow the instructions below for your operating system.

2.1.1 Windows
1. Visit the Sun Java downloads page. The most recent version of Java is Java 1.6 (which is also known as Java 6). Choose the Java SE Development Kit (JDK) 6 ... option. 2. Choose the appropriate platform, Windows or Windows x64, and proceed with the download. 3. Run the installer accepting the defaults.

GeoServer User Manual, Release 1.7.4

Warning: If a Java Runtime Environment (JRE) is already installed on the system it may be desirable to disable the JRE that comes with the JDK. This can be done on the Custom Setup screen of the installer.

Chapter 2. Installation

GeoServer User Manual, Release 1.7.4

1. Create a new environment variable named JAVA_HOME and set it to the location of the JDK installed in the previous step.

2.1.2 Linux
Warning: Many Linux distributions come with a JDK pre installed. While theoretically GeoServer will run on any Java virtual machine it is strongly recommended that a Sun virtual machine is used.

2.1.3 Mac OS X
On Mac OS X systems Apple provides a JDK so no installation is necessary.

2.2 Installing GeoServer

GeoServer installation can take one of two forms: 1. Web Archive (WAR) mode inside of an external servlet container such as Tomcat 2. Standalone mode inside of an embedded Jetty container 2.2. Installing GeoServer 9

GeoServer User Manual, Release 1.7.4

Instructions for the WAR mode can be found in the Web Archive section. Instructions for the Standalone mode are dependent on operating system. Following the instructions for below for the target platform.

2.2.1 Windows
1. Visit http://geoserver.org/display/GEOS/Stable. 2. Choose the Windows Installer option and proceed with the download. 3. Run the installer accepting the defaults. Warning: If you receive the following dialect while running the installer:

It means one of two things. Either: 1. A Java JDK is not installed on the system or 2. The JAVA_HOME environment variable is not set properly Proceed to the Installing Java section for instructions. 1. Start GeoServer by navigating from the Start Menu to Programs -> GeoServer 1.7.0 -> Start GeoServer. 2. Visit http://localhost:8080/geoserver in a web browser.

2.2.2 Linux
1. Visit http://geoserver.org/display/GEOS/Stable. 2. Choose the Binary Package option and proceed with the download. 3. From the command line unzip the archive:
% unzip geoserver-1.7.0-bin.zip

4. Start GeoServer by changing directory to geoserver-1.7.0/bin and executing the startup.sh script:
% cd geoserver-1.7.0/bin % sh startup.sh

5. Visit http://localhost:8080/geoserver in a web browser.

2.2.3 Mac OS X
As of 1.7.0 we should have a dmg installer. Update the docs.

10

Chapter 2. Installation

GeoServer User Manual, Release 1.7.4

2.2.4 Web Archive

1. Visit http://geoserver.org/display/GEOS/Stable. 2. Choose the Web Archive option and proceed with the download. 3. Extract the le geoserver.war le from the downloaded archive. 4. Deploy geoserver.war inside the servlet container. 5. Visit http://localhost:8080/geoserver in a web browser. Note: Replace port 8080 with whatever port the servlet container is congured to listen on.

2.2.5 Post installation

At this point GeoServer should be up and running but it is strongly recommend that some post-install conguration is carried out. Data directory By default GeoServer is congured to run of an internal data directory. To ensure a smooth upgrade path when installing new versions of GeoServer it is recommended that an external data directory is set up. Proceed to the next section: GeoServer Data Directory. Server performance By default GeoServer is not congured for optimal performance. If GeoServer is being run in a production environment in which maximal performance is necessary it is recommended that the default conguration be changed based on Running In A Production Environment.

2.3 Upgrading GeoServer

2.3.1 Performing a minor upgrade
A minor GeoServer upgrade occurs when moving to a newer version of GeoServer that has a different patch number. For example moving from GeoServer 1.7.0 to 1.7.1, or moving from 1.7.0 to 1.7.4, etc... For all upgrades it is strongly recommended that GeoServer is running with an external data directory. See the :ref: section. Warning: It is strongly recommend that the GeoServer data directory is backed up before performing any upgrade.

Standalone upgrade Note: This section applies if GeoServer is being run in Standalone mode and not inside of a servlet container.

2.3. Upgrading GeoServer

11

GeoServer User Manual, Release 1.7.4

If GeoServer is congured to run with an external data directory and the GEOSERVER_DATA_DIR is set appropriately, then upgrading only involves installing the new GeoServer version. The new version will recognize the envioronment variable and run accordingly. If GeoServer is congured to run with an internal data directory then the data directory from the old installation must be copied and overwrite the data directory from the new installation:
% ls geoserver-1.7.0 geoserver-1.7.1 % rm -rf geoserver-1.7.1/data_dir % cp -R geoserver-1.7.0/data_dir geoserver-1.7.1

Web Archive upgrade Note: This section applies if GeoServer is being run in Web Archive mode inside of a servlet container or application server. Upgrading GeoServer inside of a servlet container is specic to the container being run. The instructions below describe the generic process but it is important to review the servlet container documentation regarding web application upgrades. If GeoServer is congured to run with an external data directory: 1. Undeploy the old GeoServer version. 2. Deploy the new GeoServer version. If the web application uses the GEOSERVER_DATA_DIR context parameter in the web.xml le to locate the directory then perform the following additional steps: 1. Edit web.xml, and point the GEOSERVER_DATA_DIR context parameter to the location of the data directory. 2. Restart the GeoServer web application. This step may be unnecessary if the servlet container supports automatic reloading upon le modication. If GeoServer is congured to run with an internal data directory: Warning: Undeploying the web application will delete the data directory. You must copy the data directory to a location external to the web application. 1. Backup the data directory. 2. Undeploy the old geoserver version. 3. Deploy the new geoserver version. 4. Copy the backed up data directory into the web application root over-writting the existing directory. 5. Restart the web application. Example:
% cp -R /opt/tomcat5/webapps/geoserver/data /backups <<undeploy old version>> <<deploy new version>> % rm -rf /opt/tomcat5/webapps/geoserver/data % cp -R /backups/data /opt/tomcat5/webapps/geoserver <<restart web application>>

12

Chapter 2. Installation

GeoServer User Manual, Release 1.7.4

2.3.2 Performing a major upgrade

A minor GeoServer upgrade occurs when moving to a newer version of GeoServer that has a different minor number. For example moving from GeoServer 1.6.0 to 1.7.0, or moving from 1.5.5 to 1.7.1, etc... Performing a major upgrade is the same process as performing a minor upgrade with an additional step. To perform a full upgrade: 1. Follow the steps in the previous section: Performing a minor upgrade. 2. Stop GeoServer. 3. Remove the Geotools directory from the operating system temporary le system storage. Note: On Windows systems this directory is C:\Documents and Settings\<user>\Local Settings\Temp. On Linux and Mac OS systems this directory is usually /tmp. 4. Restart GeoServer.

2.3. Upgrading GeoServer

13

GeoServer User Manual, Release 1.7.4

14

Chapter 2. Installation

CHAPTER 3

Getting Started

This section of the user guide contains a number of tutorials designed to get new GeoServer users performing common tasks quickly and easily.

3.1 Web Administration Interface Quickstart

The Web Administration Tool is a web based used to congure all aspects of GeoServer, from adding data to tweaking service settings. The web admin tool is accessed via web browser at http://<host>:<port>/geoserver. http://localhost:8080/geoserver in a default installation running on the local host.

15

GeoServer User Manual, Release 1.7.4

3.1.1 Logging in
In order to change any server settings a user must rst be authenticated. Any time the user navigates to Config from the main page authentication will take place.

Note: The default adminstrator username is admin, and the default password is geoserver. To change these defaults see the :ref: section.

3.1.2 Submit-Apply-Save workow

Making a change to server conguration with the web admin tool follows a three phase process: 1. Submit the page.

At this point the change has been sent to the server, but not applied to the GeoServer instance. 2. Apply the change.

16

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

Once the change has been applied it is live. However if GeoServer is shutdown the change will not persist. 3. Save the change.

Saving persists all applied changes to disk so that the change is realized on subsequent GeoServer startups.

3.1.3 Map Preview

The map preview tool provides a built-in OpenLayers map for each layer being published by a GeoServer instance. It can be a useful tool for verifying the conguration of a particular layer, or as a means to explore a layer visually. The map preview tool is found by navigating to the Demo section from the main Welcome page and selecting Map Preview.

3.1. Web Administration Interface Quickstart

17

GeoServer User Manual, Release 1.7.4

3.1.4 Sample request tool

The sample request tool provides a form based interface for executing requests against GeoServer. It can be a useful tool for experimenting with various GET and POST requests. The sample request tool is found by navigating to the Demo section from the main Welcome page and selecting Sample Requests.

As well as allowing the user to specify request, the sample request tool also provides a set of pre-canned requests. These requests originate from the demo directory inside of the GeoServer data directory.

3.2 Adding a Shapele

This tutorial walks through the steps of publishing a Shapele with GeoServer. Note: This tutorial assumes that GeoServer is running on http://localhost:8080/geoserver.

18

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

3.2.1 Getting started

1. Download the zip le nyc_roads.zip. It contains a shapele with a subset of roads from New York City that will be used during in this tutorial. 2. Unzip nyc_roads.zip into <GEOSERVER_DATA_DIR>/data where GEOSERVER_DATA_DIR is the root of the GeoServer data directory. Unzipping the archive will result in the following four les:
nyc_roads.shp nyc_roads.shx nyc_roads.dbf nyc_roads.prj

3.2.2 Create a new data store

The rst step is to create a data store for the Shapele. The data store tells GeoServer how the shapele should be loaded, in particular where it is located. 1. In a web browser navigate to http://localhost:8080/geoserver. 2. Navigate to Config->Data->DataStores.

3. Create a new data store by clicking the New link.

3.2. Adding a Shapele

19

GeoServer User Manual, Release 1.7.4

4. Select Shapefile from the drop down and enter nyc_roads_shapele in the text eld. Then click the New button.

5. Specify the Shapele location by entering file:data/nyc_roads.shp in the url text eld. Then click the Submit button.

6. Click the Apply button located in the upper left hand corner of the page.

20

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

3.2.3 Congure the feature type

The next step is to congure the feature type for the Shapele. The feature type tells GeoServer how the shapele should be published. 1. Set the style by selecting line from the Style drop down list.

2. Generate the bounds by clicking the Generate button. 3. Scroll to the bottom of the and click the Submit button. 4. Finalize changes by clicking the Apply button in the upper left hand corner of the page.

3.2. Adding a Shapele

21

GeoServer User Manual, Release 1.7.4

22

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

3.2.4 Preview the Layer

The nal step is to verify that the Shapele has been published properly. To do this Map Preview will be used. Navigate to the map preview and select the topp:nyc_roads link.

If the shapele was added properly the result should be an OpenLayers map:

3.3 Adding a PostGIS Table

This tutorial walks through the steps of publishing a PostGIS table with GeoServer. Note: This tutorial assumes that GeoServer is running on http://localhost:8080/geoserver. Note: This tutorial assumes PostGIS has been previously installed on the system.

3.3.1 Getting started

1. Download the zip le nyc_buildings.zip. It contains a PostGIS dump of a subset of buildings from New York City that will be used during in this tutorial. 2. Create a PostGIS database called nyc. This can be done with the following command line:

3.3. Adding a PostGIS Table

23

GeoServer User Manual, Release 1.7.4

24

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

createdb -T template_postgis nyc

If the PostGIS install is not set up with the postgis_template then the following sequence of commands will perform the equivalent:
...

3. Unzip nyc_buildings.zip to some location on the le system. nyc_buildings.sql. 4. Import nyc_buildings.sql into the nyc database:
psql -f nyc_buildings.sql nyc

This will result in the le

3.3.2 Create a new data store

The rst step is to create a data store for the PostGIS database nyc. The data store tells GeoServer how to connect to the database. 1. In a web browser navigate to http://localhost:8080/geoserver. 2. Navigate to Config->Data->DataStores.

3. Create a new data store by clicking the New link. 4. Select PostGIS from the drop down and enter nyc_postgis in the text eld. Then click the New button. 5. Specify the PostGIS database connection parameters: host port schema database localhost 5432 public nyc

Warning: The username and password parameters specic to the user who created the postgis database. Depending on how PostgreSQL is congured the password parameter may be unnecessary. 6. Click the Submit button. 7. Click the Apply button located in the upper left hand corner of the page.

3.3. Adding a PostGIS Table

25

GeoServer User Manual, Release 1.7.4

26

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

3.3. Adding a PostGIS Table

27

GeoServer User Manual, Release 1.7.4

3.3.3 Create a new feature type

The next step is to congure the feature type for the nyc_buildings table. The feature type tells GeoServer how the table should be published. 1. Set the style by selecting polygon from the Style drop down list.

2. Generate the bounds by clicking the Generate button.

3. Scroll to the bottom of the and click the Submit button. 4. Finalize changes by clicking the Apply button in the upper left hand corner of the page.

28

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

3.3.4 Preview the layer

The nal step is to verify that the table has been published properly. To do this Map Preview will be used. Navigate to the map preview and select the topp:nyc_buildings link.

If the table was added properly the result should be an OpenLayers map:

3.4 Styling a Map

When a new dataset is added to GeoServer the layer for it is usually assigned a very basic style. To properly visualize the data a style specic to that data must be created. 3.4. Styling a Map 29

GeoServer User Manual, Release 1.7.4

30

Chapter 3. Getting Started

GeoServer User Manual, Release 1.7.4

This tutorial walks through the steps to create a new style in GeoServer and provides an introduction to the Styled Layer Descriptor (SLD) styling language. Note: It is assumed that the tutorials Adding a Shapele and Adding a PostGIS Table have been completed.

3.4.1 Getting started

Before continuing with this tutorial it is strongly recommended that the section Introduction to SLD be rst read.

3.4.2 Creating a new style

3.4. Styling a Map

31

GeoServer User Manual, Release 1.7.4

32

Chapter 3. Getting Started

CHAPTER 4

GeoServer Data Directory

The GeoServer data directory is the location on the le system where GeoServer stores all of its conguration. This conguration denes such things as: What data is served by GeoServer? Where is that data is located? How should services such as WFS and WMS interact with and server that data? And more. The data directory also contains a number of support les used by GeoServer for various purposes. To learn more about the structure of the GeoServer data directory continue onto the Introduction to the Data Directory section. Or to learn how to create a directory for a GeoServer installation jump to the Creating a New Data Directory section.

4.1 Introduction to the Data Directory

The following gure shows the structure of a vanilla GeoServer data directory:
data_directory/ catalog.xml services.xml coverages/ data/ demo/ featureTypes/ palettes/ plugIns/ security/ styles/ templates/ user_projections/ www/

4.1.1 catalog.xml and services.xml

The catalog.xml le contains a list of all the data sources that GeoServer is congured to serve. It contains references to shapeles, PostGIS databases, GeoTIFF les, and many other types of data. The catalog le also contains other information such as a set of namespaces used by the WFS, and a set of SLD styles used by the WMS. catalog.xml is a XML le which has the following format: 33

GeoServer User Manual, Release 1.7.4

<catalog> <datastores> ... </datastores> <formats> ... </formats> <namespaces> ... </namespaces> <styles> ... </styles> </catalog>

The services.xml le contains all service level conguration. Among many things this validation options for the WFS, image rendering parameters for the WMS, etc... The services le contains an entry for each service published by GeoServer. This currently includes a WMS, WFS, and WCS entry. services.xml is a XML le which has the following format:
<services> <service type="WMS"> .. </service> <service type="WFS"> .. </service> <service type="WCS"> .. </service> </services>

4.1.2 coverages and featureTypes

The coverages and featureTypes directories contains metadata about layers which are published by GeoServer. A vector layer corresponds to the featureTypes directory, and a raster layer corresponds to the coverages directory. The term layer refers to both types. For each layer published by GeoServer a sub-directory is created under the coverages or featureTypes directory, depending on if the layer is raster or vector based. The following gure shows the contains of the two respective directories from the data directory of a vanilla GeoServer installation:
coverages/ arc_sample/ img_sample/ img_sample2_Pk50095/ mosaic_sample/ sfDem_dem/ featureTypes/ DS_giant_polygon_giant_polygon/

34

Chapter 4. GeoServer Data Directory

GeoServer User Manual, Release 1.7.4

DS_poi_poi/ DS_poly_landmarks_poly_landmarks/ DS_tiger_roads_tiger_roads/ sfArchsites_archsites/ sfBugsites_bugsites/ sfRestricted_restricted/ sfRoads_roads/ sfStreams_streams/ states/ tasmania_cities/ tasmania_roads/ tasmania_state_boundaries/ tasmania_water_bodies/

Each sub-directory contains a le named info.xml which contains metadata about the layer. Such metadata includes: The spatial reference system or projection of the dataset The spatial extent of the dataset The default style used by the WMS when rendering the layer TODO: document info.xml in more detail TODO: write a todo role extension :)

4.1.3 data
Not to the confused with the GeoServer data directory itself, the data directory is a location where actual data can be stored. This directly is commonly used to store shapeles and raster les but can be used for any data that is le based. The main benet of storing data les inside of the data directory is portability. Consider a shapele located external to the data directory at a location C:\gis_data\foo.shp. The datastore entry in catalog.xml for this shapele would like the following:
<datastore id="foo_shapefile"> <connectionParams> <parameter name="url" value="file://C:/gis_data/foo.shp" /> </connectionParams> </datastore>

Now consider trying to port this data directory to another host running GeoServer. The problem exists in that the location C:\gis_data\foo.shp probably does not exist on the second host. So either the le must be copied to the new host, or catalog.xml must be changed to reect a new location. Such steps can be avoided by storing foo.shp inside of the data directory. In such a case the datastore entry in catalog.xml becomes:
<datastore id="foo_shapefile"> <connectionParams> <parameter name="url" value="file:data/foo.shp"/> </connectionParams> </datastore>

The value attribute is re-written to be relative. In this way the entire data directory can be archived, copied to the new host, un-archived, and used directly with no additional changes.

4.1. Introduction to the Data Directory

35

GeoServer User Manual, Release 1.7.4

4.1.4 demo
The demo directory contains les which dene the sample requests available in the Sample Request Tool (http://localhost:8080/geoserver/demoRequest.do). For more information see the Sample request tool section for more information.

4.1.5 palettes
The palettes directory is used to store pre-computed Image Palettes. Image palettes are used by the GeoServer WMS as way to reduce the size of produced images while maintaining image quality.

4.1.6 security
The security directory contains all the les used to congure the GeoServer security subsystem. This includes a set of property les which dene access roles, along with the services and data each role is authorized to access. See the Security section for more information.

4.1.7 styles
The styles directory contains a number of Styled Layer Descriptor (SLD) les which contain styling information used by the GeoServer WMS. For each le in this directory there is a corresponding entry in catalog.xml:
<style id="point_style" file="default_point.sld"/>

See the Styling for more information about styling and SLD .

4.1.8 templates
The template directory contains les used by the GeoServer templating subsystem. Templates are used to customize the output of various GeoServer operations.

4.1.9 user_projections
The user_projections directory contains a single le called epsg.properties which is used to dene custom spatial reference systems which are not part of the ofcial EPSG database.

4.1.10 www
The www directory is used to allow GeoServer to act like a regular web server and serve regular les. While not a replacement for a full blown web server the www directory can be useful for serving OpenLayers map applications.

36

Chapter 4. GeoServer Data Directory

GeoServer User Manual, Release 1.7.4

4.2 Creating a New Data Directory

The easiest way to create a new data directory is to copy one that comes with a standard GeoServer installation. If GeoServer is running in Standalone mode the data directory is located at <installation root>/data_dir. Note: On Windows systems the <installation root> is located at C:\Program Files\GeoServer 1.7.0. If GeoServer is running in Web Archive mode inside of a servlet container, the data directory is located at <web application root>/data. Once the data directory has been found copy it to a new external location. To point a GeoServer instance at the new data directory proceed to the next section Setting the Data Directory.

4.3 Setting the Data Directory

Setting up a GeoServer data directory is dependent on the type of GeoServer installation. Follow the instructions below specic to the target platform.

4.3.1 Windows
On Windows platforms the location of the GeoServer data directory is controlled by the GEOSERVER_DATA_DIR environment variable. Note: When the GEOSERVER_DATA_DIR environment variable is not set, the directory data_dir under the root of the GeoServer installation is used. To set the GEOSERVER_DATA_DIR: On Windows XP systems: 1. From the Desktop or Start Menu right-click the My Computer icon and select Properties. 2. On the resulting dialog select the Advanced tab and click the Environment Variables button. 3. Click the New button and create a environment variable called GEOSERVER_DATA_DIR and set it to the desired location.

4.2. Creating a New Data Directory

37

GeoServer User Manual, Release 1.7.4

On Windows Vista systems:

4.3.2 Linux
On Linux platforms the location of the GeoServer data directory is controlled by the GEOSERVER_DATA_DIR environment variable. Setting the variable can be achieved with the following command (in a bash shell):
% export GEOSERVER_DATA_DIR=/var/lib/geoserver_data

Place the command in the .bash_profile or .bashrc le (again assuming a bash shell). Ensure that this done for the user GeoServer will be run by.

4.3.3 Mac OS X 4.3.4 Web Archive

When running GeoServer inside of a servlet container the data directory can be specied in a number of ways. The recommended method is to set a servlet context parameter. An alternative is to set a Java System Property.

38

Chapter 4. GeoServer Data Directory

GeoServer User Manual, Release 1.7.4

Servlet context parameter Servlet context parameters are specied in the WEB-INF/web.xml le for the GeoServer application:
<web-app> ... <context-param> <param-name>GEOSERVER_DATA_DIR</param-name> <param-value>/var/lib/geoserver_data</param-value> </context-param> ... </web-app>

Java system property Depending on the servlet container used it is also possible to specify the data directory location with a Java System Property. This method can be useful during upgrades, as it prevents the need to set the data directory on every single upgrade. Warning: Using a system property will typically set the property for all applications running in the servlet container, not just GeoServer. Setting the Java System Property is dependent on the servlet container. In Tomcat: Edit the le bin/setclasspath.sh under the root of the Tomcat installation. GEOSERVER_DATA_DIR system property by setting the CATALINA_OPTS variable:
CATALINA_OPTS="-DGEOSERVER_DATA_DIR=/var/lib/geoserver_data"

Specify the

In Glasssh: Edit the le domains/<<domain>>/config/domain.xml under the root of the Glasssh installation, where <<domain>> refers to the domain that the GeoServer web application is deployed under. Add a <jvm-options> inside of the <java-config> element:
... <java-config> ... <jvm-options>-DGEOSERVER_DATA_DIR=/var/lib/geoserver_data</jvm-options> </java-config> ...

4.3. Setting the Data Directory

39

GeoServer User Manual, Release 1.7.4

40

Chapter 4. GeoServer Data Directory

CHAPTER 5

Web Administration Interface

5.1 Interface basics

The Web Administration Interface is a easy-to-use, web-based graphical interface for viewing and conguring GeoServer.

5.1.1 Accessing
By default, GeoServer will start a web server on localhost at port 8080 accessible by the following URL:
http://localhost:8080/geoserver

Note: How to change this? When correctly congured, the welcome page will show up in your browser. Note: Image of main page here

5.1.2 Welcome page

The Welcome page contains lots of information at a glance, in the form of the health bars on the left side of the page. These colored bars will show graphically any miscongurations of the WFS, WMS, and WCS aspects of GeoServer (if applicable). Warning: Add description of what the bar colors mean The welcome page contains many links for through various areas of the GeoServer conguration. There are also externals links to the GeoServer homepage at http://geoserver.org . Handy links are available to the WCS GetCapabilities, WFS GetCapabilities, and WMS GetCapabilities documents. Also, a quick link to the SRS List, a listing of all projections accesible from within GeoServer. The majority of the conguration settings are contained in three menu trees, the Admin menu, Cong menu, and Demo menu.

41

GeoServer User Manual, Release 1.7.4

5.2 Admin menu

The Admin menu contains information about the currently running GeoServer. The information displayed is:

Figure 5.1: Figure 1: The Admin menu Option Locks Connections Memory Version of JVM JAI is available JAI mem capacity JAI mem used JAI mem threshold JAI tile threads JAI tile priority Description

Also available are diagnostic links. Option Free Locks Free Memory Free JAI Memory Description

42

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

5.3 Cong menu

5.3.1 Security and Making Changes
Logging In When rst navigating to the Cong menu, you will be asked to log in. This security measure prevents unauthorized persons from making changes to GeoServer. The default username and password is admin and geoserver. These can be changed only by editing the security/users.properties le in the GeoServer Data Directory.

Figure 5.2: Login screen Enter your username and password in the form, and click Submit. You may also check the box that says Remember my login on this computer in order to prevent having to log in subsequently (although this setting is specic only to the computer, and will not globally affect security). Apply, Save, Load Note: Talk about Apply, Save, Load here!

5.3. Cong menu

43

GeoServer User Manual, Release 1.7.4

Figure 5.3: Cong menu

5.3.2 Server
The Server Conguration page, accessed from the Server link, is where global server settings are made. Option Maximum Features Verbose VerboseExceptions Number of Decimals Character Set Proxy base URL Logging Profile Suppress StdOut logging Log Location JAI mem capacity JAI mem threshold JAI tile threads JAI tile priority JAI cache recycling JAI Image-I/O Caching JAI JPEG native acceleration JAI PNG native acceleration JAI Mosaic operation native acceleration Tile Cache Description

This page also has space for contact information. This information is contained in the capabilities documents and will be publicly accessible. Option Contact Person Organization Position Address Type Address City State/Province Postal Code Country Phone Number Fax Number Email Address

44

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.4: Server Conguration page

5.3. Cong menu

45

GeoServer User Manual, Release 1.7.4

Figure 5.5: Server Conguration page, continued

46

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

5.3.3 WCS
This section is for conguring the Web Coverage Service in GeoServer.

Figure 5.6: WCS Conguration page

Contents The WCS Contents page allows the WCS to be enabled or disabled. When disabled, WCS requests will not be processed. The Online Resource box is a URL which contains information relevant to the WCS.

Figure 5.7: WCS Contents page

Description The WCS Description page is where information about the WCS is populated. This information is publicly available via the WCS capabilities document.

5.3. Cong menu

47

GeoServer User Manual, Release 1.7.4

Figure 5.8: WCS Description page

48

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Option Name Title Access Constraints Fees Maintainer Keywords Abstract CoveragePlugins

Description

The WCS CoveragePlugins page displays a list of all the coverage formats supported in GeoServer. Additional coverage formats can be supported by installing extensions. Please see the section on Working with Data for information on other formats.

Figure 5.9: WCS CoveragePlugins page

5.3.4 WMS
This section is for conguring the Web Map Service in GeoServer. Contents The WMS Contents page allows the WMS to be enabled or disabled. When disabled, WCS requests will not be processed. The Online Resource box is a URL which contains information relevant to the WCS. The Limited Capabilities CRS List is a box listing of the supported spatial reference systems (SRS). GeoServer supports a large amount of SRSs, and a list of them is contained in the WMS capabilities document, which can make the document very long. By default, this box is empty, which means that GeoServer will return all supported SRS. By populating this box, only those specically mentioned in the box will be supported (and contained in the WMS capabilities document).

5.3. Cong menu

49

GeoServer User Manual, Release 1.7.4

Figure 5.10: WMS Conguration page

Figure 5.11: WMS Contents page

50

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

The Base Maps section is where layer groups are congured. Layer groups are collections of WMS layers that can be conveniently referenced as one. The page displays a list of currently congured layer groups. The conguration options for each layer group are: Option Layer-group Name Base Map Layers Base Map Styles SRS Envelope Description The name of the layer group. A list of layers comprising the layer group, separated by commas. The style used for the layer group. If blank, the layers will use their default congured styles. The projection to use for the layer group. The bounding box for the layer group. Enter coordinates, or click the GEnerate button to automatically generate them.

To create a new layer group, click the Add New Layer-Group button. Description The WMS Description page is the area where information about the WMS is populated. This information is publicly available via the WFS capabilities document. Option Name Title Access Constraints Fees Maintainer Keywords Abstract Rendering The WMS Rendering page has various options for how to generate WMS tiles. The SVG Rendering option does WHAT. The Interpolation does WHAT. The other options concern watermarking. CONTINUE. Note: Obviously, the info above needs to be eshed out. Description

5.3.5 WFS
This section is for conguring the Web Feature Service in GeoServer. Contents The WFS Contents page allows for conguration of the WFS. The WFS can be enabled or disabled here. When disabled, WFS requests will not be processed. There are three other checkboxes: srsName as XML which does WHAT, Strict CITE Test Conformance, which does WHAT, and Generate feature bounds which does WHAT. The Service Level determines WHAT. The Online Resource box is a URL which contains information relevant to the WFS.

5.3. Cong menu

51

GeoServer User Manual, Release 1.7.4

Figure 5.12: WMS Description page

52

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.13: WMS Rendering page

Figure 5.14: WFS Conguration page

5.3. Cong menu

53

GeoServer User Manual, Release 1.7.4

Note: Fill in descriptions of the above, obviously.

Figure 5.15: WFS Contents page

Description The WFS Description page is the area where information about the WFS is populated. This information is publicly available via the WFS capabilities document. Option Name Title Access Constraints Fees Maintainer Keywords Abstract Validation Note: Description on Validation Note: More screenshots of Validation needed Description

54

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.16: WFS Description page

5.3. Cong menu

55

GeoServer User Manual, Release 1.7.4

Figure 5.17: WFS Validation page

5.3.6 Data
This section is for conguring your data. The majority of conguration of GeoServer is done in this section. Namespace A namespace is a container which is used to organize other items such as datastores and featuretypes. In GeoServer, a namespace is often used to group similar layers together. Layers are often referred to by their namespace, a colon, and the featuretype. (Ex: topp:states) Two different featuretypes having the same name can exist as long as they are in different namespaces. (Ex: ns1:mylayer, ns2:mylayer) On this page, you can register a new namespace, edit (congure) an existing namespace, or delete (unregister) a namespace. You can also set the default namespace.

New
The New page allows new namespaces to be created. Enter a name, and click Submit to edit the new namespace.

Edit
The Edit page allows new or existing namespaces to be congured. Enter a URI (Uniform Resource Indicator). This is a unique identier, often just a URL. Each namespace must have a unique URI. You can can this value for Prex, but it is usually left to be the same as the name of the namespace.

56

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.18: Namespace Conguration page

Figure 5.19: New Namespace page

5.3. Cong menu

57

GeoServer User Manual, Release 1.7.4

Figure 5.20: Edit Namespace page Coveragestores A coveragestore is a le or group of les that contain one or more coverages (raster data). It is necessary to register a coveragestore in GeoServer before any coverages from that coveragestore can be loaded.

Figure 5.21: Coveragestore Conguration page On this page, you can register a new coveragestore, edit (congure) an existing coveragestore, or delete (unregister) a coveragestore.

New
The New page is where new coveragestores are loaded. Select an option under Coverage Data Set Description and name the coveragestore in the box entitled Coverage Data Set ID. Click Submit to continue. The next page will congure the coveragestore. The exact contents of this page will depend on the specic format chosen, so please see the section on Working with Data for information on specic data formats.

58

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Note: GeoServer supports many formats natively, but many more can be added through extensions. Please see the section on Working with Data for information on specic data formats.

Figure 5.22: New Coveragestore page

Edit
The Edit page is where existing coveragestores can be congured. The exact contents of this page will depend on the specic format chosen, so please see the section on Working with Data for information on specic data formats. Datastores A datastore is a le, group of les, or database that contains featuretypes (vector data). It is necessary to register a datastore in GeoServer before any featuretypes can be loaded. On this page, you can register a new datastore, edit (congure) an existing datastore, or delete (unregister) a datastore.

New
The New page is where new datastores are loaded. Select an option under Feature Data Set Description and name the datastore in the box entitled Feature Data Set ID. Click Submit to continue. The next page will congure the datastore. The exact contents of this page will depend on the specic format chosen, so please see the section on Working with Data for information on specic data formats. Note: GeoServer supports many formats natively, but many more can be added through extensions. Please see the section on Working with Data for information on specic data formats.

Edit
The Edit page is where existing datastores can be congured. The exact contents of this page will depend on the specic format chosen, so please see the section on Working with Data for information on specic data formats. 5.3. Cong menu 59

GeoServer User Manual, Release 1.7.4

Figure 5.23: Edit Coveragestore page

Figure 5.24: Datastore Conguration page

60

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.25: New Datastore page

Figure 5.26: Edit Datastore page

5.3. Cong menu

61

GeoServer User Manual, Release 1.7.4

Style Styles are methods of rendering geospatial data. Styles for GeoServer are written in Styled Layer Descriptor (SLD), a subset of XML. Please see the section on Styling for more information on working with styles.

Figure 5.27: Style Conguration page On this page, you can register or create a new style, edit (congure) an existing style, or delete (unregister) a style.

New
Create a new style here. Enter the name of the style and click New to go to the Edit page.

Figure 5.28: New Style page

62

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Edit
The Edit page presents two options for entering an SLD. There is the option of typing/pasting in SLD code, or selecting and uploading a local le that contains the SLD. There are two checkboxes, one to Fully Validate against the SLD schema and to Toggle Editor. The rst box, when checked, ensures that the code is fully compliant with the SLD schema. The second box toggles between two different text editors in the window. FeatureTypes A featuretype is a data layer that contains geographic features in a vector format. Featuretypes are contained inside datastores, which need to be loaded prior to registering the featuretype. On this page, you can register a new featuretype, edit (congure) an existing featuretype, or delete (unregister) a featuretype.

New
Register a new featuretype on this page. Select an available featuretype from the list, click New and you will be taken to the featuretype Edit page. (If the featuretype in question is not listed, make sure the datastore that contains the featuretype is properly registered.)

Edit
Note: Add description of FT edit here! Coverages A coverage is a data layer that contains geographic data in a raster format. Coverages are within coveragestores, which need to be registered prior to registering the coverage. On this page, you can register a new coverage, edit (congure) an existing coverage, or delete (unregister) a coverage.

New
Register a new coverage on this page. Select an available coverage from the list, click New and you will be taken to the coverage Edit page. (If the coverage in question is not listed, make sure the coveragestore that contains the coverage is properly registered.)

Edit
Note: Add description of Coverage edit here!

5.3. Cong menu

63

GeoServer User Manual, Release 1.7.4

Figure 5.29: Edit Style page

64

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.30: Featuretype Conguration page

Figure 5.31: New Featuretype page

5.3. Cong menu

65

GeoServer User Manual, Release 1.7.4

Figure 5.32: Edit Featuretype page

Figure 5.33: Coverage Conguration page

66

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.34: New Coverage page

5.4 Demo menu

The Demo menu contains helpful links to various demos and information pages regarding GeoServer and its various features.

5.4.1 Map Preview

The Map Preview page is a listing of all registered featuretypes and layer groups congured in GeoServer. The page has quick links to output these layers in various formats. Note: These are not all fo the output formats available through GeoServer. Please see the section on Services for more information on output formats. The output formats accessible from this page are: Option Description OpenLayers Generates a simple OpenLayers application. KML Uses the KML reector to output KML (Keyhole Markup Language). GeoRSS Outputs GeoRSS, a geographic form of an RSS feed. PDF Takes a snapshot of the default WMS output and creates a document in PDF (Portable Document Format). SVG Takes a snapshot of the default WMS output and creates a document in SVG (Scalable Vector Graphics) format. OpenLayers output The OpenLayers output has some advanced lters that are not available when using a standalone version of OpenLayers. The application that is generated contains a header which has options for easy conguration of display. To toggle this menu, click on the icon at the top left of the OpenLayers window. The possible conguration options are:

5.4. Demo menu

67

GeoServer User Manual, Release 1.7.4

Figure 5.35: Edit Coverage page

68

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.36: Demo menu

5.4. Demo menu

69

GeoServer User Manual, Release 1.7.4

Figure 5.37: Map Preview page

70

Chapter 5. Web Administration Interface

GeoServer User Manual, Release 1.7.4

Figure 5.38: OpenLayers demo

Figure 5.39: Customizing the OpenLayers demo application

5.4. Demo menu

71

GeoServer User Manual, Release 1.7.4

Option Tiling

Description Sets whether the window is populated with a single tile (redrawn with every refresh), or as a grid of tiles (refreshed only as necessary). Antialias Sets the antialias of the tiles. Options are Full, Text Only, and Disabled. Format Sets the image format of the tiles. Options are PNG 24bit, PNG 8bit, GIF, and JPEG. Width/Height These values set the width and height of the OpenLayers application window. If set to Auto, the application will determine tha optimal size. Fliter Allows custom queries to run on the dataset. Options are CQL, OGC, and FeatureID. The specic query should be entered in the box next to this eld.

5.4.2 Documentation
This is a link to the online GeoServer documentation. Warning: These demos may change, so this section is unpopulated for now.

5.4.3 Overlay on Google Maps 5.4.4 Sample Requests 5.4.5 WFS-T demo 5.4.6 GeoRSS 5.4.7 WMS Example

72

Chapter 5. Web Administration Interface

CHAPTER 6

Working with Data

This section discusses the various types of data sources that can be accessed from GeoServer.

6.1 Shapele
Note: While GeoServer has good support for the Shapele format, it is not the recommended format of choice in a production environment. Databases such as PostGIS are more suitable in production and offer better performance and scalability.

6.1.1 Adding a Shapele

As with all vector formats, adding a Shapele to GeoServer involves adding a new data store through the web administration tool. This process is described step by step in the Adding a Shapele tutorial.

6.1.2 Shapele options

url create spatial index charset memory mapped buffer The location of the Shapele. See the section below about Relative vs absolute le paths. A ag which indicates if a spatial index should be created for the Shapele. Species the character set to use when reading attribute information from the associated DBF le. A ag which indicates wether memory mapped i/o should be used when reading the shapele.

6.1.3 Relative vs absolute le paths

When specifying the location of a Shapele can be given as an absolute path or a relative path. An absolute le path species the location from the root of the le system. For example:
file:C:\gis_data\shapefiles\my_shapefile.shp

73

GeoServer User Manual, Release 1.7.4

Figure 6.1: Conguring a shapele as a datastore

74

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

A relative le path species the location relative to the root of the GeoServer data directory. For example:
file:data/shapefiles/my_shapefile.shp

6.1.4 Performance considerations 6.1.5 Common problems

6.2 PostGIS
PostGIS is an open source spatial database based on PostgreSQL and is currently the most popular open source spatial database today. PostGIS was developed by Refractions Research.

6.2.1 Adding a PostGIS database

As with all vector formats, adding a PostGIS database to GeoServer involves adding a new data store through the web administration tool. This process is described step by step in the Adding a PostGIS Table tutorial.

6.2.2 PostGIS options

host port schema user password wkb_enabled The database host. The port the database is listening for connections on. The default is 5432 for PostGIS. The database schema to load tables from. The default for PostGIS is the public schema. The name of the user to connect to the database as. The password to use when connecting to the database. Left blank for no password. Species wether Well Known Binary (WKB) or Well Known Text (WKT) should be used when reading and writing geometry objects to and from PostGIS. It is recommended that WKB be used as it is faster and more accurate than WKT. Flag which controls how bounding box comparisons are made against geometries in the database. See the Using loose bounding box section below for more information. Flag affecting how table bounds are calculated. See the Using estimated extent section below. Connection pool conguration parameters. See the Database Connection Pooling section for details.

loose bbox

estimated_extent max connections min connections validate connections

6.2.3 Using loose bounding box

When set only the bounding box of a geometry is used which results in a signicant performance gain. The downside is that some geometries may be considered inside of a bounding box when they are technically not.

6.2. PostGIS

75

GeoServer User Manual, Release 1.7.4

Figure 6.2: Conguring a PostGIS datastore

76

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

If the primary use of the database is through the WMS this ag can be set as a loss of some accuracy is usually acceptable. However if using with the WFS and making use of BBOX ltering capabilities, this ag should not be set.

6.2.4 Using estimated extent

When set GeoServer will make use the PostGIS estimated_extent function when calculating the spatial extent of a table. While setting this ag can result in a serious performance gain caution should be taken when setting it.

6.2.5 Publishing a PostGIS view

Publishing a view follows the same process as publishing a table. The only additional step is to manually ensure that the view has an entry in the geometry_columns table. For example consider a table with the schema:
my_table( id int PRIMARY KEY, name VARCHAR, the_geom GEOMETRY )

Also consider the following view:

CREATE VIEW my_view as SELECT id, the_geom FROM my_table;

Ad this point the table cannot be published by GeoServer. The following step to manually create the geometry_columns entry is necessary:
INSERT INTO geometry_columns VALUES (,public,my_view,my_geom, 2, 4326, POINT );

6.2.6 Performance considerations

GEOS GEOS (Geometry Engine Open Source) is an additional component which optionally can be installed with PostGIS. ... If PostGIS is installed on Windows via the installer it is automatically included. On other platforms like Linux it is optional. It is recommended that GEOS be installed in any PostGIS instance used by GeoServer as GeoServer makes use of its functionality when doing spatial operations like intersections. When GEOS is disabled these operations are performed internally in GeoServer which results in a performance hit. Spatial indexing Creating a spatial index on tables with a spatial component (ie geometry column) is strongly recommended. Any table of non-trivial size which does not have a spatial index will be slow to query spatially. ...

6.2. PostGIS

77

GeoServer User Manual, Release 1.7.4

6.2.7 Common problems

Primary keys The transactional nature of a relational database makes formats such as PostGIS ideal for transactional WFS. However in order to enable the transactional extensions on a table it must have a primary key. Any table without a primary key dened on it is considered as read only.

6.3 Directory
Loading and conguring multiple shapeles can be a very time consuming process. But if your shapeles all exist in one directory, they can be added in as individual datastores simultaneously by using the directory datastore. Note: While GeoServer has good support for the Shapele format, it is not the recommended format of choice in a production environment. Databases such as PostGIS are more suitable in production and offer better performance and scalability.

6.3.1 Adding a directory

Navigate to the new datastore page (Cong > Data > Datastores > New) in the Web Administration Interface. In the drop down list for Feature Data Set Description, select Directory of spatial les. Name this datastore in the eld marked Feature Data Set ID and click New. On the next page, select the namespace to use (this will be used as a prex for each shapele in the directory), a description (if any), and the path to the directory. This should be one level inside the GeoServer data directorys data directory. (Example: file:data/myshpfolder) When done, click Submit. (Apply and Save as you would normally do.) All of the shapeles contained in the directory will be registered, but none of them will be available until they are individually congured (by going to the Create New FeatureType page at Cong > Data > Featuretypes > New).

6.4 External Web Feature Server

6.4.1 Overview
GeoServer has the ability to load data from a remote Web Feature Server (WFS). This is useful if the WFS lacks certain functionality that GeoServer contains. For example, if the WFS is not also a Web Map Server (WMS), data from the WFS can be cascaded through GeoServer to utilize GeoServers WMS. If the remote WFS has a WMS but that WMS cannot output KML, data can be cascaded through GeoServers WMS to output KML.

6.4.2 Adding an external WFS

To connect to an external WFS, it is necessary to load it as a new datastore. Navigate to the Create New Feature Data Set page (Cong -> Data -> Datastore -> New) and an option for Web Feature Server will be in the dropdown menu for Feature Data Set Description. Select this option, enter a name in the box for Feature Data Set ID, and click New.

78

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

Figure 6.3: Creating a new datastore from an external WFS

6.4.3 Web Feature Server options

The next page contains conguration options for connecting to the remote WFS. Fill out the form then click Submit. To apply the changes, click Apply then Save. Option ReDescription quired? Feature Data Set ID N/A The name of the datastore as set on the previous page. Enabled N/A When this box is checked the datastore will be available to GeoServer Namespace Yes The namespace associated with this datastore. Description No A description of this datastore. WFSDataStoreFactory:GET_CAPABILITIES_URL Yes The URL of the GetCapabilities document of the remote WFS. WFSDataStoreFactory:PROTOCOL No (T/F): WFSDataStoreFactory:USERNAME No The username to use for authentication with the WFS. WFSDataStoreFactory:PASSWORD No The password associated with the above username for authentication with the WFS. WFSDataStoreFactory:ENCODING No WFSDataStoreFactory:TIMEOUT No WFSDataStoreFactory:BUFFER_SIZE No WFSDataStoreFactory:TRY_GZIP No (T/F): WFSDataStoreFactory:LENIENT No (T/F): WFSDataStoreFactory:MAXFEATURES No Sets the maximum features for the remote WFS to return. You may now add featuretypes as you would normally do, by navigating to the Create New Feature Type page (Cong -> Data -> Featuretype -> New). Note: Should more info go here, or should this point elsewhere?

6.4. External Web Feature Server

79

GeoServer User Manual, Release 1.7.4

Figure 6.4: Conguring a new datastore from an external WFS

80

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

6.4.4 Performance considerations 6.4.5 Common problems

6.5 ArcSDE
Warning: ArcSDE support is not enabled by default and requires the ArcSDE extension to be installed prior to use. Please see the section on Installing the ArcSDE extension for details. ESRIs ArcSDE is a spatial engine that runs on top of a relational database such as Oracle or SQL Server. GeoServer with the ArcSDE extension supports ArcSDE versions 9.2 and 9.3. It has been tested with Oracle 10g and Microsoft SQL Server 2000 Developer Edition. The ArcSDE extension is based on the GeoTools ArcSDE driver and uses the ESRI Java API libraries. See the GeoTools ArcSDE page for more technical details. There are two types of ArcSDE data that can be added to GeoServer: vector and raster.

6.5.1 Vector support

ArcSDE provides efcient access to vector layers, (featureclasses in ArcSDE jargon), over a number of relational databases. GeoServer can set up featuretypes for registered ArcSDE featureclasses and spatial views. For versioned ArcSDE featureclasses, GeoServer will work on the default database version, for both read and write access. Transactional support is enabled for featureclasses with a properly set primary key, regardless if the featureclass is managed by a user or by ArcSDE. If a featureclass has no primary key set, it will be available as read-only.

6.5.2 Raster support

ArcSDE provides efcient access to multi-band rasters by storing the raw raster data as database blobs, dividing it into tiles and creating a pyramid. It also allows a compression method to be set for the tiled blob data and an interpolation method for the pyramid resampling. All the bands comprising a single ArcSDE raster layer must have the same pixel depth, which can be one of 1, 4, 8, 16, and 32 bits per sample for integral data types. For 8, 16 and 32 bit bands, they may be signed or unsigned. 32 and 64 bit oating point sample types are also supported. ArcSDE rasters may also be color mapped, as long as the raster has a single band of data typed 8 or 16 bit unsigned. Finally, ArcSDE supports raster catalogs. A raster catalog is a mosaic of rasters with the same spectral properties but instead of the mosaic being precomputed, the rasters comprising the catalog are independent and the mosaic work performed by the application at runtime. Technical Detail Compression methods Number of bands Bit depth for color-mapped rasters Raster Catalogs Status LZW, JPEG Any number of bands except for 1 and 4 bit rasters (supported for single-band only). 8 bit and 16 bit Any pixel storage type

6.5. ArcSDE

81

GeoServer User Manual, Release 1.7.4

6.5.3 Installing the ArcSDE extension

Warning: Due to licensing requirements, not all les are included with the extension. To install ArcSDE support, it is necessary to download additional les. Just installing the ArcSDE extension will have no effect.

GeoServer les 1. Download the ArcSDE extension from the GeoServer download page. 2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation. Required external les There are three les required that are not packaged with the GeoServer extension: File Notes jsde_sdk.jar Also known as jsde##_sdk.jar where ## is the version number, such as 92 for ArcSDE version 9.2 jpe_sdk.jar Also known as jpe##_sdk.jar where ## is the version number, such as 92 for ArcSDE version 9.2 icu4j_3_2.jar Only needed for ArcSDE version 9.2 and newer The rst two les can be downloaded from ESRIs website or copied from the ArcSDE installation media. To download the JSDE/JPE JAR les from ESRIs website: 1. Navigate to http://support.esri.com/index.cfm?fa=downloads.patchesServicePacks.listPatches&PID=66 2. Find the link to the latest service pack for your version of ArcSDE 3. Scroll down to Installing this Service Pack -> ArcSDE SDK -> UNIX (regardless of your target OS) 4. Download any of the target les (but be sure to match 32/64 bit to your OS) 5. Open the archive, and extract the appropriate JARs. Note: The JAR les may be in a nested archive inside this archive. To download the third le (icu4j_3_2.jar): 1. Navigate to ftp://ftp.software.ibm.com/software/globalization/icu/icu4j/3.2/ 2. Download the le icu4j_3_2.jar. When downloaded, copy all three les to the WEB-INF/lib directory of the GeoServer installation. After all GeoServer les and external les have been downloaded and copied, restart GeoServer.

6.5.4 Adding an ArcSDE vector datastore

In order to serve vector data layers, it is rst necessary to register the ArcSDE instance as a datastore in GeoServer. Navigate to the Create New Feature Data Set page, accessed in the Datastores page in the Cong menu menu of the Web Administration Interface. (From the Welcome page: Cong -> Data -> Datastore -> New) and an option for ArcSDE will be in the dropdown menu for Feature Data Set Description. Select this option, enter a name in the box for Feature Data Set ID, and click New. Note: If ArcSDE is not an option in the Feature Data Set Description drop down box, the extension is not properly installed. Please see the section on Installing the ArcSDE extension. 82 Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

Figure 6.5: Creating a new ArcSDE datastore

6.5.5 Conguring an ArcSDE vector datastore

The next page contains conguration options for the ArcSDE vector datastore. Fill out the form then click Submit. To apply the changes, click Apply then Save. Option Feature Data Set ID Enabled Namespace Description server port instance user password Required? N/A N/A Yes No Yes Yes No Yes No Description The name of the datastore as set on the previous page. When this box is checked the datastore will be available to GeoServer The namespace associated with the datastore. A description of the datastore. The URL of the ArcSDE instance. The port that the ArcSDE instance is set to listen to. Default is 5151. The name of the specic ArcSDE instance, where applicable, depending on the underlying database. The username to authenticate with the ArcSDE instance. The password associated with the above username for authentication with the ArcSDE instance. Connection pool conguration parameters. See the Database Connection Pooling section for details. Connection pool conguration parameters. See the Database Connection Pooling section for details. Connection pool conguration parameters. See the Database Connection Pooling section for details.

pool.minConnections No pool.maxConnections No pool.timeOut No

You may now add featuretypes as you would normally do, by navigating to the Create New Feature Type page, accessed from the FeatureTypes page in the Cong menu menu of the Web Administration Interface (From the Welcome page: Cong -> Data -> Featuretypse -> New).

6.5.6 Adding an ArcSDE raster coveragestore

In order to serve raster layers (or coverages), it is rst necessary to register the ArcSDE instance as a coveragestore in GeoServer. Navigate to the Create New Coverage Data Set page, accessed from the Coveragestores page in the Cong menu menu of the Web Administration Interface (From the Welcome page: Cong ->

6.5. ArcSDE

83

GeoServer User Manual, Release 1.7.4

Figure 6.6: Conguring a new ArcSDE vector datastore

84

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

Data -> Coveragestores -> New) and an option for ArcSDE Raster Format will be in the dropdown menu for Coverage Data Set Description. Select this option, enter a name in the box for Coverage Data Set ID, and click New. Note: If ArcSDE Raster Format is not an option in the Coverage Data Set Description drop down box, the extension is not properly installed. Please see the section on Installing the ArcSDE extension.

Figure 6.7: Creating a new ArcSDE coveragestore

6.5.7 Conguring an ArcSDE raster coveragestore

The next page contains conguration options for the ArcSDE instance. Fill out the form then click Submit. To apply the changes, click Apply then Save. Option Coverage Data Set ID Enabled Namespace Type URL Description Required? N/A N/A Yes No Yes No Description The name of the coveragestore as set on the previous page. When this box is checked the coveragestore will be available to GeoServer. The namespace associated with the coveragestore. The type of coveragestore. Leave this to say ArcSDE Raster. The URL of the raster, of the form sde://<user>:<pwd>@<server>/#<tableName>. A description of the coveragestore.

You may now add coverages as you would normally do, by navigating to the Create New Coverage Type page, accessed from the Coverages page in the Cong menu menu of the Web Administration Interface (From the Welcome page: Cong -> Data -> Coverages -> New).

6.6 Geographic Markup Language (GML)

Geographic Markup Language (GML) is a XML based format for representing vector based spatial data. Note: GeoServer does not come built-in with support for GML, it must be installed through an extension. Proceed to Installing the GML extension for installation details. 6.6. Geographic Markup Language (GML) 85

GeoServer User Manual, Release 1.7.4

Figure 6.8: Conguring a new ArcSDE raster coveragestore

86

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

Warning: Currently the GML extension is unmaintained and carries unsupported status. While still usable, do not expect the same reliability as with other drivers.

6.6.1 Supported versions

Currently GML version 2 is supported.

6.6.2 Installing the GML extension

1. Download the GML extension from the GeoServer download page. Warning: loaded. Ensure the extension matching the version of the GeoServer installation is down-

2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation.

6.6.3 Adding a GML le

Once the extension is properly installed GML will show up as an option when creating a new data store.

Figure 6.9: Creating a GML datastore

6.6.4 GML options

url The location of the GML le.

6.6. Geographic Markup Language (GML)

87

GeoServer User Manual, Release 1.7.4

Figure 6.10: Conguring a GML datastore

6.7 MySQL
MySQL is an open source relational database with some limited spatial functionality. Note: GeoServer does not come built-in with support for MySQL, it must be installed through an extension. Proceed to Installing the MySQL extension for installation details. Warning: Currently the MySQL extension is unmaintained and carries unsupported status. While still usable, do not expect the same reliability as with other drivers.

6.7.1 Installing the MySQL extension

1. Download the MySQL extension from the GeoServer download page. Warning: loaded. Ensure the extension matching the version of the GeoServer installation is down-

2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation.

6.7.2 Adding a MySQL database

Once the extension is properly installed MySQL will show up as an option when creating a new datastore.

88

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

Figure 6.11: Creating a MySQL datastore

6.7.3 MySQL options

host port database user password max connections min connections validate connections The mysql server host name or ip address. The port on which the mysql server is accepting connections. The name of the database to connect to. The name of the user to connect to the mysql database as. The password to use when connecting to the database. Left blank for no password. Connection pool conguration parameters. See the Database Connection Pooling section for details.

6.8 Oracle
Oracle Spatial and Locator are the spatial extensions of Oracle. Note: GeoServer does not come built-in with support for Oracle, it must be installed through an extension. Proceed to Installing the Oracle extension for installation details.

6.8.1 Supported versions 6.8.2 Installing the Oracle extension

1. Download the Oracle extension from the GeoServer download page. Warning: loaded. Ensure the extension matching the version of the GeoServer installation is down-

2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation.

6.8. Oracle

89

GeoServer User Manual, Release 1.7.4

Figure 6.12: Conguring a MySQL datastore

90

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

6.8.3 Oracle Call Interface (OCI)

A connection can be established in one of two ways. The standard way to connect to oracle is with the JDBC driver, a completely portable Java library that runs as a thin client on any computer. This is the recommended way to establish an oracle connection.. An alternative is to establish an OCI (Oracle Call Interface) connection. This requires the OCI drivers to be installed on the same machine as the GeoServer instance is running on. Connecting with OCI has the benet of increased performance.

6.8.4 Adding an Oracle database

Once the extension is properly installed Oracle and Oracle OCI will show up as a options when creating a new data store.

Figure 6.13: Creating an Oracle datastore

6.8.5 Oracle options

host port user password instance schema max connections min connections validate connections The oracle server host name or ip address. The port on which the oracle server is accepting connections. The name of the user to connect to the oracle database as. The password to use when connecting to the database. Left blank for no password. The name of the oracle instance being connected to. The database schema to access tables from. Connection pool conguration parameters. See the Database Connection Pooling section for details.

6.8. Oracle

91

GeoServer User Manual, Release 1.7.4

Figure 6.14: Conguring an Oracle datastore

92

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

Figure 6.15: Conguring Oracle OCI options

6.8. Oracle

93

GeoServer User Manual, Release 1.7.4

6.8.6 Oracle OCI options

alias user password schema The name of the user to connect to the oracle database as. The password to use when connecting to the database. Left blank for no password. The database schema to access tables from.

6.9 Oracle Next Generation

Oracle Spatial and Locator are the spatial extensions of Oracle. Note: GeoServer does not come built-in with support for Oracle, it must be installed through an extension. Proceed to Installing the Oracle extension for installation details.

6.9.1 Supported versions 6.9.2 Installing the Oracle NG extension

1. Download the Oracle NG extension from the GeoServer download page. Warning: loaded. Ensure the extension matching the version of the GeoServer installation is down-

2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation.

6.9.3 Adding an Oracle database

Once the extension is properly installed OracleNG will show up as an option when creating a new data store.

Figure 6.16: Creating an Oracle datastore

94

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

6.9.4 Oracle options

Figure 6.17: Conguring an Oracle datastore

6.9. Oracle Next Generation

95

GeoServer User Manual, Release 1.7.4

host port database schema user password Loose bbox

max connections min connections validate connections

The oracle server host name or ip address. The port on which the oracle server is accepting connections. The name of the database to connect to. The database schema to access tables from. The name of the user to connect to the oracle database as. The password to use when connecting to the database. Left blank for no password. Flag which controls how bounding box comparisons are made against geometries in the database. See the Using loose bounding box section below for more information. Connection pool conguration parameters. See the Database Connection Pooling section for details.

6.9.5 Using loose bounding box

When set only the bounding box of a geometry is used which results in a signicant performance gain. The downside is that some geometries may be considered inside of a bounding box when they are technically not. If the primary use of the database is through the WMS this ag can be set as a loss of some accuracy is usually acceptable. However if using with the WFS and making use of BBOX ltering capabilities, this ag should not be set.

6.10 SQL Server

Microsofts SQL Server <http://www.microsoft.com/sqlserver/2008/> is a relational database with spatial functionality. Note: GeoServer does not come built-in with support for SQL Server, it must be installed through an extension. Proceed to Installing the SQL Server extension for installation details.

6.10.1 Supported versions

The extension supports SQL Server 2008.

6.10.2 Installing the SQL Server extension

1. Download the SQL Server extension from the GeoServer download page. Warning: loaded. Ensure the extension matching the version of the GeoServer installation is down-

2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation. SQL Server JDBC driver 1. Navigate to JDBC driver download page. 2. Click the Download SQL Server 2005 JDBC Driver 1.2 link.

96

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

3. Click the Download button. # Accept the license and choose the operating system. # Extract the contents of the archive and copy the le sqljdbc.jar to the WEB-INF/lib directory of the GeoServer instance.

6.10.3 Adding a SQL Server database

Once the extension is properly installed SQL Server will show up as an option when creating a new data store.

Figure 6.18: Creating a SQL Server datastore

6.10.4 SQL Server options

host The sql server instance host name or ip address. port The port on which the sql server instance is accepting connections. database The name of the database to connect to. schema The database schema to access tables from. user The name of the user to connect to the oracle database as. password The password to use when connecting to the database. Left blank for no password.

6.10. SQL Server

97

GeoServer User Manual, Release 1.7.4

Figure 6.19: Conguring a SQL Server datastore

98

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

max connections min connections Connection pool conguration parameters. See the Database Connection Pooling section for details.

6.11 Vector Product Format

Vector Product Format (VPF) is a military standard for vector-based digital map products produced by the U.S. Department of Defense. For more information visit The National Geospatial-Intelligence Agency. Note: GeoServer does not come built-in with support for VPF, it must be installed through an extension. Proceed to Installing the VPF extension for installation details.

6.11.1 Installing the VPF extension

1. Download the VPF extension from the GeoServer download page. Warning: loaded. Ensure the extension matching the version of the GeoServer installation is down-

2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation.

6.11.2 Adding a VPF le

Once the extension is properly installed Vector Product Format Library will show up as an option when creating a new data store.

Figure 6.20: Creating a VPF datastore

6.11. Vector Product Format

99

GeoServer User Manual, Release 1.7.4

Figure 6.21: Conguring a VPF datastore

6.11.3 VPF options

url The location of the VPF le.

6.12 Database Connection Pooling

When serving data from a spatial database connection pooling is an important aspect of achieving good performance. When GeoServer serves a request that involves loading data from a database table, a connection must rst be established with the database. This connection comes with a cost as it takes time to set up such a connection. The purpose served by a connection pool is to maintain connection to an underlying database between requests. The benet of which is that connection setup only need to occur once on the rst request. Subsequent requests use existing connections and achieve a performance benet as a result. Whenever a data store backed by a database is added to GeoServer an internal connection pool is created. This connection pool is congurable.

100

Chapter 6. Working with Data

GeoServer User Manual, Release 1.7.4

Figure 6.22: Connection options

6.12.1 Connection pool options

max connections The maximum number of connections the pool can hold. When the maximum number of connections is exceeded, additional requests that require a database connection will be halted until a connection from the pool becomes available. The maximum number of connections limits the number of concurrent requests that can be made against the database. The minimum number of connections the pool will hold. This number of connections is held even when there are no active requests. When this number of connections is exceeded due to serving requests additional connections are opened until the pool reaches its maximum size (described above). Flag indicating wether connections from the pool should be validated before they are used. A connection in the pool can become invalid for a number of reasons including network breakdown, database server timeout, etc... The benet of setting this ag is that an invalid connection will never be used which can prevent client errors. The downside of setting the ag is that a performance penalty is paid in order to validate connections.

min connections

validate connections

6.12. Database Connection Pooling

101

GeoServer User Manual, Release 1.7.4

102

Chapter 6. Working with Data

CHAPTER 7

Styling

7.1 Introduction to SLD

Geospatial data has no intrinsic visual component. In order to see data, it must be styled, and given color, thickness, and other visible attributes. In GeoServer, this styling is accomplished using a markup language called Styled Layer Descriptor, or SLD for short. SLD is an XML-based markup language and is very powerful, though it can be intimidating. This page will give a basic introduction to what one can do with SLD and how GeoServer handles it. Note: Since GeoServer uses SLD exclusively for styling, the terms SLD and style will often be used interchangeably.

7.1.1 Types of styling

Data that GeoServer can serve consists of three classes of shapes: Points, lines, and polygons. Lines (one dimensional shapes) are the simplest, as they have only the edge to style (also known as stroke). Polygons, two dimensional shapes, have an edge and an inside (also known as a ll), both of which can be styled differently. Points, even though they lack dimension, have both an edge and a ll (not to mention a size) that can be styled. For lls, color can be specied; for strokes, color and thickness can be specied. More advanced styling is possible than just color and thickness. Points can be specied with well-known shapes like circles, squares, stars, and even custom graphics or text. Lines can be styled with a dash styles and hashes. Polygons can be lled with a custom tiled graphics. Styles can be based on attributes in the data, so that certain features are styled differently. Text labels on features are possible as well. Features can be styled based on zoom level, with the size of the feature determining how it is displayed. The possibilities are vast.

7.1.2 Style metadata 7.1.3 GeoServer and SLD

Every layer (featuretype) registered with GeoServer needs to have at least one style associated with it. GeoServer comes bundled with a few basic styles, and any number of new styles can be added. It is possible to change any layers associated style at any time in the featuretype edit page. (From the Web Administration Interface: Cong menu > Data) When adding a layer and a style to GeoServer at the same

103

GeoServer User Manual, Release 1.7.4

time, the style should be added rst, so that the new layer can be associated with the style immediately. You can add a style in the Style menu. (From the Web Administration Interface : Cong menu > Data)

7.1.4 Denitions
Symbolizer Rule FeatureTypeStyle

7.1.5 A basic style

This SLD takes a layer that contains points, and styles them as red circles with a size of 6 pixels. (This is the rst example in the Points section of the SLD Cook Book.)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

<?xml version="1.0" encoding="ISO-8859-1"?> <StyledLayerDescriptor version="1.0.0" xsi:schemaLocation="http://www.opengis.net/sld StyledLayerDescriptor.xsd" xmlns="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <NamedLayer> <Name>Simple point</Name> <UserStyle> <Title>GeoServer SLD Cook Book: Simple point</Title> <FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </Mark> <Size>6</Size> </Graphic> </PointSymbolizer> </Rule> </FeatureTypeStyle> </UserStyle> </NamedLayer> </StyledLayerDescriptor>

Dont let the lengthy nature of this simple example intimidate; only a few lines are really important to understand. Line 14 states that we are using a PointSymbolizer, a style for point data. Line 17 states that we are using a well known name, a circle, to style the points. There are many well known names for shapes such as square, star, triangle, etc. Lines 18-20 states to ll the shape with a color of #FF0000 (red). This is an RGB color code, written in hexadecimal, in the form of #RRGGBB. Finally, line 22 species that the size of the shape is 6 pixels in width. The rest of the structure contains metadata about the style, such as Name/Title/Abstract. Many more examples can be found in the SLD Cook Book.

104

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Note: You will nd that some tags have prexes, such as ogc: in front of them. The reason for this is because they are XML namespaces. In the tag on lines 2-7, there are two XML namespaces, one called xmlns, and one called xmlns:ogc. Tags corresponding to the rst namespace do not need a prex, but tags corresponding to the second require a prex of ogc:. It should be pointed out that the name of the namespaces are not important: The rst namespace could be xmlns:sld (as it often is) and then all of the tags in this example would require an sld: prex. The important part is that the namespaces need to match the tags.

7.1.6 Troubleshooting
SLD is a type of programming language, not unlike creating a web page or building a script. As such, problems may arise that may require troubleshooting. When adding a style into GeoServer, it is automatically checked for validation with the OGC SLD specication (although that may be bypassed), but it will not be checked for errors. It is very easy to have syntax errors creep into a valid SLD. Most of the time this will result in a blank map (nothing displayed), but sometimes errors will prevent the map from displaying at all. The easiest way to x errors in an SLD is to try to isolate the error. If the SLD is long and incorporates many different rules and lters, try temporarily removing some of them to see if the errors go away. To minimize errors when creating the SLD, it is recommended to use a text editor that is designed to work with XML. Editors designed for XML can make nding and removing errors much easier by providing syntax highlighting and (sometimes) built-in error checking.

7.2 SLD Cook Book

The SLD Cook Book is a collection of SLD recipes for creating various types of map styles. It is divided into four sections, the rst three based on vector shapes (points, lines, and polygons) and the fourth section for rasters. Each example contains an inline snippet of the code specic to the style, a screenshot showing actual GeoServer output, and a link to download the full SLD that created the output. These examples use four data sets created especially for each section. Warning: Add link to download shapeles.

7.2.1 Points
Points, in theory, are the simplest shape. However, there are many different ways that a point can be styled, perhaps more than even lines and polygons. The point layer that is used for the examples below contains information about the major cities for a ctional country. The data contains attribute columns for city names (name) and population (pop). Warning: Add link to point shapele Warning: The code examples shown on this page are not the full SLD code, as they omit the header and footer information required for SLDs for the sake of brevity. Please use the links to download the full SLDs for each example.

7.2. SLD Cook Book

105

GeoServer User Manual, Release 1.7.4

Simple Point This example species points to be styled as red circles with a diameter of 6 pixels.

Details
There is one <Rule> in one <FeatureTypeStyle> for this style, which is the simplest possible situation. (All subsequent examples will share this characteristic unless otherwise specied.) Line 6 species the shape of the symbol (a circle), with line 8 determining the ll color to be red (#FF0000). Line 11 sets the size of the graphic to be 6 pixels.

Code
1 2 3 4 5 6 7 8 9 10 11 12

<FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </Mark> <Size>6</Size> </Graphic>

106

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

13 14 15

</PointSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

Simple Point With Stroke This example adds a stroke (or border) around the simple point, colored black and with a thickness of 2 pixels.

Details
Much of this example is similar to the simple point mentioned above. Lines 10-13 specify the stroke, with line 11 setting the color to black (#000000) and line 12 setting the width to 2 pixels. (Omitting line 12 would revert the stroke-width to the default of 1 pixel.)

Code
1 2 3

<FeatureTypeStyle> <Rule> <PointSymbolizer>

7.2. SLD Cook Book

107

GeoServer User Manual, Release 1.7.4

4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

<Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> <Stroke> <CssParameter name="stroke">#000000</CssParameter> <CssParameter name="stroke-width">2</CssParameter> </Stroke> </Mark> <Size>6</Size> </Graphic> </PointSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

Rotated Square This example uses a square instead of a circle, colors it green, sizes it larger, and rotates the square by 45 degrees.

108

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Details
Line 6 sets the shape of the point to be a square, with line 8 setting the color to a muted green (#009900). Line 11 sets the size of the square to be 12 pixels, and rotation is set to 45 degrees on line 12.

Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

<FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>square</WellKnownName> <Fill> <CssParameter name="fill">#009900</CssParameter> </Fill> </Mark> <Size>12</Size> <Rotation>45</Rotation> </Graphic> </PointSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

Transparent Triangle The example replaces the shape with a triangle, retains the black stroke, and sets the ll of the triangle to 20% opacity (mostly transparent).

Details
Line 6 once again sets the shape, in this case to a triangle. Line 8 sets the ll color, and line 9 sets the opacity to 0.2 (20% opaque). This means the green color looks much lighter on a plain white background, although were the point imposed on a dark background, the resulting color would be different. Line 12 and line 13 determine the stroke color and width, respectively. Finally, line 16 sets the size of the point to be 12 pixels.

Code
1 2 3 4 5 6 7 8

<FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>triangle</WellKnownName> <Fill> <CssParameter name="fill">#009900</CssParameter>

7.2. SLD Cook Book

109

GeoServer User Manual, Release 1.7.4

9 10 11 12 13 14 15 16 17 18 19 20

<CssParameter name="fill-opacity">0.2</CssParameter> </Fill> <Stroke> <CssParameter name="stroke">#000000</CssParameter> <CssParameter name="stroke-width">2</CssParameter> </Stroke> </Mark> <Size>12</Size> </Graphic> </PointSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

Point As Graphic This examples styles points as a graphic instead of as a simple shape.

Details
This style uses an external graphic. Lines 5-10 specify the details. Here, the graphic is contained in the same directory as the style (the styles directory), so no path information is necessary, however an external URL could have been used. Line 8 sets the path and le name of the graphic, with line 9 indicating the

110

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

le format (MIME type) of the graphic (image/png). Lines 11 determine the size of the displayed graphic, which can be independent of the actual size of the graphic itself, although in this case they are the same (32 pixels).

Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

<FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <ExternalGraphic> <OnlineResource xlink:type="simple" xlink:href="smileyface.png" /> <Format>image/png</Format> </ExternalGraphic> <Size>32</Size> </Graphic> </PointSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

7.2. SLD Cook Book

111

GeoServer User Manual, Release 1.7.4

Point With Default Label This example shows a text label on the simple point, showing the name attribute of the point. In the absence of any other customization, this is how a label will be displayed.

Details
Lines 3-13 (the <PointSymbolizer>) are identical to the simple point example. The label style is set in the <TextSymbolizer> on lines 14-22. Lines 15-17 determine what text to display, which in this case is the value of the name attribute. Line 20 sets the text color. Dont forget about line 18: although there isnt any content in the <Font /> tag, it is still required by the OGC SLD specication.

Code
1 2 3 4 5 6 7 8 9 10 11

<FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </Mark> <Size>6</Size>

112

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

12 13 14 15 16 17 18 19 20 21 22 23 24

</Graphic> </PointSymbolizer> <TextSymbolizer> <Label> <ogc:PropertyName>name</ogc:PropertyName> </Label> <Font /> <Fill> <CssParameter name="fill">#000000</CssParameter> </Fill> </TextSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

Point With Styled Label This example improves the label style by centering the label above the point and specifying the font name and size.

Details
Lines 3-13 indicate the same simple point as above. The <TextSymbolizer> on lines 14-39 contain much more details about the label than in the previous example. Lines 15-17 specify the attribute to use to display 7.2. SLD Cook Book 113

GeoServer User Manual, Release 1.7.4

the label (again, name). Lines 18-23 set the font information: line 19 sets the font to be Arial, line 20 sets the font size to 12, line 21 sets the font style to normal, and line 22 sets the font weight to bold. Lines 24-35 (<LabelPlacement>) determine the placement of the label relative to the point. There is the <AnchorPoint> (lines 26-29), which sets the place of intersection between the label and point, which here (line 27) is set to halfway (0.5) along the horizontal direction. There is also <Displacement> (lines 30-33), the offset of the label relative to the line, which in this case is 0 pixels in the horizontal direction (line 31) and 5 pixels in the vertical direction (lines 32). Finally, line 37 sets the font color to black (#000000). The net result is a centered label placed slightly above the point.

Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

<FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </Mark> <Size>6</Size> </Graphic> </PointSymbolizer> <TextSymbolizer> <Label> <ogc:PropertyName>name</ogc:PropertyName> </Label> <Font> <CssParameter name="font-family">Arial</CssParameter> <CssParameter name="font-size">12</CssParameter> <CssParameter name="font-style">normal</CssParameter> <CssParameter name="font-weight">bold</CssParameter> </Font> <LabelPlacement> <PointPlacement> <AnchorPoint> <AnchorPointX>0.5</AnchorPointX> <AnchorPointY>0.0</AnchorPointY> </AnchorPoint> <Displacement> <DisplacementX>0</DisplacementX> <DisplacementY>5</DisplacementY> </Displacement> </PointPlacement> </LabelPlacement> <Fill> <CssParameter name="fill">#000000</CssParameter> </Fill> </TextSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

114

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Point With Rotated Label This example rotates the previous label by 45 degrees and sets 25 pixels of displacement to make the label farther away from the point.

Details
Much of this is the same as the styled label above. There are only three important differences. Line 32 species 25 pixels of vertical displacement (instead of 5 pixels as used before). Lines 54-56 specify a rotation of 45 degrees counter-clockwse. (Rotation values increase clockwise, which is why the value is negative.) Finally, line 38 sets the font color to be a shade of purple (#99099).

Code
1 2 3 4 5 6 7 8 9 10 11

<FeatureTypeStyle> <Rule> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </Mark> <Size>6</Size>

7.2. SLD Cook Book

115

GeoServer User Manual, Release 1.7.4

12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

</Graphic> </PointSymbolizer> <TextSymbolizer> <Label> <ogc:PropertyName>name</ogc:PropertyName> </Label> <Font> <CssParameter name="font-family">Arial</CssParameter> <CssParameter name="font-size">12</CssParameter> <CssParameter name="font-style">normal</CssParameter> <CssParameter name="font-weight">bold</CssParameter> </Font> <LabelPlacement> <PointPlacement> <AnchorPoint> <AnchorPointX>0.5</AnchorPointX> <AnchorPointY>0.0</AnchorPointY> </AnchorPoint> <Displacement> <DisplacementX>0</DisplacementX> <DisplacementY>25</DisplacementY> </Displacement> <Rotation>-45</Rotation> </PointPlacement> </LabelPlacement> <Fill> <CssParameter name="fill">#990099</CssParameter> </Fill> </TextSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

Attribute-Based Point This example alters the look of the points based on the population attribute.

Details
The populations of the cities are as follows: City (name) Born Supox City Ruckis Thisland Synopolis San Glissando Detrainia Population (pop) 157860 578231 98159 34879 24567 76024 205609

(The labels have been removed in this example to simplify the style. Please refer to the previous example to see which points refer to which cities.)

116

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

This style contains more than one <Rule>. Each rule varies the style based on the value of the population (pop) attribute for each point. The order of the rules does not matter. The rst rule, on lines 2-22, species the styling of those points whose population attribute is less than 50,000. Lines 5-10 set this lter, with lines 6-9 setting the less than lter, line 7 denoting the attribute, and and line 8 with the value of 50,000. The graphic is a circle (line 14), and the size is 8 pixels (line 19). The second rule (lines 23-49) is very similar, specifying a style for points whose population attribute is between 50,000 and 100,000. The population lter is set on lines 36-37, and it is longer than the rst rule because two criteria need to be set: PropertyIsGreaterThanOrEqualTo and PropertyIsLessThan. (Notice the And in lines 27 and 36.) The size of the graphic is changed to be 12 pixels on line 46. The third rule (lines 50-70) species a style for points whose population attribute is greater than 100,000. The population lter is set on lines 53-58, and the only other difference again is the size of the circle, which in this rule (line 67) is 16 pixels. The result of this style is that cities with a larger population have larger points.

Code
1 2 3 4 5 6 7 8

<FeatureTypeStyle> <Rule> <Name>SmallPop</Name> <Title>1 to 50000</Title> <ogc:Filter> <ogc:PropertyIsLessThan> <ogc:PropertyName>pop</ogc:PropertyName> <ogc:Literal>50000</ogc:Literal>

7.2. SLD Cook Book

117

GeoServer User Manual, Release 1.7.4

9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66

</ogc:PropertyIsLessThan> </ogc:Filter> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#0033CC</CssParameter> </Fill> </Mark> <Size>8</Size> </Graphic> </PointSymbolizer> </Rule> <Rule> <Name>MediumPop</Name> <Title>50000 to 100000</Title> <ogc:Filter> <ogc:And> <ogc:PropertyIsGreaterThanOrEqualTo> <ogc:PropertyName>pop</ogc:PropertyName> <ogc:Literal>50000</ogc:Literal> </ogc:PropertyIsGreaterThanOrEqualTo> <ogc:PropertyIsLessThan> <ogc:PropertyName>pop</ogc:PropertyName> <ogc:Literal>100000</ogc:Literal> </ogc:PropertyIsLessThan> </ogc:And> </ogc:Filter> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#0033CC</CssParameter> </Fill> </Mark> <Size>12</Size> </Graphic> </PointSymbolizer> </Rule> <Rule> <Name>LargePop</Name> <Title>Greater than 100000</Title> <ogc:Filter> <ogc:PropertyIsGreaterThanOrEqualTo> <ogc:PropertyName>pop</ogc:PropertyName> <ogc:Literal>100000</ogc:Literal> </ogc:PropertyIsGreaterThanOrEqualTo> </ogc:Filter> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#0033CC</CssParameter> </Fill> </Mark>

118

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

67 68 69 70 71

<Size>16</Size> </Graphic> </PointSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

Zoom-Based Point This example alters the look of the points based on zoom level.

Figure 7.1: Zoomed out

Details
Zoom-based styles can be some of the most complex SLD les. When combined with attribute-based styles, SLD les can grow quite cumbersome. However, zoom-based styles can also make your maps much more realistic, since one is used to seeing things get larger as one zooms in. That is precisely what this example shows. The points (now all styled identically) will vary in size based on the zoom level. Note: Determining the zoom level is beyond the scope of this page.

7.2. SLD Cook Book

119

GeoServer User Manual, Release 1.7.4

Figure 7.2: Partially zoomed

120

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Figure 7.3: Zoomed in

7.2. SLD Cook Book

121

GeoServer User Manual, Release 1.7.4

Warning: Where do we point people who want to know more? This style contains three rules. (The order of the rules does not matter.) The rst rule (lines 2-16) is for the largest scale denominator (when the view is zoomed in). The zoom is set on line 4, applicable to any map with a scale denominator of 160,000,000 or less. The rule draws a circle (line 8) with a size of 12 pixels (line 13). The second rule (lines 17-32) is the middle zoom level. The zoom is set on lines 19-20, applicable to any map with a scale denominator between 160,000,000 and 320,000,000. The rule draws a circle with a size of 8 pixels (line 29). The third rule (lines 33-47) is the display when the map is the most zoomed out. The zoom is set on line 35, applicable to any map with a scale denominator of 320,000,000 or more. The rule draws a circle with a size of 4 pixels (lines 44). The result of this style is that points are drawn larger as one zooms in and smaller as one zooms out.

Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

<FeatureTypeStyle> <Rule> <Name>Large</Name> <MaxScaleDenominator>160000000</MaxScaleDenominator> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#CC3300</CssParameter> </Fill> </Mark> <Size>12</Size> </Graphic> </PointSymbolizer> </Rule> <Rule> <Name>Medium</Name> <MinScaleDenominator>160000000</MinScaleDenominator> <MaxScaleDenominator>320000000</MaxScaleDenominator> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#CC3300</CssParameter> </Fill> </Mark> <Size>8</Size> </Graphic> </PointSymbolizer> </Rule> <Rule> <Name>Small</Name> <MinScaleDenominator>320000000</MinScaleDenominator> <PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill>

122

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

41 42 43 44 45 46 47 48

<CssParameter name="fill">#CC3300</CssParameter> </Fill> </Mark> <Size>4</Size> </Graphic> </PointSymbolizer> </Rule> </FeatureTypeStyle>

Warning: Add link to SLD

7.2.2 Lines
Lines, by having length but no width, can seem to be a simple shape. However, there are many tricks for making nicer lines, which is especially important when styling roads. The line layer used in the examples below contain road information about a section of Supox, a major city in the ctional country of Frungy. Download this layer. Warning: Add link to line data

Simple line This example shows a basic line style, colored black with a thickness of three (3) pixels. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Better line style An often used trick for improving the style of lines is to draw the line twice, once with a small thickness, and once with a slightly larger thickness. This has the effect of creating a ll and stroke look for lines. This example fakes a blue ll and a gray stroke by drawing a blue line at 3 pixels, and a gray line at 5 pixels. Since these lines are drawn twice, the order of the drawing is very important. In this style, all of the gray lines are drawn rst, followed by all of the blue lines. This not only ensures that the blue lines wont be obscured, but also allows for better styling at intersections (so the inner lines connect). Warning: Add code Warning: Add screenshot

7.2. SLD Cook Book

123

GeoServer User Manual, Release 1.7.4

Warning: Add link to SLD

Dashed line This example takes the simple line and creates a dashed line. The style as drawn consists of ve (5) pixels of drawn line, followed by two (2) pixels of blank space. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Railroad (hatching) This example leverages the use of hatching to create a railroad style. Both the line and the hatches are black, with a two (2) pixel thickness. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Default label This example shows a text label on the simple line. In the absence of any other customization, this is how a label will be displayed. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Label following line Warning: Add description

124

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Repeated label If the lines are very long, it may be advantageous to repeat the label in multiple places. However, two many repeats can clutter up your map. This example repets the label every one hundred (100) pixels. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Displaced label This example shows the labels displaced from their lines by a distance of ten (10) pixels. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Attribute-based style There are various road classes in Supox, ranging from back roads to high-speed freeways. This example styles the lines differently based on road class. Warning: Add more description Warning: Add code Warning: Add screenshot Warning: Add link to SLD

7.2. SLD Cook Book

125

GeoServer User Manual, Release 1.7.4

Zoom-based style When making a nice looking map, it is benecial to make shapes look larger as the map is zoomed in. This example the simple line style and adjusts it for multiple zoom levels. (Each zoom level effectively adds 100% more code, so this example will be fairly long, although much of it is duplicated code.) Warning: Add more description Warning: Add code Warning: Add screenshot Warning: Add link to SLD

7.2.3 Polygons
Polygons are two dimensional shapes, having an edge (or stroke) and an inside (or ll). Many of the same tricks for styling points and lines can be applied to polygons. The polygon layer used in the examples below contain information about countries in and around the ctional country of Frungy. Download this layer. Warning: Add link to polygon data

Simple polygon This example shows a polygon styled in blue.

Details
There is one <Rule> in one <FeatureTypeStyle> for this style, which is the simplest possible situation. (All subsequent examples will share this characteristic unless otherwise specied.) Line 5 species the ll color of the polygon to be #000080, or a muted blue. The borders around the polygons as shown in the gure are an artifacts of the renderer.

Code
1 2 3 4 5 6 7 8 9

<FeatureTypeStyle> <Rule> <PolygonSymbolizer> <Fill> <CssParameter name="fill">#000080</CssParameter> </Fill> </PolygonSymbolizer> </Rule> </FeatureTypeStyle>

126

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Warning: Add link to SLD

Simple polygon with stroke This example shows the above polygon but adds a stroke of grey, with a one (5) pixel thickness. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Polygon opacity This example alters the above style to have a 50% opacity of the blue ll. Warning: Add code Warning: Add screenshot

7.2. SLD Cook Book

127

GeoServer User Manual, Release 1.7.4

Warning: Add link to SLD

External graphic for ll This example uses a graphic to be tiled as a ll for the polygon. The graphic is contained in the same directory as the polygon. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Default label This example shows a text label on the polygon. In the absence of any other customization, this is how a label will be displayed. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Adding space around label This example adds space around the label to make sure it is not repeated too closely. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Label halo This example alters the look of the label by adding a white halo. Warning: Add code

128

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Warning: Add screenshot Warning: Add link to SLD

Attribute-based style This example styles the polygons based on the populations of the countries that they represent. Warning: Add more description Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Zoom-based style This example sets the labels only to be displayed at certain zoom levels Warning: Add more description Warning: Add code Warning: Add screenshot Warning: Add link to SLD

7.2.4 Rasters
Rasters are geographic data displayed in a grid. They are similar to graphics like PNG les, except that instead of each point containing visual information, each point contains geographic information. The examples below use a data layer that contains an elevation model for the ctional city of Supox. Download this layer. Warning: Add link to raster data

7.2. SLD Cook Book

129

GeoServer User Manual, Release 1.7.4

Two color gradient This example shows a two color style with green at low elevations and brown at high elevations. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Two color gradient with transparency This example is identical to the above except it sets the layer to 50% opacity. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Three color gradient with partial transparency This example sets a three color style, with the third color being transparent, so that the green color gradually fades away at lower elevations. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

Many color gradient This example shows an eight color style. Warning: Add code Warning: Add screenshot Warning: Add link to SLD

130

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

7.3 SLD Reference

A symbolizer species how data should be visualized. There are 5 types of symbolizers: PointSymbolizer, which is used to portray point data; LineSymbolizer, which is used to portray line data; PolygonSymbolizer, which is used to portray polygon data; RasterSymbolizer, which is used to portray raster data; and TextSymbolizer, which is used to portray text labels. Warning: Intro for lters and scale.

7.3.1 PointSymbolizer
The PointSymbolizer styles points, Points are elements that contain only position information. Syntax The outermost element is the <Graphic> tag. This determines the type of visualization. There are ve possible tags to include inside the <Graphic> tag: Tag Required? Description <ExternalGraphic> No (when using Species an image le to use as the symbolizer. <Mark>) <Mark> No (when using Species a common shape to use as the symbolizer. <ExternalGraphic>) <Opacity> No Determines the opacity (transparency) of symbolizers. Values range from 0 (completely transparent) to 1 (completely opaque). Default is 1. <Size> Yes Determines the size of the symbolizer in pixels. When used with an image le, this will specify the height of the image, with the width scaled accordingly. <Rotation>No Determines the rotation of the graphic in degrees. The rotation increases in the clockwise direction. Negative values indicate counter-clockwise rotation. Default is 0. Within the <ExternalGraphic> tag, there are also additional tags: Tag Required? <OnlineResource> Yes <Format> Yes Description The location of the image le. Can be either a URL or a local path relative to the SLD. The MIME type of the image format. Most standard web image formats are supported.

Within the <Mark> tag, there are also additional tags: Tag Required? <WellKnownName> Yes No (when using <Stroke>) <Stroke> No (when using <Fill>) <Fill> 7.3. SLD Reference Description The name of the common shape. Options are circle, square, triangle, star, cross, or x. Default is square. Species how the symbolizer should be lled. Options are a <CssParameter name="fill"> specifying a color in the form #RRGGBB, or <GraphicFill> for a repeated graphic. Species how the symbolizer should be drawn on its border. Options are a <CssParameter name="fill"> specifying a color in the form #RRGGBB or <GraphicStroke> for a repeated graphic. 131

GeoServer User Manual, Release 1.7.4

Example Consider the following symbolizer taken from the Simple Point example in the Points section in the SLD Cook Book.
1 2 3 4 5 6 7 8 9 10 11

<PointSymbolizer> <Graphic> <Mark> <WellKnownName>circle</WellKnownName> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </Mark> <Size>6</Size> </Graphic> </PointSymbolizer>

The symbolizer contains a <Graphic> tag, which is required. Inside this tag is the <Mark> tag and <Size> tag, which are the minimum required tags inside <Graphic> (when not using the <ExternalGraphic> tag). The <Mark> tag contains the <WellKnownName> tag and a <Fill> tag. No other tags are required. In summary, this example species the following: 1. Data will be rendered as points 2. Points will be rendered as circles 3. Circles will be rendered with a diameter of 6 pixels and lled with the color red Further examples can be found in the Points section of the SLD Cook Book.

7.3.2 LineSymbolizer
The LineSymbolizer styles lines. Lines are one-dimensional geometry elements that contain position and length. Lines can be comprised of multiple line segments. Syntax The outermost tag is the <Stroke> tag. This tag is required, and determines the visualization of the line. There are three possible tags that can be included inside the <Stroke> tag. Tag <GraphicFill> <GraphicStroke> <CssParameter> Required? No No No Description Renders the pixels of the line with a repeated pattern. Renders the line with a repeated linear graphic. Determines the stroke styling parameters.

When using the <GraphicStroke> and <GraphicFill> tags, it is required to insert the <Graphic> tag inside them. The syntax for this tag is identical to that mentioned in the PointSymbolizer section above. Within the <CssParameter> tag, there are also additional parameters that go inside the actual tag:

132

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Parameter

ReDescription quired? name="stroke" No Species the solid color given to the line, in the form #RRGGBB. Default is black (#000000). name="stroke-width" No Species the width of the line in pixels. Default is 1. name="stroke-opacity" No Species the opacity (transparency) of the line. possible values are between 0 (completely transparent) and 1 (completely opaque). Default is 1. name="stroke-linejoin" No Determines how lines are rendered at intersections of line segments. Possible values are mitre (sharp corner), round (rounded corner), and bevel (diagonal corner). Default is mitre. name="stroke-linecap" No Determines how lines are rendered at ends of line segments. Possible values are butt (sharp square edge), round (rounded edge), and square (slightly elongated square edge). Default is butt. name="stroke-dasharray" No Encodes a dash pattern as a series of numbers separated by spaces. Odd-indexed numbers (rst, third, etc) determine the length in pxiels to draw the line, and even-indexed numbers (second, fourth, etc) determine the length in pixels to blank out the line. Default is an unbroken line. name="stroke-dashoffset" No Species the distance in pixels into the dasharray pattern at which to start drawing. Default is 0. Warning: Maybe a screenshot of the different linecaps etc?

Example

7.3.3 PolygonSymbolizer
The LineSymbolizer styles polygons. Lines are two-dimensional geometry elements. They can contain styling information about their border (stroke) and their ll. Syntax A <PolygonSymbolizer> can have two outermost tags: Tag <Fill> <Stroke> Required? No (when using <Stroke>) No (when using <Fill>) Description Determines the styling for the ll of the polygon. Determines the styling for the stroke of the polygon.

The details for the <Stroke> tag are identical to that mentioned in the LineSymbolizer section above. Within the <Fill> tag, there are additional tags: Tag <GraphicFill> <CssParameter> Required? No No Description Renders the ll of the polygon with a repeated pattern. Determines the ll styling parameters.

When using the <GraphicFill> tag, it is required to insert the <Graphic> tag inside it. The syntax for this tag is identical to that mentioned in the PointSymbolizer section above. Within the <CssParameter> tag, there are also additional parameters that go inside the actual tag:

7.3. SLD Reference

133

GeoServer User Manual, Release 1.7.4

Parameter

ReDescription quired? name="fill" No Species the ll color for the polygon, in the form #RRGGBB. Default is grey (#808080). name="fill-opacity" No Species the opacity (transparency) of the ll of the polygon. Possible values are between 0 (completely transparent) and 1 (completely opaque). Default is 1. Example Consider the following symbolizer taken from the Simple Point example in the Polygons section in the SLD Cook Book.
1 2 3 4 5

<PolygonSymbolizer> <Fill> <CssParameter name="fill">#000080</CssParameter> </Fill> </PolygonSymbolizer>

This symbolizer contains only a <Fill> tag. Inside this tag is a <CssParameter> that species a ll color for the polygont o be #000080, or a muted blue. Further examples can be found in the Polygons section of the SLD Cook Book.

7.3.4 RasterSymbolizer
The RasterSymbolizer styles rasters. Rasters are not vectored matrix coverage data, such as satellite photos and digital elevation models (DEM). Syntax Warning: Coming soon

Example Warning: Coming soon

7.3.5 TextSymbolizer
The TextSymbolizer species text labels. Syntax A <TextSymbolizer> contains the following tags:

134

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Tag

Required? <Label> Yes <Font> No <LabelPlacement> No <Halo> No <Fill> No

Description Species the content of the text label Species the font information for the labels. Sets the position of the label relative its associate feature. Creates a colored background around the text label, for low contrast situations. Determines the ll color of the text label.

Each of the above tags have additional sub tags. For the <Label> tag: Tag Required? Description

Within the <Font> tag, the <CssParameter> tag is the only tag included. There are four types of parameters for this tag, each included inside the <CssParameter> tag: Parameter Required? name="font-family" No name="font-style" No name="font-weight" No name="font-size" No Description Determines the family name of the font to use for the label. Default is Times. Determines the style of the font. Options are normal, italic, and oblique. Default is normal. Determines the weight of the font. Options are normal and bold. Default is normal. Determines the size of the font in pixels. Default is 10.

Within the <LabelPlacement> tag, there are many tags for specifying the placement of the label: Tag Required? Description

Within the <Halo> tag, there are two tags to specify the details of the halo: Tag <Radius> <Fill> Required? No No Description Sets the size of the halo radius in pixels. Default is 1. Sets the color of the halo in the form of #RRGGBB. Default is white (#FFFFFF).

The <Fill> tag is identical to that described in the WHERE~? above. Example

7.3.6 Filters
A lter is the mechanism in SLD for specifying predicates. Similar in nature to a WHERE clause in SQL, lters are the language for specifying which styles should be applied to which features in a data set. The lter language used by SLD is itself an <OGC standard dened in the Filter Encoding specication freely available. A lter is used to select a subset of features of a dataset to apply a symbolizer to. There are three types of lters:

7.3. SLD Reference

135

GeoServer User Manual, Release 1.7.4

Attribute lters Attribute lters are used to constrain the non-spatial attributes of a feature. Example
1 2 3 4

<PropertyIsEqualTo> <PropertyName>NAME</PropertyName> <Literal>Bob</Literal> </PropertyIsEqualTo>

The above lter selects those features which have a {{NAME}} attribute which has a value of Bob. A variety of equality operators are available: PropertyIsEqualTo PropertyIsNotEqualTo PropertyIsLessThan PropertyIsLessThanOrEqualTo PropertyIsGreatherThan PropertyIsGreatherThanOrEqualTo PropertyIsBetween Spatial lters Spatial lters used to constrain the spatial attributes of a feature. Example
1 2 3 4 5 6 7 8

<Intersects> <PropertyName>GEOMETRY</PropertyName> <Literal> <gml:Point> <gml:coordinates>1 1</gml:coordinates> </gml:Point> </Literal> </Intersects>

The above lter selects those features with a geometry that intersects the point (1,1). A variety of spatial operators are available: Intersects Equals Disjoint Within Overlaps Crosses DWithin Beyond Distance

136

Chapter 7. Styling

GeoServer User Manual, Release 1.7.4

Logical lters Logical lters are used to create combinations of lters using the logical operators And, Or, and Not. Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14

<And> <PropertyIsEqualTo> <PropertyName>NAME</PropertyName> <Literal>Bob</Literal> </PropertyIsEqualTo> <Intersects> <PropertyName>GEOMETRY</PropertyName> <Literal> <gml:Point> <gml:coordinates>1 1</gml:coordinates> </gml:Point> </Literal> </Intersects> </And>

Rules A rule combines a number of symbolizers with a lter to dene the portrayal of a feature. Consider the following example:
<Rule> <ogc:Filter> <ogc:PropertyIsGreaterThan> <ogc:PropertyName>POPULATION</ogc:PropertyName> <ogc:Literal>100000</ogc:Literal> </ogc:PropertyIsGreaterThan> </ogc:Filter> <PointSymbolizer> <Graphic> <Mark> <Fill><CssParameter name="fill">#FF0000</CssParameter> </Mark> </Graphic> </PointSymbolizer> </Rule>

The above rule applies only to features which have a POPULATION attribute greater than 100,000 and symbolizes then with a red point. An SLD document can contain many rules. Multiple rule SLDs are the basis for thematic styling. Consider the above example expanded:
<Rule> <ogc:Filter> <ogc:PropertyIsGreaterThan> <ogc:PropertyName>POPULATION</ogc:PropertyName> <ogc:Literal>100000</ogc:Literal> </ogc:PropertyIsGreaterThan> </ogc:Filter> <PointSymbolizer> <Graphic>

7.3. SLD Reference

137

GeoServer User Manual, Release 1.7.4

<Mark> <Fill><CssParameter name="fill">#FF0000</CssParameter> </Mark> </Graphic> </PointSymbolizer> </Rule> <Rule> <ogc:Filter> <ogc:PropertyIsLessThan> <ogc:PropertyName>POPULATION</ogc:PropertyName> <ogc:Literal>100000</ogc:Literal> </ogc:PropertyIsLessThan> </ogc:Filter> <PointSymbolizer> <Graphic> <Mark> <Fill><CssParameter name="fill">#0000FF</CssParameter> </Mark> </Graphic> </PointSymbolizer> </Rule>

The above snippet denes an additional rule which engages when POPULATION is less than 100,000 and symbolizes the feature as a green point. Rules support the notion of scale dependence which allows one to specify the scale at which a rule should engage. This allows for different portrayals of a feature based on map scale. Consider the following example:
<Rule> <MaxScaleDenominator>20000</MaxScaleDenominator> <PointSymbolizer> <Graphic> <Mark> <Fill><CssParameter name="fill">#FF0000</CssParameter> </Mark> </Graphic> </PointSymbolizer> </Rule> <Rule> <MinScaleDenominator>20000</MinScaleDenominator> <PointSymbolizer> <Graphic> <Mark> <Fill><CssParameter name="fill">#0000FF</CssParameter> </Mark> </Graphic> </PointSymbolizer> </Rule>

The above rules specify that at a scale below 1:20000 features are symbolized with red points, and at a scale above 1:20000 features are symbolized with blue points.

7.3.7 Scale

138

Chapter 7. Styling

CHAPTER 8

Services

GeoServer serves data using standard protocols established by the Open Geospatial Consortium. The Web Feature Service (WFS) allows for requests of geographical feature data (vectors). The Web Map Service (WMS) allows for requests of images generated from geographical data. Finally, the Web Coverage Service (WCS) allows for requests of coverage data (rasters). These services are the heart of GeoServer.

8.1 Web Feature Service

8.1.1 WFS basics
Warning: Add intro here

Differences between WFS versions The major differences between the WFS versions are: WFS 1.1.0 returns GML3 as the default GML. In WFS 1.0.0 the default was GML2. (GeoServer still supports requests in both GML3 and GML2 formats.) GML3 has slightly different ways of specifying a geometry. In WFS 1.1.0, the way to specify the SRS (Spatial Reference System, aka projection) is urn:x-ogc:def:crs:EPSG:XXXX, whereas in version 1.0.0 the specication was http://www.opengis.net/gml/srs/epsg.xml#XXXX. This change has implications on the axis order of the returned data. WFS 1.1.0 supports on-the-y reprojection of data, which allows for data to be returned in a SRS other than the native. Axis ordering WFS 1.0.0 servers return geographic coordinates in longitude/latitude (x/y) order. This is the most common way to distribute data as well (for example, most shapeles adopt this order by default).

139

GeoServer User Manual, Release 1.7.4

However, the traditional axis order for geographic and cartographic systems is latitude/longitude (y/x), the opposite and WFS 1.1.0 specication respects this. This can cause difculties when switching between servers with different WFS versions, or when upgading your WFS. To sum up, the defaults are as follows: WFS 1.1.0 request = latitude/longitude WMS 1.0.0 request = longitude/latitude GeoServer, however, in an attempt to minimize confusion and increase interoperability, has adopted the following conventions when specifying projections in the follow formats: EPSG:xxxx - longitude/latitude http://www.opengis.net/gml/srs/epsg.xml#xxxx - longitude/latitude urn:x-ogc:def:crs:EPSG:xxxx - latitude/longitude

8.1.2 WFS output formats

WFS returns features and feature information in a number of possible formats. This page shows a list of the output formats. In all cases the syntax for setting an output format is:
outputFormat=<outputformat>

where <outputformat> is any of the options below. Note: Some additional output formats are available with the use of an extension, such as Excel. This list applies just to the basic GeoServer installation. The full list of output formats supported by your GeoServer instance can be found by requesting your WFS GetCapabilities. Format GML2 GML3 Shapele JSON CSV Syntax outputFormat=GML2 outputFormat=GML3 outputFormat=shape-zip outputFormat=json outputFormat=csv Notes Default option using WFS 1.0.0 Default option using WFS 1.1.0 Created in a ZIP archive

8.1.3 WFS vendor parameters

WFS Vendor parameters are options that are not dened in the ofcial WFS specication, but are allowed by it. GeoServer supports a range of custom WFS parameters. CQL lters When specifying a WFS GetFeature GET request, a lter can be specied in CQL (Common Query Language), as opposed to encoding the XML into the request. CQL sports a much more compact and human readable syntax compared to OGC lters. CQL isnt as exible as OGC lters, however, and cant encode as many types of lters as the OGC specication does. In particular, lters by feature ID are not supported.

140

Chapter 8. Services

GeoServer User Manual, Release 1.7.4

Example
A sample lter request using an OGC lter taken from a GET request:

filter=%3CFilter%20xmlns:gml=%22http://www.opengis.net/gml%22%3E%3CIntersects%3E%3CPropertyName%3Ethe

The same lter using CQL:

cql_filter=INTERSECT(the_geom,%20POINT%20(-74.817265%2040.5296504))

Reprojection WFS 1.1 allows the ability to reproject data (to have GeoServer store the data in one projection and return GML in another). GeoServer supports this using WFS 1.0 as well. When doing a WFS 1.0 GetFeature GET request you can add this parameter to specify the reprojection SRS:
srsName=<srsName>

where <srsName> is the code for the projection (such as EPSG:4326). For POST requests, you can add the same code to the Query element. XML request validation By default, GeoServer is slightly more forgiving than the WFS specication requires. To force incoming XML requests to be strictly valid, use the following parameter:
strict=[true|false]

where false is the default option.

Example
Consider the following POST request:
<wfs:GetFeature service="WFS" version="1.0.0" xmlns:wfs="http://www.opengis.net/wfs"> <Query typeName="topp:states"/> </wfs:GetFeature>

This request will be processed successfully in GeoServer, but technically this request is invalid: The Query element should be prexed with wfs: The namespace prex has not been mapped to a namespace URI Executing the above command with strict=true results in an error. For the request to be processed, it must be altered:

<wfs:GetFeature service="WFS" version="1.0.0" xmlns:wfs="http://www.opengis.net/wfs" xmlns:topp="http <wfs:Query typeName="topp:states"/> </wfs:GetFeature>

8.1. Web Feature Service

141

GeoServer User Manual, Release 1.7.4

GetCapabilities namespace lter WFS GetCapabilities requests can be ltered to only return layers corresponding to a particular namespace. To do this, add the following code to your request:
namespace=<namespace>

where <namespace> is the namespace prex you wish to lter on. Using an invalid namespace prex will not cause any errors, but the document returned will contain no information on any layers. Note: This only affects the capabilities document, and not any other requests. WFS requests given to other layers, even when a different namespace is specied, will still be processed. Warning: Using this parameter may cause your capabilities document to become invalid (as the WFS specication requires the document to return at least one layer).

8.1.4 WFS reference

Introduction The Web Feature Service (WFS) is a standard created by the OGC that refers to the sending and receiving of geospatial data through HTTP. WFS encodes and transfers information in Geography Markup Language, a subset of XML. The current version of WFS is 1.1.0. GeoServer supports both version 1.1.0 (the default since GeoServer 1.6.0) and version 1.0.0. There are differences between these two formats, some more subtle than others, and this will be noted where differences arise. The current version of WFS is 1.1. WFS version 1.0 is still used in places, and we will note where there are differences. However, the syntax will often remain the same. An important distinction must be made between WFS and Web Map Service, which refers to the sending and receiving of geographic information after it has been rendered as a digital image. Benets of WFS One can think of WFS as the source code to the maps that one would ordinarily view (via WMS). WFS leads to greater transparency and openness in mapping applications. Instead of merely being able to look at a picture of the map, as the provider wants the user to see, the power is in the hands of the user to determine how to visualize (style) the raw geographic and attribute data. The data can also be downloaded, further analyzed, and combined with other data. The transactional capabilities of WFS allow for collaborative mapping applications. In short, WFS is what enables open spatial data. Operations WFS can perform the following operations:

142

Chapter 8. Services

GeoServer User Manual, Release 1.7.4

Operation GetCapabilities

Description Retrieves a list of the servers data, as well as valid WFS operations and parameters DescribeFeatureType Retrieves information and attributes about a particular dataset GetFeature Retrieves the actual data, including geometry and attribute values LockFeature Prevents a feature type from being edited Transaction Edits existing featuretypes by creating, updating, and deleting. GetGMLObject (Version 1.1.0 only) - Retrieves element instances by traversing XLinks that refer to their XML IDs. A WFS server that supports transactions is sometimes known as a WFS-T. GeoServer fully supports transactions. GetCapabilities The GetCapabilities operation is a request to a WFS server for a list of what operations and services (capabilities) are being offered by that server. A typical GetCapabilities request would look like this (at URL http://www.example.com/wfs): Using a GET request (standard HTTP):
http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetCapabilities

The equivalent using POST:

<GetCapabilities service="WFS" xmlns="http://www.opengis.net/wfs" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wfs http://schemas.opengis.net/wfs/1.1.0/wfs.xsd"/>

GET requests are simplest to decode, so we will discuss them in detail, but the POST requests are analogous. (The actual requests would be all on one line, with no line breaks, but our convention here is to break lines for clarity.) Here there are three parameters being passed to our WFS server, service=wfs, version=1.1.0, and request=GetCapabilities. At a bare minimum, it is required that a WFS request have these three parameters (service, version, and request). GeoServer relaxes these requirements (setting the default version if omitted), but ofcially they are mandatory, so they should always be included. The service key tells the WFS server that a WFS request is forthcoming. The version key refers to which version of WFS is being requested. Note that there are only two version numbers ofcially supported: 1.0.0 and 1.1.0. Supplying a value like 1 or 1.1 will likely return an error. The request key is where the actual GetCapabilities operation is specied. The Capabilities document that is returned is a long and complex chunk of XML, but very important, and so it is worth taking a closer look. (The 1.0.0 Capabilities document is very different from the 1.1.0 document discussed here, so beware.) There are ve main components we will be discussing (other components are beyond the scope of this document.):

8.1. Web Feature Service

143

GeoServer User Manual, Release 1.7.4

ServiceIdentication ServiceProvider OperationsMetadata

This section contains basic header information such as the Name and ServiceType. The ServiceType mentions which version(s) of WFS are supported.

This section provides contact information about the company behind the WFS server, including telephone, website, and email. This section describes the operations that the WFS server recognizes and the parameters for each operation. A WFS server can be set up not to respond to all aforementioned operations. FeatureThis section lists the available featuretypes. They are listed in the form TypeList namespace:featuretype. Also, the default projection of the featuretype is listed here, along with the resultant bounding box for the data in that projection. FilThis section lists lters available in which to request the data. SpatialOperators (Equals, ter_Capabilities Touches), ComparisonOperators (LessThan, GreaterThan), and other functions are all listed here. These lters are not dened in the Capabilities document, but most of them (like the ones mentioned here) are self-evident. DescribeFeatureType The purpose of the DescribeFeatureType is to request information about an individual featuretype before requesting the actual data. Specically, DescribeFeatureType will request a list of features and attributes for the given featuretype, or list the featuretypes available. Lets say we want a list of featuretypes. The appropriate GET request would be:
http://www.example.com/wfs? service=wfs& version=1.1.0& request=DescribeFeatureType

Note again the three required elds (service, version, and request). This will return the list of featuretypes, sorted by namespace. If we wanted information about a specic featuretype, the GET request would be:
http://www.example.com/wfs? service=wfs& version=1.1.0& request=DescribeFeatureType& typeName=namespace:featuretype

The only difference between the two requests is the addition of typeName=namespace:featuretype, where featuretype is the name of the featuretype and namespace is the name of the namespace that featuretype is contained in. GetFeature The GetFeature operation requests the actual spatial data. This is the source code spoken about previously. More so than the other operations, it is complex and powerful. Obviously, not all of its abilities will be discussed here. The simplest way to run a GetFeature command is without any arguments.
http://www.example.com/wfs? service=wfs& version=1.1.0&

144

Chapter 8. Services

GeoServer User Manual, Release 1.7.4

request=GetFeature& typeName=namespace:featuretype

This syntax should be request=GetFeature.

familiar

from

previous

examples.

The

only

difference

is

the

It is not recommended to run this command in a web browser, as this will return the geometries for all features in a featuretype. This can be a great deal of data. One way to limit the output is to specify a feature. In this case, the GET request would be:
http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& featureID=feature

Here there is the additional parameter of featureID=feature. Replace feature with the ID of the feature you wish to retrieve. If the name of the feature is unknown, or if you wish to limit the amount of features returned, there is the maxFeatures parameter.
http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& maxFeatures=N

In the above example, N is the number of features to return. A question that may arise at this point is how the WFS server knows which N Features to return. The bad news is that it depends on the internal structure of the data, which may not be arranged in a very helpful way. The good news is that it is possible to sort the features based on an attribute, via the following syntax. (This is new as of 1.1.0.)
http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& maxFeatures=N& sortBy=property

In the above example, sortBy=property determines the sort. Replace property with the attribute you wish to sort by. The default is to sort ascending. Some WFS servers require sort order to be specied, even if ascending. If so, append a +A to the request. To sort descending, add a +D to the request, like so:
http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& maxFeatures=N& sortBy=property+D

8.1. Web Feature Service

145

GeoServer User Manual, Release 1.7.4

It is not necessary to to use sortBy with maxFeatures, but they can often complement each other. To narrow the search not by feature, but instead by an attribute, use the propertyName key in the form propertyName=property. You can specify a single property, or multiple properties separated by commas. For a single property from all features, use the following:
http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& propertyName=property

For a single property from just one feature:

http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& featureID=feature& propertyName=property

Or more than one property from a feature:

http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& featureID=feature& propertyName=property1,property2

All of these permutations so far have centered around parameters of a non-spatial nature, but it is also possible to query for features based on geometry. While there are very limited tools available in a GET request for spatial queries (much more are available in POST requests using lters) one of the most important can be used. This is known as the bounding box or BBOX. The BBOX allows us to ask for only such features that are contained (or partially contained) inside a box of the coordinates we specify. The form of the bbox query is bbox=a1,b1,a2,b2where a, b, c, and d refer to coordinates. Notice that the syntax wasnt bbox=x1,y1,x2,y2 or bbox=y1,x1,y2,x1. The reason the coordinatefree a,b syntax was used above is because the order depends on the coordinate system used. To specify the coordinate system, append srsName=CRS to the WFS request, where CRS is the coordinate reference system. As for which corners of the bounding box to specify (bottom left / top right or bottom right / top left), that appears to not matter, as long as the bottom is rst. So the full request for returning features based on bounding box would look like this:
http://www.example.com/wfs? service=wfs& version=1.1.0& request=GetFeature& typeName=namespace:featuretype& bbox=a1,b1,a2,b2

146

Chapter 8. Services

GeoServer User Manual, Release 1.7.4

LockFeature Transaction GetGMLObject

8.2 Web Map Service

8.2.1 WMS basics 8.2.2 WMS output formats
WMS returns images in a number of possible formats. This page shows a list of the output formats. In all cases the syntax for setting an output format is:
format=<format>

where <format> is any of the options below. Note: The list of output formats supported by your GeoServer instance can be found by a WMS GetCapabilities request. Format PNG PNG8 JPEG GIF TIFF TIFF8 GeoTIFF GeoTIFF8 SVG PDF GeoRSS KML KMZ OpenLayers Syntax Notes

format=image/png Default format=image/png8 Same as PNG, but computes an optimal 256 color (8 bit) palette, so the image size is usually smaller format=image/jpeg format=image/gif format=image/tiff format=image/tiff8 Same as TIFF, but computes an optimal 256 color (8 bit) palette, so the image size is usually smaller format=image/geotiff Same as TIFF, but includes extra GeoTIFF metadata format=image/geotiff8 Same as TIFF, but includes extra GeoTIFF metadata and computes an optimal 256 color (8 bit) palette, so the image size is usually smaller format=image/svg format=application/pdf format=rss format=kml format=kmz format=application/openlayers Generates an OpenLayers HTML application.

8.2.3 WMS vendor parameters

WFS vendor parameters are options that are not dened in the ofcial WFS specication, but are allowed by it. GeoServer supports a range of custom WFS parameters.

8.2. Web Map Service

147

GeoServer User Manual, Release 1.7.4

lter The WMS specication does not allow for much ltering of data. GeoServers WMS lter options are expanded to match those allowed by WFS. The filter parameter encodes a list of OGC lters (in XML). The list is enclosed in () parenthesis. When this parameter is used in a GET request, the brackets of XML need to be URL-encoded. If more than one layer is specied in the layers parameter, then more than one lter can be specied here, each corresponding to a layer. An example of an OGC lter encoded as part of a GET request:

filter=%3CFilter%20xmlns:gml=%22http://www.opengis.net/gml%22%3E%3CIntersects%3E%3CPropertyName%3Ethe

cql_lter The cql_filter parameter is similar to the filter parameter, expect that the lter is encoded using CQL (Common Query Language). This makes the request much more human readable. However, CQL isnt as exible as OGC lters, and cant encode as many types of lters as the OGC specication does. In particular, lters by feature ID are not supported. If more than one layer is specied in the layers parameter, then more than one lter can be specied here, each corresponding to a layer. An example of the same lter as above using CQL:
cql_filter=INTERSECT(the_geom,%20POINT%20(-74.817265%2040.5296504))

featureid The featureid parameter lters by feature ID, a unique value given to all features. Multiple features can be selected by separating the featureids by comma, as seen in this example:
featureid=states.1,states.45

buffer The buffer parameter species the number of extra pixels that should be taken into account when rendering a map (using the GetMap operation). This is important for catching features that are outside the current bounding box, but whose styling is thick enough to be visible inside the relevant area. GeoServer will try to compute this buffer automatically by parsing the SLD, but that may fail if line widths and point sizes are not literal values. When these size are linked to attributes, this parameter may be necessary. The syntax for using a buffer is:
buffer=<bufferwidth>

where <bufferwidth> is the radius of the buffer in pixels. Buffer also applies to the GetFeatureInfo operation. This creates a search radius, where feature info will be returned for the area around the location of the request. This is useful when working with an OpenLayers map (such as those generated by the Map Preview page) as it relaxes the need to click precisely on a point for the appropriate feature info to be returned. The default value of the buffer parameter is 0 pixels.

148

Chapter 8. Services

GeoServer User Manual, Release 1.7.4

palette It is sometimes advisable (for speed and bandwidth reasons) to downsample the bit depth of returned maps. The way to do this is to create an image with a limited color palette, and save it in the palettes directory inside your GeoServer Data Directory. It is then possible to specify the palette parameter of the form:
palette=<image>

where <image> is the lename of the palette image (without the extension). To force a web-safe palette, you can use the syntax palette=safe. tiled When using a tiled client such as OpenLayers, there can be issues with duplicated labels. To deal with this, GeoServer can create metatiles, that is, images are rendered and then split into smaller tiles (by default in a 3x3 pattern) before being served. In order for meta-tiling to work properly, the tile size must be set to 256x256 pixels, and two extra parameters must be set. The tiled parameter is of the form:
tiled=[yes|no]

For metatiling to function, this must be set to yes. tilesorigin The tilesorigin parameter, also necessary for metatiling, is of the form:
tilesorigin=x,y

where x and y are the coordinates of the lower left corner (the origin) of the layer in OpenLayers. kmattr The kmattr parameter determines whether the KML returned by GeoServer should include clickable attributes or not. This parameter primarily affects Google Earth rendering. The syntax is:
kmattr=[true|false]

kmscore The kmscore parameter sets whether GeoServer should render data as vector or raster. This parameter primarily affects Google Earth rendering. The syntax is:
kmscore=<value>

The possible values for this parameter are between 0 (force raster output) and 100 (force vector output). See the page on KML Scoring for more information on this parameter.

8.2. Web Map Service

149

GeoServer User Manual, Release 1.7.4

maxFeatures and startIndex GeoServer WMS supports the parameters maxFeatures and startIndex. Both can be used together to provide paging support. This is helpful in situations such as KML crawling, where it is desirable to be able to retrieve the map in sections when there are a large number of features. Note that not every layer will support paging. The startindex parameter species with a positive integer the index in an ordered list of features to start rendering. For a layer to be queried this way, the underlying feature source shall support paging (such as PostGIS). The maxfeatures parameter sets a limit on the amount of features rendered, using a positive integer. When used with startindex, the features rendered will be the ones starting at the startindex value. layout The layout option chooses a named layout for decorations, a tool for visually annotating GeoServers WMS output. Layouts can be used to add information such as compasses and legends to the maps you retrieve from GeoServer. WMS Decorations are discussed further in the Advanced GeoServer Conguration section. namespace WMS GetCapabilities requests can be ltered to only return layers corresponding to a particular namespace. The syntax is:
namespace=<namespace>

where <namespace> is the namespace prex. Using an invalid namespace prex will not cause any errors, but the document returned will not contain information on any layers, only layer groups. Note: This only affects the capabilities document, and not any other requests. WMS requests given to other layers, even when a different namespace is specied, will still be processed.

8.2.4 WMS reference

The Web Map Service (WMS) is a standard created by the OGC that refers to the sending and receving of geographically registered map images through HTTP. GeoServer supports WMS version 1.1.1, and so the information below will refer to this specic version unless otherwise noted. WMS can perform the following operations: Operation GetCapabilities GetMap GetFeatureInfo DescribeLayer Description Retrieves a list of the servers data, as well as valid WMS operations and parameters Retrieves a map image based on geographic data Retrieves information about particular features as shown on a map image Retrieves an XML description of a map layer

150

Chapter 8. Services

GeoServer User Manual, Release 1.7.4

GetCapabilities GetMap GetFeatureInfo DescribeLayer

8.3 Web Coverage Service

8.3.1 WCS basics 8.3.2 WCS output formats 8.3.3 WCS vendor parameters 8.3.4 WCS reference

8.3. Web Coverage Service

151

GeoServer User Manual, Release 1.7.4

152

Chapter 8. Services

CHAPTER 9

Security

This section details the security subsystem in GeoServer. The system is based on Acegi.

9.1 Accessing secured resources

The Web Administration Interface is secured by form-based authentication, with an optional rememberme cookie setting. The OGC services are secured using HTTP BASIC authentication, provided on each call. The form-based authentication is based on browser session, so if the same browser is used to access services as well, the authentication will be remembered. Here is the process for accessing a secured resource: 1. If no authentication is provided, anonymous login will be assumed. 2. If any authentication information is included, it will be used. In the case of form-based information, a session will be created to store it. In the case of HTTP BASIC authentication, session integration will be performed only if a session is already available (to avoid overhead). 3. If the resource being accessed is secured and the current user is anonymous, authentication will be requested either using HTTP BASIC authentication (for services) or by using form based login (for the web adminsitration interface). 4. If the resource accessed is secured and the currently authenticated user lacks sufcient access rights, an HTTP 404 error will be returned.

9.2 Users and roles

Security in GeoServer is a role-based system. Roles are created to serve particular functions (Examples: access WFS, administer UI, read certain layers), and users are linked to those roles.

153

GeoServer User Manual, Release 1.7.4

9.2.1 Setting users and roles

Linking users and roles is done via the le users.properties. This le is in the GeoServer data directory in the security directory. Be default, this le contains one line:
admin=geoserver,ROLE_ADMINISTRATOR

There is only one predened role: ROLE_ADMINISTRATOR. This role provides full access to all systems inside GeoServer. This le links the user admin (with password geoserver) to this role. Note: It should go without saying that if you are using GeoServer in a production environment, this default behavior should be immediately changed. Other users and roles can be created by adding to the users.properties le. The syntax is:
user=password,role[,role2,...]

where: user is the user name password is the password associated with that user role[,role2,...] is the name of the role(s) associated with this user Although the default administrator role is ROLE_ADMINISTRATOR, the naming convention is not mandatory. Multiple users can be linked with the same role. Users and passwords are case-sensitive.

9.3 Service-level security

Note: Service-level security and Layer-level security cannot be combined. For example, it is not possible to specify access to a specic OGC service on one specic layer. GeoServer allows access to be determined on a service level (WFS, WMS). Access to services is linked to roles. (See also Users and roles.) Services and roles are linked in a le called services.properties, which is located in the security directory in your GeoServer data directory.

9.3.1 Syntax
The syntax for setting security is as follows. (Parameters in brackets are optional.):
service[.method]=role[,role2,...]

where: service can be wfs, wms, or wcs method can be any method supported by the service. (Ex: GetFeature for WFS, GetMap for WMS) role[,role2,...] is the name(s) of predened roles. Note: Make sure that your role is linked to a user, unless you want to deny access to everyone. Set this in the users.properties le.

154

Chapter 9. Security

GeoServer User Manual, Release 1.7.4

9.3.2 Examples
By default, no service-level security is set. Two examples are given in the service.properties le by default, commented out:
wfs.GetFeature=ROLE_WFS_READ wfs.Transaction=ROLE_WFS_WRITE

The rst line will link access to the WFS GetFeature method to the role ROLE_WFS_READ. The second line will link access to the WFS Transactions to the role ROLE_WFS_WRITE.

9.4 Layer-level security

Note: Layer-level security and Service-level security cannot be combined. For example, it is not possible to specify access to a specic OGC service on one specic layer. GeoServer allows access to be determined on a per-layer basis. Access to layers are linked to roles. (See also Users and roles.) Layers and roles are linked in a le called layers.properties, which is located in the security directory in your GeoServer data directory.

9.4.1 Syntax
The syntax for setting security is as follows. (Parameters in brackets [] are optional):
namespace.layer.permission=role[,role2,...]

where: namespace is the name of the namespace. The wildcard * is used to indicate all namespaces. layer is the name of a featuretype or coverage. The wildcard * is used to indicate all layers. permission is the type of access permission (r for read access, w for write access). role[,role2,...] is the name(s) of predened roles. The wildcard * is used to indicate the permission is applied to all users, including anonymous users. Each entry must have a unique combination of namespace, layer, and permission values. If a permission at the global level is not specied, global permissions are assumed to allow read/write access. If a permission for a namespace is not specied, it inherits permissions from the global specication. If a permission for a layer is not specied, it inherits permissions from its namespace specication. If a user belongs to multiple roles, the least restrictive permission they inherit will apply. The layers.properties le may contain a further directive that species the way in which GeoServer will advertise secured layers and behave when a secured layer is accessed without the necessary privileges. The line is:
mode=option

where option can be one of three values:

9.4. Layer-level security

155

GeoServer User Manual, Release 1.7.4

Option hide (default)

Description Hides layers that the user does not have read access to, and behaves as if a layer is read only if the user does not have write permissions. The capabilities documents will not contain the layers the current user cannot access. This is the highest security mode. Because of this, it can sometimes not work very well with clients such as uDig or Google Earth. challenge Allows free access to metadata, but any attempt at accessing actual data is met by a HTTP 401 code (which forces most clients to show an authentication dialog). The capabilities documents contain the full list of layers. DescribeFeatureType and DescribeCoverage work ne. This mode works ne with clients such as uDig or Google Earth. mixed Hides the layers the user cannot read from the capabilities documents, but triggers authentication for any other attempt to access the data or the metadata. This option is useful if you dont want the world to see the existence of some of your data, but you still want selected people to whom you give direct data access links to get the data after authentication.

9.4.2 Examples
Protecting a single namespace and a single layer The following entries demonstrate conguring GeoServer so that it is primarily a read-only server:
*.*.r=* *.*.w=NO_ONE private.*.r=TRUSTED_ROLE private.*.w=TRUSTED_ROLE topp.congress_district.w=STATE_LEGISLATORS

In this example, here is the map of roles to permissions: Role NO_ONE TRUSTED_ROLE STATE_LEGISLATURES (All other users) Locking down GeoServer The following entries demonstrate conguring GeoServer so that it is locked down:
*.*.r=TRUSTED_ROLE *.*.w=TRUSTED_ROLE topp.*.r=* army.*.r=MILITARY_ROLE,TRUSTED_ROLE army.*.w=MILITARY_ROLE,TRUSTED_ROLE

private.* (none) r/w (none) r

topp.* w r r r

topp.congress_district (none) r r/w r

(all other namespaces) w r r r

In this example, here is the map of roles to permissions: Role TRUSTED_ROLE MILITARY_ROLE (All other users) topp.* r/w r r army.* r/w r/w (none) (All other namespaces) r/w (none) (none)

156

Chapter 9. Security

GeoServer User Manual, Release 1.7.4

A more complex situation The following entries demonstrate conguring GeoServer with global-, namepace-, and layer-level permissions:
*.*.r=TRUSTED_ROLE *.*.w=NO_ONE topp.*.r=* topp.states.r=USA_CITIZEN_ROLE,LAND_MANAGER_ROLE,TRUSTED_ROLE topp.states.w=NO_ONE topp.poly_landmarks.w=LAND_MANAGER_ROLE topp.military_bases.r=MILITARY_ROLE topp.military_bases.w=MILITARY_ROLE

In this example, here is the map of roles to permissions: Role topp.statestopp.poly_landmarks topp.military_bases topp.(all other layers) NO_ONE w r (none) w TRUSTED_ROLE r r (none) r MILITARY_ROLE (none) r r/w r USA_CITIZEN_ROLE r r (none) r LAND_MANAGER_ROLE r r/w (none) r (All other users) (none) r (none) r (All other namespaces) w r (none) (none) (none) (none)

Note: The entry topp.states.w=NO_ONE is not needed, because this permission would be inherited from the global level, i.e. the line *.*.w=NO_ONE. Invalid conguration le The following set of entries would not be valid because the namespace, layer, and permission combinations of the entries are not unique:
topp.state.rw=ROLE1 topp.state.rw=ROLE2,ROLE3

9.5 Disabling security

If you are using an external security subsystem, you may want to disable the built-in security to prevent conicts. Warning: Beware! If security is disabled, youll have to make sure the external one locks down the administration interface, otherwise it will be completely unlocked! To disable GeoServer security, rst shut down GeoServer, open the web.xml le (located inside the WEB-INF directory) and comment out the Acegi Filter Chain Proxy lter denition parameters. These two pieces of code should look something like this:
<filter> <filter-name>Acegi Filter Chain Proxy</filter-name> <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class> <init-param>

9.5. Disabling security

157

GeoServer User Manual, Release 1.7.4

<param-name>targetClass</param-name> <param-value>org.acegisecurity.util.FilterChainProxy</param-value> </init-param> </filter> <filter-mapping> <filter-name>Acegi Filter Chain Proxy</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>

Comment these sections out. When GeoServer is restarted, the internal security subsystem will be completely disabled.

158

Chapter 9. Security

CHAPTER 10

Caching with GeoWebCache

GeoWebCache is a WMS tiling client. It runs as a proxy server between a map client and map server, caching tiles as they are requested, eliminating redundant requests and saving large amounts of processing time. GeoWebCache has been integrated into GeoServer, although it is also available as a standalone product. These pages will discuss GeoServers built-in GeoWebCache instance. For information about the standalone product, please see the GeoWebCache homepage.

10.1 Setup
10.1.1 Pointing GeoWebCache to GeoServers WMS
By default, GeoWebCache expects GeoServer to be accessible at the following URL:
http://localhost:8080/geoserver

To point GeoWebCache elsewhere, you will need to specify the location of your GeoServer instances WMS GetCapabilities path. Stop GeoServer if it is currently running, and then add the following code to your GeoServers web.xml le (located in the WEB-INF directory):
<context-param> <param-name>GEOSERVER_WMS_URL</param-name> <param-value>http://example.com/path/wms?request=GetCapabilities</param-value> </context-param>

Make sure to replace the URL inside <param-value> with your GeoServer instances WMS GetCapabilities path. Restart GeoServer when done. 159

GeoServer User Manual, Release 1.7.4

Note: There is a quick link to the WMS GetCapabilities path accessible from the Welcome page of the Web Administration Interface. (See Interface basics for details.)

10.1.2 Setting the directory for cached data

GeoWebCache will automatically store cached tiles in the gwc directory inside your GeoServer data directory. To change this, stop GeoServer (if it is running) and add the following code to your GeoServers web.xml le (located in the WEB-INF directory):
<context-param> <param-name>GEOWEBCACHE_CACHE_DIR</param-name> <param-value>C:\temp</param-value> </context-param>

Make sure to change the path inside <param-value> to the desired path. Restart GeoServer when done.

10.2 Using GeoWebCache

Note: tion. For an advanced discussion of using GeoWebCache, please see the GeoWebCache documenta-

10.2.1 Cached requests vs. non-cached requests

GeoWebCache works as a proxy between your client and GeoServer, and therefore acts as its own WMS. To direct your client to GeoWebCache (and thus receive cached tiles) you only need to change the WMS URL. If your application requests WMS tiles from GeoServer at this URL:
http://example.com/geoserver/wms

You can invoke GeoWebCaches WMS instead at this URL:

http://example.com/geoserver/gwc/service/wms

In other words, add /gwc/service in between the path to your GeoServer instance and the WMS call. As soon as tiles are requested through GeoWebCache, GeoWebCache automatically starts caching. This means that initial requests for tiles will not be accelerated. To automate this process of requesting tiles, you can seed the cache. See the section on Seeding and refreshing for more details.

10.2.2 Integration with external mapping sites

The Documentation on the GeoWebCache homepage contains examples for creating applications that integrate with: Google Maps Google Earth Microsoft Virtual Earth 160 Chapter 10. Caching with GeoWebCache

GeoServer User Manual, Release 1.7.4

10.2.3 Support for custom projections

The version of GeoWebCache that comes bundled with GeoServer automatically congures every layer served in GeoServer with the two most common projections: EPSG:4326 (standard Latitude/Longitude) EPSG:900913 (Spherical Mercator, the projection used in Google Maps) If you need another projection, you can create a custom conguration le, geowebcache.xml, in the same directory that contains the cache (this path was determined in the Setup section). This conguration le is the same as used by the standalone version of GeoWebCache and documented on the GeoWebCache Conguration page. The conguration syntax directly supports the most common WMS parameters, such as style, palette, and background color. To avoid conicts, the layers in this le should be named differently from the ones that are automatically loaded from GeoServer.

10.2.4 Troubleshooting
Sometimes errors will occur when requesting data from GeoWebCache. Below are some of the most common reasons. Grid misalignment Sometimes errors will occur saying that the resolution is not supported or the bounds do not align. When this happens, it is usually due to the client making requests that do not align with the grid of tiles that GeoWebCache has created. The map bounds or layer bounds may differ from those of the grid, or the resolution may not be correct. If you are using OpenLayers as a client, looking at the source code of the included demos may provide more clues to matching up the grid.

10.3 Demo page

GeoWebCache comes with a demo page that allows quick access to some of the most basic functionality of the software. From within the demo page you can view congured layers, reload the conguration to add new layers, and seed/refresh the existing cache on a per-layer basis. Warning: Add screenshot of demo page

10.3.1 Loading
To view the GeoWebCache demo page, append /gwc/demo to the address of your GeoServer instance. For example, if your GeoServer is at the following address:
http://example.com/geoserver

The GeoWebCache demo page is accessible here:

http://example.com/geoserver/gwc/demo

If there is a problem loading this page, GeoWebCache may be set up incorrectly. Verify the steps on the Using GeoWebCache page have been carried out successfully.

10.3. Demo page

161

GeoServer User Manual, Release 1.7.4

10.3.2 Refreshing layer list

The demo page contains a list of every layer that GeoWebCache is aware of. This is related (but not always identical) to the list of layers as published in GeoServers WMS GetCapabilities document. If changes have been made to GeoServer, GeoWebCache will not automatically become aware of them. If there is a discrepancy, the Reload Conguration button will poll GeoServer for the most up-to-date list. Pressing this button will trigger authentication to GeoServer. Use the same username and password that you would use to log in to the Web Administration Interface. (See Security and Making Changes for more information.) After a successful login, the number of layers found and loaded will be displayed. Warning: Add screenshot(s) of reload conguration

10.3.3 Layers and output formats

For each layer that GeoWebCache serves, links are available for the following functions: Option OpenLayers EPSG:4326 OpenLayers EPSG:900913 Google Earth KML (PNG) Google Earth KML (vector) Custom Description Creates an OpenLayers application in the projection EPSG:4326 (standard Latitude/Longitude) Creates an OpenLayers application in the projection EPSG:900913 (Spherical Mercator, the projection used in Google Maps) Outputs raster KML for viewing in Google Earth Outputs vector KML for viewing in Google Earth

Also on the list is an option to Seed this layer. More on this option can be found on the Seeding and refreshing page.

10.4 Seeding and refreshing

The primary benet to GeoWebCache is that it allows for the acceleration of normal WMS tile request processing by eliminating the need for the tiles to be regenerated for every request. That said, the tiles need to be generated at some point, and there are two ways for tiles to be generated.

10.4.1 Generating tiles

The rst way for tiles to be generated is during normal map viewing. In this case, tiles are cached only when they are requested, either through map browsing (such as in OpenLayers) or through manual WMS tile requests. The rst time a map view is requested it will be roughly at the same speed as a standard GeoServer WMS request. The second and subsequent map viewings will be greatly accelerated as those tiles will have already been generated. The main advantage to this method is that it requires no preprocessing, and that only the data that has been requested will be cached, thus potentially saving disk space as well. The disadvantage to this method is that map viewing will be intermittently accelerated, reducing the quality of user experience. The rst way for tiles to be generated is during normal map viewing. In this case, tiles are cached only when they are requested, either through map browsing (such as in OpenLayers) or through manual WMS tile requests. The rst time a map view is requested it will be roughly at the same speed as a standard GeoServer WMS request. The second and subsequent map viewings will be greatly accelerated as those tiles will have already been generated. The main advantage to this method is that it requires

162

Chapter 10. Caching with GeoWebCache

GeoServer User Manual, Release 1.7.4

no preprocessing, and only the data requested will be cached, thus potentially saving disk space. The disadvantage to this method is that map viewing will be intermittently accelerated, reducing the quality of the user experience. The other way for tiles to be generated is by seeding. Seeding is the process where map tiles are generated and cached automatically. The advantage to this process is that the user experience is greatly enhanced, as by the time the user sees the map, it is already accelerated. The disadvantage to this process is that seeding can be a very time- and disk-consuming process.

10.4.2 Seeding options

The Demo page contains a link next to each layer entitled Seed this layer. This link will trigger authentication with the GeoServer conguration. Use the same username and password that you would use to log in to the Web Administration Interface. (See Security and Making Changes for more information.) After a successful login, a new page shows up with seeding options. Warning: Add screenshot for seeding options page The seeding options page contains various parameters for conguring the way that the layer is seeded. Option Number of threads to use Type of operation SRS Format Description Possible values are between 1 and 16.

Zoom start

Zoom stop

Bounding box

Sets the operation. There are three possible values: Seed (adds missing tiles, but does not overwrite existing ones), Reseed (like Seed, but overwrites existing tiles) and Truncate (deletes all tiles within the given parameters) Species the projection to use when creating tiles (possible values are EPSG:4326 and EPSG:900913) Sets the image format of the tiles. Can be application/vnd.google-earth.kml+xml (Google Earth KML), image/gif (GIF), image/jpeg (JPEG), image/png (24 bit PNG), and image/png8 (8 bit PNG) Sets the minimum zoom level. Lower values indicate map views that are more zoomed out. When seeding, GeoWebCache will only create tiles for those zoom levels inclusive of this value and Zoom stop. Sets the maximum zoom level. Higher values indicate map views that are more zoomed in. When seeding, GeoWebCache will only create tiles for those zoom levels inclusive of this value and Zoom start. (optional) Allows seeding to occur over a specied area, instead of the full extent of the layer. This is useful if your layer contains data over a large area, but the application will only request tiles from a certain area. The four boxes correspond to Xmin, Ymin, Xmax, and Ymax.

When nished, click Submit. Warning: Please be mindful when seeding your cache. Currently there is no progress bar to inform you of the time required to perform the operation, nor is there any intelligent handling of disk space. In short, the seed may take a very long time, and the cache may ll up your disk.

10.4. Seeding and refreshing

163

GeoServer User Manual, Release 1.7.4

10.4.3 Manually deleting cached content

If you have direct access to the le system on the server, you can also delete the appropriate layers in the cache directory (typically named gwc in the data directory, although this can be changed). The structure of the cache directory is [root] > layer > projection_zoomlevel.

164

Chapter 10. Caching with GeoWebCache

CHAPTER 11

Google Earth

This section contains information on Google Earth support in GeoServer. Google Earth is a 3-D virtual globe program. A free download from Google, it allows the user to virtually view, pan, and y around Earth imagery. The imagery on Google Earth is obtained from a variety of sources, mainly from commercial satellite and aerial photography providers. Google Earth recognizes a markup language called KML (Keyhole Markup Language) for data exchange. GeoServer integrates with Google Earth by supporting KML as a native output format. Any data congured to be served by GeoServer is thus able to take advantage of the full visualization capabilities of Google Earth.

11.1 Overview
11.1.1 Why use GeoServer with Google Earth?
GeoServer is useful when one wants to put a lot of data on to Google Earth. GeoServer automatically generates KML that can be easily and quickly served and visualized in Google Earth. GeoServer operates entirely through a Network Link, which allows it to selectively return information for the area being viewed. With GeoServer as a robust and powerful server and Google Earth providing rich visualizations, they are a perfect match for sharing your data.

11.1.2 Standards-based implementation

GeoServer supports Google Earth by providing KML as a Web Map Service (WMS) output format. This means that adding data published by GeoServer is as simple as constructing a standard WMS request and specifying application/vnd.google-earth.kml+xml as the outputFormat. Since generating KML is just a WMS request, it fully supports Styling via SLD. See the next section (Quickstart) to view GeoServer and Google Earth in action.

11.2 Quickstart
Note: If you are using GeoServer locally, the GEOSERVER_URL is usually

165

GeoServer User Manual, Release 1.7.4

http://localhost:8080/geoserver

11.2.1 Viewing a layer

Once GeoServer is installed and running, open up a web browser and navigate to the Welcome page. Navigate to the web_admin_map_preview by clicking Demo then Map Preview. You will be presented with a list of the currently congured layers in your GeoServer instance. Find the row that says topp:states. To the right of the layer click on the link that says KML.

Figure 11.1: The Map Preview page

If Google Earth is correctly installed on your computer, you will see a dialog asking how to open the le. Select Open with Google Earth.

When Google Earth is nished loading the result will be similar to below.

166

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

Figure 11.2: Open with Google Earth

11.2. Quickstart

167

GeoServer User Manual, Release 1.7.4

Figure 11.3: The topp:states layer rendered in Google Earth

11.2.2 Direct access to KML

All of the congured FeatureTypes are available to be output as KML (and thus loaded into Google Earth). The URL structure for KMLs is:
http://GEOSERVER_URL/wms/kml?layers=<layername>

For example, the topp:states layer URL is:

http://GEOSERVER_URL/wms/kml?layers=topp:states

11.2.3 Adding a Network Link

An alternative to serving KML directly into Google Earth is to use a Network Link. A Network Link allows for better integration into Google Earth. For example, using a Network Link enables the user to refresh the data within Google Earth, without having to retype a URL, or click on links in the GeoServer Map Preview again. To add a Network Link, pull down the Add menu, and go to Network Link. The New Network Link dialog box will appear. Name your layer in the Name eld. (This will show up in My Places on the main Google Earth screen.) Set Link to:
http://GEOSERVER_URL/wms/kml?layers=topp:states

168

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

(Dont forget to replace the GEOSERVER_URL.) Click OK. You can now save this layer in your My Places.

Figure 11.4: Adding a network link

Check out the sections on Tutorials and the KML Styling for more information.

11.3 KML Styling

11.3.1 Introduction
Keyhole Markup Langauge (KML), when created and output by GeoServer, is styled using Styled Layer Descriptors (SLD). This is the same approach used to style standard WMS output formats, but is a bit different from how Google Earth is normally styled, behaving more like Cascading Style Sheets (CSS). The style of the map is specied in the SLD le as a series of rules, and then the data matching those rules is styled appropriately in the KML output. For those unfamiliar with SLD, a goo place to start is the Introduction to SLD. The remainder of this guide contains information about how to construct SLD documents in order to impact the look of KML produced by GeoServer.

11.3. KML Styling

169

GeoServer User Manual, Release 1.7.4

Contents Basic SLD Creation Wizard SLD Structure Points Lines Polygons Text Labels Descriptions

11.3.2 Basic SLD Creation Wizard

GeoServer includes a very basic wizard for creating styles from scratch. This wizard can be accessed from your GeoServers admin page by going to the FeatureType editor. From the Welcome page, navigate to Cong -> Data -> FeatureTypes -> Edit) Click the button that says Create new SLD.

Figure 11.5: Figure 1: Invoking the SLD creation wizard A new screen will appear that allows you to customize how your data will appear on a map. (Figure 2 refers to what will be seen when styling line data; styling polygons and points will make this page look slightly different.) Fill in all the required elds. When nished, click Apply Style and then Finished.

11.3.3 SLD Structure

The following is a skeleton of a SLD document. It can be used as a base on which to expand upon to create more interesting and complicated styles.
<StyledLayerDescriptor version="1.0.0" xsi:schemaLocation="http://www.opengis.net/sld StyledLayerDescriptor.xsd" xmlns="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <NamedLayer> <Name>Default Line</Name> <UserStyle> <Title>My Style</Title> <Abstract>A style</Abstract>

170

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

Figure 11.6: Figure 2: Using the SLD creation wizard to style line data

11.3. KML Styling

171

GeoServer User Manual, Release 1.7.4

<FeatureTypeStyle> <Rule> <!-- symbolizers go here --> </Rule> </FeatureTypeStyle> </UserStyle> </NamedLayer> </StyledLayerDescriptor>

Figure 3: Basic SLD structure In order to test the code snippets in this document, create an SLD with the content as shown in Figure 3, and then add the specic code you wish to test in the space that says <!-- symbolizers go here -->. To view, edit, or add SLD les to GeoServer, navigate to Cong -> Data -> Styles.

11.3.4 Points
In SLD, styles for points are specied via a PointSymbolizer. An empty PointSymbolizer element will result in a default KML style:
<PointSymbolizer> </PointSymbolizer>

Figure 11.7: Figure 4: Default point Three aspects of points that can be specied are color, opacity, and the icon. Point Color The color of a point is specied with a CssParameter element and a fill attribute. The color is specied as a six digit hexadecimal code.

172

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

<PointSymbolizer> <Graphic> <Mark> <Fill> <CssParameter name="fill">#ff0000</CssParameter> </Fill> </Mark> </Graphic> </PointSymbolizer>

Figure 11.8: Figure 5: Setting the point color (#ff0000 = 100% red)

Point Opacity The opacity of a point is specied with a CssParameter element and a fill-opacity attribute. The opacity is specied as a oating point number between 0 and 1, with 0 being completely transparent, and 1 being completely opaque.
<PointSymbolizer> <Graphic> <Mark> <Fill> <CssParameter name="fill-opacity">0.5</CssParameter> </Fill> </Mark> </Graphic> </PointSymbolizer>

Point Icon An icon different from the default can be specied with the ExternalGraphic element:

11.3. KML Styling

173

GeoServer User Manual, Release 1.7.4

Figure 11.9: Figure 6: Setting the point opacity (0.5 = 50% opaque)

<PointSymbolizer> <Graphic> <ExternalGraphic> <OnlineResource xlink:type="simple" xlink:href="http://maps.google.com/mapfiles/kml/pal3/icon55.png"/> <Format>image/png</Format> </ExternalGraphic> </Graphic> </PointSymbolizer>

Figure 11.10: Figure 7: A custom icon for points In Figure 7, the custom icon is specied as a remote URL. It is also possible to place the graphic in the GeoServer styles directory, and then specify the lename only: 174 Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

<PointSymbolizer> <Graphic> <ExternalGraphic> <OnlineResource xlink:type="simple" xlink:href="icon55.png"/> <Format>image/png</Format> </ExternalGraphic> </Graphic> </PointSymbolizer>

Figure 8: Specifying a local le for a graphic point

11.3.5 Lines
Styles for lines are specied via a LineSymbolizer. An empty LineSymbolizer element will result in a default KML style:
<LineSymbolizer> </LineSymbolizer>

Figure 11.11: Figure 9: Default line

11.3. KML Styling

175

GeoServer User Manual, Release 1.7.4

The aspects of the resulting line which can be specied via a LineSymbolizer are color, width, and opacity. Line Color The color of a line is specied with a CssParameter element and a stroke attribute. The color is specied as a six digit hexadecimal code.
<LineSymbolizer> <Stroke> <CssParameter name="stroke">#ff0000</CssParameter> </Stroke> </LineSymbolizer>

Figure 11.12: Figure 10: Line rendered with color #ff0000 (100% red)

Line Width The width of a line is specied with a CssParameter element and a stroke-width attribute. The width is specied as an integer (in pixels): 176 Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

<LineSymbolizer> <Stroke> <CssParameter name="stroke-width">5</CssParameter> </Stroke> </LineSymbolizer>

Figure 11.13: Figure 11: Line rendered with a width of ve (5) pixels

Line Opacity The opacity of a line is specied with a CssParameter element and a fill-opacity attribute. The opacity is specied as a oating point number between 0 and 1, with 0 being completely transparent, and 1 being completely opaque.
<LineSymbolizer> <Stroke> <CssParameter name="stroke-opacity">0.5</CssParameter> </Stroke> </LineSymbolizer>

11.3. KML Styling

177

GeoServer User Manual, Release 1.7.4

Figure 11.14: Figure 12: A line rendered with 50% opacity

178

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

11.3.6 Polygons
Styles for polygons are specied via a PolygonSymbolizer. An empty PolygonSymbolizer element will result in a default KML style:
<PolygonSymbolizer> </PolygonSymbolizer>

Polygons have more options for styling than points and lines, as polygons have both an inside (ll) and an outline (stroke). The aspects of polygons that can be specied via a PolygonSymbolizer are stroke color, stroke width, stroke opacity, ll color, and ll opacity. Polygon Stroke Color The outline color of a polygon is specied with a CssParameter element and stroke attribute inside of a Stroke element. The color is specied as a 6 digit hexadecimal code:
<PolygonSymbolizer> <Stroke> <CssParameter name="stroke">#0000FF</CssParameter> </Stroke> </PolygonSymbolizer>

Polygon Stroke Width The outline width of a polygon is specied with a CssParameter element and stroke-width attribute inside of a Stroke element. The width is specied as an integer.
<PolygonSymbolizer> <Stroke> <CssParameter name="stroke-width">5</CssParameter> </Stroke> </PolygonSymbolizer>

Figure 14: Polygon with stroke width of ve (5) pixels Polygon Stroke Opacity The stroke opacity of a polygon is specied with a CssParameter element and stroke attribute inside of a Stroke element. The opacity is specied as a oating point number between 0 and 1, with 0 being completely transparent, and 1 being completely opaque.
<PolygonSymbolizer> <Stroke> <CssParameter name="stroke-opacity">0.5</CssParameter> </Stroke> </PolygonSymbolizer>

11.3. KML Styling

179

GeoServer User Manual, Release 1.7.4

Figure 11.15: Figure 13: Outline of a polygon (#0000FF or 100% blue)

180

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

11.3. KML Styling

181

GeoServer User Manual, Release 1.7.4

Figure 11.16: Figure 15: Polygon stroke opacity of 0.5 (50% opaque)

182

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

Polygon Fill Color The ll color of a polygon is specied with a CssParameter element and fill attribute inside of a Fill element. The color is specied as a six digit hexadecimal code:
<PolygonSymbolizer> <Fill> <CssParameter name="fill">#0000FF</CssParameter> </Fill> </PolygonSymbolizer>

Figure 11.17: Figure 16: Polygon ll color of #0000FF (100% blue)

Polygon Fill Opacity The ll opacity of a polygon is specied with a CssParameter element and fill-opacity attribute inside of a Fill element. The opacity is specied as a oating point number between 0 and 1, with 0 being completely transparent, and 1 being completely opaque.

11.3. KML Styling

183

GeoServer User Manual, Release 1.7.4

<PolygonSymbolizer> <Fill> <CssParameter name="fill-opacity">0.5</CssParameter> </Fill> </PolygonSymbolizer>

Figure 11.18: Figure 17: Polygon ll opacity of 0.5 (50% opaque)

11.3.7 Text Labels

There are two ways to specify a label for a feature in Google Earth. The rst is with Freemarker templates (LINK?), and the second is with a TextSymbolizer. Templates take precedence over symbolizers. Freemarker Templates Specifying labels via a Freemarker template involves creating a special text le called title.ftl and placing it into the featureTypes directory (inside the GeoServer data directory) for the dataset to be labeled. For example, to create a template to label the states dataset by state name one would create the le here: <data_dir>/featureTypes/states/title.ftl. The content of the le would be: 184 Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

${STATE_NAME.value}

Figure 11.19: Figure 18: Using a Freemarker template to display the value of STATE_NAME For more information on Placemark Templates, please see our full tutorial (LINK FORTHCOMING). TextSymbolizer In SLD labels are specied with the Label element of a TextSymbolizer. (Note the ogc: prex on the PropertyName element.)
<TextSymbolizer> <Label> <ogc:PropertyName>STATE_NAME</ogc:PropertyName> </Label> </TextSymbolizer>

The aspects of the resulting label which can be specied via a TextSymbolizer are color and opacity.

11.3. KML Styling

185

GeoServer User Manual, Release 1.7.4

Figure 11.20: Figure 19: Using a TextSymbolizer to display the value of STATE_NAME

186

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

TextSymbolizer Color The color of a label is specied with a CssParameter element and fill attribute inside of a Fill element. The color is specied as a six digit hexadecimal code:
<TextSymbolizer> <Label> <ogc:PropertyName>STATE_NAME</ogc:PropertyName> </Label> <Fill> <CssParameter name="fill">#000000</CssParameter> </Fill> </TextSymbolizer>

Figure 11.21: Figure 20: TextSymbolizer with black text color (#000000)

TextSymbolizer Opacity The opacity of a label is specied with a CssParameter element and fill-opacity attribute inside of a Fill element. The opacity is specied as a oating point number between 0 and 1, with 0 being completely transparent, and 1 being completely opaque. 11.3. KML Styling 187

GeoServer User Manual, Release 1.7.4

<TextSymbolizer> <Label> <ogc:PropertyName>STATE_NAME</ogc:PropertyName> </Label> <Fill> <CssParameter name="fill-opacity">0.5</CssParameter> </Fill> </TextSymbolizer>

Figure 11.22: Figure 21: TextSymbolizer with opacity 0.5 (50% opaque)

11.3.8 Descriptions
When working with KML, each feature is linked to a description, accessible when the feature is clicked on. By default, GeoServer creates a list of all the attributes and values for the particular feature. It is possible to modify this default behavior. Much like with featureType titles, which are edited by creating a title.ftl template, a custom description can be used by creating template called description.ftl and placing it into the featureTypes directory (inside the GeoServer data directory) for the dataset. For instance, to create a template to provide a description for the states dataset, one would create the le: 188 Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

Figure 11.23: Figure 22: Default description for a feature

11.3. KML Styling

189

GeoServer User Manual, Release 1.7.4

<data_dir>/featureTypes/states/description.ftl. As an example, if the content of the description template is:

This is the state of ${STATE_NAME.value}.

The resultant description will look like this:

Figure 11.24: Figure 23: A custom description It is also possible to create one description template for all featureTypes in a given namespace. To do this, create a description.ftl le as above, and save it as <data_dir>/templates/<namespace>/description.ftl. Please note that if a description template is created for a specic featureType that also has an associated namespace description template, the featureType template (i.e. the most specic template) will take priority. One can also create more complex descriptions using a combination of HTML and the attributes of the data. A full tutorial on how to use templates to create descriptions is available in our page on KML Placemark Templates. (LINK?) 190 Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

Basic SLD Creation Wizard SLD Structure Points Lines Polygons Text Labels Descriptions

11.4 Tutorials
11.4.1 Placemark Templates 11.4.2 Height Templates 11.4.3 Time Templates 11.4.4 Super-Overlays and GeoWebCache 11.4.5 Super-Overlays and Extrudes with Building Data

11.5 Features
This section delves into greater detail about the various functionality and options possible with KML output and Google Earth.

11.5.1 KML Reector

Standard WMS requests can be quite long and cumbersome. The following is an example of a request for KML output from GeoServer:

http://localhost:8080/geoserver/ows?service=WMS&request=GetMap&version=1.1.1&format=application/vnd.g

GeoServer includes an alternate way of requesting KML, and that is to use the KML reector. The KML reector is a simpler URL-encoded request that uses sensible defaults for many of the parameters in a standard WMS request. Using the KML reector one can shorten the above request to:
http://localhost:8080/geoserver/wms/kml?layers=topp:states

Using the KML reector The only mandatory parameter is the layers parameter. The syntax is as follows:
http://GEOSERVER_URL/wms/kml?layers=<layer>

where GEOSERVER_URL is the URL of your GeoServer instance, and <layer> is the name of the featuretype to be served. The following table lists the default assumptions:

11.4. Tutorials

191

GeoServer User Manual, Release 1.7.4

Key request service version srs format width height bbox kmattr kmplacemark kmscore styles

Value GetMap wms 1.1.1 EPSG:4326 applcation/vnd.google-earth.kmz+xml 256 256 <layer bounds> true false 50 [default style for the featuretype]

Any of these defaults can be changed when specifying the request. For instance, to specify a particular style, one can append styles=population to the request:
http://localhost:8080/geoserver/wms/kml?layers=topp:states&styles=population

To specify a different bounding box, append the parameter to the request:

http://localhost:8080/geoserver/wms/kml?layers=topp:states&bbox=-124.73,24.96,-66.97,49.37

Reector modes The KML reector can operate in one of three modes: superoverlay, refresh, and download. The mode is set by appending the following parameter to the URL:
mode=<mode>

where <mode> is one of the three reector modes. The details for each mode are as follows: Mode Description superoverlay (default for versions 1.7.1 and later) Returns KML as a super-overlay. A super-overlay is a form of KML in which data is broken up into regions. Please see the section on KML Super-Overlays for more information. refresh (default for versions prior to 1.7.1) Returns dynamic KML that can be refreshed/updated by the Google Earth client. Data is refreshed and new data/imagery is downloaded when zooming/panning stops. This mode can return either vector or raster (placemark or overlay) The decision to return either vector or raster data is determined by the value of kmscore. Please see the section on KML Scoring for more information. download Returns KML which contains the entire data set. In the case of a vector layer, this will include a series of KML placemarks. With raster layers, this will include a single KML ground overlay. This is the only mode that doesnt dynamically request new data from the server, and thus is self-contained KML. More about the superoverlay mode When requesting KML using the superoverlay mode, there are four additional submodes available regarding how and when data is requested. These options are set by appending the following parameter to the KML reector request:

192

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

superoverlay_mode=<submode>

where <submode> is one of the following options: Submode auto Description

(default) Always returns vector features if the original data is in vector form, and returns raster imagery if the original data is in raster form. This can sometimes be less than optimal if the geometry of the features are very complicated, which can slow down Google Earth. raster Always returns raster imagery, regardless of the original data. This is almost always faster, but all vector information is lost in this view. overview Displays either vector or raster data depending on the view. At higher zoom levels, raster imagery will be displayed, and at lower zoom levels, vector features will be displayed. The determination for when to switch between vector and raster is made by the regionation parameters set on the server. See the section on KML Regionation for more information. hybrid Displays both raster and vector data at all times.

11.5.2 Toggling Placemarks

Vector Placemarks When GeoServer generates KML for a vector dataset, it attaches information from the data to each feature that is created. When clicking on a vector feature, a pop-up window is displayed. This is called a placemark. By default this is a simple list which displays attribute data, although this information can be customized using Freemarker templates. If you would like this information not to be shown when a feature is clicked (either for security reasons, or simply to have a cleaner user interface), it is possible to disable this functionality. To do so, use the kmattr parameter in a KML request to turn off attribution. The syntax for kmattr is as follows:
format_options=kmattr:[true|false]

Note that kmattr is a format option, so the syntax is slightly different from the usual key-value pair. For example:
http://localhost:8080/geoserver/wms/kml?layers=topp:states&format_options=kmattr:false

Raster Placemarks Unlike vector features, where the placemark is enabled by default, placemarks are disabled by default with raster images of features. To enable this feature, you can use the kmplacemark format option in your KML request. The syntax is similar to the kmattr format option specied above:
format_options=kmplacemark:[true|false]

For example, using the KML reector, the syntax would be:
http://localhost:8080/geoserver/wms/kml?layers=topp:states&format_options=kmplacemark:true

11.5. Features

193

GeoServer User Manual, Release 1.7.4

11.5.3 Customizing Placemarks

KML output can leverage some powerful visualization abilities in Google Earth. Titles can be displayed on top of the features. Descriptions (custom HTML shown when clicking on a feature) can be added to customize the views of the attribute data. In addition, using Google Earths time slider, time-based animations can be created. Finally, height of features can be set, as opposed to the default ground overlay. All of these can be accomplished by creating Freemarker templates. Freemarker templates are text les (with limited HTML code), saved in the GeoServer Data Directory, that utilize variables that link to specic attributes in the data. Titles Specifying labels via a template involves creating a special text le called title.ftl and placing it into the featuretypes directory inside the GeoServer Data Directory for the dataset to be labeled. For instance, to create a template to label the states layer by state name, one would create the le: <data_dir>/featureTypes/states/title.ftl. The content of the le would be:
${STATE_NAME.value}

Descriptions When working with KML, each feature is linked to a description, accessible when the feature is clicked on. By default, GeoServer creates a list of all the attributes and values for the particular feature. It is possible to modify this default behavior. Much like with featuretype titles, which are edited by creating a title.ftl template, specifying descriptions via a template involves creating a special text le called description.ftl and placing it into the featuretypes directory inside the GeoServer Data Directory for the dataset to be labeled. For instance, a sample description template would be saved here: <data_dir>/featureTypes/states/description.ftl. The content of the le could be:
This is the state of ${STATE_NAME.value}.

The resulting description will look like this: Warning: Add SS: A custom description It is also possible to create one description template for all layers in a given namespace. To do this, create a description.ftl le as above, and save it here:
<data_dir>/templates/<namespace>/description.ftl.

Please note that if a description template is created for a specic layer that also has an associated namespace description template, the layer template (i.e. the most specic template) will take priority.

11.5.4 KML Height and Time

Height GeoServer by default creates two dimensional overlays in Google Earth. However, GeoServer can output features with height information (also called KML extrudes) if desired. This can have the effect of having

194

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

features oat above the ground, or create bar graph style structures in the shape of the features. The height of features can be linked to an attribute of the data. Setting the height of features is determined by using a KML Freemarker template. Create a le called height.ftl, and save it in the same directory as the featuretype in your GeoServer Data Directory. For example, to create a height template for the states layer, the le should be saved in <data_dir>/featureTypes/states/height.ftl. To set the height based on an attribute, the syntax is:
${ATTRIBUTE.value}

Replace the word ATTRIBUTE with the name of the height attribute in your data set. Time Google Earth also contains a time slider, which can allow animations of data, and show changes over time. As with height, time can be linked to an attirbute of the data, as long as the data set has a date/time attribute. Lnking this date/time attribute to the time slider in Google Earth is accomplished by creating a Freemarker template. Create a le called time.ftl, and save it in the same directory that contains your datas info.xml. To set the time based on an attribute the syntax is:
${DATETIME_ATTRIBUTE.value}

Replace the word DATETIME_ATTRIBUTE with the name of the date/time attribute. When creating KML, GeoServer will automatically link the data to the time element in Google Earth. If set successfully, the time slider will automatically appear.

11.5.5 KML Legends

WMS includes a GetLegendGraphic operation which allows a WMS client to obtain a legend graphic from the server for a particular layer. Combining the legend with KML overlays allows the legend to be viewed inside Google Earth. To get GeoServer to include a legend with the KML output, append legend=true to the KML reector request. For example:
http://localhost:8080/geoserver/wms/kml?layers=topp:states&legend=true

The resulting Google Earth output looks like this: Warning: Add SS with legend.

11.5.6 Filters
Though not specic to Google Earth, GeoServer has the ability to lter data returned from the Web Map Service. The KML Reector will pass through any WMS filter or cql_filter parameter to GeoServer to constrain the response. Note: Filters are basically a translation of a SQL WHERE statement into web form. Though limited to a single table, this allows users to do logical lters like AND and OR to make very complex queries,

11.5. Features

195

GeoServer User Manual, Release 1.7.4

leveraging numerical and string comparisons, geometric operations (bbox, touches, intersects, disjoint), LIKE statements, nulls, and more. Filter There simplest lter is very easy to include. It is called the featureid lter, and it lets you lter to a single feature by its ID. The syntax is:
featureid=<feature>

where <feature> is the feature and its ID. An example would be:
http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&featureid=states.5

This request will output only the state of Maryland. The feature IDs of your data are most easily found by doing WFS or KML requests and examining the resulting output. CQL Filter Using lters in a URL can be very unwieldy, as one needs to include URL-encoded XML:

http:/localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&FILTER=%3CFilter%3E%3CPropertyIsBet

Instead, one can use Common Query Language (CQL), which allows one to specify the same statement more succinctly:

http://localhost:8080/geoserver/wms/kml?layers=topp:states&CQL_FILTER=LAND_KM+BETWEEN+100000+AND+1500

This query will return all the states in the US with areas between 100,000 and 150,000 km^2.

11.5.7 KML Super-Overlays

Super-overlays are a form of KML in which data is broken up into regions. This allows Google Earth to refresh/request only particular regions of the map when the view area changes. Super-overlays are used to efciently publish large sets of data. (Please see Googles page on super-overlays for more information.) GeoServer supports two types of super-overlays: raster and vector. With raster super-overlays, GeoServer intelligently produces imagery appropriate to the current zoom level and dynamically outputs new imagery when the zoom level changes. With vector super-overlays, feature data is requested for only the visible features and new features are dynamically loaded as necessary. Raster super-overlays require less resources on the client, but vector super-overlays have a higher output quality. When using the KML Reector, super-overlays are enabled by default, whether the data in question is raster or vector. For more information on the various options for KML super-overlay output, please see the page on the KML Reector.

196

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

Raster Super-Overlays Consider this image, which is generated from GeoServer. When zoomed out, the data is at a small size. Warning: Add SS from old site, Fig 1 When zooming in, the image grows larger, but since the image is at low resolution (orignially designed to be viewed small), the quality degrades. Warning: Add SS from old site, Fig 2 However, in a super-overlay, the KML document requests a new image from GeoServer of a higher resolution for that zoom level. As the new image is downloaded, the old image is replaced by the new image. Warning: Add SS from old site, Fig 3

Raster Super-Overlays and GeoWebCache GeoServer implements super-overlays in a way that is compatible with the WMS Tiling Client Recommendation. Super-overlays are generated such that the tiles of the super-overlay are the same tiles that a WMS tiling client would request. One can therefore use existing tile caching mechanisms and reap a potentially large performance benet. The easiest way to tile cache a raster super overlay is to use GeoWebCache which is built into GeoServer:
http://GEOSERVER_URL/gwc/service/kml/<layername>.<imageformat>.kmz

where GEOSERVER_URL is the URL of your GeoServer instance. It is also possible to use TileCache with raster super-overlays. Vector Super-Overlays GeoServer can include the feature information directly in the KML document. This has lots of benets. It allows the user to select (click on) features to see descriptions, toggle the display of individual features, as well as have better rendering, regardless of zoom level. For large datasets, however, the feature information can take a long time to download and use a lot of client-side resources. Vector super-overlays allow the client to only download part of a dataset, and request more features as necessary. Vector super-overlays can use the process of KML Regionation to organize features into a hierarchy. The regionation process can operate in a variety of modes. Most of the modes require a regionation attribute which is used to determine which features should be visible at a particular zoom level. Please see the KML Regionation page for more details. Vector Super-Overlays and GeoWebCache As with raster super-overlays, it is possible to cache vector super-overlays using GeoWebCache. Below is the syntax for generating a vector super-overlay KML document via GeoWebCache:

11.5. Features

197

GeoServer User Manual, Release 1.7.4

http://GEOSERVER_URL/gwc/service/kml/<layername>.kml.kmz

where GEOSERVER_URL is the URL of your GeoServer instance. Unlike generating a super-overlay with the standard KML Reector, it is not possible to specify the regionation properties as part of the URL. These parameters must be set in the FeatureTypes conguration in the Cong menu section of the Web Administration Interface. (Cong -> Data -> FeatureType -> Edit)

11.5.8 KML Regionation

Displaying vector features on Google Earth is a very powerful way of creating nicely-styled maps. However, it is not always optimal to display all features at all times. Displaying too many features can create an unsightly map, and can adversely affect Google Earths performance. To combat this, GeoServers KML output includes the ability to limit features based on certain criteria. This process is known as regionation. Regionation is active by default when using the superoverlay KML reector mode. Regionation Attributes The most important aspect of regionation is to decide how to determine which features show up more prominently than others. This can be done either by geometry, or by attribute. One should choose the option that best exemplies the relative importance of the feature. When choosing to regionate by geometry, only the larger lines and polygons will be displayed at higher zoom levels, with smaller ones being displayed when zooming in. When regionating by an attribute, the higher value of this attribute will make those features show up at higher zoom levels. (Choosing an attribute with a non-numeric value will be ignored, and will instead default to regionation by geometry.) Regionation Strategies Regionation strategies sets how to determine which features should be shown at any given time or zoom level. There are ve types of regionation strategies: Strategy Description best_guess (default) The actual strategy is determined by the type of data being operated on. If the data consists of points, the random strategy is used. If the data consists of lines or polygons, the geometry strategy is used. external-sorting Creates a temporary auxiliary database within GeoServer. It takes slightly extra time to build the index upon rst request. native-sorting Uses the default sorting algorithm of the backend where the data is hosted. It is faster than external-sorting, but will only work with PostGIS datastores. geometry Externally sorts by length (if lines) or area (if polygons). random Uses the existing order of the data and does not sort. In most cases, the best_guess strategy is sufcient. Setting Regionation Parameters Regionation strategies and attributes are featuretype-specic, and therefore are set in the FeatureTypes editing page in the Cong menu of the Web Administration Interface. (Cong -> Data -> FeatureType -> Edit)

198

Chapter 11. Google Earth

GeoServer User Manual, Release 1.7.4

11.5.9 KML Scoring

Note: KML scoring only applies when using the super-overlay mode refresh. See KML Super-Overlays for more information. GeoServer can return KML in one of two forms. The rst is as a number of placemark elements (vectors). Each placemark corresponds to a feature in the underlying dataset. This form only applies to vector datasets. The second form is as an overlay (image). In this form the rendering is done by the GeoServer WMS and only the resulting graphic is sent to Google Earth. This is the only form available for raster datasets, but can be applied to vector datasets as well. There are advantages to and disadvantages to each output mode when rendering vector data. Placemarks look nicer, but there can be performance problems with Google Earth if the data set is large. Overlays put less of a strain on Google Earth, but arent as nice looking. The following shows the same dataset rendered in Placemark form on the left and Overlay form on the right. Warning: SS Placemark Warning: SS Overlay KML scoring is the process of determing whether to render features as rasters or as vectors. The kmscore attribute GeoServer makes the determination on whether to render a layer as raster or vector based on how many features are in the data set and an attribute called kmscore. The kmscore attribute determines the maximum amount of vector features rendered. It is calculated by this formula:
maximum number of features = 10^(kmscore/15)

The following table shows the values of this threashold for various values of the kmscore parameter: kmscore 0 10 20 30 40 50 60 70 80 90 100 Maximum # of features Force overlay/raster output 4 21 100 Approx. 450 (default) Approx. 2150 Approx. 10,000 Approx. 45,000 Approx. 200,000 Approx. 1,000,000 Force placemark/vector output

The syntax for specifying kmscore is:

kmscore=<value>

where <value> is an integer between 0 and 100. For example:

11.5. Features

199

GeoServer User Manual, Release 1.7.4

http://localhost:8080/geoserver/wms/kml?layers=topp:states&mode=refresh&kmscore=20

The kmscore attribute will be ignored if using a reector mode other than refresh.

200

Chapter 11. Google Earth

CHAPTER 12

Running In A Production Environment

GeoServer is geared towards many different uses, from the simple test to the enterprise-level data server. While many of the optimizations for GeoServer are set by default, here are some considerations for running GeoServer in a production environment.

12.1 Java Considerations

12.1.1 Use Suns JDK
GeoServer speed depends a lot on the chosen Java Development Kit (JDK). For best performance, use Sun JDK 1.6 (also known as JDK 6). If this is not possible, use Sun JDK 1.5. Non-Sun JDKs may work, but are generally not tested or supported. OpenJDK currently does not work with GeoServer, as it lacks sufcient support for 2D rendering.

12.1.2 Install native JAI extensions

The Java Advanced Imaging API (JAI) is an advanced image manipulation library built by Sun. GeoServer requires JAI to work with coverages and leverages it for WMS output generation. By default, GeoServer ships with the pure Java version of JAI, but for best performance, install the native JAI version in your JDK. Installing native JAI Please refer to the GeoTools page on JAI installation Once you have installed JAI, you may remove the JAI related les from your GeoServer instance:
jai_core-x.y.z.jar jai_imageio-x.y.jar jai_codec-x.y.z.jar

where x, y, and z refer to specic version numbers.

201

GeoServer User Manual, Release 1.7.4

12.2 Container Considerations

Java web containers such as Tomcat or Jetty ship with congurations that allow for quick startup but dont always deliver the best performance.

12.2.1 Optimize your JVM

Set the following performance settings in the Java virtual machine for your container. These settings are not specic to any container. Option -server Description Enables the server Java Virtual Machine (JVM), which compiles bytecode much earlier and with stronger optimizations. Startup and initial calls will be slower due to just-in-time (JIT) compilation taking longer, but subsequent calls will be faster. -Xmx256M -Xms48m Allocates extra memory to your server. By default, JVM will use only 64MB of heap. If youre serving just vector data, youll be streaming, so having more memory wont increase performance. If youre serving coverages, however, JAI will use a disk cache. -Xmx256M allocates 256MB of memory to GeoServer (use more if you have excess memory). It is also a good idea to congure the JAI tile cache size (see the Server page in the Web Administration Interface section) so that it uses 75% of the heap (0.75). -Xmx48m will tell the virtual machine to grab a 48MB heap on startup, which will make heap management more stable during heavy load serving. -XX:SoftRefLRUPolicyMSPerMB=36000 Increases the lifetime of soft references in GeoServer. GeoServer uses soft references to cache datastore references and other similar requests. Making them live longer will increase the effectiveness of the cache. -XX:MaxPermSize=128m Increases the maximum size of permanent generation (or permgen) allocated to GeoServer to 128MB. Permgen is the heap portion where the class bytecode is stored. GeoServer uses lots of classes, and it may exhaust that space quickly, leading to out of memory errors. This is especially important if youre deploying GeoServer along with other applications in the same container, or if you need to deploy multiple GeoServer instances inside the same container. -XX:XX:+UseParallelGC Enables the throughput garbage collector. For more information about JVM conguration, see the article Performance tuning garbage collection in Java.

12.3 Conguration Considerations

12.3.1 Use production logging
Logging may visibly affect the performance of your server. High logging levels are often necessary to track down issues, but by default you should run with low levels. (You can switch the logging levels at runtime, so dont worry about having to stop the server to gather more information.) You can change the logging level by going to the :ref:web_admin_cong_server section of the Web Administration Interface. Youll want to choose the PRODUCTION conguration.

202

Chapter 12. Running In A Production Environment

GeoServer User Manual, Release 1.7.4

12.3.2 Set a service strategy

A service strategy is the method in which output is served to the client. This is a balance between proper form (being absolutely sure of reporting errors with the proper OGC codes, etc) and speed (serving output as quickly as possible). This is a decision to be made based on the function that GeoServer is providing for you. You can congure the service strategy by modifying the web.xml le of your GeoServer instance. The possible strategies are: Strategy SPEED Description Serves output right away. This is the fastest strategy, but proper OGC errors are usually omitted. BUFFER Stores the whole result in memory, and then serves it after the output is complete. This ensures proper OGC error reporting, but delays the response quite a bit and can exhaust memory if the response is large. FILE Similar to BUFFER, but stores the whole result in a le instead of in memory. Slower than BUFFER, but ensures there wont be memory issues. PARTIAL-BUFFER A balance between BUFFER and SPEED, this strategy tries to buffer in memory a few KB of response, then serves the full output.

12.3.3 Personalize your server

This is isnt a performance consideration, but is just as important. In order to make GeoServer as useful as possible, you should customize the servers metadata to your organization. It may be tempting to skip some of the conguration steps, and leave in the same keywords and abstract as the sample. But this will only confuse potential users. Here is a short list: Fill out WFS, WMS, and WCS Contents sections (this info will be broadcast as part of the GetCapabilities documents) Serve your data with your own namespace (and provide a correct URI) Remove default layers (such as topp:states)

12.3.4 Set security

GeoServer by default includes WFS-T (transactions), which lets users modify your data. If you dont want your database modied, you can turn off transactions in the Cong WFS Content section of the Web Administration Interface. Set the Service Level to Basic. If youd like some users to be able to modify some but not all of your data, you will have to set up an external security service. An easy way to accomplish this is to run two GeoServer instances and congure them differently, and use a simple authentication to only allow certain users to have access. For extra security, make sure that the connection to the datastore that is open to all is with a user who has read only permissions. This will eliminate the possibility of a SQL injection (though GeoServer is generally not vulnerable to that sort of attack).

12.3.5 Cache your data

Server-side caching of WMS tiles is the best way to increase performance. In caching, pre-rendered tiles will be saved, eliminating the need for redundant WMS calls. There are several ways to set up WMS caching for GeoServer. GeoWebCache is the simplest method, as it comes bundled with GeoServer. (See the section on 12.3. Conguration Considerations 203

GeoServer User Manual, Release 1.7.4

Caching with GeoWebCache for more details.) Another option is TileCache. You can also use a more generic caching system, such as OSCache (an embedded cache service) or Squid (a web cache proxy).

12.4 Data Considerations

12.4.1 Use an external data directory
GeoServer comes with a data directory inside the container. However, it is a good idea to separate the data from the application. Using an external data directory allows for much easier upgrades, since there is no risk of conguration information being overwritten. An external data directory also makes it easy to transfer your conguration elsewhere if desired. To point to an external data directory, you only need to edit the web.xml le.

12.4.2 Use a spatial database

Shapeles are a very common format for geospatial data.. But if you are running GeoServer in a production environment, it is better to convert your shapeles to a spatial database, such as PostGIS. This is essential if doing transactions (WFS-T). Most of the spatial databases provide shapele conversion tools. Although there are many options (see the section on Working with Data), PostGIS is recommended. Oracle, DB2, and ArcSDE are also supported.

12.4.3 Pick the best performing coverage formats

There are very signicant differences between performance of the various coverage formats. Warning: http://geoserver.org/display/GEOSDOC/High+performance+coverage+serving is linked to here. Once that page is added to these docs, lets update this link.

12.5 Other Considerations

12.5.1 Host your application separately
GeoServer includes a few sample applications in the Demo menu, embedded right in the GeoServer container. We recommend against doing this for production instances. To make upgrades and troubleshooting easier, please use a separate container for your application. It is ne to use one container manager (such as Tomcat or Jetty) to host both GeoServer and your application.

12.5.2 Proxy your server

GeoServer can have the capabilities documents properly report a proxy. You can congure this in the Server Cong menu of the Web Administration Interface and entering the URL of the external proxy in the eld labeled Proxy base URL.

204

Chapter 12. Running In A Production Environment

GeoServer User Manual, Release 1.7.4

12.5.3 Set up clustering 12.5.4 Publish your servers capabilities documents

In order to make it easier to nd your data, put a link to your capabilities document somewhere on the web. This will ensure that a search engine will crawl and index it. Also, see the section on GeoSearch on how to get your data crawled by Googles geo crawler.

12.5. Other Considerations

205

GeoServer User Manual, Release 1.7.4

206

Chapter 12. Running In A Production Environment

CHAPTER 13

Extensions

Extensions add various bits of functionality to GeoServer, but do not come with the vanilla GeoServer distribution.

13.1 GeoSearch 13.2 Imagemap 13.3 OGR Output 13.4 REST

The REST extension provides a RESTful interface through which clients can congure a GeoServer instance through simple HTTP calls. With it clients can programatically congure the data served by GeoServer. For information on getting and installing the REST extensions proceed to the Installing the REST Extension section. For details about the API and some hands on examples proceed to the REST Conguration API Reference or REST Conguration Examples sections.

13.4.1 Installing the REST Extension

1. Download the REST extension from the GeoServer download page. Warning: loaded. Ensure the extension matching the version of the GeoServer installation is down-

2. Extract the contents of the archive into the WEB-INF/lib directory of the GeoServer installation.

207

GeoServer User Manual, Release 1.7.4

13.4.2 Overview of REST

REST is an acronym for REpresentational State Transfer. The basic idea of REST is to rely on a xed set of operations on named resources, where the representation of each resource is the same for retrieving and setting information. In other words, if you retrieve data in an XML format, you can send data back to the server in the same XML format to set it. Operations on resources are implemented with the standard primitives of HTTP: GET, DELETE, PUT, POST, HEAD, etc. Each resource is represented as a standard URI. For more information about REST visit the wikedia page.

13.4.3 REST Conguration API Reference

Formats and representations A format species how a resource should be represented. A format is used: In an operation to specify what representation should be returned to the client In a POST or PUT operation to specify the representation being sent to the server In a GET operation the format can be specied in a number of ways. The rst is with the Accepts header. For instance setting the header to text/xml would specify the desire to have the resource returned as XML. The second method of specifying the format is via le extension. For example consider the resource foo. To request a representation of foo as XML the request uri would end with foo.xml. To request as JSON the request uri would end with foo.json. When no format is specied the server will use its own internal format, usually html. In a POST or PUT operation the format species 1) the representatin of the content being sent to the server, and 2) the representation of the resposne to be sent back. The former is specied with the Content-type header. To send a representation in XML, the content type text/xml or application/xml would be used. The latter is specied with the Accepts header as specied in the above paragraph describing a GET operation. Authentication POST, PUT, and DELETE requests (requests that modify resources) require the client to be authenticated. Currently the only supported method of authentication is Basic authentication. See the examples section for examples of how to perform authentication with various clients and environments. Status codes A Http request uses a status code to relay the outcome of the request to the client. Different status codes are used for various purposes through out this document. These codes are described in detail by the http specication. Workspaces A workspace is a grouping of data stores. More commonly known as a namespace, it is commonly used to group data that is related in some way.

208

Chapter 13. Extensions

GeoServer User Manual, Release 1.7.4

Note: For GeoServer 1.x a workspace can be considered the equivalent of a namespace, and the two are kept in sync. For example, the namespace topp, http://openplans.org/topp corresponds to the workspace topp.

Operations
/workspaces[.<format>] Method GET POST PUT DELETE Action List all workspaces Create a new workspace Return Code 200 201 with Location header 405 405 Formats HTML, XML, JSON XML, JSON Default Format HTML

Representations: HTML XML JSON /workspaces/<ws>[.<format>] Method GET POST PUT DELETE Action Returns workspace ws 200 200 Return Code 200 405 Modify workspace ws Delete workspace ws Formats HTML, XML, JSON XML, JSON XML, JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a workspace that does not exist -> 404 PUT that changes name of workspace -> 403 DELETE against a workspace that is non-empty -> 403 /workspaces/default[.<format>] Method GET POST PUT DELETE Action Returns default workspace 200 Return Code 200 405 Set default workspace 405 Formats HTML, XML, JSON XML, JSON Default Format HTML

Namespaces A namespace is a uniquely identiable grouping of feature types. A namespaces is identied by a prex and a uri.

13.4. REST

209

GeoServer User Manual, Release 1.7.4

Note: In GeoServer 1.7.4 a namespace is used to group data stores, serving the same purpose as a workspace. In 1.7.4 the two are kept in sync. Therefore when adding a new namespace a workspace whose name matches the prex of the namespace is implicitly created.

Operations
/namespaces[.<format>] Method GET POST PUT DELETE Action List all namespaces Create a new namespace Return Code 200 201 with Location header 405 405 Formats HTML, XML, JSON XML, JSON Default Format HTML

Representations: HTML XML JSON /namespaces/<ns>[.<format>] Method GET POST PUT DELETE Action Returns namespace ns 200 200 Return Code 200 405 Modify namespace ns Delete namespace ns Formats HTML, XML, JSON XML, JSON XML, JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a namespace that does not exist -> 404 PUT that changes prex of namespace -> 403 DELETE against a namespace whose corresponding workspace is non-empty -> 403 /namespaces/default[.<format>] Method GET POST PUT DELETE Data stores A data store is a source of spatial data that is vector based. It can be a le in the case of a Shapele, a database in the case of PostGIS, or a server in the case of a remote Web Feature Service. Action Returns default namespace 200 Return Code 200 405 Set default namespace 405 Formats HTML, XML, JSON XML, JSON Default Format HTML

210

Chapter 13. Extensions

GeoServer User Manual, Release 1.7.4

Operations
/workspaces/<ws>/datastores[.<format>] Method GET POST PUT DELETE Representations: HTML XML JSON /workspaces/<ws>/datastores/<ds>[.<format>] Method GET POST PUT DELETE Action Return data store ds Modify data store ds Delete data store ds Return Code 200 405 Formats HTML, XML, JSON Default Format HTML Action List all data stores in workspace ws Create a new data store Return Code 200 201 with Location header 405 405 Formats HTML, XML, JSON XML, JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a data store that does not exist -> 404 PUT that changes name of data store -> 403 PUT that changes workspace of data store -> 403 DELETE against a data store that contains congured feature types -> 403 /workspaces/<ws>/datastores/<ds>/file[.<extension>] The extension parameter species the type of data store. The following extensions are supported: Extension shp gml properties Datastore Shapele GML (Geographic Markup Language) Property le

13.4. REST

211

GeoServer User Manual, Release 1.7.4

MethodAction

Return Code 200 405 200 405

Formats

Default Format

Parameters

GET POST PUT

Get the underlying les for the data store as a zip le with mime type application/zip. Creates or overwrites the les for data store ds.

See notes below.

congure

DELETE Exceptions: GET for a data store that does not exist -> 404 GET for a data store that is not le based -> 404

When the le for a datastore are PUT, it can be as a standalone le, or as a zipped archive. The standalone le method is only applicable to data stores that work from a single le, GML for example. Data stores like Shapele must be sent as a zip archive. When uploading a zip archive the Content-type should be set to application/zip. When uploading a standalone le the content type should be appropriately set based on the le type. The configure parameter is used to control how the data store is congured upon le upload. It can take one of the three values rst, none, or all. first - Only setup the rst feature type available in the data store. This is the default value. none - Do not congure any feature types. all - Congure all feature types. Feature types A feature type is a vector based spatial resource or data set that originates from a data store. In some cases, like Shapele, a feature type has a one-to-one relationship with its data store. In other cases, like PostGIS, the relationship of feature type to data store is many-to-one, with each feature type corresponding to a table in the database.

Operations
/workspaces/<ws>/datastores/<ds>/featuretypes[.<format>] Method Action GET POST PUT DELETE Representations: HTML XML JSON List all feature types in datastore ds Create a new feature type Return Code 200 201 with Location header 405 405 Formats HTML, XML, JSON XML, JSON Default Format HTML Parameters list

212

Chapter 13. Extensions

GeoServer User Manual, Release 1.7.4

Exceptions: GET for a feature type that does not exist -> 404 PUT that changes name of feature type -> 403 PUT that changes data store of feature type -> 403 The list parameter is used to control the category of feature types that are returned. It can take one of the three values congured, available, or all. configured - Only setup or congured feature types are returned. This is the default value. available - Only uncongured feature types (not yet setup) but are available from the specied datastore will be returned. all - The union of configured and available. /workspaces/<ws>/datastores/<ds>/featuretypes/<ft>[.<format>] Method GET POST PUT DELETE Action Return feature type ft Modify feature type ft Delete feature type ft Return Code 200 405 200 200 Formats HTML, XML, JSON XML,JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a feature type that does not exist -> 404 PUT that changes name of feature type -> 403 PUT that changes data store of feature type -> 403 Coverage stores A coverage store is a source of spatial data that is raster based.

Operations
/workspaces/<ws>/coveragestores[.<format>] Method GET POST PUT DELETE Representations: HTML Action List all coverage stores in workspace ws Create a new coverage store Return Code 200 201 with Location header 405 405 Formats HTML, XML, JSON XML, JSON Default Format HTML

13.4. REST

213

GeoServer User Manual, Release 1.7.4

XML JSON /workspaces/<ws>/coveragestores/<cs>[.<format>] Method GET POST PUT DELETE Action Return coverage store cs Modify coverage store cs Delete coverage store ds Return Code 200 405 Formats HTML, XML, JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a coverage store that does not exist -> 404 PUT that changes name of coverage store -> 403 PUT that changes workspace of coverage store -> 403 DELETE against a coverage store that contains congured coverage -> 403 /workspaces/<ws>/coveragestores/<cs>/file[.<extension>] The extension parameter species the type of coverage store. ported: Extension geotiff worldimage mosaic Coveragestore GeoTIFF Geo referenced image (JPEG,PNG,TIF) Image mosaic Return Code 200 405 200 Formats Default Format Parameters The following extensions are sup-

MethodAction

GET

Get the underlying les for the coverage store as a zip le with mime type application/zip.

POST PUT Creates or overwrites the les for coverage store cs. DELETE Exceptions: GET for a data store that does not exist -> 404 GET for a data store that is not le based -> 404

See notes below.

congure, coverageName

405

When the le for a coveragestore is PUT, it can be as a standalone le, or as a zipped archive. The standalone le method is only applicable to coverage stores that work from a single le, GeoTIFF for example. Coverage stores like Image moscaic must be sent as a zip archive. When uploading a zip archive the Content-type should be set to application/zip. When uploading a standalone le the content type should be appropriately set based on the le type. The coverageName parameter is used to specify the name of the coverage within the coverage store. This parameter is only

214

Chapter 13. Extensions

GeoServer User Manual, Release 1.7.4

relevant if the configure parameter is not equal to none. If not specied the resulting coverage will receive the same name as its containing coverage store. Note: Currently the relationship between a coverage store and a coverage is one to one. However there is currently work underway to support multi-dimensional coverages, so in the future this parameter is likely to change. Coverages A coverage is a raster based data set which originates from a coverage store.

Operations
/workspaces/<ws>/coveragestores/<cs>/coverages[.<format>] Method GET POST PUT DELETE Representations: HTML XML JSON /workspaces/<ws>/coveragestores/<cs>/coverages/<c>[.<format>] Method GET POST PUT DELETE Action Return coverage c Modify coverage c Delete coverage c Return Code 200 405 200 200 Formats HTML, XML, JSON XML,JSON Default Format HTML Action List all coverages in coverage store cs Create a new coverage Return Code 200 201 with Location header 405 405 Formats HTML, XML, JSON XML, JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a coverage that does not exist -> 404 PUT that changes name of coverage -> 403 PUT that changes coverage store of coverage -> 403 Styles A style describes how a resource (feature type or coverage) should be symbolized or rendered by a Web Map Service. In GeoServer styles are specied with SLD. 13.4. REST 215

GeoServer User Manual, Release 1.7.4

Operations
/styles[.<format>] Method GET POST PUT DELETE Action Return all styles Create a new style Return Code 200 201 with Location header 405 405 Formats HTML, XML, JSON SLD, XML, JSON Default Format HTML Parameters name

Representations: HTML XML JSON The name parameter species the name to be given to the style. This option is most useful when POSTing a style in SLD format, and an appropriate name can be not be inferred from the SLD itself. /styles/<s>[.<format>] Method GET POST PUT DELETE Action Return style s Modify style s Delete style s Return Code 200 405 200 200 Formats SLD, HTML, XML, JSON SLD,XML,JSON Default Format HTML

Representations: SLD HTML XML JSON Exceptions: GET for a style that does not exist -> 404 PUT that changes name of style -> 403 DELETE against style which is referenced by existing layers -> 403 Layers A layer is a published resource (feature type or coverage). Note: In GeoServer 1.x a layer can considered the equivalent of a feature type or a coverage. In GeoServer 2.x, the two will be separate entities, with the relationship from a feature type to a layer being one-tomany.

Operations
/layers[.<format>]

216

Chapter 13. Extensions

GeoServer User Manual, Release 1.7.4

Method GET POST PUT DELETE

Action Return all layers

Return Code 200 405 405 405

Formats HTML, XML, JSON

Default Format HTML

Representations: HTML XML JSON /layers/<l>[.<format>] Method GET POST PUT DELETE Action Return layer l Modify layer l Return Code 200 405 200 405 Formats HTML, XML, JSON XML,JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a layer that does not exist -> 404 PUT that changes name of layer -> 403 PUT that changes resource of layer -> 403 /layers/<l>/styles[.<format>] Method GET POST PUT DELETE Action Return all styles for layer l Add a new style to layer l Return Code 200 201, with Location header 405 405 Formats SLD, HTML, XML, JSON XML, JSON Default Format HTML

Layer groups A layer group is a grouping of layers and styles that can be accessed as a single layer in a WMS GetMap request. A Layer group is often referred to as a base map.

Operations
/layergroups[.<format>] Method GET POST PUT DELETE Action Return all layer groups Add a new layer group Return Code 200 201, with Location header 405 405 Formats HTML, XML, JSON XML,JSON Default Format HTML

13.4. REST

217

GeoServer User Manual, Release 1.7.4

Representations: HTML XML JSON /layergroups/<lg>[.<format>] Method GET POST PUT DELETE Action Return layer group lg Modify layer group lg Delete layer group lg Return Code 200 405 200 200 Formats HTML, XML, JSON XML,JSON Default Format HTML

Representations: HTML XML JSON Exceptions: GET for a layer group that does not exist -> 404 POST that species layer group with no layers -> 400 PUT that changes name of layer group -> 403

13.4.4 REST Conguration Examples

This section contains a number of examples which illustrate various uses of the REST data conguration api. The examples are grouped by environment/language. cURL The examples in this section use the cURL utility, which is a handy command line tool for executing HTTP requests and transferring les. Though cURL is used the examples apply to any HTTP-capable tool or library.

Adding a new workspace

The following creates a new workspace named acme with a POST request:
curl -u admin:geoserver -v -XPOST -H Content-type: text/xml \ -d <workspace><name>acme</name></workspace> \ http://localhost:8080/geoserver/rest/workspaces

The response should contain the following:

< < < < < HTTP/1.1 201 Created Date: Fri, 20 Feb 2009 01:56:28 GMT Location: http://localhost:8080/geoserver/rest/workspaces/acme Server: Noelios-Restlet-Engine/1.0.5 Transfer-Encoding: chunked

218

Chapter 13. Extensions

GeoServer User Manual, Release 1.7.4

Note the Location response header which species the location of the newly created workspace. The following retrieves the new workspace as XML with a GET request:
curl -XGET -H Accept: text/xml http://localhost:8080/geoserver/rest/workspaces/acme

The response should look like:

<workspace> <name>acme</name> <dataStores> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/g </dataStores> <coverageStores> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/g </coverageStores> </workspace>

Specifying the Accept header to relay the desired representation of the workspace can be tedious. The following is an equivalent (yet less RESTful) request:
curl -XGET http://localhost:8080/geoserver/rest/workspaces/acme.xml

Uploading a Shapele
In this example a new datastore will be created by uploading a Shapele. The following uploads the zipped shapele roads.zip and creates a new datastore named roads:
curl -u admin:geoserver -XPUT -H Content-type: application/zip \ --data-binary @roads.zip \ http://localhost:8080/geoserver/rest/workspaces/acme/datastores/roads/file.shp

The following retrieves the created data store as XML:

curl -XGET http://localhost:8080/geoserver/rest/workspaces/acme/datastores/roads.xml

<dataStore> <name>roads</name> <workspace> <name>acme</name> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/g </workspace> <connectionParameters> <namespace>http://acme</namespace> <url>file:/Users/jdeolive/devel/geoserver/1.7.4/data/minimal/data/roads/roads.shp</url> </connectionParameters> <featureTypes> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/g </featureTypes> </dataStore>

By default when a Shapele is uploaded a feature type is automatically created. See :ref:web_admin_cong_featuretypes_ for details on how to control this behaviour. The following retrieves the created feature type as XML:

13.4. REST

219

GeoServer User Manual, Release 1.7.4

curl -XGET http://localhost:8080/geoserver/rest/workspaces/acme/datastores/roads/featuretypes/roads.xml

<featureType> <name>roads</name> <nativeName>roads</nativeName> <namespace> <name>acme</name> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/g </namespace> ... </featureType>

Changing a feature type style

In the previous example a Shapele was uploaded, and in the process a feature type was created. Whenever a feature type is created an layer is implicitly created for it. The following retrieves the layer as XML:
curl -XGET http://localhost:8080/geoserver/rest/layers/acme:roads.xml

<layer> <name>roads</name> <path>/</path> <type>VECTOR</type> <defaultStyle> <name>roads_style</name> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/g </defaultStyle> <styles> <style> <name>line</name> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080 </style> </styles> <resource class="featureType"> <name>roads</name> <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/g </resource> <enabled>false</enabled> </layer>

When the layer is created a default style named polygon is assigned to it. This style can viewed with a WMS GetMap request. In this example a new style will be created and assigned to the layer created in the previous example. The following creates a new style named roads_style by uploading the le roads.sld:
curl -u admin:geoserver -XPUT -H Content-type: application/vnd.ogc.sld+xml \ -d @roads.sld http://localhost:8080/geoserver/rest/styles/roads_style

The following applies the newly created style to the layer created in the previous example:

220

Chapter 13. Extensions

GeoServer User Manual, Release 1.7.4

curl -u admin:geoserver -XPUT -H Content-type: text/xml \ -d <layer><defaultStyle><name>roads_style</name></defaultStyle></layer> \ http://localhost:8080/geoserver/rest/layers/acme:roads

The new style can be viewed with the same GetMap request as above.

Adding a PostGIS database

Note: This section assumes that a PostGIS database named nyc is present on the local system and is accessible by the user bob. In this example a PostGIS database named nyc will be added as a new data store. In preparation create the database and import the nyc.sql le:
psql nyc < nyc.sql

The following represents the new data store:

<dataStore> <name>nyc</name> <connectionParameters> <host>localhost</host> <port>5432</port> <database>nyc</database> <user>bob</user> <dbtype>postgis</dbtype> </connectionParameters> </dataStore>

Save the above xml into a le named nycDataStore.xml. The following adds the new datastore:
curl -u admin:geoserver -XPOST -T nycDataStore.xml -H Content-type: text/xml \ http://localhost:8080/geoserver/rest/workspaces/acme/datastores

Adding a PostGIS table

In this example two tables from the PostGIS database created in the previous example will be added as feature types. The following adds the table buildings as a new feature type:
curl -u admin:geoserver -XPOST -H Content-type: text/xml \ -d <featureType><name>buildings</name></featureType> \ http://localhost:8080/geoserver/rest/workspaces/acme/datastores/nyc/featuretypes

The following retrieves the created feature type:

curl -XGET http://localhost:8080/geoserver/rest/workspaces/acme/datastores/nyc/featuretypes/buildings

This GetMap request shows the rendered buildings layer. The following adds the table parks as a new feature type:

13.4. REST

221

GeoServer User Manual, Release 1.7.4

curl -u admin:geoserver -XPOST -H Content-type: text/xml \ -d <featureType><name>parks</name></featureType> \ http://localhost:8080/geoserver/rest/workspaces/acme/datastores/nyc/featuretypes

This GetMap request shows the rendered parks layer.

Creating a layer group

In this example the layers added in previous examples will be used to create a layer group. First a few styles need to be added. The following adds a style for the buildings layer:
curl -u admin:geoserver -XPUT -H Content-type: application/vnd.ogc.sld+xml -d @buildings.sld \ http://localhost:8080/geoserver/rest/styles/buildings_style

The following adds a style for the parks layer:

curl -u admin:geoserver -XPUT -H Content-type: application/vnd.ogc.sld+xml -d @parks.sld \ http://localhost:8080/geoserver/rest/styles/parks_style

The following represents the new layer group:

<layerGroup> <name>nyc</name> <layers> <layer>roads</layer> <layer>parks</layer> <layer>buildings</layer> </layers> <styles> <style>roads_style</style> <style>parks</style> <style>buildings_style</style> </styles> </layerGroup>

Save the following in a le named nycLayerGroup.xml. group:

The following creates the new layer

curl -u admin:geoserver -XPOST -d @nycLayerGroup.xml -H Content-type: text/xml \ http://localhost:8080/geoserver/rest/layergroups

This GetMap request shows the rendered layer group. PHP

13.5 GeoExt Styler 13.6 WFS Versioning

For information about extensions that add support for additional data formats, such as arcsde_data or SQL Server, see the Working with Data section.

222

Chapter 13. Extensions

CHAPTER 14

Tutorials

223

GeoServer User Manual, Release 1.7.4

224

Chapter 14. Tutorials

CHAPTER 15

Frequently Asked Questions

15.1 General 15.2 Installation 15.3 Conguration 15.4 Troubleshooting

225

GeoServer User Manual, Release 1.7.4

226

Chapter 15. Frequently Asked Questions

CHAPTER 16

Advanced GeoServer Conguration

GeoServer provides a variety of options to customize your service for different situations. While none of the conguration options discussed in this section are required for a basic GeoServer installation, they allow you to adapt your GeoServer to your own needs, beyond the options exposed in OGC standard services.

16.1 WMS Decorations

WMS Decorations provide a framework for visually annotating images from WMS with absolute, rather than spatial, positioning. Examples of decorations include compasses, legends, and watermarks.

16.1.1 Conguration
To use decorations in a GetMap request, the administrator must rst congure a decoration layout. These layouts are stored in a subdirectory called layouts in the GeoServer Data Directory as XML les, one le per layout. Each layout le must have the extension .xml. Once a layout foo.xml is dened, users can request it by adding &format_options=layout:foo to the request parameters. Layout les follow a very simple XML structure; a root node named layout containing any number of decoration elements. Each decoration element has several attributes: Attribute type affinity offset size Meaning the type of decoration to use (see Decoration Types) the region of the map image to which the decoration is anchored how far from the anchor point the decoration is drawn the maximum size to render the decoration. Note that some decorations may dynamically resize themselves.

Each decoration element may also contain an arbitrary number of option elements providing a parameter name and value:
<option name="foo" value="bar"/>

Option interpretation depends on the type of decoration in use.

227

GeoServer User Manual, Release 1.7.4

16.1.2 Decoration Types

While GeoServer allows for decorations to be added via extension, there is a core set of decorations included in the default installation. These decorations include: The image decoration (type="image") overlays a static image le onto the document. If height and width are specied, the image will be scaled to t, otherwise the image is displayed at full size. Option Name url opacity Meaning provides the URL or le path to the image to draw (relative to the GeoServer data directory) a number from 0 to 100 indicating how opaque the image should be.

The scaleratio decoration (type="scaleratio") overlays a text description of the maps scale ratio onto the document. Option Name bgcolor fgcolor Meaning the background color for the text. supports RGB or RGBA colors specied as hex values. the color for the text and border. follows the color specication from bgcolor.

The scaleline decoration (type="scaleline") overlays a graphic showing the scale of the map in world units. Option Name bgcolor fgcolor fontsize Meaning the background color, as used in scaleratio the foreground color, as used in scaleratio the size of the font to use

The legend decoration (type="legend") overlays a graphic containing legends for the layers in the map.

16.1.3 Example
A layout conguration le might look like this:
<layout> <decoration type="image" affinity="bottom,right" offset="6,6" size="80,31"> <option name="url" value="pbGS_80x31glow.png"/> </decoration> <decoration type="scaleline" affinity="bottom,left" offset="36,6"/> <decoration type="legend" affinity="top,left" offset="6,6" size="auto"/> </layout>

Used against the states layer from the default GeoServer data, this layout produces an image like the following.

228

Chapter 16. Advanced GeoServer Conguration

GeoServer User Manual, Release 1.7.4

Figure 16.1: The default states layer, drawn with the decoration layout above.

16.1. WMS Decorations

229