GeoServer開發(fā)手冊系列.doc

目 錄寫在前面3一 介紹4二 工具4Java4Maven4Subversion4三 源代碼4源代碼5提交5庫結(jié)構(gòu)5分支結(jié)構(gòu)6快速入門6取出源代碼7由Maven構(gòu)建7由Maven生成Eclipse工程文件9導(dǎo)入模塊進(jìn)Eclipse9在Eclipse中運行GeoServer12訪問GeoServer首頁13Maven指南13安裝Maven13運行Maven13構(gòu)建13跳過測試14離線構(gòu)建14構(gòu)建擴(kuò)展14Profiles15Eclipse15構(gòu)建Web模塊15使用Jetty運行web模塊16Eclipse指南16導(dǎo)入模塊17運行和調(diào)試17設(shè)置數(shù)據(jù)目錄17更改Jetty默認(rèn)端口18配置Jetty的JNDI資源19Eclipse首選項20代碼格式化21代碼模板22文本編輯器22編譯器23OWS服務(wù)24OWS服務(wù)概覽24實現(xiàn)一個簡單的OWS服務(wù)24建立25創(chuàng)建插件27試一試30REST服務(wù)34簡介34RESTful服務(wù)實現(xiàn)35基于Maps的Restful服務(wù)實現(xiàn)43基于反射的Restful服務(wù)實現(xiàn)49GeoServer中的Wicket開發(fā)55Web用戶接口61簡介61實現(xiàn)一個Wicket UI擴(kuò)展63寫在前面. 3一 介紹. 4二 工具. 4Java. 4Maven. 4Subversion. 4三 源代碼. 4源代碼. 4提交. 5庫結(jié)構(gòu). 5分支結(jié)構(gòu). 5四 快速入門. 6取出源代碼. 6由Maven構(gòu)建. 6由Maven生成Eclipse工程文件. 7導(dǎo)入模塊進(jìn)Eclipse. 7在Eclipse中運行GeoServer. 10訪問GeoServer首頁. 11五 Maven指南. 11六 Eclipse指南. 11七 編程指南. 12八 釋放指南. 12九 釋放測試檢查列表. 12十 CITE測試指南. 12十一 政策與步驟寫在前面我一直對OSGeo的軟件和應(yīng)用很感興趣，希望致力于這些軟件在中國的普及與應(yīng)用，GeoServer開發(fā)手冊是這些工作的一部分。在近幾年開源Web Map/GIS實踐應(yīng)用中，GeoServer的熱度一直穩(wěn)中有升。下圖是Google趨勢就GeoServer、MapServer的分析圖表。圖 1 GeoServer、MapServer趨勢分析尤其有意思的是，在GeoServer的使用國家分布來看，以德國居多，其次就是中國（見圖2）?？梢?，在中國或者說中文環(huán)境下，使用開源地理信息服務(wù)器GeoServer比較多。我個人也比較喜歡GeoServer，因為我覺得它的配置、使用比起MapServer方便，至少不需要去編輯某些文件。圖 2 GeoServer搜索量前5名國家（見Google趨勢）此次翻譯以2.0.2版本為原型，對于翻譯中出現(xiàn)不正確的地方，希望大家不吝賜教，與我交流。一 介紹空。二 工具在GeoServer開發(fā)者環(huán)境搭建以前，需要安裝以下工具：JavaGeoServer開發(fā)需要JDK1.5及其以上版本，可從Sun Microsystems獲取。注：除了可以使用Sun提供的JDK以外，也可以使用其它的，但這里我們推薦使用Sun的。MavenGeoserver使用Maven工具構(gòu)建。當(dāng)前推薦版本是2.1.0，可從Apache獲取。雖然2.1.0是推薦的，但2.0.8以上版本同樣可用。SubversionGeoserver源代碼由subversion庫完成存儲和版本管理。對于不同平臺有多種subversion客戶端可獲取。更多細(xì)節(jié)請訪問：/getting.html 。三 源代碼源代碼GeoServer源代碼存放在: /geoserver。使用以下方式取出開發(fā)版/trunk版本svn co /geoserver/trunk geoserver使用以下方式取出穩(wěn)定版/stable版本：svn co /geoserver/branches/1.7.x geoserver警告：Geoserver庫包含大量空間數(shù)據(jù)。從上取出這些數(shù)據(jù)對于低帶寬用戶來說相對就很慢或者很昂貴，這種情況下，用戶可以通過以下方式僅獲取源代碼：svn co /geoserver/trunk/src提交通過以下步驟提交到代碼庫：1. 安裝subversion配置文件，請看后面?zhèn)渥ⅰ?. 注冊獲取提交權(quán)限。3. 將庫切換到”https”協(xié)議，例如：root of checkout% svn switch /geoserver/trunk庫結(jié)構(gòu)/geoserver/ branches/ spike/ tags/ trunk/l branches包含以前所有穩(wěn)定的開發(fā)分支，1.6.x，1.7.x，etcl spike包含實驗版本和原型l tags包含以前所有釋放版本l trunk為當(dāng)前開發(fā)分支。分支結(jié)構(gòu)每個開發(fā)分支都有如下所示的結(jié)構(gòu)：/geoserver/ doc/ src/ data/l doc包含用戶和開發(fā)人員向?qū)У脑次募 src包含Geoserver本身的Java源碼l data包含多種GeoServer的數(shù)據(jù)目錄快速入門本章介紹快速搭建、運行GeoServer開發(fā)環(huán)境具體步驟。我們假定您已經(jīng)安裝好所有必須的工具（內(nèi)容見第二章）。注：本章的上的是為了盡快的讓開發(fā)者搭建和運行GeoServer。對于一些更加深入的介紹請見Maven指南和Eclipse指南。l 取出源代碼l 由Maven構(gòu)建l 由Maven生成Eclipse工程文件l 導(dǎo)入模塊進(jìn)Eclipsel 在Eclipse里運行GeoServerl 訪問GeoServer首頁取出源代碼由subversion庫中取出源代碼。選取trunk作為最新開發(fā)源碼，或者那些基本不可能經(jīng)常更新的版本的穩(wěn)定分支。要么是：svn co /geoserver/trunk geoserver-trunk或者（穩(wěn)定的1.7.x分支 ）svn co /geoserver/branches/1.7.x geoserver-1.7.x在這頁示例里面，我們假定你取出源碼到一個名為geoserver的目錄，不過，最好還是把名字取得更詳細(xì)一點為好。由Maven構(gòu)建修改目錄到源樹的根，執(zhí)行以下maven構(gòu)建命令：cd geoserver/srcmvn clean install成功構(gòu)建后會產(chǎn)生類似于以下的輸出：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導(dǎo)入模塊進(jìn)Eclipse1. 啟動運行Eclipse集成開發(fā)環(huán)境2. 打開Eclipse首選項Preferences3. 依次點擊進(jìn)入：Java，BuildPath，Classpath Variables，點擊New4. 創(chuàng)建類路徑變量名稱”M2_REPO”,并且設(shè)置它的值為本地Maven庫的位置，點擊OK。5. 單擊OK以應(yīng)用新的Eclipse首選項。6. 在包瀏覽Package Explorer右鍵并單擊導(dǎo)入Import7. 選擇 已有工程導(dǎo)入工作區(qū) Existing Projects into Workspace，單擊下一步：8. 進(jìn)入geoserver/src目錄9. 確保所有模塊都被選取，單擊完成Finish在Eclipse中運行GeoServer1. 在包瀏覽Package Explorer中選擇web-app模塊（1.7.x或更早版本是web）2. 點擊進(jìn)入org.geoserver.web包（1.7.x或更早版本是org.vfny.geoserver.jetty）3. 在Start類上右鍵，單擊Run as， Java Application訪問GeoServer首頁l 幾秒后，就可通過http:/localhost:8080/geoserver訪問到GeoServerl 默認(rèn)的用戶admin的密碼是geoserverMaven指南本章是使用Maven構(gòu)建GeoServer的參考。安裝Maven見工具（第二章）運行MavenMaven提供了從模塊編譯到生成測試覆蓋報告的多種命令。大部分maven命令可在源樹的根運行，或者某個特模塊。注：在準(zhǔn)備由源樹的根運行maven命令時，請記住要將取出的根目錄變換到src目錄。在由源樹的根運行一個命令時，或者從包含其它模塊的目錄時，命令將會為所有模塊運行。當(dāng)從單個模塊運行命令時，它只為這個模塊運行。構(gòu)建GeoServer最常用的命令是安裝命令：mvn clean install雖然clean命令不是必須的，但我們還是推薦用上。上面的命令做了以下的事：l 編譯源代碼l 運行單元測試l 安裝成果到本地Maven庫跳過測試通常在構(gòu)建時跳過單元測試很有用處。在構(gòu)建命令中添加-DskipTests標(biāo)志就可以只編譯單元測試而不會運行測試。mvn -DskipTests clean install離線構(gòu)建Maven操作會自動下載待構(gòu)建模塊中聲明的依賴庫。當(dāng)處理快照（SNAPSHOT）依賴時，這就有可能會有問題。Maven每次執(zhí)行一天內(nèi)的首次構(gòu)建時，會嘗試更新它的快照依賴。由于GeoServer依賴GeoTools庫的快照版本，這時可能會有問題。最終導(dǎo)致Maven下載大量GeoTools更新模塊并且急劇增加構(gòu)建時間。而如果你只是本地構(gòu)建geotools，這些就顯得不必要了。這時，可以使用“離線”方式運行Maven來改進(jìn)：mvn -o clean install在離線模式中，Maven不會下載任何外部依賴，也不會更新任何快照依賴。構(gòu)建擴(kuò)展默認(rèn)情況下，擴(kuò)展沒有被包含在構(gòu)建中。它們得通過Profile來明確增加到構(gòu)建中。比如下面的示例就將restconfig擴(kuò)展添加到構(gòu)建中：mvn clean install -P restconfig可以同時添加多個擴(kuò)展同時使用：mvn clean install -P restconfig,oracle有個特殊的名為allExtensions的Profile可以添加所有擴(kuò)展：mvn clean install -P allExtensionsProfilesEclipseMaven的Eclipse插件用于為模塊生成eclipse工程：mvn eclipse:eclipse經(jīng)過此操作后，這些模塊就可以導(dǎo)入Eclipse工作區(qū)。 該插件有個很有用的功能就是可下載第三方依賴的相關(guān)源代碼。這是通過添加downloadSources標(biāo)志來做的：mvn -DdownloadSources eclipse:eclipse警告：當(dāng)你首次啟用downloadSources標(biāo)志時，構(gòu)建過程需要很長時間，因為它要下載GeoServer所依賴的每個庫的源代碼。構(gòu)建Web模塊當(dāng)安裝好web模塊后，它會通過內(nèi)建的特殊配置構(gòu)建。默認(rèn)情況下它注是minimal配置。盡管如此，它也可以通過設(shè)置configId和configDirectory標(biāo)志來定制任意配置。比如：mvn clean install -DconfigId=release -DconfigDirectory=/home/jdeolive/geoserver_1.7.x/data上面命令可使用GeoServer上的release配置構(gòu)建web模塊。configId是包含的配置目錄名稱，configDirectory是包含的配置目錄的父級目錄。configDirectory可以像剛才的一樣的絕對路徑，也可以是針對web模塊自身的相對路徑：mvn clean install -DconfigId=release -DconfigDirectory=./././data上面的命令與之前有同樣的效果，盡管是引用了相對于web模塊的路徑。該路徑，./././data，在GeoServer取出(check out)的代碼目錄結(jié)構(gòu)是標(biāo)準(zhǔn)結(jié)構(gòu)的情況下可用。使用Jetty運行web模塊Maven的jetty插件可用于運行嵌入了jetty容器的基于web的模塊：cd geoserver_1.7.x/src/webmvn jetty:run注：該命令必須從web模塊運行，如果從其它模塊運行就會失敗。上面的命令將會使用自帶的數(shù)據(jù)目錄來運行GeoServer。為了使用其它的數(shù)據(jù)目錄可以啟用GEOSERVER_DATA_DIR標(biāo)志：mvn -DGEOSERVER_DATA_DIR=/path/to/datadir jetty:run Eclipse指南本章是使用Eclipse開發(fā)GeoServer的參考。l 導(dǎo)入模塊l 運行和調(diào)試l 設(shè)置數(shù)據(jù)目錄l 更改Jetty默認(rèn)端口l 配置Jetty中JNDI資源l Eclipse首選項l 代碼格式化l 代碼模塊l 文本編輯器l 編譯器導(dǎo)入模塊參見Maven指南中的Eclipse部分。運行和調(diào)試運行和調(diào)試web-app模塊中org.geoserver.web.Start類。具體步驟見快速入門。設(shè)置數(shù)據(jù)目錄如果未設(shè)置，GeoServer默認(rèn)會使用web-app模塊里的minimal目錄作為它的數(shù)據(jù)目錄。若要修改，執(zhí)行以下步驟：1.在Eclipse菜單中打開調(diào)試配置（Debug Configurations）2.先把Start配置，選擇Argument面板，并且填寫-DGEOSERVER_DATA_DIR參數(shù)，設(shè)置數(shù)據(jù)目錄為絕對路徑。更改Jetty默認(rèn)端口如果未設(shè)置，Jetty默認(rèn)會使用8080端口。修改請按以下方式：1. 打開上節(jié)所說的Start配置中的Argument面板。2. 填寫-Djetty.port參數(shù)，設(shè)置它到期望的端口配置Jetty的JNDI資源JNDI資源如數(shù)據(jù)資源可以通過提供系統(tǒng)屬性中名為jetty.config.file的Jetty服務(wù)器配置文件來配置，這個可以在Start配置中的Argument面板上通過VM argument參數(shù)指定。配置文件路徑是相對于web-app模塊根路徑的，該模塊是啟動配置運行的地方。例如：-Djetty.config.file=./././././settings/jetty.xml以下的Jetty服務(wù)器配置文件就配置了一個JNDI數(shù)據(jù)源：jdbc/demo，它是一個Oracle數(shù)據(jù)庫的連接池。 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模塊和數(shù)據(jù)目錄沒有特定于Jetty的相關(guān)信息，因此JNDI資源可以被測試在Jetty下，以便于后面在Tomcat下的開發(fā)。也可以看看GeoServer用戶手冊中Tomcat中建立JNDI連接池章節(jié)。Eclipse首選項代碼格式化1. 下載文件：/geotools/trunk/build/eclipse/formatter.xml2. 轉(zhuǎn)到首選項中Java，Code Style，F(xiàn)ormatter，點擊Import3. 選擇步驟1中下載的formatter.xml文件。4. 點擊Apply代碼模板1. 下載文件：/geotools/trunk/build/eclipse/codetemplates.xml2. 轉(zhuǎn)到首選項Java，Code Style, Formatter,點擊Important3. 選擇步驟1中下載的formatter.xml文件。4. 點擊Apply文本編輯器1. 轉(zhuǎn)到General，Editors，Text Editors2. 選中Insert Space for tabs3. 選中Show print margin，將Print margin column設(shè)置為1004. 選中Show line numbers5. 選中Show whitespace characters（可選）注：顯示空白字符可幫助我們發(fā)現(xiàn)無意中提交不必要的空格。6. 點擊Apply編譯器1. 轉(zhuǎn)到Java, Compiler, Building2. 擴(kuò)展開Output folder，并將.svn/加到Filtered resources列表中。3. 點擊ApplyOWS服務(wù)本節(jié)介紹GeoServer中OWS服務(wù)（原文為RESTful服務(wù)，可能為筆誤）如何工作。OWS服務(wù)概覽TBA實現(xiàn)一個簡單的OWS服務(wù)本節(jié)將通過以下場景來介紹如何給GeoServer創(chuàng)建一個簡單的GeoServer OWS服務(wù)。該服務(wù)需要提供一個能廣告叫做“sayHello”的單一操作的功能（capabilities）文檔。該sayHello操作的結(jié)果是一個簡單的字符串：“Hello World”。內(nèi)容：實現(xiàn)一個簡單的OWS服務(wù)l 建立l 創(chuàng)建插件l 試一試建立創(chuàng)建插件的第一步是為它建立一個maven工程。該工程我們稱為“hello”。1. 在本地文件系統(tǒng)中任意地方創(chuàng)建一個名為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目錄下創(chuàng)建Java源文件目錄。hello/ + pom.xml + src/ + main/ + java/創(chuàng)建插件插件是一系列由spring beans實現(xiàn)的擴(kuò)展。實例中擴(kuò)展興趣點是一個HelloWorld的POJO。1. 創(chuàng)建一個名為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() ); 該服務(wù)相對比較簡單。它提供了一個一個名為sayHello的方法，帶有HttpServletRequest，HttpServletResponse參數(shù)。該函數(shù)的參數(shù)列表會由org.geoserver.ows.Dispatcher自動發(fā)現(xiàn)。2. 創(chuàng)建applicationContext.xml文件將上面的類申明為一個bean。 sayHello 到此，hello工程內(nèi)容應(yīng)該是看上去像下面這樣了：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我們服務(wù)內(nèi)定義的方法服務(wù)serviceapplicationContext.xml文件中Service描述符的名稱版本versionapplicationContext.xml文件中Service描述符的版本可選方法1.與web模塊一起構(gòu)建另外一個可選方法是在新的插件工程上從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源中運行作為嘗試插件開發(fā)的一種可選方法：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服務(wù)本節(jié)是GeoServer中運行RESTful服務(wù)的的預(yù)覽。簡介GeoServer使用著名的Restlet庫提供系統(tǒng)所有REST相關(guān)功能。Restlet是由Java編寫的輕量級rest框架，它能很好的集成基于已有的servlet的應(yīng)用程序Rest派發(fā)GeoServer里面，所有路徑/rest下面的請求都被認(rèn)為是一個restful請求。這每一個請求都交由一個rest派發(fā)器來處理。派發(fā)器的工作職責(zé)是請每個請求導(dǎo)向到相關(guān)的處理終端上。該終端就是restlet。Restlet由spring環(huán)境加載，因此它們是可插拔的。RestletsRestlet是處理派發(fā)器轉(zhuǎn)發(fā)來的調(diào)用，與org.restlet.Restlet類相對應(yīng)。我們可以擴(kuò)展該類以實現(xiàn)一個服務(wù)端點（服務(wù)點）。同樣，我們也可以為了某個特殊目的擴(kuò)展出一個子類。下節(jié)描述的就是一個名為finder的子類。Finders和資源Restful服務(wù)通常是實現(xiàn)了某一個資源。Finder對象是一個特殊的restlet，它的職責(zé)是為特定的請求找到正確的資源。該資源就作為一個最終的終點，并處理請求。相關(guān)的類是org.restlet.Finder和org.restlet.resource.Resource。表達(dá)RepresentationsRepreentation，通常是指特殊狀態(tài)的狀態(tài)或者資源編碼的格式。例如，當(dāng)某個特殊資源請求進(jìn)來時，該資源的表達(dá)就返回給了客戶端。RESTful服務(wù)實現(xiàn)本節(jié)描述GeoServer如何實現(xiàn)一個restful服務(wù)，