This page last changed on Jan 29, 2013 by aaime.

Overview

A rest service to expose an easy to parse snapshot of all the loaded jars

Proposed By

Carlo Cancellieri

Assigned to Release

2.2.4 and 2.3.0

State

Choose one of: Under Discussion, In Progress, Completed, Rejected, Deferred

Motivation

For a better integration of GeoServer (and all of the installed plugin) into a continuous integration environment
GeoServer may provide a rest service to expose an easy to parse snapshot of all the loaded jars into the running instance.
This will be extremely useful for bug reports and to programmatically keep track of the extensions deployed into the application.

Proposal

To complete the integration of GeoServer (and all of the installed plugin) into a continuous integration environment we should provide a rest service to expose (at least):

.. release (version)
.. revision (svn tag or git hash)
.. build date (optional)

for GeoServer and all of the installed extensions (f.e.):

.. monitoring
.. control flow

plus other custom plugins.

My proposal is based on java Manifest + maven and its plugins and does not require core module changes. Essentially I will:

  • Add some settings to the parent pom.xml of the core, modules and extensions.
  • Provide a ManifestLoader singleton which will define the data model and the methods to filter over it.
  • Modify the REST config package '''adding''' required Resource and Finder classes

The pom settings

Each parent pom will also add a special key called '''GeoServerModule''' to be able to identify a GeoServer core,extension or community jar from a dependency.

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-jar-plugin</artifactId>
 <configuration>
 <archive>
 <configuration>
	<archive>
		<manifest>
			<addDefaultImplementationEntries>
                          true
                        </addDefaultImplementationEntries>
			<addDefaultSpecificationEntries>
                          true
                        </addDefaultSpecificationEntries>
		</manifest>
		<manifestEntries>
			<GeoServerModule>core</GeoServerModule>
			<Application-Name>
                          ${project.build.finalname}
                        </Application-Name>
			<Project-Version>${project.version}</Project-Version>
			<Iteration-Name>${iteration}</Iteration-Name>
			<Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
			<Git-Revision>${build.commit.id}</Git-Revision>
		</manifestEntries>
	</archive>
	</configuration>
 </archive>
 </configuration>
</plugin>

The REST path:

GET request on the path:
/rest/about/manifest.format

Will result in a file in the '.format' format listing all of the registered Manifest resources.

GET request on the path:
/rest/about/version.format

Will result in a file in the '.format' format listing informations coming from the following

resources:

  • GeoServer
  • GeoTools
  • GeoWebCache

Supported formats:

Supported format are:
JSON, XML and HTML (default is HTML)

The data model:

The model is very simple and is shared between the version and the resource request to parse both requests with the same parser and to reduce number of needed classes in geoserver.

<about>
 <resource name="{NAME}">
  <{PROPERTY}>{VALUE}</{PROPERTY}>
 </resource>
 ...
</about>

You can customize the results adding a properties file called '''manifest.properties''' into the datadir.
Here is the default implementation which can be overridden by the one into the datadir.

# group(1) defines the name attribute of of the resource
resourceNameRegex=.+/(.*).(jar|war)
# list of properties to exclude from the resource
resourceAttributeExclusions=Import-Package,Export-Package,Class-Path,Require-Bundle
# list of properties to include into the Version.
# [optionally] You can specify a replacement string for a property key:
# 	key:replace
versionAttributeInclusions=Project-Version:Version,Build-Timestamp,Git-Revision,Specification-Version:Version,Implementation-Version:Git-Revision

How to extend:

A project or extension should use the maven jar plugin to create the Manifest.mf file:

The manifest entries can be customized adding special keys and other build information using maven variables with the maven jar plugin configured as shown:

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-jar-plugin</artifactId>
 <configuration>
 <archive>
 <configuration>
	<archive>
		<manifest>
			<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
			<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
		</manifest>
		<manifestEntries>
			<Application-Name>${project.build.finalname}</Application-Name>
			<Project-Version>${project.version}</Project-Version>
			<Iteration-Name>${iteration}</Iteration-Name>
			<Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
			<Git-Revision>${build.commit.id}</Git-Revision>
		</manifestEntries>
	</archive>
	</configuration>
 </archive>
 </configuration>
</plugin>

Examples:

How HTML will result

get http://GEOSERVER/rest/about/manifest.html (with username and password)

  About:

   Resource name: activation-1.1

      Manifest-Version : 1.0
      Specification-Title : JavaBeans(TM) Activation Framework Specification
      Specification-Version : 1.1
      Ant-Version : Apache Ant 1.6.5
      Specification-Vendor : Sun Microsystems, Inc.
      Implementation-Version : 1.1
      Extension-Name : javax.activation
      Implementation-Vendor : Sun Microsystems, Inc.
      Implementation-Vendor-Id : com.sun
      Implementation-Title : Sun Java System Application Server
      Created-By : 1.5.0_06-b03 (Sun Microsystems Inc.)

   Resource name: aopalliance-1.0

      Manifest-Version : 1.0
      Ant-Version : Apache Ant 1.5.4
      Created-By : 1.4.2_01-b06 (Sun Microsystems Inc.)

   Resource name: batik-anim-1.7

      Manifest-Version : 1.0
      Build-Id : 20080103-095140-EST (cam [Linux 2.6.22-1-486 i386, Java 1.4.2_12-b03])
      Ant-Version : Apache Ant 1.6.5
      Implementation-Version : 1.7+r608262
      Implementation-Vendor : The Apache Software Foundation (http://xmlgraphics.apache.org/batik/)
      Implementation-Title : Batik animation
      Created-By : 1.4.2_12-b03 (Sun Microsystems Inc.)

      ...

How JSON will result

get http://GEOSERVER/rest/about/manifest.json (with username and password)

{
about: {
 resource: [
 {
  @name: "activation-1.1",
  Manifest-Version: 1,
  Specification-Title: "JavaBeans(TM) Activation Framework Specification",
  Specification-Version: 1.1,
  Ant-Version: "Apache Ant 1.6.5",
  Specification-Vendor: "Sun Microsystems, Inc.",
  Implementation-Version: 1.1,
  Extension-Name: "javax.activation",
  Implementation-Vendor: "Sun Microsystems, Inc.",
  Implementation-Vendor-Id: "com.sun",
  Implementation-Title: "Sun Java System Application Server",
  Created-By: "1.5.0_06-b03 (Sun Microsystems Inc.)"
 },
 {
  @name: "aopalliance-1.0",
  Manifest-Version: 1,
  Ant-Version: "Apache Ant 1.5.4 ",
  Created-By: "1.4.2_01-b06 (Sun Microsystems Inc.)"
 },
 {
  @name: "batik-anim-1.7",
  Manifest-Version: 1,
  Build-Id: "20080103-095140-EST (cam [Linux 2.6.22-1-486 i386, Java 1.4.2_12-b03])",
  Ant-Version: "Apache Ant 1.6.5",
  Implementation-Version: "1.7+r608262",
  Implementation-Vendor: "The Apache Software Foundation (http://xmlgraphics.apache.org/batik/)",
  Implementation-Title: "Batik animation",
  Created-By: "1.4.2_12-b03 (Sun Microsystems Inc.)"
 },
...
 }
}

Example with control-flow plugin installed into the lib dir:

get http://GEOSERVER/rest/about/manifest.xml (with username and password)

will result in something like:

<about>
 <resource name="activation-1.1">
  <Manifest-Version>1.0</Manifest-Version>
  <Specification-Title>JavaBeans(TM) Activation Framework Specification</Specification-Title>
  <Specification-Version>1.1</Specification-Version>
  <Ant-Version>Apache Ant 1.6.5</Ant-Version>
  <Specification-Vendor>Sun Microsystems, Inc.</Specification-Vendor>
  <Implementation-Version>1.1</Implementation-Version>
  <Extension-Name>javax.activation</Extension-Name>
  <Implementation-Vendor>Sun Microsystems, Inc.</Implementation-Vendor>
  <Implementation-Vendor-Id>com.sun</Implementation-Vendor-Id>
  <Implementation-Title>Sun Java System Application Server</Implementation-Title>
  <Created-By>1.5.0_06-b03 (Sun Microsystems Inc.)</Created-By>
 </resource>
  ...
 <resource name="xstream-1.4.3">
  <Manifest-Version>1.0</Manifest-Version>
  <Archiver-Version>Plexus Archiver</Archiver-Version>
  <Built-By>joehni</Built-By>
  <Build-Jdk>1.7.0_05</Build-Jdk>
  <Created-By>Apache Maven</Created-By>
 </resource>
</about>

Example:

get http://localhost:8080/geoserver/rest/about/version.xml

<about>
 <resource name="GeoServer">
  <Build-Timestamp>11-Dec-2012 17:55</Build-Timestamp>
  <Git-Revision>e66f8da85521f73d0fd00b71331069a5f49f7865</Git-Revision>
  <Version>2.3-SNAPSHOT</Version>
 </resource>
 <resource name="GeoTools">
  <Build-Timestamp>04-Dec-2012 02:31</Build-Timestamp>
  <Git-Revision>380a2b8545ee9221f1f2d38a4f10ef77a23bccae</Git-Revision>
  <Version>9-SNAPSHOT</Version>
 </resource>
 <resource name="GeoWebCache">
  <Git-Revision>2a534f91f6b99e5120a9eaa5db62df771dd01688</Git-Revision>
  <Version>1.3-SNAPSHOT</Version>
 </resource>
</about>

2. Example with control-flow plugin installed into the lib dir:

When you add the control-flow to the lib dir of geoserver it will be loaded by the class loader so its the manifest file will be added to the list of the returned resources.

doing a get on http://GEOSERVER/rest/about/manifest.xml (with username and password)

will result in something like:

<about>
 <resource name="activation-1.1">
  <Manifest-Version>1.0</Manifest-Version>
  <Specification-Title>JavaBeans(TM) Activation Framework Specification</Specification-Title>
  <Specification-Version>1.1</Specification-Version>
  <Ant-Version>Apache Ant 1.6.5</Ant-Version>
  <Specification-Vendor>Sun Microsystems, Inc.</Specification-Vendor>
  <Implementation-Version>1.1</Implementation-Version>
  <Extension-Name>javax.activation</Extension-Name>
  <Implementation-Vendor>Sun Microsystems, Inc.</Implementation-Vendor>
  <Implementation-Vendor-Id>com.sun</Implementation-Vendor-Id>
  <Implementation-Title>Sun Java System Application Server</Implementation-Title>
  <Created-By>1.5.0_06-b03 (Sun Microsystems Inc.)</Created-By>
 </resource>
  ...
 <resource name="control-flow-2.3-SNAPSHOT">
  <GeoServerModule>extension</GeoServerModule>
  <Iteration-Name/>
  <Specification-Title>OWS request flow controller</Specification-Title>
  <Archiver-Version>Plexus Archiver</Archiver-Version>
  <Specification-Version>2.3-SNAPSHOT</Specification-Version>
  <Specification-Vendor>The Open Planning Project</Specification-Vendor>
  <Application-Name/>
  <Implementation-Version>2.3-SNAPSHOT</Implementation-Version>
  <Implementation-Vendor-Id>org.geoserver.extension</Implementation-Vendor-Id>
  <Build-Jdk>1.6.0_31</Build-Jdk>
  <Created-By>Apache Maven</Created-By>
  <Implementation-Title>OWS request flow controller</Implementation-Title>
  <Manifest-Version>1.0</Manifest-Version>
  <Built-By>cancellieri</Built-By>
  <Build-Timestamp>11-Dec-2012 17:55</Build-Timestamp>
  <Git-Revision>e66f8da85521f73d0fd00b71331069a5f49f7865</Git-Revision>
  <Implementation-Vendor>The Open Planning Project</Implementation-Vendor>
  <Project-Version>2.3-SNAPSHOT</Project-Version>
 </resource>
  ...
 <resource name="xstream-1.4.3">
  <Manifest-Version>1.0</Manifest-Version>
  <Archiver-Version>Plexus Archiver</Archiver-Version>
  <Built-By>joehni</Built-By>
  <Build-Jdk>1.7.0_05</Build-Jdk>
  <Created-By>Apache Maven</Created-By>
 </resource>
</about>

Filtering over resource name:

You can also filter over resulting resources names attribute using regular expressions:

get http://localhost:8080/geoserver/rest/about/manifest.xml?manifest=gwc-.*

Will get only resources with the name attribute matching 'gwc-.*'

<about>
  <resource name="gwc-2.3-SNAPSHOT.jar">
    <GeoServerModule>core</GeoServerModule>
    <Iteration-Name></Iteration-Name>
    <Specification-Title>GeoWebCache (GWC) Module</Specification-Title>
    <Archiver-Version>Plexus Archiver</Archiver-Version>
    <Specification-Version>2.3-SNAPSHOT</Specification-Version>
    <Specification-Vendor>The Open Planning Project</Specification-Vendor>
    <Application-Name></Application-Name>
    <Implementation-Version>2.3-SNAPSHOT</Implementation-Version>
    <Implementation-Vendor-Id>org.geoserver</Implementation-Vendor-Id>
    <Build-Jdk>1.6.0_31</Build-Jdk>
    <Created-By>Apache Maven</Created-By>
    <Implementation-Title>GeoWebCache (GWC) Module</Implementation-Title>
    <Manifest-Version>1.0</Manifest-Version>
    <Built-By>cancellieri</Built-By>
    <Build-Timestamp>10-Dec-2012 15:44</Build-Timestamp>
    <Git-Revision>273093e75b5611efda139cb93bdf850a6dd6ac3a</Git-Revision>
    <Implementation-Vendor>The Open Planning Project</Implementation-Vendor>
    <Project-Version>2.3-SNAPSHOT</Project-Version>
  </resource>
   ...
  <resource name="gwc-wmts-1.3-20121121.201712-111.jar">
    <Manifest-Version>1.0</Manifest-Version>
    <Specification-Title>org.geowebcache</Specification-Title>
    <Archiver-Version>Plexus Archiver</Archiver-Version>
    <Specification-Version>1.3-SNAPSHOT</Specification-Version>
    <Specification-Vendor>http://geowebcache.org</Specification-Vendor>
    <Built-By>jetty</Built-By>
    <Implementation-Version>2a534f91f6b99e5120a9eaa5db62df771dd01688/2a534f91f6b99e5120a9eaa5db62df771dd01688</Implementation-Version>
    <Implementation-Vendor>http://geowebcache.org</Implementation-Vendor>
    <Build-Jdk>1.6.0_21</Build-Jdk>
    <Implementation-Title>org.geowebcache</Implementation-Title>
    <Created-By>Apache Maven</Created-By>
  </resource>
</about>

Filtering over resource properties:

You can filter over resulting resources properties using:

http://localhost:8080/geoserver/rest/about/manifest.xml?key=GeoServerModule

Will get only resources with the property named 'GeoServerModule'

<about>
 <resource name="control-flow-2.3-SNAPSHOT">
  <GeoServerModule>extension</GeoServerModule>
  <Iteration-Name/>
  <Specification-Title>OWS request flow controller</Specification-Title>
  <Archiver-Version>Plexus Archiver</Archiver-Version>
  <Specification-Version>2.3-SNAPSHOT</Specification-Version>
  <Specification-Vendor>The Open Planning Project</Specification-Vendor>
  <Application-Name/>
  <Implementation-Version>2.3-SNAPSHOT</Implementation-Version>
  <Implementation-Vendor-Id>org.geoserver.extension</Implementation-Vendor-Id>
  <Build-Jdk>1.6.0_31</Build-Jdk>
  <Created-By>Apache Maven</Created-By>
  <Implementation-Title>OWS request flow controller</Implementation-Title>
  <Manifest-Version>1.0</Manifest-Version>
  <Built-By>cancellieri</Built-By>
  <Build-Timestamp>11-Dec-2012 17:55</Build-Timestamp>
  <Git-Revision>e66f8da85521f73d0fd00b71331069a5f49f7865</Git-Revision>
  <Implementation-Vendor>The Open Planning Project</Implementation-Vendor>
  <Project-Version>2.3-SNAPSHOT</Project-Version>
 </resource>
 ...
 <resource name="wms-2.3-SNAPSHOT">
  <GeoServerModule>core</GeoServerModule>
  <Iteration-Name/>
  <Specification-Title>Web Map Service Module</Specification-Title>
  <Archiver-Version>Plexus Archiver</Archiver-Version>
  <Specification-Version>2.3-SNAPSHOT</Specification-Version>
  <Specification-Vendor>The Open Planning Project</Specification-Vendor>
  <Application-Name/>
  <Implementation-Version>2.3-SNAPSHOT</Implementation-Version>
  <Implementation-Vendor-Id>org.geoserver</Implementation-Vendor-Id>
  <Build-Jdk>1.6.0_31</Build-Jdk>
  <Created-By>Apache Maven</Created-By>
  <Implementation-Title>Web Map Service Module</Implementation-Title>
  <Manifest-Version>1.0</Manifest-Version>
  <Built-By>cancellieri</Built-By>
  <Build-Timestamp>11-Dec-2012 17:55</Build-Timestamp>
  <Git-Revision>e66f8da85521f73d0fd00b71331069a5f49f7865</Git-Revision>
  <Implementation-Vendor>The Open Planning Project</Implementation-Vendor>
  <Project-Version>2.3-SNAPSHOT</Project-Version>
 </resource>
</about>

Filtering over resource properties (2):

You can filter over resulting resources properties and value using:

http://localhost:8080/geoserver/rest/about/manifest.xml?key=GeoServerModule&value=extension

Will get only resources where the property named 'GeoServerModule' has value equals to 'extension'

<about>
 <resource name="control-flow-2.3-SNAPSHOT">
  <GeoServerModule>extension</GeoServerModule>
  <Iteration-Name/>
  <Specification-Title>OWS request flow controller</Specification-Title>
  <Archiver-Version>Plexus Archiver</Archiver-Version>
  <Specification-Version>2.3-SNAPSHOT</Specification-Version>
  <Specification-Vendor>The Open Planning Project</Specification-Vendor>
  <Application-Name/>
  <Implementation-Version>2.3-SNAPSHOT</Implementation-Version>
  <Implementation-Vendor-Id>org.geoserver.extension</Implementation-Vendor-Id>
  <Build-Jdk>1.6.0_31</Build-Jdk>
  <Created-By>Apache Maven</Created-By>
  <Implementation-Title>OWS request flow controller</Implementation-Title>
  <Manifest-Version>1.0</Manifest-Version>
  <Built-By>cancellieri</Built-By>
  <Build-Timestamp>11-Dec-2012 17:55</Build-Timestamp>
  <Git-Revision>e66f8da85521f73d0fd00b71331069a5f49f7865</Git-Revision>
  <Implementation-Vendor>The Open Planning Project</Implementation-Vendor>
  <Project-Version>2.3-SNAPSHOT</Project-Version>
 </resource>
</about>

Filtering over resource properties (3):

You can filter over resulting resources properties value using:

http://localhost:8080/geoserver/rest/about/manifest.xml?value=extension

Note

Note also that non maven project can still use this using their custom (ant?) mechanisms to update their /META-INF/MANIFEST.MF file.

Feedback

Ref to the DEV ML

Backwards Compatibility

State here any backwards compatibility issues.

Voting

Alessio Fabiani: +1
Andrea Aime: +1
Ben Caradoc-Davies: +1
Christian Mueller: +1
Gabriel Roldán: +0
Jody Garnett: +1
Jukka Rahkonen: +1
Justin Deoliveira: +0
Phil Scadden: +1
Simone Giannecchini: +0

backport 2.2

Alessio Fabiani: +1
Andrea Aime: +1
Ben Caradoc-Davies: +1
Christian Mueller: +0
Gabriel Roldán:
Jody Garnett: +1
Jukka Rahkonen:
Justin Deoliveira: +1
Phil Scadden:
Simone Giannecchini: +1

Links

http://maven.apache.org/shared/maven-archiver/examples/manifest.html http://docs.oracle.com/javase/....//docs/api/java/util/jar/Manifest.html https://github.com/kevinsawicki/github-maven-example/blob/master/example/pom.xml

[JIRA Task|]
[Email Discussion|]
[Wiki Page|]

Document generated by Confluence on May 14, 2014 23:00