Escolar Documentos
Profissional Documentos
Cultura Documentos
Release 2.0.2
GeoServer
CONTENTS
1 2
Introduction Tools 2.1 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Maven . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 Subversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Source Code 3.1 Committing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Repository structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Branch structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quickstart 4.1 Check out source code . . . . . . . . . . 4.2 Build with Maven . . . . . . . . . . . . 4.3 Generate Eclipse project les with Maven 4.4 Import modules into Eclipse . . . . . . . 4.5 Run GeoServer from Eclipse . . . . . . . 4.6 Access GeoServer front page . . . . . . Maven Guide 5.1 Installing Maven . . . . . . . . . . 5.2 Running Maven . . . . . . . . . . 5.3 Building . . . . . . . . . . . . . . 5.4 Skipping tests . . . . . . . . . . . . 5.5 Building ofine . . . . . . . . . . . 5.6 Building extensions . . . . . . . . 5.7 Proles . . . . . . . . . . . . . . . 5.8 Eclipse . . . . . . . . . . . . . . . 5.9 Building the web module . . . . . . 5.10 Running the web module with Jetty
3 5 5 5 5 7 7 7 8 9 9 9 10 10 14 15 17 17 17 17 17 18 18 18 18 19 19 21 21 21 24 29 29 34 i
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
Eclipse Guide 6.1 Importing modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Running and debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 Eclipse preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programming Guide 7.1 OWS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Web User Interface . . . . . . . . . Wicket Development In GeoServer Extension Points . . . . . . . . . . WPS design guide . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
43 48 52 52 55 55 55 55 56 56 57 57 57 58 58 60 61 61 61 64 64 64 66 69 70 73 73 73 73 73 75 78 79 79 80 80 82 83 84 84 84 85 87 87 88 89 90 92
Release Guide 8.1 Notify developer lists . . . . . . . . . . 8.2 Prerequisites . . . . . . . . . . . . . . 8.3 Update source code . . . . . . . . . . . 8.4 Update the README . . . . . . . . . 8.5 Create a release tag . . . . . . . . . . . 8.6 Update version numbers in tag . . . . . 8.7 Upgrade branch pom versions . . . . . 8.8 Set tag pom versions . . . . . . . . . . 8.9 Build release artifacts . . . . . . . . . 8.10 Build documentation . . . . . . . . . . 8.11 CITE testing . . . . . . . . . . . . . . 8.12 Hand testing . . . . . . . . . . . . . . 8.13 Deploy Artifacts . . . . . . . . . . . . 8.14 Build Windows installer . . . . . . . . 8.15 Build Mac OS X installer . . . . . . . 8.16 Release on JIRA . . . . . . . . . . . . 8.17 Upload release artifacts to SourceForge 8.18 Release on SourceForge . . . . . . . . 8.19 Create a download page . . . . . . . . 8.20 Announce the release . . . . . . . . . . Release Testing Checklist 9.1 Artifact size . . . . 9.2 Demos . . . . . . . 9.3 Sample requests . . 9.4 Map preview . . . . 9.5 KML . . . . . . . . 9.6 GeoWebCache . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
10 Cite Test Guide 10.1 Check out CITE tools 10.2 Build the CITE tools . 10.3 Run the test engine . . 10.4 Run WFS 1.0 tests . . 10.5 Run WFS 1.1 tests . . 10.6 Run WMS 1.1 tests . . 10.7 Run WCS 1.1 tests . . 10.8 Run WCS 1.0 tests . . 10.9 Command line . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
11 Policies and Procedures 11.1 Comitting . . . . . . . . . . . . . . 11.2 Code Review . . . . . . . . . . . . 11.3 Community Process . . . . . . . . 11.4 GeoServer Improvement Proposals 11.5 Community Modules . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
ii
Welcome to the GeoServer Developer Manual. The manual is for those who want to help with the development process, including source code, software releasing, and other administrative work.
CONTENTS
CONTENTS
CHAPTER
ONE
INTRODUCTION
Chapter 1. Introduction
CHAPTER
TWO
TOOLS
The following tools need to installed on the system before a GeoServer developer environment can be set up.
2.1 Java
Developing with GeoServer requires a Java Development Kit (JDK) 1.5 or greater, available from Sun Microsystems. Note: While it is possible to use a JDK other than the one provided by Sun, it is recommended that the Sun JDK be used.
2.2 Maven
GeoServer uses a tool known as Maven to build. The current recommended version of Maven is 2.1.0 and is available from Apache. While 2.1.0 is recommended any version greather than 2.0.8 should also work.
2.3 Subversion
GeoServer source code is stored and versioned in a subversion repository. There are a variety of subversion clients available for a number of different platforms. Visit http://subversion.tigris.org/getting.html for more details.
Chapter 2. Tools
CHAPTER
THREE
SOURCE CODE
The GeoServer source code is located at http://svn.codehaus.org/geoserver. To check out the development / trunk version:
svn co http://svn.codehaus.org/geoserver/trunk geoserver
Warning: The GeoServer repository contains a signicant amount of spatial data. Checking it out over a slow or low bandwidth connection can be costly. In such cases it may be desirable to check out only the sources:
svn co http://svn.codehaus.org/geoserver/trunk/src
3.1 Committing
In order to commit to the repository the following steps must be taken: 1. Install this subversion cong le. See additional notes below. 2. Register for commit access as described here. 3. Switch the repository to the https protocol. Example:
[root of checkout]% svn switch https://svn.codehaus.org/geoserver/trunk
branches contains all previously stable development branches, 1.6.x, 1.7.x, etc...
spike contains experimental projects and mock ups tags contains all previously released versions trunk is the current development branch
doc contains the sources for the user and developer guides src contains the java sources for GeoServer itself data contains a variety of GeoServer data directories
CHAPTER
FOUR
QUICKSTART
A step by step guide describing how to quickly get up and running with a GeoServer development environment. This guide assumes that all the necessary Tools are installed. Note: This guide is designed to get developers up and running as quick as possible. For a more comprehensive guide see the Maven Guide and the Eclipse Guide. Check out source code Build with Maven Generate Eclipse project les with Maven Import modules into Eclipse Run GeoServer from Eclipse Access GeoServer front page
In this example we will pretend that you checked the source out into a directory called geoserver, but a more descriptive name is recommended.
[INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO] [INFO]
-----------------------------------------------------------------------Reactor Summary: -----------------------------------------------------------------------GeoServer ............................................. SUCCESS [10.271s] GeoServer Maven Plugins ............................... SUCCESS [0.865s] Configuration Deployment PlugIn ....................... SUCCESS [3.820s] GeoServer Maven Archetypes ............................ SUCCESS [0.054s] GeoServer WFS Output Format Archetype ................. SUCCESS [0.390s] Core Platform Module .................................. SUCCESS [5.270s] Data Module ........................................... SUCCESS [4.521s] Open Web Service Module ............................... SUCCESS [2.730s] Main Module ........................................... SUCCESS [10.077s] Web Coverage Service Module ........................... SUCCESS [3.785s] Web Coverage Service 1.1.1 Module ..................... SUCCESS [5.254s] Validation Module ..................................... SUCCESS [1.131s] Web Feature Service Module ............................ SUCCESS [6.695s] Web Feature Service Module ............................ SUCCESS [1.197s] Web Map Service Module ................................ SUCCESS [8.519s] Geoserver REST Support Code ........................... SUCCESS [3.366s] GeoWebCache (GWC) Module .............................. SUCCESS [0.255s] Web Application Module ................................ SUCCESS [27.386s] Community Space ....................................... SUCCESS [0.312s] GeoServer Extensions .................................. SUCCESS [0.071s] ----------------------------------------------------------------------------------------------------------------------------------------------BUILD SUCCESSFUL ------------------------------------------------------------------------
10
Chapter 4. Quickstart
4. Create a classpath variable named M2_REPO and set the value to the location of the local Maven repository, and click Ok
5. Click Ok to apply the new Eclipse preferences 6. Right-click in the Package Explorer and click Import...
11
12
Chapter 4. Quickstart
8. Navigate to the geoserver/src directory 9. Ensure all modules are selected and click Finish
13
14
Chapter 4. Quickstart
15
16
Chapter 4. Quickstart
CHAPTER
FIVE
MAVEN GUIDE
A reference for building GeoServer with Maven.
5.3 Building
The most commonly maven command used with GeoServer is the install command:
mvn clean install
While the clean command is not necessary, it is recommented. Running this command does the following: compiles source code runs unit tests installs artifacts into the local maven repository
17
In ofine mode Maven will not attempt to download any external dependencies, and will not attempt to update any SNAPSHOT dependencies.
After which the modules can be imported into an eclipse workspace. A useful feature of the plugin is the ability to download associated source code for third party dependencies. This is done with the downloadSources ag:
18
Warning: The rst time you enable the downloadSources ag the build will take a long time as it will attempt to download the sources for every single library GeoServer depends on.
The above command builds the web module against the release conguration that is shipped with GeoServer. The configId is the name of the conguration directory to include, and the configDirectory is the parent directory of the conguration directory to include. The configDirectory can either be specied as an absolute path like in the above example, or it can be specied relative to the web module itself:
mvn clean install -DconfigId=release -DconfigDirectory=../../../data
The above command does the same as the rst, however references the congDirectory relative to the web module. This path, ../../../data, can be used if the GeoServer checkout has the standard layout.
Note: This command must be run from the web module, it will fail if run from elsewhere. The above command will run GeoServer with the built in data directory. To specify a different data directory the GEOSERVER_DATA_DIR ag is used:
mvn -DGEOSERVER_DATA_DIR=/path/to/datadir jetty:run
19
20
CHAPTER
SIX
ECLIPSE GUIDE
A reference for developing GeoServer with Eclipse. Importing modules Running and debugging Setting the data directory Changing the default port for Jetty Conguring JNDI resources in Jetty Eclipse preferences Code formatting Code templates Text editors Compiler
21
2. Select the Start conguration, select the Arguments panel and specify the -DGEOSERVER_DATA_DIR parameter, setting it to the absolute path of the data directory
22
The following Jetty server conguration le congures a JNDI data source jdbc/demo that is a connection pool for an Oracle database:
<?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/conf <Configure class="org.mortbay.jetty.Server"> <New class="org.mortbay.jetty.plus.naming.Resource"> <Arg>jdbc/demo</Arg> <Arg> <New class="org.apache.commons.dbcp.BasicDataSource"> <Set name="driverClassName">oracle.jdbc.driver.OracleDriver</Set> <Set name="url">jdbc:oracle:thin:@oracle.example.com:1521:demodb</Set> <Set name="username">claudius</Set> <Set name="password">s3cr3t</Set> <Set name="maxActive">20</Set> <Set name="maxIdle">10</Set> <Set name="minIdle">0</Set> <Set name="maxWait">10000</Set> <Set name="minEvictableIdleTimeMillis">300000</Set> <Set name="timeBetweenEvictionRunsMillis">300000</Set> <Set name="numTestsPerEvictionRun">20</Set>
23
<Set name="poolPreparedStatements">true</Set> <Set name="maxOpenPreparedStatements">100</Set> <Set name="testOnBorrow">true</Set> <Set name="validationQuery">SELECT SYSDATE FROM DUAL</Set> </New> </Arg> </New> </Configure>
Jetty does not mandate a reference-ref in GeoServer WEB-INF/web.xml, so there is no need to modify that le. No Jetty-specic information is required inside the GeoServer web-app module or data directory, so JNDI resources can be tested under Jetty for later deployment under Tomcat. See also the tutorial Setting up a JNDI connection pool with Tomcat in the GeoServer User Manual.
24
25
6. Click Apply
26
6.3.4 Compiler
1. Navigate to Java, Compiler, Building 2. Expand Output folder and add .svn/ to the list of Filtered resources
3. Click Apply
27
28
CHAPTER
SEVEN
PROGRAMMING GUIDE
7.1 OWS Services
This section provides an overview of how RESTful services work in GeoServer.
Setup The rst step in creating our plug-in is setting up a maven project for it. The project will be called hello. 1. Create a new directory called hello anywhere on your le system. 2. Add a maven pom called pom.xml to the hello directory:
29
<!-- set parent pom to community pom --> <parent> <groupId>org.geoserver</groupId> <artifactId>community</artifactId> <version>2.0.1</version> </parent> <groupId>org.geoserver</groupId> <artifactId>hello</artifactId> <packaging>jar</packaging> <version>1.0</version> <name>Hello World Service Module</name> <!-- declare depenency on geoserver main --> <dependencies> <dependency> <groupId>org.geoserver</groupId> <artifactId>main</artifactId> <version>2.0.1</version> </dependency> </dependencies> <repositories> <repository> <id>opengeo</id> <name>opengeo</name> <url>http://repo.opengeo.org</url> </repository> </repositories> </project>
Creating the Plug-in A plug-in is a collection of extensions realized as spring beans. In this example the extension point of interest is a HelloWorld POJO (Plain Old Java Object). 1. Create a class called HelloWorld:
import import import import java.io.IOException; javax.servlet.ServletException; javax.servlet.http.HttpServletRequest; javax.servlet.http.HttpServletResponse;
30
} public void sayHello(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.getOutputStream().write( "Hello World".getBytes() ); } }
The service is relatively simple. It provides a method sayHello(..) which takes a HttpServletRequest, and a HttpServletResponse. The parameter list for this function is automatically discovered by the org.geoserver.ows.Dispatcher. 1. Create an applicationContext.xml declaring the above class as a bean.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd <beans> <!-- Spring will reference the instance of the HelloWorld class by the id name "helloService" --> <bean id="helloService" class="HelloWorld"> </bean> <!-- This creates a Service descriptor, which allows the org.geoserver.ows.Dispatcher to locate it. --> <bean id="helloService-1.0.0" class="org.geoserver.platform.Service"> <!-- used to reference the service in the URL --> <constructor-arg index="0" value="hello"/> <!-- our actual service POJO defined previously --> <constructor-arg index="1" ref="helloService"/> <!-- a version number for this service --> <constructor-arg index="2" value="1.0.0"/> <!-- a list of functions for this service --> <constructor-arg index="3"> <list> <value>sayHello</value> </list> </constructor-arg> </bean> </beans>
At this point the hello project should look like the following:
hello/ + pom.xml + src/ + main/ + java/ + HelloWorld.java + applicationContext.xml
[INFO] Scanning for projects... [INFO] ---------------------------------------------------------------------------[INFO] Building Hello World Service Module [INFO] task-segment: [install] [INFO] ---------------------------------------------------------------------------[INFO] [resources:resources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:compile] [INFO] Compiling 1 source file to /home/ak/geoserver/community/hello/target/classes [INFO] [resources:testResources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:testCompile] [INFO] No sources to compile [INFO] [surefire:test] [INFO] No tests to run. [INFO] [jar:jar] [INFO] Building jar: /home/ak/geoserver/community/hello/target/hello-1.0.jar [INFO] [jar:test-jar {execution: default}] [WARNING] JAR will be empty - no content was marked for inclusion! [INFO] Building jar: /home/ak/geoserver/community/hello/target/hello-1.0-tests.jar [INFO] [install:install] [INFO] Installing /home/ak/geoserver/community/hello/target/hello-1.0.jar to /home/ak/.m2/repository/ [INFO] Installing /home/ak/geoserver/community/hello/target/hello-1.0-tests.jar to /home/ak/.m2/repos [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESSFUL [INFO] -----------------------------------------------------------------------[INFO] Total time: 6 seconds [INFO] Finished at: Fri Sep 21 14:52:31 EDT 2007 [INFO] Final Memory: 27M/178M [INFO] -----------------------------------------------------------------------
1. Copy target/hello-1.0.jar into the WEB-INF/lib directory of your GeoServer install 2. Restart GeoServer 3. Visit http://<host>/geoserver/ows?request=sayHello&service=hello&version=1.0.0 request the method we dened in our service service the name we passed to the Service descriptor in the applicationContext.xml version the version we passed to the Service descriptor in the applicationContext.xml
32
1. Visit http://localhost:8080/geoserver/ows?request=sayHello&service=hello&version=1.0.0
7.2.1 Overview
GeoServer uses a library known as Restlet for all REST related functionality. Restlet is a lightweight rest framework written in Java that integrates nicely with existing servlet based applications. REST dispatching In GeoServer, all requests under the path /rest are considered a call to a restful service. Every call of this nature is handled by a rest dispatcher. The job of the dispatcher is to route the request to the appropriate end point. This end point is known as a restlet.
Restlets are loaded from the spring context, and therefore are pluggable. Restlets A restlet is the generic entity which handles calls routed by the dispatcher, and corresponds to the class org.restlet.Restlet. One can extend this class directly to implement a service endpoint. Alternatively one can extend a subclass for a specialized purpose. Namely a nder, which is described in the next section. Finders and resources Restful services are often implemented around the concept of resources. A nder is a special kind of restlet whose job is to nd the correct resource for a particular request. The resource then serves as the nal end point and handles the request. The appropriate classes from the restlet library are org.restlet.Finder and org.restlet.resource.Resource. 34 Chapter 7. Programming Guide
Representations A representation, commonly referred to as a format, is the state of a particular state or encoding of a resource. For instance, when a request for a particular resource comes in, a representation of that resource is returned to the client.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xs <modelVersion>4.0.0</modelVersion> <groupId>org.geoserver</groupId> <artifactId>hello_rest</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>hello_rest</name> <dependencies> <dependency> <groupId>org.geoserver</groupId> <artifactId>rest</artifactId> <version>2.0-SNAPSHOT</version> </dependency> <dependency> <groupId>org.geoserver</groupId> <artifactId>main</artifactId> <version>2.0-SNAPSHOT</version> <classifier>tests</classifier> <scope>test</scope> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>3.8.1</version> <scope>test</scope> </dependency> <dependency> <groupId>com.mockrunner</groupId> <artifactId>mockrunner</artifactId> <version>0.3.1</version>
35
<scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.5</source> <target>1.5</target> </configuration> </plugin> </plugins> </build> </project>
1. Create the directory src/main/java under the root of the new module:
[hello_rest]% mkdir -p src/main/java
Create the resource class 1. The class org.geoserver.rest.AbstractResource is a convenient base class available when creating new resources. Create a new class called HelloResource in the package org.geoserver.hellorest, which extends from AbstractResource.
package org.geoserver.hellorest; import import import import import java.util.List; org.geoserver.rest.AbstractResource; org.geoserver.rest.format.DataFormat; org.restlet.data.Request; org.restlet.data.Response;
public class HelloResource extends AbstractResource { @Override protected List<DataFormat> createSupportedFormats(Request request, Response response) { return null; } }
2. The rst method to implement is createSupportedFormats(). The purpose of this method is to create mapping from an extension, to a particular format. For now the goal will be to return the text Hello World when a .txt extension is requested by the client.
import java.util.ArrayList; import org.geoserver.rest.format.StringFormat; ... @Override protected List<DataFormat> createSupportedFormats(Request request, Response response) {
36
List<DataFormat> formats = new ArrayList(); formats.add(new StringFormat( MediaType.TEXT_PLAIN )); return formats; }
3. The next step is to override the handleGet() method. This method is called when a GET request is made for the resource.
@Override public void handleGet() { //get the appropriate format DataFormat format = getFormatGet(); //transform the string "Hello World" to the appropriate response getResponse().setEntity(format.toRepresentation("Hello World")); }
The above makes use of the getFormatGet() method, whose purpose is to determine the extension being requested by the client, and look up the appropriate format for it. In this case when the client requests the .txt extension, the StringFormat setup in the previous step will be found. Create the application context 1. The next step is to create an application context that tells GeoServer about the resource created in the previous section. Create the directory src/main/resources under the root of the hello_rest module:
[hello_rest]% mkdir src/main/resources
2. Add the following applicationContext.xml le to the src/main/resources directory under the root of the hello_rest module.
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-bea <beans> <bean id="hello" class="org.geoserver.hellorest.HelloResource"/> <bean id="helloMapping" class="org.geoserver.rest.RESTMapping"> <property name="routes"> <map> <entry> <key><value>/hello.{format}</value></key> <value>hello</value> </entry> </map> </property> </bean> </beans>
There are two things to note above. The rst is the hello bean which is an instance of the HelloResource class created in the previous section. The second is the helloMapping bean, which denes a template for the uri in which the resource will be accessed. The above mapping species that the resource will be located at /rest/hello.{format} where format is the representation being requested by the client. As implemented hello.txt is the only supported representation.
37
Test 1. Create the directory /src/test/java under the root of the hello_rest module:
[hello_rest]% mkdir -p src/test/java
2. Create a new test class called HelloResourceTest in the package org.geoserver.hellorest, which extends from org.geoserver.test.GeoServerTestSupport:
package org.geoserver.hellorest; import org.geoserver.test.GeoServerTestSupport; public class HelloResourceTest extends GeoServerTestSupport { public void test() throws Exception { } }
3. Add a statement which makes a GET request for /rest/hello.txt and asserts it is equal to the string Hello World:
public void test() throws Exception { assertEquals( "Hello World", getAsString("/rest/hello.txt")); }
38
public class HelloMapResource extends MapResource { @Override public Map getMap() throws Exception { return null; } }
2. The rst method to implement is getMap(). The purpose of this method is to create a map based data structure which represents the resource. For now a simple map will be created with a single key message, containing the Hello World string:
@Override public Map getMap() throws Exception { HashMap map = new HashMap(); map.put( "message", "Hello World"); return map; }
Update the application context 1. The next step is to update an application context and tell GeoServer about the new resource created in the previous section. Update the applicationContext.xml le so that it looks like the following:
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-bea <beans> <bean id="hello" class="org.geoserver.hellorest.HelloResource"/> <bean id="helloMap" class="org.geoserver.hellorest.HelloMapResource"/> <bean id="helloMapping" class="org.geoserver.rest.RESTMapping"> <property name="routes"> <map> <entry> <key><value>/hello.{format}</value></key> <!--value>hello</value--> <value>helloMap</value> </entry> </map> </property> </bean> </beans>
There are two things to note above. The rst is the addition of the helloMap bean. The second is a change to the helloMapping bean, which now maps to the helloMap bean, rather than the hello bean. Test 1. Create a new test class called HelloMapResourceTest in the package org.geoserver.hellorest, which extends from org.geoserver.test.GeoServerTestSupport:
39
2. Add a test named testGetAsXML() which makes a GET request for /rest/hello.xml:
... import org.w3c.dom.Document; import org.w3c.dom.Node; ... public void testGetAsXML() throws Exception { //make the request, parsing the result as a dom Document dom = getAsDOM( "/rest/hello.xml" ); //print out the result print(dom); //make assertions Node message = getFirstElementByTagName( dom, "message"); assertNotNull(message); assertEquals( "Hello World", message.getFirstChild().getNodeValue() ); }
3. Add a second test named testGetAsJSON() which makes a GET request for /rest/hello.json:
... import net.sf.json.JSON; import net.sf.json.JSONObject; ... public void testGetAsJSON() throws Exception { //make the request, parsing the result into a json object JSON json = getAsJSON( "/rest/hello.json"); //print out the result print(json); //make assertions assertTrue( json instanceof JSONObject ); assertEquals( "Hello World", ((JSONObject)json).get( "message" ) ); }
40
Create a new resource class 1. Create a new class called HelloReflectiveResource in the package org.geoserver.hellorest, which extends from ReflectiveResource:
package org.geoserver.hellorest; import org.geoserver.rest.ReflectiveResource; public class HelloReflectiveResource extends ReflectiveResource { @Override protected Object handleObjectGet() throws Exception { return null; } }
2. The rst method to implement is handleObjectGet(). The purpose of this method is to return the underlying object representing the resource. In this case, an instance of the Hello class created in the previous step.
41
@Override protected Object handleObjectGet() throws Exception { return new Hello( "Hello World" ); }
Update the application context 1. The next step is to update an application context and tell GeoServer about the new resource created in the previous section. Update the applicationContext.xml le so that it looks like the following:
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-bea <beans> <bean id="hello" class="org.geoserver.hellorest.HelloResource"/> <bean id="helloMap" class="org.geoserver.hellorest.HelloMapResource"/> <bean id="helloReflective" class="org.geoserver.hellorest.HelloReflectiveResource"/> <bean id="helloMapping" class="org.geoserver.rest.RESTMapping"> <property name="routes"> <map> <entry> <key><value>/hello.{format}</value></key> <!--value>hello</value--> <!--value>helloMap</value--> <value>helloReflective</value> </entry> </map> </property> </bean> </beans>
There are two things to note above. The rst is the addition of the helloReflective bean. The second is a change to the helloMapping bean, which now maps to the helloReflective bean. Test 1. Create a new test class called HelloReflectiveResourceTest in the package org.geoserver.hellorest, which extends from org.geoserver.test.GeoServerTestSupport:
package org.geoserver.hellorest; import org.geoserver.test.GeoServerTestSupport; public class HelloReflectiveResourceTest extends GeoServerTestSupport { }
2. Add a test named testGetAsXML() which makes a GET request for /rest/hello.xml:
... import org.w3c.dom.Document;
42
import org.w3c.dom.Node; ... public void testGetAsXML() throws Exception { //make the request, parsing the result as a dom Document dom = getAsDOM( "/rest/hello.xml" ); //print out the result print(dom); //make assertions Node message = getFirstElementByTagName( dom, "message"); assertNotNull(message); assertEquals( "Hello World", message.getFirstChild().getNodeValue() ); }
3. Add a second test named testGetAsJSON() which makes a GET request for /rest/hello.json:
... import net.sf.json.JSON; import net.sf.json.JSONObject; ... public void testGetAsJSON() throws Exception { //make the request, parsing the result into a json object JSON json = getAsJSON( "/rest/hello.json"); //print out the result print(json); //make assertions assertTrue( json instanceof JSONObject ); JSONObject hello = ((JSONObject) json).getJSONObject( "org.geoserver.hellorest.Hello" ); assertEquals( "Hello World", hello.get( "message" ) ); }
43
Plug-ins Because of its component based nature Wicket components can be loaded from the classpath. Which means that web applications can be built in a modular fashion, rather than in a monolithic fashion. GeoServer takes this concept one step further to provide a pluggable user interface, in which Wicket components can be plugged in via Spring and the regular GeoServer plug-in mechanism. Each component that is plugged in is described by a component descriptor. A component descriptor is an instance of the org.geoserver.web.ComponentInfo class:
public abstract class ComponentInfo<C extends Component> implements Serializable { /** * the id of the component */ String id; /** * the title of the component */ String title; /** * The description of the component */ String description; /** * the class of the component */ Class<C> componentClass; }
A ComponentInfo instance contains meta information about the component being plugged in such as its title and description, as well as the class which implements the component. Each subclass of ComponentInfo represents a specic extension point. For instance the class org.geoserver.web.MenuPageInfo represents the extension point for main pages, ie pages that are linked to from the main menu of the application.
44
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xs <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.geoserver</groupId> <artifactId>web2</artifactId> <version>2.0-SNAPSHOT</version> </parent> <groupId>org.geoserver</groupId> <artifactId>hello_web</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>hello_web</name> <dependencies> <dependency> <groupId>org.geoserver.web</groupId> <artifactId>web-core</artifactId> <version>2.0-SNAPSHOT</version> </dependency> </dependencies> <build> <plugins> <plugin> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.5</source> <target>1.5</target> </configuration> </plugin> </plugins> </build> </project>
3. Create the directory src/main/java under the root of the new module:
[hello_web]% mkdir -p src/main/java
Create the page class 1. The class org.geoserver.web.GeoServerBasePage is the base class for all pages in GeoServer. Create a new class called HelloPage in the package org.geoserver.helloweb, which extends from GeoServerBasePage:
package org.geoserver.helloweb; import org.geoserver.web.GeoServerBasePage; public class HelloPage extends GeoServerBasePage {
45
2. The rst task is to implement the constructor. In Wicket a page or component builds itself in its constructor. This page is basic and will simply create a label which has the value Hello World!:
import org.apache.wicket.markup.html.basic.Label; ... public HelloPage() { add( new Label( "hellolabel", "Hello World!") ); }
In the above code, an instance of Label is created. The rst argument to its constructor is the component id. In Wicket every component must have an id. In the next section this id will be used to bind the component to its HTML presentation. The second argument to the Label constructor is the value of the world, in this case the string Hello World! Create the page presentation 1. With the page completed, the next step is to create the HTML presentation for the page. To do this create a le named HelloPage.html in the same directory as the HelloPagejava class:
<html> <body> <wicket:extend> <div wicket:id="hellolabel"></div> </wicket:extend> </body> </html>
There are few things to note about the HTML. The rst is the use of the <wicket:extend> element. This tells wicket that HelloPage is an extension of another page, in this case GeoServerBasePage, and it should inherit presentation from that page. The second thing to note is the attribute wicket:id on the <div> element. This is what binds the <div> tag to the Label component created in the previous section. The value of wicket:id must match the id given to the component, in this case hellolabel. Create the i18n le With Wicket (and any web application framework), any string that appears in the web application should be interationalized. In GeoServer, this is performed by creating an internationalization (i18n) le named GeoServerApplication.properties. 1. Create the (i18n) le GeoServerApplication.properties in the src/main/java directory:
HelloPage.page.title=Hello HelloPage.page.description=A page to say hello
The above i18n le declares two keys, one for the title of the page and one for the description of the page.
46
Create the application context 1. The nal step is to create an application context which tells GeoServer about the page created in the previous section. Create the directory src/main/resources under the root of the hello_web module:
[hello_web]% mkdir src/main/resources
2. Add the following applicationContext.xml le to the src/main/resources directory, under the root of the hello_rest module:
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-bea <beans> <bean id="helloPage" class="org.geoserver.web.MenuPageInfo"> <property name="id" value="helloPage"/> <property name="titleKey" value="HelloPage.page.title"/> <property name="descriptionKey" value="HelloPage.page.description"/> <property name="componentClass" value="org.geoserver.helloweb.HelloPage"/> </bean> </beans>
The above bean declaration declares an instance of the MenuPageInfo class which is a descriptor for pages linked from the main page of the GeoServer web application. The property titleKey is the title of the page and it receives the value of the title i18n key created in the previous section. Similar for the the descriptionKey property. Test the extension At this point, the hello_web module should look like the following:
hello_web/ pom.xml src/main/java applicationContext.xml GeoServerApplication.properties org/geoserver/helloweb/ HelloPage.java HelloPage.html
2. Copy the hello_web-1.0-SNAPSHOT.jar le from the hello_web/target directory into the WEB-inf/lib directory of a GeoServer installation:
3. Start or restart GeoServer 4. Navigate to http://localhost:8080/geoserver/web Upon success a link titled Hello should appear in the menu on the left side of the main GeoServer page. Following the link brings up the HelloPage
47
48
package org.geoserver.web.example; import org.geoserver.web.GeoServerBasePage; public class MyPage extends GeoServerBasePage{ // We will fill in the rest later, for now the page can just be blank }
for
internationalized
strings,
at
org.geoserver.web.example.MyPage.page.title=My Example Page org.geoserver.web.example.MyPage.page.description=An example page for developers trying to extend the
If you create a jar with these three les and add it to the GeoServer classpath, you should see the new link in the left-hand menu.
49
Purpose A wicket:id attribute tells Wicket the name to be used for an element when attaching Wicket Components Requires no contents, but species that classes extending this page can insert content at this position. <wicket:extend></wicket:extend> Species that the enclosed content will be inserted into a parent page at the point indicated by <wicket:child/> <wicket:panel></wicket:panel>imilar to wicket:extend, but used in creating custom components S rather than extending pages. <wicket:head></wicket:head> Indicates a section (like a CSS or JavaScript include) that should be added to the header of pages that include this markup (can be used for pages or panels). <wicket:link></wicket:link> Encloses sections in which Wicket will rewrite links to pages, CSS les, and other resources that it manages. (This lets you refer to resources using paths relative to the Java source and not the rendered HTML.) <wicket:message Tells Wicket to look up a string in the internationalization database and key="i18nKey"> Default replace the provided text if one is found. Text </wicket:message> Wicket provides quite a few components, of which several can be seen in the Wicket Component Reference. In general, Wicket components require a Model object which handles the getting, setting, and conversion to/from String of the value associated with a component. For the purposes of this example, we will focus on one of the simplest, the Label, which simply replaces the contents of the element it is bound to with a value provided at runtime. Continuing the example from above, we can pass a String to the Labels constructor and it is transparently converted to a Model:
package org.geoserver.web.example; import org.geoserver.web.GeoServerBasePage; import org.apache.wicket.markup.html.basic.Label; public class MyPage extends GeoServerBasePage{ public MyPage(){ add(new Label("label", "Hello World")); } }
<html> <head></head> <body> <wicket:extend> Greetings, GeoServer User! My message for you is <span wicket:id="label"> thanks for using GeoSer </wicket:extend> </body> </html>
Of course, there are much more complicated (and useful) things we can do with Wicket, but this example demonstrates the most common usage; just adding some behavior to an HTML element.
50
a Wicket Link component and customize the onClick behavior to call the appropriate constructor. (You can use setResponsePage in other methods that handle user input as well, such as on form submits. Check the Wicket documentation for more information.) An example:
//... import org.apache.wicket.markup.html.link.Link; //... add(new Link("link"){ public void onClick(){ setResponsePage(new MyPage()); } });
51
<ul> <li> <label for="foo"><wicket:message key="foo"> Foo </wicket:message> <input wicket:id="foo" type="text"></input> </li> </ul>
Avoid requiring special knowledge from the user. For example, where a list of values is required, provide a widget that allows manipulating the list one element at a time rather than expecting a commaseparated list of values. Custom Components We recommend creating a reusable Wicket component for any complex values that might need to be edited by users, such as a bounding box or a list of free strings. By extracting this into a component, it is much simpler to provide consistent, rich editing for users.
a set of XML parsers to parse the HTTP POST requests, found int the org.geoserver.wps.xml and org.geoserver.wps.xml.v1_0_0 a service object interface and implementations responding to the various WPS methods, in particular org.geoserver.wps.DefaultWebProcessingService, which in turn delegates most of the work to the GetCapabilities, DescribeProcess and ExecuteProcess classes a set of output transformers taking the results generated by DefaultWebProcessingService and turning them into the appropriate response (usually, XML). You can nd some of those in the org.geoserver.wps.response package, whilst some others are generic ones that have been parametrized and declared in the Spring context (see the applicationContext.xml le). The module uses extensively the following GeoTools modules:
52
net.opengis.wps which contains EMF models of the various elements and types described in the WPS schemas. Those objects are usually what ows between the KVP parsers, XML decoders, the service implementation, and the output transformers gt-xsd-wps and gt-xsd, used for all XML encoding and decoding needs gt-process that provides the concept of a process, with the ability to self describe its inputs and outputs, and of course execute and produce results
The WPS module shows an example of the above by bridging the Sextante API to the GeoTools process one, see the org.geoserver.wps.sextante package. This also means its possible to rely on libraries of existing processes provided they are wrapped into a GeoTools process API container.
53
to bigger data amounts) - there is no set of demo requests nor a GUI to build a request. That is considered fundamental to reduce the time spent trying to gure out how to build a proper request so it will be tackled sooner rather than later.
54
CHAPTER
EIGHT
RELEASE GUIDE
This guide details the process of performing a GeoServer release.
8.2 Prerequisites
The following are necessary to perform a GeoServer release: 1. Commit access to GeoServer svn 2. Edit access to the GeoServer wiki 3. Administration rights to the GeoServer bug tracker (JIRA) 4. Write access to GeoServer Maven Repository For steps 2 through 4 above you may also ask someone on the developer list to perform the associated steps. If a parallel GeoTools release is being preformed, see the GeoTools Release Guide. Alternatively you can (nicely) ask one of the GeoTools developers to perform the release for you.
55
Example:
GeoServer 1.7.1 (December 08, 2008) ----------------------------------The second release of the 1.7.1 series includes some great KML and Google Earth improvements, along with other new features and bug fixes. The new and note worthy for this release includes: * * * * * * KML Super Overlay and Regionating Support KML Extrude Support KML Reflector Improvements Mac OS X Installer New SQL Server DataStore Extension Improved Oracle DataStore Extension
And much more. The entire changelog can be found at : http://jira.codehaus.org/browse/GEOS/fixforversion/14502 This release is based on GeoTools 2.5.2.
Note: The xforversion number for the JIRA changelog can be found by exploring the GeoServer JIRA before or after building the changelog. See the links to the various unreleased versions. 2. Commit changes to the README:
svn commit -m "Updating README for [VERSION]" release/README.txt
56
svn co https://svn.codehaus.org/geoserver/tags/[VERSION]
Warning: svn switch may also be used to switch to the release tag but caution must be taken to switch back to the branch after the release has been performed.
2. Commit changes:
svn commit -m "Updated version numbers for [VERSION]" release web/src/main/java
Example:
find . -name pom.xml -exec sed -i s/1.7.1-SNAPSHOT/1.7.2-SNAPSHOT/g {} \;
2. Commit changes:
svn commit -m "Upgrading pom version to [NEWVERSION]-SNAPSHOT" .
57
Example:
find . -name pom.xml -exec sed -i s/1.7.1-SNAPSHOT/1.7.1/g {} \;
2. Commit changes:
svn commit -m "Setting pom versions to [VERSION]" .
2. Build javadocs:
mvn javadoc:javadoc
3. Build artifacts:
mvn assembly:attached
At this point the release artifacts will be located in target/release. Note: Due to an issue with the version of the maven assembly plugin currently used, the source artifact contains target directories containing compiled classes and jars for each module, which increases its size signicantly. The source artifact should be unpacked, the directories removed, and re-archived:
unzip geoserver-1.7.1-src.zip rm geoserver-1.7.1-src.zip cd geoserver-1.7.1 find . -name target -exec rm -rf {} \; cd .. zip -r geoserver-1.7.1-src.zip geoserver-1.7.1
58
8.10.1 HTML
1. Change to the root of the documentation directory, or check it out (if you dont already have it) from https://svn.codehaus.org/geoserver/tags/[VERSION]/doc 2. Change directory to doc/user. 3. Build HTML les for the User Manual. Option 1: Run the make command:
make html
Note: You may need to create the build/html directory. 4. Change directory to build/html and archive its contents:
cd build/html zip -r geoserver-[VERSION]-htmldoc.zip *
5. Go back to the root of the documentation tree, and change directory to doc/developer. 6. Build HTML les for the Developer Manual. Option 1: Run the make command:
make html
Note: You may need to create the build/html directory. 7. Change directory to build/html 8. Move the zip created for the user manual (in step 4) into this directory. 9. Add the contents of the current directory to the existing zip:
zip -r geoserver-[VERSION]-htmldoc.zip *
Note: When done, the zip le should contain two folders, one called user containing the HTML output for the User Manual, and one called developer containing the HTML output for the Developer Manual.
8.10.2 PDF
Note: Building PDF les from Sphinx is a two step process. First, it is necessary to create LaTeX les from Sphinx. Next, convert the LaTeX le to PDF using pdatex. Note: Building PDF les, in addition to Sphinx, requires the pdatex utility. 1. Change to the root of the documentation directory. 2. Change directory to doc/user.
59
3. Build LaTeX les for the User Manual. Option 1: Run the make command:
make latex
Note: You may need to create the build/latex directory. 4. Change directory to build/latex. 5. Convert the .tex le to .pdf:
pdflatex GeoServerUserManual.tex GeoServerUserManual.pdf
6. Go back to the root of the documentation tree, and change directory to doc/developer. 7. Build LaTeX les for the Developer Manual. Option 1: Run the make command:
make latex
Note: You may need to create the build/latex directory. 8. Change directory to build/latex 9. Convert the .tex le to .pdf pdatex GeoServerDeveloperManual.tex GeoServerDeveloperManual.pdf 10. Move the PDF created for the User Manual into this directory. 11. Create a zip containing the two PDF les:
zip -r geoserver-[VERSION]-pdfdoc.zip *.pdf
2. Execute the GeoServer CITE tests as described in the Cite Test Guide. 3. Unzip the war package and deploy the war in a servlet container such as Tomcat:
unzip geoserver-*-war.zip cp geoserver.war /opt/tomcat5/webapps
60
4. Copy the les from src/release/installer/win to the root of the unpacked archive (the same directory level as the start.jar):
GeoServerEXE.nsi gs.ico header.bmp side_left.bmp splash.bmp wrapper.conf wrapper.dll wrapper.exe wrapper.jar wrapper-server-license.txt
5. Right-click on the installer script GeoServerEXE.nsi and select Compile Script. After successfully compiling the script, an installer named geoserver-[VERSION].exe will be located in the root of the unpacked archive.
61
62
63
3. Click the Manage link on the right hand side of the page. 4. Find the row for the version being released and click the Release link located on the right. 5. Move back any open issues to the next version, and click the Release button.
65
The simplest way for developers working under a Unix like system is to use scp:
scp *.zip username@frs.sourceforge.net:uploads
6. Enter the release version and click the Create This Release button.
7. Copy the contents of the README (from previous step) into the Release Notes text box. 8. Generate the change log from JIRA (text format) and copy the contents into the Change Log text box.
66
9. Click the Preserve my pre-formatted text check box. 10. Click the Submit/Refresh button.
11. Scroll down to the Add Files To This Release section and check off all the primary artifacts. Warning: Be sure not to include the extension/plugin artifacts in this step! 12. Click the Add Files and/or Refresh View button. 13. Scroll down to the Edit Files In This Release section. 14. For the .dmg artifact set the Processor to i386 and the File Type to .dmg. 8.18. Release on SourceForge 67
68
15. For the .exe artifacts set the Processor to i386 and the File Type to .exe. 16. For the src artifact set the Processor to Platform-Independent and the File Type to Source .zip. 17. For all other artifacts set the Processor to Platform-Independent and the File Type to .zip. Note: The processor and le type must be set one artifact at a time, clicking the the Update/Refresh button at each step.
5. Select Download and click the Next button. 6. Fill out the elds for the following variables:
VERSION DATE JIRA_VERSION SF_RELEASE_ID
Note: The SF_RELEASE_ID is the release number assigned by SourceForge for the release created in the previous step. 7. Click the Insert Variables button.
69
Along with many other improvements and bug fixes. The entire change log for the 1.7.1 series is available in the issue tracker: http://jira.codehaus.org/browse/GEOS/fixforversion/14502 A very special thanks to all those who contributed bug fixes, new features, bug reports, and testing to this release. -The GeoServer Team
8.20.2 SourceForge
1. Log in to SourceForge. 2. Edit the release, and scroll down to the bottom of the page. 3. Check the Im sure check box, and click the Send Notice button. 4. Repeat for the extension release.
70
1. Log into the GeoServer Blog. 2. Create a new post. The post should be more colorful than the average announcement. It is meant to market and show off any and all new features. Examples of previous posts: http://blog.geoserver.org/2008/12/09/geoserver-171-released/ http://blog.geoserver.org/2008/10/27/geoserver-170-released/ 3. Do not publish the post. Instead present it to the GeoServer outreach team for review, and they will publish it.
8.20.4 SlashGeo
Note: This step requires an account on http://slashgeo.org 1. Go to http://slashgeo.org, and log in, creating an account if necessary. 2. Click the Submit Story link on the left hand side of the page. Examples of previous stories: http://technology.slashgeo.org/technology/08/12/09/1745249.shtml http://industry.slashgeo.org/article.pl?sid=08/10/27/137216
8.20.5 FreeGIS
Send an email to bjoern dot broscheit at uni-osnabrueck dot de. Example:
Subject: GeoServer update for freegis GeoServer 1.7.1 has been released with some exciting new features. The big push for this release has been improved KML support. The new and noteworthy include: * * * * * * * * * KML Super Overlay and Regionating Support KML Extrude Support KML Reflector Improvements Mac OS X Installer Dutch Translation Improved Style for Web Admin Interface New SQL Server DataStore Extension Improved Oracle DataStore Extension Default Templates per Namespace
Along with many other improvements and bug fixes. The entire change log for the 1.7.1 series is available in the issue tracker: http://jira.codehaus.org/browse/GEOS/fixforversion/14502
71
8.20.6 FreshMeat
Note: This step requires an account on http://freshmeat.net/ 1. Go to http://freshmeat.net/ and log in. 2. Search for geoserver and click the resulting link. 3. Click the add release link at the top of the page. 4. Choose the Default branch 5. Enter the version and choose the appropriate Release focus. Note: The release focus is usually 4,5,6, or 7. Choose which ever is appropriate. 6. Enter a succinct description (less than 600 characters) of the Changes. 7. Update the links to the following elds: Zip OS X package Changelog 8. Click the Step 3 button. 9. Click the Finish button.
72
CHAPTER
NINE
9.2 Demos
To do the demo page, http://localhost:8080/geoserver/demo.do, and test all of the demos. This includes: WFS-T demo GeoRSS demo with Google Maps, Virtual Earth, and Yahoo Maps WMS Overlay demo WMS Example
73
3. Go back to the map preview and click the GeoRSS link next to topp:states
4. Go back to the map preview and click the OpenLayers link next to topp:states. 5. Enable the options toolbar and specify the CQL lter:
STATE_ABBR EQ TX
74
9.5 KML
1. Go back to the map preview and click the KML link next to topp:states 2. Open the result in Google Earth 3. Zoom out as far as possible and notice the smaller states (on the east coast) disappear.
4. Close Google Earth Warning: If you do not shut down Google Earth it will cache information and throw off the next steps. 5. Go to the feature type editor page for the topp:states feature type
9.5. KML
75
6. Change the KML Regionating Attribute to SAMP_POP and change the KML Regionating Strategy to external-sorting:
.. image:: states_kml_config.png
7. Submit and Apply changes 8. Go back to the map preview page and again click the KML link next to topp:states, opening the result in Google Earth 9. Zoom out as far as possible and notice the smaller population states (green) disappear
10. Go back to the map preview page and click the KML link next to nurc:Img_Sample, opening the result in Google Earth
76
11. Zoom in and notice tiles load 12. Follow the link http://localhost:8080/geoserver/wms/kml?layers=topp:states&mode=refresh , opening the result in Google Earth 13. Notice the KML reload every time the camera is stopped 14. Edit the description template for the states layer as follows:
This is the state of ${STATE_NAME.value}.
15. Refresh the KML by moving the camera and click on a placemark
16. Append the parameter kmscore=0 to the above link and open the result in Google Earth 17. Notice the rasterized version of the KML
18. Follow the link http://localhost:8080/geoserver/wms/kml?layers=topp:states&mode=download , saving the result to disk. 19. Examine the le on disk and notice a raw dump of all placemarks for the layer.
9.5. KML
77
9.6 GeoWebCache
1. Go the geowebcache demo page, http://localhost:8080/geoserver/gwc/demo 2. Click the EPSG:4326" link for topp:states 3. Zoom in and notice the tiles load. 4. Repeat steps 2 to 3 for EPSG:900913
78
CHAPTER
TEN
Note: This step is necessary if the engine is to be run as a web application in Jetty. 4. From the cite directory check out the sources for legacy cite testing component:
mkdir cite1 svn co https://svn.opengeospatial.org:8443/ogc-projects/cite/components/cite1/trunk cite1
5. From the cite directory check out the test sources for each test suite that is to be run:
79
mkdir tests svn co -r 2740 https://svn.opengeospatial.org:8443/ogc-projects/cite/scripts/wfs/1.0.0/trunk te svn co -r 2740 https://svn.opengeospatial.org:8443/ogc-projects/cite/scripts/wfs/1.1.0/trun svn co -r 2740 https://svn.opengeospatial.org:8443/ogc-projects/cite/scripts/wms/1.1.1/trunk tes svn co -r 2740 https://svn.opengeospatial.org:8443/ogc-projects/cite/scripts/wcs/1.0.0/trunk svn co -r 2740 https://svn.opengeospatial.org:8443/ogc-projects/cite/scripts/wcs/1.1.1/trunk
Warning: To check out the test sources an account on the OGG portal is required. If you do not have one ask on the developer list for someone to check out the tests for you.
[INFO] [compiler:testCompile] [INFO] No sources to compile [INFO] [surefire:test] [INFO] No tests to run. [INFO] [jar:jar] [WARNING] JAR will be empty - no content was marked for inclusion! [INFO] Building jar: /Users/jdeolive/Devel/geoserver/trunk/trunk/src/community/cite/target/cite-1.0.j [INFO] [install:install] [INFO] Installing /Users/jdeolive/Devel/geoserver/trunk/trunk/src/community/cite/target/cite-1.0.jar [INFO] -----------------------------------------------------------------------[INFO] BUILD SUCCESSFUL [INFO] -----------------------------------------------------------------------[INFO] Total time: 27 seconds [INFO] Finished at: Mon Jul 20 10:43:13 EST 2009 [INFO] Final Memory: 20M/36M [INFO] ------------------------------------------------------------------------
80
[INFO] [jetty:run-exploded] [INFO] Configuring Jetty for project: Compliance + Interopability Testing + Evaluation (CITE) Mo [INFO] Context path = /teamengine [INFO] Tmp directory = determined at runtime [INFO] Web defaults = org/mortbay/jetty/webapp/webdefault.xml [INFO] Web overrides = none [INFO] Starting jetty 6.1.8 ... 2009-07-20 10:45:03.551::INFO: jetty-6.1.8 2009-07-20 10:45:03.707::INFO: No Transaction manager found - if your webapp requires one, plea 2009-07-20 10:45:09.893::INFO: Started SelectChannelConnector@0.0.0.0:9090 [INFO] Started Jetty Server
2. In a web browser navigate to http://localhost:9090/teamengine Note: By default the engine is congured to run on port 9090. This can be changed by editing the engine/pom.xml le. 3. Click the Start Testing link. geoserver. When prompted for a username and password use geoserver and
81
5. Choose the test suite to run from the drop down lists and provide a name for the session
6. Click the Start a new test session button Warning: The engine uses a pop-up window to display the status of the test suite. The pop-up will need to be unblocked by the browser and javascript must be enabled for it to work.
82
3. Change directory to the citewfs-1.0 data directory and execute the script cite_data.sql:
psql -U cite cite < cite_data.sql
5. Create a new wfs-1.0.0 session in teamengine and congure it with the following parameters: (a) Capabilities URL:
http://localhost:8080/geoserver/wfs?request=getcapabilities&service=wfs&version-1.0.0
If you are running an actual release install the H2 extension available from the download page. 1. Change directory to the citewfs-1.1-h2 data directory and Unpack the H2 database:
cd <root of geoserver sources/data/citewfs-1.1-h2 unzip cite.db.zip
2. Start GeoServer with the citewfs-1.1-h2 data directory. 3. Create a new wfs-1.1.0 session in teamengine and congure it with the following parameters: (a) Capabilities URL:
http://localhost:8080/geoserver/wfs?service=wfs&request=getcapabilities&version=1.1.0
(b) Supported Conformance Classes: Ensure WFS-Transaction is checked Ensure WFS-Xlink is unchecked (c) GML Simple Features: SF-0
83
(b) UpdateSequence Values: Ensure Automatic is selected 2 for value that is lexically higher 0 for value that is lexically lower (c) Certification Profile : QUERYABLE (d) Optional Tests: Ensure Recommendation Support is checked Ensure GML FeatureInfo is checked Ensure Fees and Access Constraints is checked For BoundingBox Constraints ensure Either is selected (e) Click OK
84
(b) MIME Header Setup: image/tiff (c) Update Sequence Values: 2 for value that is lexically higher 0 for value that is lexically lower (d) Grid Resolutions: 0.1 for RESX 0.1 for RESY (e) Options: Ensure Verify that the server supports XML encoding is checked Ensure Verify that the server supports range set axis is checked (f) Schemas: Ensure that original schemas is selected (g) Click OK
Where testsuite is <service>-<version> identier for the test suite. Example: wfs-1.1.0. Note: When running from the command line the engine uses a Swing pop-up dialog to congure a test session. If you are running Linux and get a blank window, try export AWT_TOOLKIT="MToolkit" before executing run.sh.
The above command will output all the tests run as part of the test suite. For each test the log will report if it passed or failed. For example, to list all the wfs-1.1.0 tests that failed:
sh log.sh wfs-1.1.0 | grep "wfs:wfs-1.1.0" | grep "Failed"
Note: The intermediate grep for wfs:wfs-1.1.0 will lter out all subtests that failed. The output of the above command will be something like: 10.9. Command line 85
Test wfs:wfs-1.1.0-LockFeature-tc1.1 (wfs-1.1.0/d39e32742_1/d39e728_1/d39e29904_1/d39e28567_1) Passed Test wfs:wfs-1.1.0-LockFeature-tc2.1 (wfs-1.1.0/d39e32742_1/d39e728_1/d39e29904_1/d39e28580_1) Passed Test wfs:wfs-1.1.0-LockFeature-tc3.1 (wfs-1.1.0/d39e32742_1/d39e728_1/d39e29904_1/d39e28585_1) Passed
The long string in parantheses beside the test name is the test id. To log information about a specic test append its test id as a parameter to the run.sh script. Example:
sh run.sh wfs-1.1.0 wfs-1.1.0/d39e32742_1/d39e728_1/d39e29904_1/d39e28567_1
86
CHAPTER
ELEVEN
87
3. Notify the developer list After a developer has signed up on Codehaus they must notify the developer list. A project despot will then approve the request to join the project. Core commit access The process of obtaining core commit access is far less mechanical than the one to obtain community commit access. It is based soley on trust. To obtain core commit access a developer must rst obtain the trust of the other core commiters. The way this is typically done is through continuous code review of patches. After a developer has submitted enough patches that have been met with a postitive response, and those patches require little modications, the developer will be granted core commit access. There is no magic number of patches that make the criteria, it is based mostly on the nature of the patches, how in depth the they are, etc... Basically it boils down the developer being able to show that they understand the code base well enough to not seriously break anything.
88
The above guidelines are not rules. In general code review is always welcome and if there is a question as to if a change should be reviewed or not, always heir on the side of getting it reviewed.
89
Maintaining the short term road map Being the most important part of the road map, the process for maintaining and updating the short term road map is well dened. Road map updates occur weekly and take place on the developer list as follows: 1. At the beginning of the week an email is sent to the developer list with the subject line #roadmap update <DATE>. This email is more or less an quick overview of the current state of the road map and contains: The next scheduled release date A list of the unresolved road map items 2. Developers (or any community members) may reply to the initial email and provide progress updates on road map items assigned to them. Developers may also propose changes and updates to the road map. Examples of such updates include proposing: new features to be added to the road map, see Adding features features which need to be moved back to a future release due to lack of resourcing features which need to be moved back to a future release due to other issues a change to the scheduled release date 3. Developers and community members discuss the proposed changes on the list. Those updates which are agreed upon are factored into the road map and it is updated. Adding features During the road map update developers propose new features and improvements to be added to the road map. The following are the prerequisites for proposing a new feature: 1. The feature has a sponsor. This means either a developer willing to carry out the work or a customer who is paying for it 2. The feature has has gone through the GSIP process if necessary. Whether a feature requires a GSIP is decided by the community when the feature is proposed After a feature has met the above prerequisites it is assigned to a release on the road map. The determining factor for what release a feature should be assigned to is based on the estimate of the time to implement the feature, and the current Release cycle for the branch the feature is being implemented on. If the time to implement the feature does not allow it to be assigned to the next release it is scheduled accordingly into a future release. Release cycle GeoServer follows a regular release cycle. Usually this cycle is a release every month. However once a development branch has become stable the release cycle drops off to every few months. Similarly on an unstable development branch the release cycle can be every few months, until the branch becomes stable enough for monthly releases.
90
91
92
4. Add a Maven POM Every module in the build requires a maven pom le, pom.xml. Use the following as a template:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSc <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.geoserver</groupId> <artifactId>geoserver</artifactId> <version>1.7.0-SNAPSHOT</version> <!-- change this to the proper GeoServer version --> </parent> <groupId>org.geoserver</groupId> <artifactId>myCommunityModule</artifactId> <version>1.0-SNAPSHOT</version> <packaging>jar</packaging> <name>My Community Module</name> <dependencies> <!-- add any dependencies your module has here -->
93
</dependencies> </project>
Add the le to the root of the new community module, myCommunityModule/pom.xml 5. Add a build prole The nal step involves adding the new module to the maven build, and in particular adding a build prole for it. To do this: (a) Edit community/pom.xml and add the following inside of the <profiles> element:
<profiles> ... <profile> <id>myComunityModule</id> <modules> <module>myCommunityModule</module> </modules> </profile> </profiles>
(b) Edit web/pom.xml and add the following inside of the <profiles> element:
<profiles> ... <profile> <id>myCommunityModule</id> <dependencies> <dependency> <groupId>org.geoserver</groupId> <artifactId>myCommuityModule</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies> </profile> </profiles> .. warning:: If the community module depends on any other community modules, they too should be included in the profile definition. .. warning:: Ensure that the name of the profile matches the name of the community module
94
Requirements The following properties must hold true in order to promote a community module: 1. The module has at least a handful of users In order to avoid cluttering the main code base, only those community modules which are of interest to at least 3 users (this may include the maintainer) are promoted. 2. The module has a designated and active maintainer Every core and extension module requires a module maintainer. The job of the maintainer is to x bugs and address issues which arise with the module. If a community module is promoted and the maintainer drops off, the module is in danger of being demoted back to community status. 3. The module is considered stable by the majority of the PSC A module will only be promoted if it is deemed stable by the majority of the PSC. Those PSC members deeming it unstable must provide a reasonable justication for the assertion. 4. The module maintains 40% test coverage A minimum of 40% test coverage must be maintained by the module in order to be promoted. Of course higher coverage is encouraged. The more test coverage a community module the more credibility it gets. 5. The module has no IP violations The module must not contain any code with a license or copyright that violates the GPL. 6. The module has a page in the user manual Each module needs a page in the user manual documenting its function and usage. Tutorials and walk-throughs are encouraged. 7. The maintainer has signed the GeoServer Contributor Agreement The Open Planning Project (TOPP) retains all copyright on code released as part of GeoServer. Since core and extension modules are released along with the rest of GeoServer, the maintainer of said modules must agree to assign copyright of code to TOPP. Process 1. Submit a GeoServer Improvement Proposal To promote a community module the contributor must create a GeoServer Improvement Proposals (GSIP). The proposal must then go through the regular feedback and voting process. 2. Move the module Once the proposal is accepted, the next step is to move the module out of the community space. Where the module ends up depends on wether it is being promoted to a core module, or an extension. Core modules Core modules live under the root of the source tree:
[geoserver]% svn move community/myCommunityModule . [geoserver]% svn commit -m "promoting my community module to a core module" myCommunityModule co
Extensions Extension modules live under the extension directory, under the root of the source tree:
95
[geoserver]% svn move community/myCommunityModule extension [geoserver]% svn commit -m "promoting my community module to an extension" extension community
3. Update the build Once the module has been moved, the maven build must be updated. Core modules (a) Edit community/pom.xml and remove the prole for the community module (b) Edit pom.xml under the root of the source tree and add a module enty:
<modules> ... <module>myCommunityModule</module> </modules>
(a) Edit web/pom.xml and move the dependency on the community module into the main dependencies section of the pom. Then remove the prole Extensions (a) Copy the prole for the community module from community/pom.xml to extension/pom.xml (b) Remove the prole from community/pom.xml 4. Update the release process The next step is to include the new module in the release process. Core modules (a) Edit release/src.xml and add an <include> for the module:
... <moduleSets> <moduleSet> ... <include>org.geoserver:myCommunityModule</include> </moduleSet> </moduleSets> ...
Extensions (a) Create a new directory under release/extensions which matches the name of the extension (b) Add the following to the new directory: i. A license called <module>-LICENSE.txt which contains the license for the extension ii. A readme called <module>-README.txt which contains instructions on how to install the extension Warning: Dont skip this step. iii. Any static les that are required by the extension (example would be a proprietary driver not available for download via maven) (c) Create a release descriptor called ext-<module>.xml under the release directory which follows the following structure (where %module% is the name of the module):
96
<assembly> <id>%module%</id> <formats> <format>zip</format> </formats> <includeBaseDirectory>false</includeBaseDirectory> <fileSets> <fileSet> <directory>release/extensions/%module%</directory> <outputDirectory></outputDirectory> <includes> <include>*</include> </includes> </fileSet> <fileSet> <directory>release/target/dependency</directory> <outputDirectory></outputDirectory> <includes> <include>%module%-*.jar</include> </includes> </fileSet> <fileSet> <directory>release/extensions</directory> <outputDirectory></outputDirectory> <includes> <include>LICENSE.txt</include> </includes> </fileSet> </fileSets> </assembly> * Add the * Add the additional include elements in the second fileSet for jar dependencies of the module additional include elements in the third fileSet for static file dependencies of the module
(e) Add an entry for the release descriptor to the root pom.xml of the source tree (ie. one step up from the release directory):
<!-- artifact assembly --> <plugin> <artifactId>maven-assembly-plugin</artifactId> <version>2.1</version> <configuration> <descriptors>
97
<descriptor>release/src.xml</descriptor> <descriptor>release/war.xml</descriptor> <descriptor>release/javadoc.xml</descriptor> <descriptor>release/bin.xml</descriptor> <descriptor>release/doc.xml</descriptor> ... <descriptor>release/ext-%module%.xml</descriptor> </descriptors> </configuration> </plugin>
(a) Update the documentation Add a page to the user manual for the new module. Todo Finish this by linking somwhere... (b) Download the contributor agreement The nal step in the process is to download and ll out the contributor agreement form. Follow the instructions on the form to submit it.
98
1. Call for a maintainer Before demoting the module rst try to nd a new maintainer for it. Send an email to both the developer and user list advertising the module is in danger of getting pushed back to community status. Wait a few days to see if anyone steps up to take on maintainership. 2. Move the module and update the build If no one steps up to take on the maintainer role, reverse the steps described here, taken to promote the module. In summary: (a) Move the module back to the community directory (b) Disable any of the modules release artifacts (c) Move the prole for the module from extension/pom.xml to community/pom.xml in the case of an extension module
99