GeoServer开发手册系列.doc

目 录写在前面3一 介绍4二 工具4Java4Maven4Subversion4三 源代码4源代码5提交5库结构5分支结构6快速入门6取出源代码7由Maven构建7由Maven生成Eclipse工程文件9导入模块进Eclipse9在Eclipse中运行GeoServer12访问GeoServer首页13Maven指南13安装Maven13运行Maven13构建13跳过测试14离线构建14构建扩展14Profiles15Eclipse15构建Web模块15使用Jetty运行web模块16Eclipse指南16导入模块17运行和调试17设置数据目录17更改Jetty默认端口18配置Jetty的JNDI资源19Eclipse首选项20代码格式化21代码模板22文本编辑器22编译器23OWS服务24OWS服务概览24实现一个简单的OWS服务24建立25创建插件27试一试30REST服务34简介34RESTful服务实现35基于Maps的Restful服务实现43基于反射的Restful服务实现49GeoServer中的Wicket开发55Web用户接口61简介61实现一个Wicket UI扩展63写在前面. 3一 介绍. 4二 工具. 4Java. 4Maven. 4Subversion. 4三 源代码. 4源代码. 4提交. 5库结构. 5分支结构. 5四 快速入门. 6取出源代码. 6由Maven构建. 6由Maven生成Eclipse工程文件. 7导入模块进Eclipse. 7在Eclipse中运行GeoServer. 10访问GeoServer首页. 11五 Maven指南. 11六 Eclipse指南. 11七 编程指南. 12八 释放指南. 12九 释放测试检查列表. 12十 CITE测试指南. 12十一 政策与步骤写在前面我一直对OSGeo的软件和应用很感兴趣，希望致力于这些软件在中国的普及与应用，GeoServer开发手册是这些工作的一部分。在近几年开源Web Map/GIS实践应用中，GeoServer的热度一直稳中有升。下图是Google趋势就GeoServer、MapServer的分析图表。图 1 GeoServer、MapServer趋势分析尤其有意思的是，在GeoServer的使用国家分布来看，以德国居多，其次就是中国（见图2）。可见，在中国或者说中文环境下，使用开源地理信息服务器GeoServer比较多。我个人也比较喜欢GeoServer，因为我觉得它的配置、使用比起MapServer方便，至少不需要去编辑某些文件。图 2 GeoServer搜索量前5名国家（见Google趋势）此次翻译以2.0.2版本为原型，对于翻译中出现不正确的地方，希望大家不吝赐教，与我交流。一 介绍空。二 工具在GeoServer开发者环境搭建以前，需要安装以下工具：JavaGeoServer开发需要JDK1.5及其以上版本，可从Sun Microsystems获取。注：除了可以使用Sun提供的JDK以外，也可以使用其它的，但这里我们推荐使用Sun的。MavenGeoserver使用Maven工具构建。当前推荐版本是2.1.0，可从Apache获取。虽然2.1.0是推荐的，但2.0.8以上版本同样可用。SubversionGeoserver源代码由subversion库完成存储和版本管理。对于不同平台有多种subversion客户端可获取。更多细节请访问：/getting.html 。三 源代码源代码GeoServer源代码存放在: /geoserver。使用以下方式取出开发版/trunk版本svn co /geoserver/trunk geoserver使用以下方式取出稳定版/stable版本：svn co /geoserver/branches/1.7.x geoserver警告：Geoserver库包含大量空间数据。从上取出这些数据对于低带宽用户来说相对就很慢或者很昂贵，这种情况下，用户可以通过以下方式仅获取源代码：svn co /geoserver/trunk/src提交通过以下步骤提交到代码库：1. 安装subversion配置文件，请看后面备注。2. 注册获取提交权限。3. 将库切换到”https”协议，例如：root of checkout% svn switch /geoserver/trunk库结构/geoserver/ branches/ spike/ tags/ trunk/l branches包含以前所有稳定的开发分支，1.6.x，1.7.x，etcl spike包含实验版本和原型l tags包含以前所有释放版本l trunk为当前开发分支。分支结构每个开发分支都有如下所示的结构：/geoserver/ doc/ src/ data/l doc包含用户和开发人员向导的源文件l src包含Geoserver本身的Java源码l data包含多种GeoServer的数据目录快速入门本章介绍快速搭建、运行GeoServer开发环境具体步骤。我们假定您已经安装好所有必须的工具（内容见第二章）。注：本章的上的是为了尽快的让开发者搭建和运行GeoServer。对于一些更加深入的介绍请见Maven指南和Eclipse指南。l 取出源代码l 由Maven构建l 由Maven生成Eclipse工程文件l 导入模块进Eclipsel 在Eclipse里运行GeoServerl 访问GeoServer首页取出源代码由subversion库中取出源代码。选取trunk作为最新开发源码，或者那些基本不可能经常更新的版本的稳定分支。要么是：svn co /geoserver/trunk geoserver-trunk或者（稳定的1.7.x分支 ）svn co /geoserver/branches/1.7.x geoserver-1.7.x在这页示例里面，我们假定你取出源码到一个名为geoserver的目录，不过，最好还是把名字取得更详细一点为好。由Maven构建修改目录到源树的根，执行以下maven构建命令：cd geoserver/srcmvn clean install成功构建后会产生类似于以下的输出：INFOINFOINFO -INFO Reactor Summary:INFO -INFO GeoServer . SUCCESS 10.271sINFO GeoServer Maven Plugins . SUCCESS 0.865sINFO Configuration Deployment PlugIn . SUCCESS 3.820sINFO GeoServer Maven Archetypes . SUCCESS 0.054sINFO GeoServer WFS Output Format Archetype . SUCCESS 0.390sINFO Core Platform Module . SUCCESS 5.270sINFO Data Module . SUCCESS 4.521sINFO Open Web Service Module . SUCCESS 2.730sINFO Main Module . SUCCESS 10.077sINFO Web Coverage Service Module . SUCCESS 3.785sINFO Web Coverage Service 1.1.1 Module . SUCCESS 5.254sINFO Validation Module . SUCCESS 1.131sINFO Web Feature Service Module . SUCCESS 6.695sINFO Web Feature Service Module . SUCCESS 1.197sINFO Web Map Service Module . SUCCESS 8.519sINFO Geoserver REST Support Code . SUCCESS 3.366sINFO GeoWebCache (GWC) Module . SUCCESS 0.255sINFO Web Application Module . SUCCESS 27.386sINFO Community Space . SUCCESS 0.312sINFO GeoServer Extensions . SUCCESS 0.071sINFO -INFO -INFO BUILD SUCCESSFULINFO -由Maven生成Eclipse工程文件生成Eclipse使用的.project文件和.classpath文件：mvn eclipse:eclipse导入模块进Eclipse1. 启动运行Eclipse集成开发环境2. 打开Eclipse首选项Preferences3. 依次点击进入：Java，BuildPath，Classpath Variables，点击New4. 创建类路径变量名称”M2_REPO”,并且设置它的值为本地Maven库的位置，点击OK。5. 单击OK以应用新的Eclipse首选项。6. 在包浏览Package Explorer右键并单击导入Import7. 选择 已有工程导入工作区 Existing Projects into Workspace，单击下一步：8. 进入geoserver/src目录9. 确保所有模块都被选取，单击完成Finish在Eclipse中运行GeoServer1. 在包浏览Package Explorer中选择web-app模块（1.7.x或更早版本是web）2. 点击进入org.geoserver.web包（1.7.x或更早版本是org.vfny.geoserver.jetty）3. 在Start类上右键，单击Run as， Java Application访问GeoServer首页l 几秒后，就可通过http:/localhost:8080/geoserver访问到GeoServerl 默认的用户admin的密码是geoserverMaven指南本章是使用Maven构建GeoServer的参考。安装Maven见工具（第二章）运行MavenMaven提供了从模块编译到生成测试覆盖报告的多种命令。大部分maven命令可在源树的根运行，或者某个特模块。注：在准备由源树的根运行maven命令时，请记住要将取出的根目录变换到src目录。在由源树的根运行一个命令时，或者从包含其它模块的目录时，命令将会为所有模块运行。当从单个模块运行命令时，它只为这个模块运行。构建GeoServer最常用的命令是安装命令：mvn clean install虽然clean命令不是必须的，但我们还是推荐用上。上面的命令做了以下的事：l 编译源代码l 运行单元测试l 安装成果到本地Maven库跳过测试通常在构建时跳过单元测试很有用处。在构建命令中添加-DskipTests标志就可以只编译单元测试而不会运行测试。mvn -DskipTests clean install离线构建Maven操作会自动下载待构建模块中声明的依赖库。当处理快照（SNAPSHOT）依赖时，这就有可能会有问题。Maven每次执行一天内的首次构建时，会尝试更新它的快照依赖。由于GeoServer依赖GeoTools库的快照版本，这时可能会有问题。最终导致Maven下载大量GeoTools更新模块并且急剧增加构建时间。而如果你只是本地构建geotools，这些就显得不必要了。这时，可以使用“离线”方式运行Maven来改进：mvn -o clean install在离线模式中，Maven不会下载任何外部依赖，也不会更新任何快照依赖。构建扩展默认情况下，扩展没有被包含在构建中。它们得通过Profile来明确增加到构建中。比如下面的示例就将restconfig扩展添加到构建中：mvn clean install -P restconfig可以同时添加多个扩展同时使用：mvn clean install -P restconfig,oracle有个特殊的名为allExtensions的Profile可以添加所有扩展：mvn clean install -P allExtensionsProfilesEclipseMaven的Eclipse插件用于为模块生成eclipse工程：mvn eclipse:eclipse经过此操作后，这些模块就可以导入Eclipse工作区。 该插件有个很有用的功能就是可下载第三方依赖的相关源代码。这是通过添加downloadSources标志来做的：mvn -DdownloadSources eclipse:eclipse警告：当你首次启用downloadSources标志时，构建过程需要很长时间，因为它要下载GeoServer所依赖的每个库的源代码。构建Web模块当安装好web模块后，它会通过内建的特殊配置构建。默认情况下它注是minimal配置。尽管如此，它也可以通过设置configId和configDirectory标志来定制任意配置。比如：mvn clean install -DconfigId=release -DconfigDirectory=/home/jdeolive/geoserver_1.7.x/data上面命令可使用GeoServer上的release配置构建web模块。configId是包含的配置目录名称，configDirectory是包含的配置目录的父级目录。configDirectory可以像刚才的一样的绝对路径，也可以是针对web模块自身的相对路径：mvn clean install -DconfigId=release -DconfigDirectory=./././data上面的命令与之前有同样的效果，尽管是引用了相对于web模块的路径。该路径，./././data，在GeoServer取出(check out)的代码目录结构是标准结构的情况下可用。使用Jetty运行web模块Maven的jetty插件可用于运行嵌入了jetty容器的基于web的模块：cd geoserver_1.7.x/src/webmvn jetty:run注：该命令必须从web模块运行，如果从其它模块运行就会失败。上面的命令将会使用自带的数据目录来运行GeoServer。为了使用其它的数据目录可以启用GEOSERVER_DATA_DIR标志：mvn -DGEOSERVER_DATA_DIR=/path/to/datadir jetty:run Eclipse指南本章是使用Eclipse开发GeoServer的参考。l 导入模块l 运行和调试l 设置数据目录l 更改Jetty默认端口l 配置Jetty中JNDI资源l Eclipse首选项l 代码格式化l 代码模块l 文本编辑器l 编译器导入模块参见Maven指南中的Eclipse部分。运行和调试运行和调试web-app模块中org.geoserver.web.Start类。具体步骤见快速入门。设置数据目录如果未设置，GeoServer默认会使用web-app模块里的minimal目录作为它的数据目录。若要修改，执行以下步骤：1.在Eclipse菜单中打开调试配置（Debug Configurations）2.先把Start配置，选择Argument面板，并且填写-DGEOSERVER_DATA_DIR参数，设置数据目录为绝对路径。更改Jetty默认端口如果未设置，Jetty默认会使用8080端口。修改请按以下方式：1. 打开上节所说的Start配置中的Argument面板。2. 填写-Djetty.port参数，设置它到期望的端口配置Jetty的JNDI资源JNDI资源如数据资源可以通过提供系统属性中名为jetty.config.file的Jetty服务器配置文件来配置，这个可以在Start配置中的Argument面板上通过VM argument参数指定。配置文件路径是相对于web-app模块根路径的，该模块是启动配置运行的地方。例如：-Djetty.config.file=./././././settings/jetty.xml以下的Jetty服务器配置文件就配置了一个JNDI数据源：jdbc/demo，它是一个Oracle数据库的连接池。 jdbc/demo oracle.jdbc.driver.OracleDriver jdbc:oracle:thin::1521:demodb claudius s3cr3t 20 10 0 10000 300000 300000 20 true 100 true SELECT SYSDATE FROM DUAL Jetty没有在GeoServer的WEB-INF/web.xml指定reference-ref，因此没必要修改该文件。GeoServer web-app模块和数据目录没有特定于Jetty的相关信息，因此JNDI资源可以被测试在Jetty下，以便于后面在Tomcat下的开发。也可以看看GeoServer用户手册中Tomcat中建立JNDI连接池章节。Eclipse首选项代码格式化1. 下载文件：/geotools/trunk/build/eclipse/formatter.xml2. 转到首选项中Java，Code Style，Formatter，点击Import3. 选择步骤1中下载的formatter.xml文件。4. 点击Apply代码模板1. 下载文件：/geotools/trunk/build/eclipse/codetemplates.xml2. 转到首选项Java，Code Style, Formatter,点击Important3. 选择步骤1中下载的formatter.xml文件。4. 点击Apply文本编辑器1. 转到General，Editors，Text Editors2. 选中Insert Space for tabs3. 选中Show print margin，将Print margin column设置为1004. 选中Show line numbers5. 选中Show whitespace characters（可选）注：显示空白字符可帮助我们发现无意中提交不必要的空格。6. 点击Apply编译器1. 转到Java, Compiler, Building2. 扩展开Output folder，并将.svn/加到Filtered resources列表中。3. 点击ApplyOWS服务本节介绍GeoServer中OWS服务（原文为RESTful服务，可能为笔误）如何工作。OWS服务概览TBA实现一个简单的OWS服务本节将通过以下场景来介绍如何给GeoServer创建一个简单的GeoServer OWS服务。该服务需要提供一个能广告叫做“sayHello”的单一操作的功能（capabilities）文档。该sayHello操作的结果是一个简单的字符串：“Hello World”。内容：实现一个简单的OWS服务l 建立l 创建插件l 试一试建立创建插件的第一步是为它建立一个maven工程。该工程我们称为“hello”。1. 在本地文件系统中任意地方创建一个名为hello的新目录。2. 给hello目录添加名为pom.xml文件。 4.0.0 org.geoserver community 2.0.1 org.geoserver hello jar 1.0 Hello World Service Module org.geoserver main 2.0.1 opengeo opengeo 3. 在hello目录下创建Java源文件目录。hello/ + pom.xml + src/ + main/ + java/创建插件插件是一系列由spring beans实现的扩展。实例中扩展兴趣点是一个HelloWorld的POJO。1. 创建一个名为HelloWorld的类：import java.io.IOException;import javax.servlet.ServletException;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;public class HelloWorld public HelloWorld() / Do nothing public void sayHello(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException response.getOutputStream().write( Hello World.getBytes() ); 该服务相对比较简单。它提供了一个一个名为sayHello的方法，带有HttpServletRequest，HttpServletResponse参数。该函数的参数列表会由org.geoserver.ows.Dispatcher自动发现。2. 创建applicationContext.xml文件将上面的类申明为一个bean。 sayHello 到此，hello工程内容应该是看上去像下面这样了：hello/ + pom.xml + src/ + main/ + java/ + HelloWorld.java + applicationContext.xml试一试1. 安装hello模块。hello% mvn installhello% mvn installINFO Scanning for projects.INFO -INFO Building Hello World Service ModuleINFO task-segment: installINFO -INFO resources:resourcesINFO Using default encoding to copy filtered resources.INFO compiler:compileINFO Compiling 1 source file to /home/ak/geoserver/community/hello/target/classesINFO resources:testResourcesINFO Using default encoding to copy filtered resources.INFO compiler:testCompileINFO No sources to compileINFO surefire:testINFO No tests to run.INFO jar:jarINFO Building jar: /home/ak/geoserver/community/hello/target/hello-1.0.jarINFO jar:test-jar execution: defaultWARNING JAR will be empty - no content was marked for inclusion!INFO Building jar: /home/ak/geoserver/community/hello/target/hello-1.0-tests.jarINFO install:installINFO Installing /home/ak/geoserver/community/hello/target/hello-1.0.jar to /home/ak/.m2/repository/org/geoserver/hello/1.0/hello-1.0.jarINFO Installing /home/ak/geoserver/community/hello/target/hello-1.0-tests.jar to /home/ak/.m2/repository/org/geoserver/hello/1.0/hello-1.0-tests.jarINFO -INFO BUILD SUCCESSFULINFO -INFO Total time: 6 secondsINFO Finished at: Fri Sep 21 14:52:31 EDT 2007INFO Final Memory: 27M/178MINFO -1.拷贝target/hello-1.0.jar文件到到你的GeoServer安装的WEB-INF/lib目录。2.重启GeoServer。3.访问：http:/geoserver/ows?request=sayHello&service=hello&version=1.0.0请求request我们服务内定义的方法服务serviceapplicationContext.xml文件中Service描述符的名称版本versionapplicationContext.xml文件中Service描述符的版本可选方法1.与web模块一起构建另外一个可选方法是在新的插件工程上从web模块申明一个依赖。1. 像上面一样安装hello模块。2. 编辑web/pom.xml，添加如下依赖： org.geoserver hello 1.03. 安装、运行web模块web mvn install jetty:run4. 访问：http:/localhost:8080/geoserver/ows?request=sayHello&service=hello&version=1.0.0可选方法2：由GeoServer源中运行作为尝试插件开发的一种可选方法：1. 安装hello模块。2. 更改路径到web模块3. 安装web模块。4. 拷贝/target/hello-1.0.jar文件到/target/geoserver/WEB-INF/lib目录 ：/dev/geoserver/web% cp /hello/target/hello-1.0.jar target/geoserver/WEB-INF/lib5. 使用Jetty运行打包的war。/dev/geoserver/web% mvn jetty6:run-exploded6. 访问：http:/localhost:8080/geoserver/ows?request=sayHello&service=hello&version=1.0.0REST服务本节是GeoServer中运行RESTful服务的的预览。简介GeoServer使用著名的Restlet库提供系统所有REST相关功能。Restlet是由Java编写的轻量级rest框架，它能很好的集成基于已有的servlet的应用程序Rest派发GeoServer里面，所有路径/rest下面的请求都被认为是一个restful请求。这每一个请求都交由一个rest派发器来处理。派发器的工作职责是请每个请求导向到相关的处理终端上。该终端就是restlet。Restlet由spring环境加载，因此它们是可插拔的。RestletsRestlet是处理派发器转发来的调用，与org.restlet.Restlet类相对应。我们可以扩展该类以实现一个服务端点（服务点）。同样，我们也可以为了某个特殊目的扩展出一个子类。下节描述的就是一个名为finder的子类。Finders和资源Restful服务通常是实现了某一个资源。Finder对象是一个特殊的restlet，它的职责是为特定的请求找到正确的资源。该资源就作为一个最终的终点，并处理请求。相关的类是org.restlet.Finder和org.restlet.resource.Resource。表达RepresentationsRepreentation，通常是指特殊状态的状态或者资源编码的格式。例如，当某个特殊资源请求进来时，该资源的表达就返回给了客户端。RESTful服务实现本节描述GeoServer如何实现一个restful服务，