user reference manual - geoserver

U S E R R E F E R E N C E M A N U A L

GeoServer

TABLE OF CONTENTS

I. WHAT IS GEOSERVER? ........................................................................................................... 1 II. INTRODUCTION ....................................................................................................................... 3

2.1. WELCOME ............................................................................................................................... 3 2.2. HISTORY .................................................................................................................................. 3 2.3. PHILOSOPHY ............................................................................................................................ 5 2.4. COMMUNICATION .................................................................................................................... 6 2.5. COMMERCIAL SUPPORT ........................................................................................................... 6

III. INSTALL .................................................................................................................................... 7 2.1. OS SPECIFIC INSTRUCTIONS .................................................................................................... 7 2.2. REQUIREMENTS ....................................................................................................................... 7 2.3. ENVIRONMENT VARIABLES ..................................................................................................... 8

2.3.1. JAVA_HOME (Required) ............................................................................................... 8 2.3.2. GEOSERVER_HOME (Required) .................................................................................. 8 2.3.3. GEOSERVER_DATA_DIR (Optional) ........................................................................... 8

2.4. GETTING GEOSERVER ........................................................................................................... 10 2.4.1. Downloading GeoServer .............................................................................................. 10 2.4.2. Which version of GeoServer? ....................................................................................... 10

2.5. INSTALLING AND STARTING GEOSERVER ............................................................................. 11 2.5.1. geoserver-*-bin.tar.gz .................................................................................................. 11 2.5.2. geoserver-*.exe ............................................................................................................. 12 2.5.3. geoserver-*.war.zip ...................................................................................................... 12

2.6. ADMINISTERING GEOSERVER ................................................................................................ 13 2.7. TESTING GEOSERVER ............................................................................................................ 13 2.8. TROUBLESHOOTING ............................................................................................................... 14

IV. USER TUTORIAL SHAPEFILE ........................................................................................... 16 4.1. INTRODUCTION ...................................................................................................................... 16

4.1.1. STEP 1. Create A DataStore ........................................................................................ 16 4.1.2. STEP 2. Create The FeatureType ................................................................................. 19 4.1.3. STEP 3. Try It Out ........................................................................................................ 21

4.2. TROUBLESHOOTING ............................................................................................................... 22 V. DATASTORE CONFIG ........................................................................................................... 23

5.1. DATASTORE .......................................................................................................................... 23 5.2. SHAPEFILE DATASTORE ........................................................................................................ 26

5.2.1. Shapefile ....................................................................................................................... 26 5.2.2. Indexed Shapefile .......................................................................................................... 27

5.3. ARCSDE DATASTORE ........................................................................................................... 28 5.3.1. ArcSDE ......................................................................................................................... 28

5.4. ORACLE DATASTORE ............................................................................................................ 30 5.4.1. Oracle ........................................................................................................................... 30 5.4.2. Troubleshooting ............................................................................................................ 32

VI. SERVICE CONFIGURATION .............................................................................................. 34 6.1. CONFIGURING GEOSERVER ................................................................................................... 34 6.2. WEB ADMIN TOOL INTRODUCTION ....................................................................................... 34

6.2.1. Accessing the Web Admin Tool .................................................................................... 35 6.2.2. Logging In ..................................................................................................................... 36 6.2.3. Changing the Password ................................................................................................ 36 6.2.4. Saving your changes ..................................................................................................... 36

6.3. ADMIN PAGE ......................................................................................................................... 37 6.4. CONFIG .................................................................................................................................. 38 6.5. VALIDATION .......................................................................................................................... 38

VII. SLD INTRO TUTORIAL ...................................................................................................... 40 7.1. SLD HELLO WORLD .............................................................................................................. 40

7.1.1. Create the SLD File ...................................................................................................... 40 7.1.2. Load Your New SLD ..................................................................................................... 42 7.1.3. Give a FeatureType Your New SLD ............................................................................. 44 7.1.4. View the Style ................................................................................................................ 46

7.2. SLD TEXT SYMBOLIZERS ...................................................................................................... 47 7.2.1. Modify the SLD File to Include Text Symbolizers ........................................................ 47

7.3. OUTLINES AND FILTERS ........................................................................................................ 50 7.3.1. Rule ............................................................................................................................... 52 7.3.2. Output ........................................................................................................................... 54

7.4. WHAT SLDS ARE, A TEXT APPROACH .................................................................................... 54 7.5. FURTHER READING ............................................................................................................... 56

I. What is GeoServer? GeoServer, as the name suggests, is a server. It is open source and it allows users to view and edit geographic data. This is the realm of Geographic Information Systems (GIS). GeoServer is a fully functional WFS-T and WMS server that follows the OGC specifications. With Geoserver you can publish data as:

þ maps/images (using the WMS), þ actual data (using the WFS), þ and allow users to update,

delete, and insert geographic data (using the WFS-T).

In short, GeoServer is one of those tools you need to display maps on web pages, where the user can zoom and pan around. It is used in conjunction with clients such as, MapBuilder (for web pages), UDig, GVSig, and others. The use of standards allows information from GeoServer to be easily combined with other geographic information.

PDRTRGeoServer

WEB

LAN

WEB

LAN

Web Page

Map Server

Desktop Appl.

Clients Server

PDRTRGeoServer

WEB

LAN

WEB

LAN

Web Page

Map Server

Desktop Appl.

Clients Server

GeoServer's focus is ease of use and support for open standards, in order to enable anyone to quickly share their geospatial information in an interoperable way. More information on specific features of GeoServer can be found here. Here is an example of what you might get if you make a WMS request to GeoServer:

Definitions § WMS: Web Map Service. Displays

geographic data as raster images (maps).

§ WMS: Web Map Service. Displays

geographic data as raster images (maps).

§ WFS: Web Feature Service. Communicates real geographic data (roads, rivers etc.) to and from the user in the form og GML.

§ WFS-T: Web Map Service-Transactional. Allows the users to edit geographic data in transaction blocks.

§ GML: Geography Markup Language. A brand of XML that describes geographic data.

User Reference Manual GeoServer Page 2

Geoserver is built on Geotools, the same Java toolkit that UDig uses.


II. Introduction

2.1. Welcome First, we'd like to welcome you to the GeoServer community. 'Who me?', you may be saying, 'I didn't sign up for any community, I just want some software'. Well simply by being interested in sharing your spatial data with others, we feel you are a part of what we are hoping to accomplish, and welcome you. We believe that the open sharing of information, and especially spatial data, is essential to tackle many of the problems of the world. GeoServer aspires to be the Apache of spatial data sharing, by providing an open source, freely available implementation of the Open Geospatial Consortium's (OGC) Web Feature Service (WFS) and Web Map Service (WMS) specifications. We hope to enable greater geographic interoperability by enforcing OGC standards and lowering the barriers to entry for geographic data providers interested in sharing their data. Even if you evaluate GeoServer and decide that another product suits your needs better, then by all means use it, we don't pretend that our software will meet every use (though we encourage you to help it do so). But if you do, please use one that fully implements OGC standards. The GeoServer Project itself strives to be as open as possible,making it easy for any one to contribute, be it with feature suggestions, bug reports, patches, documentation, encouragement, funding, development, design, translation, or more. We in building GeoServer collaboratively, so that it can effectively meet a variety of needs, hopefully leading to a world of more open technology and open spatial data. To that end we ask that if you do find the software useful you try to find a way to give back, as good users are our most valuable resource. See the How to Help section for more on this, but we would like to dispel the notion right here that it is only through writing code that you can contribute. There are many, many ways that you can help us build a better geographic data server, and some of them only take a couple of minutes. If you have had enough of our blathering at this point and just want to get started you can skip to the installation section (or the quickstart section, but if you're really impatient you've probably already done that). For a deeper introduction, including the history and philosophy of the GeoServer Project, please read on.

2.2. History GeoServer was started by The Open Planning Project(TOPP), a small non-profit in New York, looking to make urban planning decisions more open to the citizens they affect. TOPP is working to create a whole suite of tools to enable open democracy and to help make government more transparent. These tools themselves must be transparent and modifiable, so that they do not surreptitiously


put forth an agenda. And they must be freely available, so that all can truly participate, not just those who can afford to spend money on software. For this reason all tools in the suite must be open source and free. The first of these was GeoServer, which came out of a recognition that a suite of tools to enable citizen involvement in urban planning would be for naught if they could not access any spatial data. The GeoServer Project envisions a GeoSpatial Web, just like the World Wide Web, where you can search for and download text data, you could simply search and browse the spatial data web. Data providers would beable to publish their data straight to this web, and users could directly access it, without having to specifically know who might provide the data they want, contact them in some way, get emailed (or snail mailed, or pointed to a web location) some file, convert the file to a format they could work in, and then actually get started on the task they really want to do. At the time GeoServer was starting the OpenGIS Consortium was working on the Web Feature Service standard. It specifies a protocol to make spatial data directly available on the web, using GML (Geographic Markup Language), an interoperable data format. Happily Refractions Research had started work on PostGIS, giving GeoServer an open source spatial database to run on top of. After wrestling with the fact that an internal model of geographic features was needed, and not wanting to replicate a ton of work, GeoServer found the Geotools project, an open source GIS Java toolkit. Both projects have benefited immensely from this collaboration as we helped develop much of their model further, and GeoTools code turned into direct GeoServer contributions, including support for Shapefiles, Oracle, and ArcSDE, as well as the WMS that is now an integrated part of GeoServer. In 2003 GeoServer made its way to 1.0 as part of the OGC's CITE project, where we helped develop a conformance testing suite and were named the WFS reference implementation. Then we went back to the drawing board in order to build a much more scalable GeoServer, helping GeoTools redo their feature and data models. Refractions Research secured a GeoConnections grant from the Canadian government to develop GeoServer much further, and got immediately involved in the GeoTools data refactoring. Gabriel Roldan, who recently started Axis Engineering to do further work on GeoServer, helped rearchitect GeoServer to integrate GeoTools WMS, bringing us to 1.1. Then Jody Garnett and his team at Refractions really went to work, adding an innovative validation system to allow users to ensure that incoming transactions followed their defined rules. They also did the great STRUTS based web administration tool, so that users need never look at configuration files, taking us to 1.2. And through it all many, many contributions and suggestions by our users have played a huge roll in making GeoServer what it is today. David Blasby took over lead developer responsibilities in 2005, leading the charge to version 1.3. This release takes GeoServer to a much more professional piece of software. WMS support is greatly improved, and many little kinks have been


worked out. Work on uDig has greatly improved the GeoTools library, as GeoServer and uDig both perform bug fixes and feature enhancements on the same codebase. Many client applications have also been emerging, as uDig reaches maturity, gvSig continues to grow, and MapBuilder comes into its own. The future holds an integrated WCS with raster support from a group in Italy, and greatly improved handling of complex GML schemas and data types, from Gabriel Roldan and Social Change Online, with funding from the Australian government. TOPP will be focused on adding wiki like functionality to WFS-T, and re-engineering GeoServer to be more pluggable, to enable better parallel development and user contributed innovations.

2.3. Philosophy The history of GeoServer should highlight a core belief of the project - that through cooperation we can build something greater than any of us could alone. We take the full open source development model extremely seriously, far beyond just the license, we believe in creating a community working together to build GeoServer. A good representation of this philosophy can be found in Eric Raymond's The Cathedraland the Bazaar. GeoServer accepts most all contributions, and allows any one to build upon the code. We treat our users as co-developers, as they are our most valuable resource. And we believe that a number of different companies, governments, NGO's, universities and R+Dg roups can all use and contribute to GeoServer for their own ends, making the software much better for all. This is already very much happening, as the major fundings for GeoServer have come from very diverse sources. We are working on some documents to show exactly how each can use and further build GeoServer together (check the wiki), but for now we just want to emphasize that the decision structure for the project is extremely open. It is a complete meritocracy, and anyone can influence the direction. TOPP is committed to employing someone to focus on keeping GeoServer moving, doing the day to day work of keeping the community going, but is ultimately working towards a complete self sustaining community. TOPP holds the copyright, but just sees itself as a steward for an emerging community, as the license is GPL, and will transfer control of the direction of the project to a Project Management Committee (PMC), like GeoTools has. But even if you do not become a major contributor, you still very much have a say on the direction of GeoServer, and there are many, many smaller ways in which you can contribute. The other way that this core belief manifests itself is that we leverage as much already exisiting work as possible, and strive to work with other open source projects as much as possible. We've had varying success with this over the years, from GeoTools where we both have benefitted incredibly from close collaboration, to attempts to join up with other projects that were not quite as successful. But we believe strongly that the extra up front effort to just set up a collaboration pays off handsomely, as working with GeoTools has proven. So please get in touch if you are interested in collaboration. Often times it won't make sense to work directly with GeoServer, but working together at the


GeoTools level can gain us almost all the benefits of direct collaboration, as each project's efforts will feed the others. If you are working in another programming language then we encourage you to use the open OGCinterfaces, and to test against GeoServer to make sure interoperability is actually achieved (and please report any bugs on the GeoServer end!). Beyond direct collaboration, we also make use of as many other open sourceprojects as possible. GeoServer would simply not be possible withoutJetty, PostGIS, Postgresql, Tomcat, Ant, STRUTS, xerces, wkb4j, and more. One of the greatest thing about open source is that we do not need to replicate work, we can just leverage the great work of others.

2.4. Communication The two primary points of communication for the GeoServer projectare the email lists and our JIRA tasktracker. There are currently two email lists,

þ [email protected] and þ [email protected]

You may use either list, we started the user list for people who are not interested in all the development issues. We would like for the users list to be self supporting, so that experienced users can help out the newer people. The developers list gets a lot more email, which is partly historical, as it is the older list, and many people joined it before the users list was active. It also gets updates from the JIRA task tracker. Thesubscribe/unscribe interface and the archives for the lists are available at http://sourceforge.net/mail/?group_id=25086. One thing we definitely want to emphasize is to use the list for most all communication, please do not email individual developers. And be warned that if you do email individual developers they are likely to cc the list (unless you explicitly ask them not to). This is part of our belief in open collaboration - there are likely other people who have the same questions, and they would like to be able to at least read the archives and attempt to find the answer. The second primary communication point is the task tracker. It keeps track of all bugs, feature requests, tasks, and issues, ensuring that the developers remember what needs to be done. It is available here. We recommend putting all feature requests and bug reports directly to it. For more information on the tracker and how to report a bug see 1 Reporting Issues.

2.5. Commercial Support A variety of organizations offer high quality, professional, commercial support on GeoServer, for installation, training, new features, system analysis and implementation, and open source migration. See the Commercial Support page for details.


III. Install

This document describes what you need to run GeoServer, where to obtain GeoServer, and the process of installing and starting up the various GeoServer distributions.

2.1. OS Specific Instructions [Install Windows\|Install Windows">Install Windows|Install Windows">Install Windows] [Install Unix\|Install Unix">Install Unix|Install Unix">Install Unix] [Install Mac OSX\|Install Mac OSX">Install Mac OSX|Install Mac OSX">Install Mac OSX]

2.2. Requirements

The first requirement for all installations of GeoServer is that you must have a Java JDK (Development Kit) installed on your computer. If you do not have the JDK installed on your machine, you should download it from Sun.com .

Most of our testing occurred against Java JDK 1.4.2 . However, latest JDK 1.5.0 is recommended for speed increasing.

Note that just the Java Runtime Environment (JRE) is not sufficient for GeoServer. We are working on making a GeoServer that can just run with a JRE, indeed even a GeoServer that includes a JRE. But for now you will need the JDK .

You need the JDK Geoserver requires a Java JDK/JDE not just a JRE. You must have the JDK version of Java.

If your not sure if you have Java , or not sure what version, type from the command line:

java -version

If the command doesn't work or if the version is less than 1.4 then you'll have to download and install Java JDK (Development Kit) , and set JAVA_HOME environment variable.

A note on Java 1.5 We've had problems with Java 1.5 in the past, but they should be fixed from GeoServer 1.3.0. See Java 1.5 Issues for information if you are getting weird errors on basic operations.


2.3. Environment Variables

2.3.1. JAVA_HOME (Required)

You need to set the JAVA_HOME environment variable pointing to your Java JDK installation directory. Standard RPM of Java JDK (Development Kit) on Linux will install the files into /usr/java/jdk1.5.0_08. On Windows, standard Java JDK (Development Kit) installation will place the files into C:\Program Files\Java\jdk1.5.0_08.If you install Java JDK into another directory, please change theses variables to the proper values.

Optionally you can set these variables:

• Add $JAVA_HOME/bin to the $PATH variable • Add $JAVA_HOME/lib to the $CLASSPATH variable (Linux Only)

2.3.2. GEOSERVER_HOME (Required)

Point this variable to your GeoServer installation directory: In Windows, if you select geoserver-.exe* as your install method, GeoServer will be at C:\Program Files\GeoServer 1.3.3 by default. If you select geoserver--bin.tar.gz*, recommended installation directory is C:\geoserver. In Linux we recommend /usr/local/geoserver. If you install GeoServer into another directory, please change theses variables to the proper values.

2.3.3. GEOSERVER_DATA_DIR (Optional)

You can use this variable to move your GeoServer data outside of GeoServer application directory. This is useful for upgrading processes, preventing loosing of data.

A note on application data directory Previous to GeoServer 1.4-M1, application data directory was GEOSERVER_HOME/data_dir by default. Starting from version 1.4-M1, this directory is GEOSERVER_HOME/conf.

If you decide set this variable, all content of data_dir or conf directories and files needs to be moved to the new location. We have isolated Configuration Information, from the GeoServer Application Information currently being used. Configuration information is captured by a series of classes in the config package. The advantage of this approach is that it gives us a chance to recast concepts into terms acceptable to the user interface.

Optionally you can set these variables:

• Add $GEOSERVER_HOME/bin to the $PATH variable


Additional Libraries for Rasters

Why Java Advanced Imaging (JAI) You do not need to download Java Advanced Imaging (JAI) if you're using Geoserver 1.3.0 or later. Geoserver (since 1.3.0) ships with the 100% Java JAI version so you dont have to install it. You may want to install it for performance reasons if you are using [WCS] (Coverages) or Rasters.

If you are interested in the visualization (Web Map Service WMS) portion of GeoServer you may consider downloading and installing the Java Advanced Imaging (JAI) library (available here )and the Image I/O extensions (available here ).

Note we have also had success with the new Image I/O release, as it has a nice installer that does both JAI and the Image I/O extensions. It is available here . Installing these will give support for styles, as well as a number of image formats, such as jpeg, tiff, bmp, and more. Since we now include the Java JAI version most users do not need to install it. But using the native version specific to your operating system can improve performance and give additional output formats.


2.4. Getting GeoServer

2.4.1. Downloading GeoServer

GeoServer is available for download on our Sourceforge home , using their excellent file release system. Downloads are instantly available on mirrors around the world. The main GeoServer distribution is available here , though we recommend going through our download page, as it gives a clearer picture of your download options, choosing between stable, for the safe option, latest, to help us with the latest improvements, and experimental for bleeding edge features you may be dying for.

In addition there are other files that we distribute, such as DataStore Extras , which includes updated DataStores for past GeoServer version (so you can get the latest upgrades without having to completely reinstall and reconfigure GeoServer), as well as more experimental ones, such as MySQL, Indexed Shapefiles, and VPF support, that are still in testing, so we don't want to distribute them yet with the full, stable GeoServer distribution. You can view all files that GeoServer offers by clicking here

DataStore Extras Make sure the datastore extras you download is the correct version for the GeoServer you downloaded!

2.4.2. Which version of GeoServer?

We currently make four different versions of GeoServer available for download. All have the same functionality, they just differ in how you run them.

geoserver--bin.tar.gz* is the binary release. It will run GeoServer right away, without installing any additional software. The release consists of documentation, an embedded Jetty servlet container (the key to no additional software), and start up and shutdown scripts, for Windows and Linux. We recommend this release if you are on Linux and want the easiest installation.

geoserver-.exe* is exactly the same as the binary release, but also contains a nice Windows installer. It will give dialog boxes about where to install GeoServer, and installs shortcuts to stop and start GeoServer from the start menu. We recommend this release if you are on windows and want the easiest installation.

geoserver--.war.zip* is a Java WAR file, that can be plugged into any servlet container (at least theoretically), write once debug everywhere is often in effect, please report any bugs on different servlet containers to our issue tracker . We recommend this for people who are already running Java web applications and would like to keep their existing set up. It is also the smallest download, containing the GeoServer application.


geoserver--src.zip* contains the source code from which all other distributions can be built. It is a snapshot of the source code repository at the time of release. It contains Java source files, Java testing source files, docbook files (from which documentation can be built), and all the other files that are needed to build and test GeoServer. For more information about working with the source code see the developers section of this manual, as we talk much more in depth about working with it. We recommend this download for Java developers, who would like to see how GeoServer works, and who are interested in modifying and contributing to GeoServer.

2.5. Installing and Starting GeoServer

As the main difference between the four GeoServer versions is installation, we will examine each on its own. Please read the version that you are working with.

2.5.1. geoserver-*-bin.tar.gz

This is the binary distribution of GeoServer. It can be installed on Windows or Linux.

Installing

After downloading the binary distribution, uncompress it into a convenient location. This will create all the relevant files in a "geoserver" directory.

Starting Up

There are two techniques by which the GeoServer binary distribution can be started:

• Via an environment variable: Using the previously declared environment variable GEOSERVER_HOME for the path of the directory into which you have installed GeoServer.

• By changing your current working directory to $GEOSERVER_HOME/bin and executing the proper startup script.

To stop GeoServer use the same techniques as startup, but use the shutdown script, in the same location.

Uninstall

To uninstall GeoServer simply delete the directory where it was unzipped. Be sure GeoServer is not running before remove this directory.


If you setup a application directory in a different place, these files will be keept for future upgrades or bakup purpouses.

2.5.2. geoserver-*.exe

This is a nice installer for Windows users only. geoserver-*.exe is the easiest installation for Windows users. It provides a guided step by step installation process.

Installing

Just double click on the downloaded file and follow the instructions.

Starting Up

To start GeoServer simply click on the Start GeoServer icon.

Uninstall

To remove GeoServer just double click on the Uninstall link on the GeoServer start menu. Make sure that GeoServer has been shut down before uninstall it. This will remove the start menu icons and GeoServer itself.

2.5.3. geoserver-*.war.zip

Geoserver War distribution can be installed on Windows or Linux and requires a servlet container. We recommend that if you do not have a servlet container you should use the geoserver--bin.tar.gz* download, as they have an embedded Jetty servlet container, so that you need not details of setting up one up.

But if you like more control over your software, or already have a favorite container, then using the War is right for you. We do recommend sticking with the latest stable versions. We try to be as backwards compatible as possible, but we are not willing to bend over backwards for bugs that have been fixed in later versions. We recommend Jetty , Resin , and Tomcat as solid Open Source containers, and there are a bevy of commercial ones on the market as well.

This option is also most useful if you are working on a production server that already has a servlet container on it, as system administrators don't generally like to upgrade software and install new software at your every whim. And it's good to keep those guys happy, they do a lot of great, and under appreciated, work. So with the War installation you can keep them happy, as they'll have a servlet container all ready for you.


Installing

After downloading the War distribution, uncompress it into a convenient location. Then move the War file to your servlet application directory, generally *webapps/. Most modern containers will automatically detect the new War file and expand it, some will require you to restart. The War file will be expanded into the appropriate directory structure.

An additional step is needed under WebLogic 9.2. Open the WebLogic administration console, go in "Domain -> Security -> Advanced" and set "Enforce Strict URL Pattern" to false.

Starting Up

Starting the GeoServer War depends on the previously installed servlet container. Once you start up your servlet with GeoServer in the proper *webapps/ directory it should be available.

2.6. Administering GeoServer

Once installed and started up, you can administer GeoServer via the Web Administration Tool included, pointing your browser to:

http://localhost:8080/geoserver/

The server address is the name of the server, localhost if it is on your machine, but if set up on a remote machine it will be that IP address or machine name. The server port will be the port the servlet container is configured on. The default for most is 8080, but it also may be another address - check your container's configuration.

2.7. Testing GeoServer

Once you have your version of GeoServer running, we recommend a simple test, going to:

http://localhost:8080/geoserver/wfs/GetCapabilities

You should see an XML WFS Capabilities file. If you do not then go back and read your section again, as something went wrong. You can also go to:

http://localhost:8080/geoserver


and the Web Administration Tool should load. You can start to play with it, it will be discussed in length in the next section . Note that it takes a little while to load the first time, this is a one time only load, after that it should start up right away.

You can also go to the demo section, from the main welcome page, or directly at:

http://localhost:8080/geoserver/demo.do

This shows a number of sample requests that you can issue against GeoServer. It should serve as a quick demonstration of the WMS and WFS requests, as well as a test that GeoServer is in fact working properly. The requests are issued against two shapefiles that are included and configured in all geoservers by default. (We should make a demo folder download tutorial thing that has a ton of W*S requests for reference, that people can plug into the demo section and learn about the interfaces).

You may also want to check out the working demo of GeoServer with MapBuilder using WMS and WFS-T at:

http://localhost:8080/geoserver/data/mbdemos/demo/wfs-t/index.html

2.8. Troubleshooting Q: java.net.BindException: Address already in use

The most common hiccup (especially for bin and exe installs) is when another web server (or any process for that matter) has laid claim to port 8080. This is the default HTTP port that GeoServer attempts to bind to at startup. Even if you don't see a BindException, but get something else when you try to go to the geoserver admin, this is probably the problem.

To change the port that GeoServer runs on, open the file:

$GEOSERVER_HOME/etc/jetty.xml

for GeoServer 1.4.x. For older versions it's at:

$GEOSERVER_HOME/documents/jetty.xml

and search for '8080'. Change it to a port that isn't in use, and is greater than 1024, as ports less than or equal to 1024 require superuser access to bind to. Restart GeoServer and you're in business. Be sure that you always replace the "8080" in the URL you're using to access GeoServer. For example, if you change the port to 1979, you would request the URL to

http://localhost:1979/geoserver

Q: Java 1.5 Issues

We are still working against Java 1.4, and will continue to always support it. But many users are upgrading to 1.5, as it can lead to some nice speed increases. Some users have reported problems with the defaults on GeoServer 1.3 with Java 1.5. As of 1.3.0-RC6 this should be fixed (by adding an extra 1.8 megs to your download, sorry!).

The most common error due to Java 1.5 is:

javax.xml.transform.TransformerFactoryConfigurationError: Provider org.apache.xalan.processor.TransformerFactoryImpl could not be instantiated: java.lang.NullPointerException

To fix this, downloaded XALAN-J binaries and move the xalan.jar file to [tomcat]/common/endorsed if you're running tomcat or $GEOSERVER_HOME/server/geoserver/WEB-INF/lib if running the binary install. This is due to Java 1.5 not including the xalan interpretive processor, while 1.4 does. For the 1.3.0 release we will likely just include that jar, since 1.5 is becoming the standard.

note: xalan 2.7.0 has additional dependencies! xml-apis.jar, xercesImpl.jar, and serializer.jar should be copied to the same location as xalan.jar

Q: Jetty - unable to connect to WFS/WMS from outside.

To connect to Jetty from other than the 'localhost' URL, you must edit your jetty.xml file located under documents/ in the source distribution of GeoServer (the SVN or .src versions). In jetty.xml add: <Set name="Host">###.###.###.###</Set> where the hashes (#) are the IP address you want.

Q: The localhost machine is not found when trying to connect to GeoServer

This could happen if you're behind a proxy and haven't configured localhost for access. If that's the case, make sure the proxy configuration for your browser knows that you shouldn't be going through the proxy to access the "localhost" machine. In Netscape, this is under Edit/preferences -> Advanced/proxies, and in Internet Explorer, Tools -> Internet Options -> Connections -> LAN Settings.

IV. User Tutorial Shapefile

4.1. Introduction

This page will walk you through how to add a new data set to Geoserver.

There are two things you need to do to point Geoserver to a new data set. The first is to point to the new data (DataStore), the second is to set the meta information (FeatureType) describing the data.

Quick Start

1. Copy your shapefile to (geoserver install)/data_dir/data/ 2. Create a new Data Store and point it to your shapefile:

file:/data/myShapefile.shp 3. Create a new FeatureType that points to your new Data Store 4. Set the FeatureType's SRS value to be the same as your data

(lat long = 4326) 5. Hit the FeatureType's "Generate" button to create the bounding

box 6. Hit the "Apply" button. 7. Try it out in the Map Preview section of GeoServer's demo

page.

Try it out in Google Earth. Copy this link but change myFeatureType to be your FeatureType name: http://localhost:8080/geoserver/wms/kml_reflect?layers=myFeatureType

4.1.1. STEP 1. Create A DataStore

STEP 1.1

Start Geoserver and then open your running Geoserver start page. If it is run locally, the address is http://localhost:8080/geoserver <- Try clicking it if you have Geoserver already running

To get to it, open up your favorite web browser and type in that address. It will take you to the Geoserver start page.

Now we need to navigate to the DataStore config section of Geoserver.


Click on the 'Config' button. If you are not already logged in, log yourself in with the default username and password (username: admin , password: geoserver).

Next, click on the 'Data' button.

Then, click on the 'Stores' button.

STEP 1.2

You need to tell Geoserver where the data is.

Select 'New' on the left purple-ish panel

STEP 1.3

Select 'DataStore Description' as 'Shapefile' Also set DataStore ID to be your shapefile name, it can be whatever you want, not


necessarily the file name. For our example, enter mytutorial

When you are done, hit the 'New' button.

STEP 1.4

Now we need to specify the shapefile we want to use. To locate the shapefile we need to specify where it lives relative to the data directory (data_dir/). The data directory lives right under the root location of GeoServer. For example: C:\Java\Geoserver\data_dir In the data directory, there is a sub directory called data/ (C:\Java\Geoserver\data_dir\data). Place your shapefile in that directory.

In the URL field, enter the location of the file. For example:

file:data/tutorial.shp

All URLs you will use are relative to the data directory (data_dir/). If you do not want to copy your full shapefile into GeoServer, there are other ways to refer to it, see the full Shapefile DataStore section of the docs.

Hit the 'Submit' button.


Now, we need to register all the changes. To do that, hit the 'Apply' button on the left, then 'Save' if you want to save it out for future use.

4.1.2. STEP 2. Create The FeatureType

STEP 2.1

Now, back up a spot in Geoserver Config and go to Config -> Data -> FeatureType

Hit 'New'

From the drop down list, Feature Type Name, select your datastore.

Then Hit 'New'


STEP 2.2

Select your DataStore: test_datastore:::tutorial

Then hit the 'New' button.

STEP 2.3

A new screen will appear that looks a little confusing, but you can ignore most of it. One thing you have to enter is the SRS value. If you don't know what SRS is and you just want to see your stuff, then enter 4326.

Definitions SRS (Spatial Reference System): The SRS value describes what projection the data is in. It is represented by a number that uniquely identifies each projection.

Hit the 'Generate' button, this will get your bounding box and display your projection information in a faded grey color.


STEP 2.4

Now you have to add a style for the data. The style defines how the data will be drawn (color, line thickness etc..). You can use one of the pre-cooked styles in the "Style" drop down list or create your own using the "Create New SLD" button. If you select to use an existing style, make sure it can render your type of geometry. If you have points, use a style that can render points (for example the "point" SLD). For lines use a line style, for polygons use a polygon style. There are three default styles for you to use: point, line, polygon.

If you opt to create a new SLD with the SLD Wizard, it is pretty easy. It knows what geometries your data uses and will display the appropriate fields you need to style your data. All you have to do in fill in the appropriate colors, either by hand or by clicking on the little multi-colored box next to the color field. This is the color picker. When you are done configuring your style, hit the Apply Style button. Then hit the Finished button. (There is a known bug that will cause the style not to be applied if the feature type you just created hasn't been saved, this will be fixed in the next release).

STEP 2.5

Hit the 'submit' button. The window will change again and take you back to the FeatureType screen.

STEP 2.6

§ Once again, hit the 'Apply' and then 'Save' buttons.

4.1.3. STEP 3. Try It Out

STEP 3.1

You can try out the WFS with this URL (change the typename from tutorial to your featureType name): http://localhost:8080/geoserver/wfs?request=getfeature&service=wfs&version=1.0.0&typename=tutorial


You should get back a bunch of XML (GML), and it should look confusing, but you can probably make out the attributes of your file.

STEP 3.2

You can also view the data in Google Earth (sweet!). If you have Google Earth installed, all you have to do is open up a web browser and enter this URL (changing myFeatureType to match your FeatureType name): http://localhost:8080/geoserver/wms/kml_reflect?layers=myFeatureType

STEP 3.3

You can try out the WMS, instantly viewing your new layer with the MabBuilder based preview: http://localhost:8080/geoserver/mapPreview.do Just find the layer you added, and you'll get a nice zoomable map of the extent. For a more advanced view you'll actually have to dig into http://mapbuilder.sourceforge.net , or check out the Clients section for other options, both desktop and web-based]

4.2. Troubleshooting

Q: Shapefiles - why do I have issues trying to do transactions against shapefiles?

There are several issues that one can encounter when trying to do transactions against shapefiles. On windows NTFS sometimes locks the files, and if many users are operating against a featureType backed by shapefiles, there can be corruption issues. If one is to read the first lines of the Shapefile DataStore docs, one would find that we don't actually recommend using Shapefiles to do transactions against, since they were designed as a file transfer format, not as a transactional database backend. We provide transaction support for users to experiment with how a WFS-T works, but for any real production instance, we highly recommend using a real spatial database, such as PostGIS, DB2, Oracle Spatial, or ArcSDE. MySQL also has growing spatial support, but the spatial stuff is in the non-transactionally secure tables, so we don't yet recommend it for high user production environments.


V. DataStore Config

5.1. DataStore

After defining your namespace(s) the next step is to define your DataStore. A DataStore represents a single, physical, source of geographic data. It can consist of one or more featureTypes (or layers). A featureType can be a table (as in a database), a single file (as in a shapefile), a directory (as in a VPF library). The DataStore construct is used so that you do not need to define connection parameters for each and every table in a large database. Instead you define them in the DataStore, and each FeatureType (table) refers to the DataStore that defines those parameters. In the case of Shapefiles, where each file can only contain one FeatureType, this may seem to be a bit of overkill, but to be in line with the rest we define the connection parameters in the Store and the rest in the FeatureType. Each available DataStore is discussed separately, as each has its own parameters and tricks, and you are likely only interested in one or two. But all have a few common parameters.

To define a new DataStore, click on Stores from the main Data page,and then hit the New button. This will take you to a page like the following:

In the DataStore Description drop down box there will appear all the currently supported DataStores, from which you can select the type of DataStore you want to create. Note that the default GeoServer installation will not include all the possible DataStores. For example the oracle datastore(s) will only show up when the proper oracle jars are in the lib/ section, as we can not legally distribute these with GeoServer. There are also a number of DataStores available in the DataStore Extras download section (make sure your version of Geoserver is compatible with the datastores you download!), that for some reason or another are not quite ready for the default GeoServer installation. Many will be once they are well tested. Others are the latest versions of common DataStores, we make these available so users need not go through a whole upgrade procedure, they can just drop in the latest jar for their datastore. When the jars are installed correctly in the lib/ directory (each should have instructions on how to do this), it will show up in the drop down box. You just need to select it, and then fill in the appropriate parameters.


You also need to define a DataStore ID. This is just used internally, and should be unique.

After selecting the DataStore ID and the type of DataStore you would like to create then hit the New button and you will be taken to a page that looks more or less like the following:

We will examine each DataStore in turn (this one happens to be MySQL), for now we just want to point out the three common fields that all DataStores have:

Enabled allows you to 'turn off' access to the store, and all featureTypes defined in it. This can be useful for testing purposes, so GeoServer does not load everything up.

Namespace is a drop down box of the possible namespaces. You should have defined your namespace, so select that one. One thing to note is that there is a slight limitation with GeoServer here, namely that you can not define two featureTypes from the same DataStore in different namespaces. If you wish to do that the recommend way is to define two DataStores, with exactly the same connection parameters, but different DataStore ids andnamespaces. We know, it's a bit hacky, but it's the best we've got, and changing this around requires a lot of changes in GeoTools (though it should be possible if we get the arbitrary mapping of schemas correct).

Description is mostly used internally, so that other admins can get extra information about the DataStore.

As for the additional fields, they depend on the format of the data you wish to server. GeoServer 1.3 comes with support for four data types by default. PostGIS was the first datastore offered with GeoServer, and remains the best supported and


most tested. PostGIS is based on the advanced open source database PostgreSQL with extensions to handle spatial types and operations. It conforms to the OGC's Simple Features for SQL specification, completely compliant as of version 1.0. Shapefiles were the first additional datastore supported, allowing users to quickly get GeoServer running. We recommend using a real transactional database, but do offer the ability to serve and do transactions on shapefiles in GeoServer directly, with solid performance. Note that there is also a new shapefile datastore that builds and uses a spatial index, available as a DataStore Extra . Oracle is also available, though it needs an extra jar in order to run, as we are not allowed to redistribute the jar. ArcSDE is additionally supported, and 1.3 brought a number of bug fixes to get it actually working decently well. Proprietary datastores such as Oracle and ArcSDE are harder for us to support, since they can not be easily downloaded, installed and tested (and it gets even nastier when you get into different versions). The GeoServer project will do all that we can to support them, but if you require real support then we recommend you hire someone to do consulting on GeoServer, see the section on [Commercial Support].

We have also started offering DataStore Extras . This a section of the download page where we offer new and experimental DataStores. DataStores are written to be completely pluggable, you just put the appropriate jar files in the lib/ directory of GeoServer, and they are available at the next GeoServer start up. This means that we can offer new DataStores, such as MySQL and IndexedShapefile, for advanced users to test out, as well as easily make upgrades to older DataStores available. For example there were a number of speed improvements to thePostGIS datastore in 1.3, but instead of downloading the whole new server, you could just download the jar into your 1.3.0 version, and get all the improvements.


5.2. Shapefile DataStore

5.2.1. Shapefile

For users who don't have a spatial database already set up and want to get GeoServer running quickly, we offer support for Shapefiles directly in GeoServer. You can even perform transactions against Shapefiles, modifying them through the WFS-T interface. But we do not really recommend it, as they weren't designed for such purposes. Any production instance of GeoServer should use a spatial database, PostGIS has a great shp2pgsql tool to easily turn your shapefiles into PostGIS tables.

Thanks goes to the GeoTools team for this great contribution, and especially Ian Schneider, for getting things good to go for GeoServer.

The main field of the Shapefile DataStore is the url. A url is just a location, it need not be an online location (though it can be). In the case of shapefiles the most likely case is that you have the files somewhere on your computer. For GeoServer you have the choice of copying them into your GeoServer data directory, and referring to them relative to the base directory, or leaving them where they are and entering the url in your file system. The included sample shapefiles make use of the first way, but that's because we have no idea where you might put GeoServer, so can not refer to them on your file system, since we don't know the absolute location.

All file url's that start with file:data/ are interpreted byGeoServer as relative ones. This means that GeoServer will figure out the root directory for you automatically. This is best for those wanting to transfer a GeoServer configuration to another computer, as you can just include all the Shapefiles that are needed and refer to them relatively. An example of this is the states shapefile, its url is:

file:data/featureTypes/states/states.shp

Note that the web admin tool does some magic as to where to place the files. If you are adding a new shapefile we recommend that you put it in the featureTypes directory named datastoreid_shapefileName where datastoreid is the value you assign it when you create the new datastore, and shapefileName is the name of the actual file. Doing this has the nice effect of creating the configuration files in the same directory as the actual shapefiles, and thus making all directly available for download from the same spot (if you don't do this everything will still work, the files will just be in different locations, unless you move the generated config files back to your shapefile directory). Which brings up the other nice effect of using the relative locations, users can directly download the shapefiles, by just accessing it through the web. Try going to:

http://localhost:8080/geoserver/data/featureTypes/bc_roads/


All the shapefiles are there, as well as the configuration files (note that the catalog.xml file, that contains sensitive passwords, is notaccessible through the web, which is by design). In the future we are considering making GeoServer more of a full data distribution server, where it would make all layers (even database ones) available for direct download with generated shapefiles (link to jira). But for now any shapefile you put up will be available for download.

If you specifically don't want your shapefile available for download, then we recommend just inputting its absolute path. This is done differently on linux and windows file systems. On windows you wouldspecify the url as something like:

Windows file:/C:/Documents and Settings/Chris/My Documents/shapefiles/states.shp

Notice the drive letter is specified, followed by a typical filepath.

In Linux you would not specify the drive letter, just the location on the file system:

Linux file:/home/cholmes/shapefiles/states.shp

Note that a consequence of using the Url is that you actually can refer to a shapefile that is online. We certainly don't recommend it, you should instead download the file to the same computer GeoServer is running on, so you're not sending network requests every time. But it is an interesting example of how you can spread your resources around and have GeoServer centralize them and share them with the world.

There are two other optional parameters for Shapefiles. The memory mapped buffer should generally be set to true, it's more for programmers. The dbf charset parameter specifies a Character Set to be used to read the DBF file (the file that contains the attributes of the Shapefile). The default is ISO-8859-1.

5.2.2. Indexed Shapefile

The Shapefile (Indexed) option works just like the normal shapefile, except you can click the option to 'create spatial index', which will create a new index if there's not one already. You can leave the rest of the options at their defaults (todo: explain what the other options are, I think that memory mapped doesn't really matter at all, some programmer option, and I have no idea about the index type, but leaving it blank will suffice. Also these datastores should just be combined...)


5.3. ArcSDE DataStore

5.3.1. ArcSDE

ArcSDE is the least supported of the main GeoServer DataStores, mostly due to the expense and license limitations of setting up ArcSDE instances. We have also found their connection drivers a bit buggy (and the source is closed so we can't just fix them ourselves), and have also encountered problems that only seem to manifest themselves in certain instances, leading us to do some complicated work arounds. We suspect the differing problems have to do with the backend data format, but could be different versions of ArcSDE. The DataStore was contributed by and maintained by Gabriel Roldan, testing against ArcSDE 8.3. Additional users have reported success with 9.0 and 9.1.

GeoServer supports ArcSDE 8 and 9, users have reported success on 8.3, 9.0, and 9.1. We used to distribute 8.3 jars, but the public site that had them has been taken down, and they never had a clear license, so in the interest of good IP we are no longer distributing them. So the first step in getting GeoServer working is installing the proper arcsde java libraries.

For connecting both to ArcSDE 8.x and 9.x you will need the jsde and pe jars for version 9.x, since the geotools arcsde plugin that geoserver depends on is built against them. This should be found as follows:

ArcSDE Version Jars needed Location

9.0 jsde90_sdk.jar and jpe90_sdk.jar

[arcsde install dir]/arcsdesdk/sdeexe90/lib/

9.1 jsde91_sdk.jar and jpe91_sdk.jar

[arcsde install dir]/arcsdesdk/sdeexe91/lib/

Note that these jars are backwards compatible, so if you need to access an 8 and a 9 instance you can just use the newer jars. If you've used the CD to install the ArcSDE client on your computer than it likely copied the jars in to your JRE and they should be available. Check [JAVA_HOME]/lib/ext for the jars. If not you can copy the appropriate jars to your geoserver library directory (webapps/geoserver/WEB-INF/lib on a war install, [GEOSERVER_HOME]/server/geoserver/WEB-INF/lib on a binary install).

Next you'll want to download the appropriate ArcSDE jar from GeoServer Extensions . Follow the instructions, copying the gt2-arcsde jar to the geoserver library directory. After you've done that restart GeoServer and you should now have ArcSDE as an option in the drop down menu from the web admin tool at Config -> Data -> Stores -> New.

To connect to an ArcSDE instance you must have the following parameters:

Option Name Description server The machine which the ArcSDE instance is running on.

port The port the ArcSDE instance is running on. The default is 5151

instance The ArcSDE instance name user The name of the user to connect with. passwd The password of the user you are connecting with.

As with PostGIS and Oracle configuration of the files directly also needs a 'dbtype' parameter equal to 'arcsde'.

There are also a number of optional parameters to configure the ArcSDE connection 'pool'. GeoTools makes use of a number of connections, but does a decent job of managing them, so that new connections need not be made for each request. The big reason for this is that some ArcSDE licenses only allow a limited number of connections, so these values can be adjusted to minimize the number of simultaneous connections. GeoTools will share the active connections instead of making new ones. Right now it requires at least two connections, as we were having some nasty bugs with ArcSDE connections going stale (only with certain instances, and only with spatial queries, which made debugging a big hassle). With some funded development work this could easily be improved, ArcSDE could definitely benefit from some more effort. If you have more connections available we do recommend upping the pool.maxConnections parameter. The meaning of these optional parameters is as follows:

Option Name Description

pool.minConnections The number of connections the pool makes on start up. If needed these will be incremented.

pool.maxConnections The maximum number of connections that a pool is allowed to make. This should be as high as possible, but there may be license limitations.

pool.increment The number of new connections to add to the pool when incrementing. One is most likely fine.

pool.timeOut The amount of time that a connection request should wait for an unused connection before failing.

One more thing to note is that in the info.xml file the <name> parameter of the featureType may need to be the full qualified type name. It should be <instance>.<table_owner>.<table_name>, so in the example above a table called roads should be named sde.testsde.roads. But some users have also reported success without the instance prepended. Also make sure that the port number specified is the same as in the services file (%(%(%systemRoot%\system32\drivers\etc\services in windows), it should


contain a line like (if yours is different then change the port param of your datastore definition):

esri_sde 5151/tcp

5.4. Oracle DataStore

5.4.1. Oracle

GeoServer also offers Oracle Spatial support, contributed by Sean Geoghegan, and currently searching for a new maintainer. It includes native support of all OGC filters, connection pooling, and transactional capabilities. Please check the wiki for the latest information on oracle. Latest download available here .

We are no longer dependent on the sdoapi jar, thanks to some nice work done by Refractions Research. There is still one jar file that we can not distribute, the driver for the JDBC connection to Oracle, it should be called ojdbc14.jar. This is targeted at java 1.4, which is required by GeoServer. We have also found that classes12.jar works as well, the main class it needs to have is oracle.jdbc.driver.OracleDriver. If you are installing GeoServer on the same computer that is running Oracle you should be able to find the jar at $ORACLE_HOME/jdbc/lib It is also readily available from the Oracle Technology Network here . Just place the jar in the geoserver/server/geoserver/WEB-INF/lib/ directory of a geoserver binary install. Once the jar is in the directory then Oracle Spatial Database and Oracle Spatial with OCI (thick) connection should be options from the drop down menu when creating a new datastore.

There is a choice in the type of connection that you use to connect to GeoServer. The standard 'Oracle Spatial Database' connection uses a completely portable JDBC library, that runs as a thin client on any computer. If you don't have Oracle installed on your computer, and/or are not an Oracle expert and know exactly how an OCI connection works, then we recommend you use this one.

Often GeoServer will be installed on a computer that has all the OCI (Oracle Call Interface) drivers needed for a thick connection (such as when installed on the same computer as the database). In this case the thick driver is preferable, as it leads to a nice speed increase. It should come up as an option on the new datastore menu, it has a few parameters different from the standard Oracle Spatial connection. Instead of taking a host, port, and instance params it uses an 'alias'. This alias can be found in $ORACLE_HOME/network/admin/tnsnames.ora. Note that if you are using the OCI you must use the classes12.jar or ojdbc14.jar found in your $ORACLE_HOME/jdbc/lib directory.


All Oracle DataStores make use of the following parameters:


user

The name of the user to connect to the database. Must have appropriate privileges on the database connecting to. Note that through this mechanism you can actually get finer control of transactions in GeoServer. You do this by creating a user that does not have transaction privileges on the database, and only letting GeoServer connect with that user. This will not be reflected in the Capabilities documents, but all attempted inserts, updates, and deletes will be rejected.

passwd The password for the user you are connecting with.

dbtype Must be 'oracle' to use the oracle datastore. (only needed when working directly with the config files directly, the web admin tool takes care of this for you)

schema An optional field to specify which schema the tables should be found in.

Additionally, a standard JDBC connection will make use of the following parameters to specify the machine that Oracle is running on, and the port and instance to connect to.


host The machine on which oracle is running. Can be a number or name - for example localhost or 127.0.0.1 if Oracle is on the same machine as geoserver, if not it can reference the ip address or host name.

port The port the Oracle instance is running on. The default is 152. instance The Oracle instance name, should be the same as the SERVICE ID.

An OCI connection does not need that information, it uses the 'alias', which contains all the connection information, and indeed is specially configured for it. As we mentioned earlier this alias can be found in

$ORACLE_HOME/network/admin/tnsnames.ora

We have also had some success with leaving the alias as an empty string, it seems to find the appropriate default.


So the param is:

Option Name Description alias The connection alias from tnsnames.ora used to connect with.

To get your featureTypes working properly the oracle spatial table you are using must have a correct entry in the USER_SDO_GEOM_METADATA table (now works in ALL_SDO_GEOM_METADATA view, so different users than the owner can connect). And whatever table you use must have a primary key declared, it will not work otherwise. We have also seen problems using spatial filters when a spatial index is not defined, so if everything but spatial filters work it may just be that the spatial index is not defined for the table.

We have also recently had a note from users about configuring the FeatureType, if you use the default (XML fragment) then things will sometimes not work properly. Pick the 'String' option, and Oracle should sort out itself what the return type should be. If you have more feedback on this please update the wiki, and we will be working on the problem.

A nice little tool to help out figuring out if your oracle instance can be connected to and what the parameters are is lsnrctl. If you can run it I believe that means that your oracle instance will accept a connection from geoserver. And it is also useful for figuring out the hostname - mine would not accept 'localhost' or '127.0.0.1' (this is with 10g and windows xp), it needed the name of my computer, which was given by the lsnrctl program, with the services command. The 'status' command will also tell if geoserver is connected to your oracle instance. Also note that if you are working directly with the geoserver configuration files the name element in the info.xml file to specify the featureType must be all capitalized, as the JDBC driver does not recognize the table otherwise. This also means that when you request the features from GeoServer you must use upper cases. If specifying attributes in the schema.xml file they must also be all capitalized. Oracle does not use cases, but things seem to work better all around if all upper case letters are used.

5.4.2. Troubleshooting

"When adding an OCI datastore, I would get a message that libocijdbc10.so could not be found in the java.library.path (and another one). The directory which contains that "so" does exist in the LD_LIBRARY_PATH (does Tomcat pick that up?)."

Set the environment for Tomcat appropriate:

export ORACLE_HOME=/opt/oracle/product/10.1.0/Db_1 export CLASSPATH=$ORACLE_HOME/jdbc/lib/ojdbc14.jar:$ORACLE_HOME/jdbc/


lib/orai18n.jar:$ORACLE_HOME/jdbc/lib export LD_LIBRARY_PATH=$ORACLE_HOME/lib

The last setting depends on system, we have a SuSe Linux. Sometimes it is LD_PATH or SH_LIB_PATH etc.

"When adding a datastore out of table created with AutoCAD Map, Geoserver complains there are geometry columns not defined in metadata."

The problem lies in the peculiar ways of AutoCAD Map, which writes columns not only to store the entity's geometry, but for ancillary data (such as as blockscale) as well. These columns though, are not added to Oracle Spatial's metadata, hence the resulting Geoserver embarassment.

The solution (tested with AutoCAD Map 3D 2006, Oracle 10g, Geoserver 1.3.0) is to filter out those "extra" geometry columns by using a view, and then using the view (and not the underlying table) as a source for the Geoserver feature type.

The steps are the following:

1. Suppos you have created an Oracle table called 'mytable' with AutoCAD Map, and this table contains the entities' geometry in a column called 'geometry'.

2. Create an Oracle view as:

CREATE VIEW GSmytable AS SELECT geometry, entityid FROM mytable;

3. Add a suitable row for the GSmytable view in USER_SDO_GEOM_METADATA by copying the mytable diminfo and srid columns:

INSERT INTO user_sdo_geom_metadata (table_name, column_name, diminfo, srid) SELECT 'GSMYTABLE', column_name, diminfo, srid

FROM user_sdo_geom_metadata WHERE table_name = 'MYTABLE';

4. Create the feaure type using the GSmytable view.


VI. Service Configuration

6.1. Configuring GeoServer

This document and the Data document should completely describe how to configure GeoServer. This is focused on the basics of the web administrationtool, and then goes into configuring the options and metadata for the server. The Data Configuration document focuses on adding your own data to GeoServer. Both documents assume you are working with the web administration tool, for information on working with files see the developer docs.

Overview

• Go to http://localhost:8080/geoserver • Log-in (default user: admin, password: geoserver) • Configure Server, WMS and WFS. Be sure to hit 'submit'. • Preview changes with 'Apply', save them with 'Save'

6.2. Web Admin Tool Introduction

The main focus of GeoServer 1.2 was the web administration tool. It is built on STRUTS , and offers a complete graphical user interface, so that users need not ever touch configuration files. It additionally offers the ability to 'try out' new configurations before actually saving them. The work was driven by the excellent team at Refractions Research , with funding from the GeoConnections program. Notethat the web administration tool is in no way required to operate GeoServer, you are more than welcome to work directly with the configuration files. We discuss these at length in the Developer's section, see [Config Files], but for the User docs we assume that you are working through the web admin tool. Some advanced users may need to access the files directly, we will discuss those situations in the user docs. In the future it may be possible to administer a remote GeoServer using a desktop client like uDig, as we designed for such a situation. The admin tool is meant to be as intuitive and self explanatory as possible, and much help is available from it directly. Most every operation and link has a tool tip that pops up on a mouse over (when you leave the mouse on top of it for over a second). It is also designed for Internationalization, and has been translated into French and Spanish. It should start up automatically in the language that the computer running GeoServer is set to. If you are interested in translating GeoServer into another language, please get in touch. See the translation section in How to Help for more information.


6.2.1. Accessing the Web Admin Tool

To access the web admin tool simply fire up your favorite browser and enter the following address:

http://localhost:8080/geoserver You should see a page like:

The first time accessing this page will take a bit of time to load, as GeoServer needs to compile the pages of the application. This will only occur on the first access of the tool, and in future GeoServer versions we should be able to cut down that load time substantially (this is also the only place the JDK as opposed to the JRE is really needed, as java is needed to compile the web pages). As you can see the welcome page contains a few messages and links relating to GeoServer, and then also displays the Title and Abstract sections of the WMS and WFS Capabilities documents. When you edit these the changes will be reflected in the welcome page, so that it is a welcome to your GeoServer instance, with links to the Capabilities documents. It also contains links to the three main GeoServer sections. Demo is the only public section, it contains a nice page to make WMS and WFS requests against GeoServer, with a number of samples. Admin and Config both require youto login. Admin is still more at the idea stage, meant to administer arunning GeoServer. Config contains the bulk of the web admin tool, it is where all the configuration of GeoServer takes place.


6.2.2. Logging In

So that not everyone can come in and modify the configuration ofGeoServer we require a log-in to access the Admin and Config sections. Attempting to click on either from the start page will take you to the log-in page if you are not already logged in, or you can click on the login link in upper right corner. This should take you to the log-in page.

At this point there is only one username and password for the application. In the future we hope to have multiple roles and profiles, so that different users can have different levels of access. This would include administration of GeoServer, but ideally would also extend towards access and transactional capabilities on layers. Your Capabilities documents would be geared to the profile of the user accessing the application, if they were allowed to see the layer, and if they were allowed to modify it. The default password of a new GeoServerinstance is

username: admin password: geoserver

We highly recommend changing the password, so access to the administration of GeoServer is not open to all.

6.2.3. Changing the Password

To change the password go to the Config section. You will then be able to select the Server section, and from there the Password section. Enter your new user name and password, and then save.

6.2.4. Saving your changes

The GeoServer admin tool is built so that you can 'try out' your changes. You will notice three buttons on the left side whenever you are in the configuration sections of the application. The general mode of working is to hit 'Apply' after you have made the changes you would like. Do remember to hit the submit button before you hit 'apply' or the changes will not go through.

This applies the changes to the running GeoServer application, so that you can then do your normal WFS and WMS access to 'try out' the changes, to see if everything is configured correctly. But after an apply these changes have not yet


been 'committed'. If you are to restart GeoServer then the changes will be lost. So if you are happy with your changes then you should hit the 'Save' button:

This will save the current configuration as XML files that GeoServer will read the next time it starts up. If you are not happy with your changes then hitting the 'Load' button will discard the changes you have made and revert GeoServer to the state it was in when you last hit 'Save' (or last started up, if no changes have been saved). Note that the current state of saves can be ascertained by looking at the left hand tool menu. If there are changes that have been submitted, but not applied, then the Configuration line will have a star by it. Once Apply is hit then GeoServer will have a star by it, indicating that there are applied changes that have not been saved. Note that both can easily be starred, if you have applied some changes and only submitted others. The date and time for each displays the last time they were modified. One last thing to mention, the status bars all indicate the amount of successfully loaded DataStores. Just in case you were wondering. We admit this is not all that useful, but hey, it looks kinda cool, no?

6.3. Admin Page

The Administration Page is still more of a place holder for future ideas. The main useful functionality it offers at the moment is to release locks that may have gone stale. It also provides information on the JVM version and if JAI is installed. The free memory tool works more or less, but it reports very confusing numbers. The admin page in the future will likely be used to administer user roles and access permissions, but there is much work to be done before we get there.


6.4. Config

To get to the main Config page hit the 'Config' button from the welcome page:

From the main Config page there are four options. In general we recommend working through configuration from top to bottom, though you can work in most any order. If you are making a production instance of GeoServer it is very important to fill out all fields. If you are just evaluating GeoServer, wanting to try out your own data, then you can just focus on the Data Configuration section (just [DataStore Configu] and FeatureType Config if you want to get very minimal). Though the Server Configuration section should also be useful, especially if you need to debug.

1. Server Configuration 2. WMS Configuration 3. WFS Configuration 4. Data Configuration

1. Namespace Config 2. DataStore Config 3. Style Config 4. FeatureType Config

6.5. Validation

GeoServer 1.3 includes the innovative Validation capabilities, completed by Refractions Research, which gratefully acknowledges the GeoConnections Secretariat for providing matching funds for the development via the GeoInnovations program. It provides a mechanism for ensuring that features edited via GeoServer are spatially clean before allowing them to be inserted into the spatial backend databases. If you are working using GeoServer to its full WFS-T transactional capabilities we strongly recommend that you consider defining a few validation tests. These can be easily defined to ensure simple things like no 0 length geometries, and no dangling lines. But it can also express more complex tests, like ensuring that no streets overlap with defined houses, and that the street name is defined in a Gazetteer.


The Validation configuration is accessed in the WFS section. For 1.3 we don't have time to port and improve the validation guide, so for now just refer to the document created by Refractions, found

• ValidationUserGuide.pdf

If a volunteer wanted to take on the task of making a real validation guide and tutorial, it would be hugely appreciated, as there are some very powerful features there, that no one makes use of since they aren't documented. Indeed uDig 1.1 is starting to use some of the same code, which should hopefully make it easier to define test suites and share between the two. There is also information at: http://vwfs.refractions.net


VII. SLD Intro Tutorial Styled Layer Descriptors, or SLD, are what make your maps colorful. They tell the server how the map should be rendered; whether to draw lines in black, or to color them in blue with a nice outline and text labels.

They can turn your map from plain:

to nice:

SLD is an XML based language detailed in an open specification available here . This means that SLD files created for GeoServer can be re-used with any WMS that supports SLD. We don't want lock you in to learning yet another way to style maps, so we put the open standard SLD at the center of GeoServer's rendering system.

Now to get even the first image, you need an SLD. Lets look and see how we will do that...

7.1. SLD Hello World

We will start by creating a simple style for lines.

7.1.1. Create the SLD File

STEP 1 Make a new file called lines.sld. Save the file anywhere you wish. In the file, enter the following XML:

<?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>Default Line</Name> <UserStyle> <Title>A boring default style</Title> <Abstract>A sample style that just prints out a green line</Abstract> <FeatureTypeStyle>  <Rule> <Name>Rule 1</Name> <Title>Green Line</Title> <Abstract>A green line with a 2 pixel width</Abstract> <LineSymbolizer> <Stroke> <CssParameter name="stroke">#319738</CssParameter> <CssParameter name="stroke-width">2</CssParameter> </Stroke> </LineSymbolizer> </Rule> </FeatureTypeStyle> </UserStyle> </NamedLayer> </StyledLayerDescriptor>

The important part, to you, is the <rule>. This will describe what to draw and how to draw it. You can have as many rules as you want. This rule has no restrictions, so it will draw every line in green with a 2 pixel width.

The element that is actually specifying how to draw is the <LineSymbolizer>. In this element we specify the color of the line, <CssParameter name="stroke">#319738</CssParameter>, and the width of the line, <CssParameter name="stroke-width">2</CssParameter>.


7.1.2. Load Your New SLD

STEP 2

First you will have to start GeoServer. Once it is up and running, navigate to the config/data/style area:

---> --->

In this window, hit new on the left side of the navigation bar:

STEP 3

You will be asked to supply a name for your style (StyleID), lets call it lines. The name does not have to match the filename, but it is good to keep it similar to avoid confusion. Once you have entered the name, hit the New button below it.


STEP 4

The new window you will be taken to will ask for the location of the SLD document. Click on the Browse button and locate the file you created: lines.sld. Click on the file, and hit 'Open' to close the file browse window. The full path should now be in the 'Filename' text field. Make sure that the check box, Fully Validate against the SLD schema, is checked off. This will make sure our style conforms to the SLD schema.

When you have done all of that, hit the Submit button. This will trigger GeoServer to validate your SLD document and then copy it over to GeoServer's data/styles directory. Everything should work correctly. If it doesn't, there are two types of errors you may get:

1. "There is already a style by the name of lines.sld stored on GeoServer. Please rename the file and try again". All you have to do in this case is rename your file to something else. This does become an issue when you want to modify and reload the file to test it again. All you have to do is navigate to GeoServer's data/styles directory and delete the SLD document that has the conflicting name.

2. "Your .SLD file does not conform to the SLD Schema". This error is more complicated, but it usually just the result of a typo or an element that is in the wrong place. This error happens when your SLD document does not conform to the SLD schema. It will also point to where your SLD is wrong. You will have to fix the error, and submit again (hit the back button, and then hit submit).

STEP 5

For the changes to take effect, you must hit the 'Apply' button on the left hand side of the screen.


7.1.3. Give a FeatureType Your New SLD

In order to see what our style looks like, we need to tell a FeatureType what style to use. Then, whenever we view that FeatureType with the WMS, we will see our style.

STEP 6

Navigate to the FeatureType config menu (Config/Data/FeatureType):

---> --->

We now need to select an existing layer and change its Sytle. For this tutorial, we will select on of the FeatureTypes that comes installed with GeoServer: tasmania_roads:tasmania_roads In the drop down list of 'Feature Types', select tasmania_roads:tasmania_roads


Once you have selected it, hit the 'Edit' button.

STEP 7

You should now be in the FeatureType editor screen. Near the top of the screen, under the name of the FeatureType, there will be the Style drop down list. Select your 'lines' style from the list. When you have done that, go down to the bottom of the page and hit the 'Submit' button.

STEP 8

We need to register the change in GeoServer, so once again navigate to the left hand side of the screen and hit the 'Apply' button.


7.1.4. View the Style

It is now time to look at the new style we made.

STEP 9

With GeoServer still running, navigate to the Demos section of the Welcome page. In there, click on Map Preview, or just click on this link http://localhost:8080/geoserver/mapPreview.do .

This page shows you all of the enabled FeatureTypes you have. Locate the topp:tasmania_roads FeatureType and then click on the Preview button to the right of it. This will open up a new window with a MapBuilder view of the dataset. You can also click on this link http://localhost:8080/geoserver/data/generated/topp_tasmania_roads.html to view it.

Hopefully you will see this:

7.2. SLD Text Symbolizers

We will continue from the previous example where we made a style, lines.sld, that rendered lines green and 2 pixels thick. This time we will add text to the lines that will be read from the roads themselves.

7.2.1. Modify the SLD File to Include Text Symbolizers

STEP 1

Open up your lines.sld file. change it so it looks like this:

<?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>Default Line</Name> <UserStyle> <Title>A boring default style</Title> <Abstract>A sample style that just prints out a green line</Abstract> <FeatureTypeStyle>  <Rule> <Name>Rule 1</Name> <Title>Green Line</Title> <Abstract>A green line with a 2 pixel width</Abstract> <LineSymbolizer> <Stroke> <CssParameter name="stroke">#319738</CssParameter> <CssParameter name="stroke-width">2</CssParameter> </Stroke> </LineSymbolizer> <TextSymbolizer> <Label> <ogc:PropertyName>TYPE</ogc:PropertyName> </Label> <CssParameter name="font-family">Times New Roman</CssParameter> <CssParameter name="font-style">Normal</CssParameter> <CssParameter name="font-size">16</CssParameter> <CssParameter name="font-weight">bold</CssParameter> <Fill>

<CssParameter name="fill">#FF0000</CssParameter> </Fill> </TextSymbolizer> </Rule> </FeatureTypeStyle> </UserStyle> </NamedLayer> </StyledLayerDescriptor>

The part that has changed is the adition of the <TextSymbolizer> element:

<TextSymbolizer> <Label> <ogc:PropertyName>TYPE</ogc:PropertyName> </Label> <CssParameter name="font-family">Times New Roman</CssParameter> <CssParameter name="font-style">Normal</CssParameter> <CssParameter name="font-size">16</CssParameter> <CssParameter name="font-weight">bold</CssParameter> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </TextSymbolizer>

The parts of this <TextSymbolizer> are:

• <Label>: What label to give each rendered object. Here we use an attribute of the object, "TYPE". The property name is case sensitive.

• : The font and size the label will have. • <Fill>: The color that we will fill the font with

There are other options, but we are just going to do something simple for now.

STEP 2

Save your file and keep the name the same, lines.sld.

Head back over to the config/data/style/ page in GeoServer and select your style, lines, from the drop down list. Then hit the 'Edit' button.


STEP 3

In the Style Edit page, use the 'Browse' button to locate your style file, 'lines.sld'. Hit 'Open' to close the browse window, then hit the 'Submit' button.

STEP 4

We need to register our change, so head to the left side of the screen and hit the 'Apply' button.

STEP 5

Lets go and view our changes now. Head to the Map Preview page (http://localhost:8080/geoserver/mapPreview.do ) and click on the

topp:tasmania_roads preview button (http://localhost:8080/geoserver/data/generated/topp_tasmania_roads.html ).

The image should look something like this:

What you will see is the TYPE of the roads displayed. It will not render the label on all of the roads, it will only render the unique values so the road names won't clobber each other. This can become difficult if there are two nearby roads with the same name, but aren't actually the same road. You will get one with a label and one without. To fix this simply add the tag: <VendorOption name="group">no</VendorOption> in your <LabelPlacement> tag.

For an indepth document about Labeling, visit the Labeling Options page.

7.3. Outlines and Filters

This is a very brief introduction to using filters and other text symbolizer techniques with SLDs.

The following SLD document will render all non-highways in the regular green color with a red label. But it will also render the highways with an outline, and give their label an outline.

Here is the SLD:

<?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>Default Line</Name> <UserStyle> <Title>A boring default style</Title> <Abstract>A sample style that just prints out a green line</Abstract> <FeatureTypeStyle>  <Rule> <Name>Rule 1</Name> <Title>Green Line</Title> <Abstract>A green line with a 2 pixel width</Abstract> <ogc:Filter> <ogc:Not> <ogc:PropertyIsEqualTo> <ogc:PropertyName>TYPE</ogc:PropertyName> <ogc:Literal>highway</ogc:Literal> </ogc:PropertyIsEqualTo> </ogc:Not> </ogc:Filter> <LineSymbolizer> <Stroke> <CssParameter name="stroke">#319738</CssParameter> <CssParameter name="stroke-width">2</CssParameter> </Stroke> </LineSymbolizer> <TextSymbolizer> <Label> <ogc:PropertyName>TYPE</ogc:PropertyName> </Label> <CssParameter name="font-family">Times New Roman</CssParameter> <CssParameter name="font-style">Normal</CssParameter> <CssParameter name="font-size">16</CssParameter> <CssParameter name="font-weight">bold</CssParameter> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </TextSymbolizer> </Rule>  <Rule> <Name>Rule 2</Name> <Title>Outlined Highways</Title> <Abstract>A gray outline and white fill, with a 8 pixel width</Abstract> <ogc:Filter> <ogc:PropertyIsEqualTo> <ogc:PropertyName>TYPE</ogc:PropertyName>

<ogc:Literal>highway</ogc:Literal> </ogc:PropertyIsEqualTo> </ogc:Filter> <LineSymbolizer> <Stroke> <CssParameter name="stroke">#444444</CssParameter> <CssParameter name="stroke-width">8</CssParameter> </Stroke> </LineSymbolizer> <LineSymbolizer> <Stroke> <CssParameter name="stroke">#999999</CssParameter> <CssParameter name="stroke-width">4</CssParameter> </Stroke> </LineSymbolizer> <TextSymbolizer> <Label> <ogc:PropertyName>TYPE</ogc:PropertyName> </Label> <CssParameter name="font-family">Times New Roman</CssParameter> <CssParameter name="font-style">Normal</CssParameter> <CssParameter name="font-size">18</CssParameter> <CssParameter name="font-weight">bold</CssParameter> <Halo> <Radius> <ogc:Literal>2</ogc:Literal> </Radius> <Fill> <CssParameter name="fill">#FFF88B</CssParameter> <CssParameter name="fill-opacity">0.85</CssParameter> </Fill> </Halo> <Fill> <CssParameter name="fill">#FF0000</CssParameter> </Fill> </TextSymbolizer> </Rule> </FeatureTypeStyle> </UserStyle> </NamedLayer> </StyledLayerDescriptor>

7.3.1. Rule

What we have done is supply another rule to our SLD.

Rule 1

The first rule will render all non-highways with a green line. To determine what roads are not highways, we use a <filter>:

<ogc:Filter> <ogc:Not> <ogc:PropertyIsEqualTo> <ogc:PropertyName>TYPE</ogc:PropertyName> <ogc:Literal>highway</ogc:Literal> </ogc:PropertyIsEqualTo> </ogc:Not> </ogc:Filter>

This rule will only render the line if its 'TYPE' is not equal to "highway". The 'not' is specified by wrapping the "PropertyIsEqualTo" element in an <ogc:Not> element. If the TYPE is 'highway', then the rule is not rendered for that particular line segment.

Other useful filter elements are:

• <ogc:PropertyIsLessThan> • <ogc:PropertyIsGreaterThan>

Rule 2

This rule uses a filter to determine if the road's TYPE is equal to "highway". If it is, it will render two lines for the road. The first is a thick dark gray line, the other is a thinner light gray line. They are rendered in the order that they are specified.

The other thing it will do is render the labels using a <halo> in the <TextSymbolizer>. The halo is essentially a buffer outline of the text.

<Halo> <Radius> <ogc:Literal>2</ogc:Literal> </Radius> <Fill> <CssParameter name="fill">#FFF88B</CssParameter> <CssParameter name="fill-opacity">0.85</CssParameter> </Fill> </Halo>


7.3.2. Output

If it all worked out, the result should look something like this:

7.4. What SLDs are, a text approach

SLD (Styled Layer Descriptor) is a specification put out by the OGC, that defines an XML language to allow users to define symbolization of their feature data. It was written to be a complement to their Web Map Service (WMS) specification, by extending it to allow users a way to define how they want to visualize their features.

The spec is available here?

In the original WMS versions a user could ask for a 'style', specified by name, to view the map in. Each server advertised what 'styles' could be asked for with which layers. This was pretty inflexible, the only control a user had was to pick a name for a style, if the map didn't look the way she wanted it to then that was just too bad.

It became obvious that it would be nice for users to be able to tell a server what they would actually like the style to look like. And thus came SLD, a nice little xml language for machines to understand how a human would like a map to look.

So for each layer you could say 'color all my line features blue', or 'make all polygon borders black, and the insides purple', or even 'use this little triangle graphic for all my points'.

But you can also define even more complex functionality. You can define the style rules based on attributes of the features in a layer. To pull an example from


the SLD spec itself: 'For example, in a roads data set, style highways with a three-pixel red line; style four-lane roads in a two-pixel black line; and style two-lane roads in a one-pixel black line.'

The spec was originally meant for WMS, you could define an SLD document and send it to a server, and it would return the layer in the style you specified. But it has proven more useful than that. One way is to combine it with a WFS. There is a notion of a Cascading WMS, which would just be a middle layer between a WFS, adding the appropriate style and portraying it as the user wanted. A WFS defines the data, the WMS just adds the style information. GeoServer plans to have cascading WMS capabilities for version 1.3. The other place it's proven useful is as part of applications themselves. A good client could take a SLD file and apply that to the WFS response (GML) that it receives (this is what Sonny's client does, it's actually outside the original reason for the SLD spec, but a good use of it, as an SLD file could be passed to different clients ? you can send the WFS link and an SLD, so that they could actually get the data, instead of just a WMS response, which is simply a picture of the data). It's also useful as a way to define styles on the server itself. In OGC speak these are 'named' styles, as opposed to user defined ones. For user defined you send an sld document directly to the server, for a named one you just request the style by it's name. This is what GeoServer does, as there was already SLD support in GeoTools, and it's a solid way to define styles. GeoServer's styles are configured directly by reading SLD files.

There is also having SLD files themselves be passed about the read. I believe there was a discussion spec for a server that would hold SLD files, and you could request them from the server, a sort of SLD service. The SLD extensions to a WMS also describe PutStyle and GetStyle operations, where a user could upload his style to the server, and others could download the files themselves.

I don't have time right now to run through a bunch of sample SLD files, which I will in a final tutorial. You can refer to 'named' styles, but the more interesting part is the user defined stuff. There are two main sections for user defined styles (I think, I need to research this more, my SLD skills aren't nearly as strong as my WFS skills). A Rule defines in what cases the style should be applied. They can use the whole suite of OGC filters, so you really can define a lot. Complex stuff like coloring based on math expressions (add the unemployed, underemployed and temporary employed attributes, divide by total number of people, to give percentage of workers at less than full employment, and define the opacity based on the resulting number). They can also be defined for map scales, so things like only show two lane highways when we are at a certain resolution In a rule you can also define a 'legend graphic', which will show what means what on the map, by pointing to some external file (GeoServer has aspirations to create dynamic legend graphics based on the SLD definitions).

Then there are 5 types of symbolizers you can use to actually portray the features, line, polygon, point, text, and raster. A line symbolizer will define a 'stroke' for a line geometry. A stroke is made up of a couple elements, allowing you to specify


a color, or a graphic, along with things like opacity, width, joins between lines, a dash pattern and a dash offset.

A Polygon Symbolizer has a geometry and a stroke, just like a line symbolizer, but also has a 'fill', defining what color to put in the center. Can be straight color, or a graphic, of varying opacity and the like.

A point symbolizer is made up of a geometry and a Graphic. A graphic is made of either an External Graphic, or a Mark, and has an opacity, a size, and a rotation. Opacity is the same as for the other symbolizers, Size is the absolute size of the graphic in pixels (default is to be dynamic), and rotation defines the rotation of the graphic in the clockwise dimension in decimal degrees. A Mark has a well known name (like square, circle, star, ect.), and a fill and a stroke. An External Graphic uses an xlink to refer to the location of an resource on the web to use to represent the point.

(Need to wrap this up, so my explanations are getting shorter).

A text symbolizer is made up of a Geometry, a Label, a Font, a LabelPlacement, a Halo, and a Fill.

A raster symbolizer consists of a Geometry, opacity, channel selection, overlap behavior, color map, contrast enhancement, shaded relief and image outline.

(please excuse the lack of formatting and far from complete information, I will come back to it)

7.5. Further Reading

If you have gotten this far, why not go further? Check out the GeoServer docs page for more information on SLDs, and read up on the SLD specification to see all the tags you can use. It is a good read.

Also, head back to our main SLD page, especially Dave's advanced style tutorial.