GSIP 143

GSIP 143 - Extension Status

Overview

Plugins should be able to easily report basic status information: the status page would benefit from this information, and the same information could be reported via rest api.

Proposed By

• Morgan Thompson
• Kevin Smith
• Jody Garnett

Assigned to Release

This is for GeoServer 2.10. (or 2.9 if available)

State

• Under Discussion
• In Progress
• Completed
• Rejected
• Deferred

Motivation

It's tricky/tedious to tell which extensions are configured/installed. As per GEOS-6068 we would like an extension point to report configuration and installation details.

Proposal

Proposed ExtensionStatus interface:

interface ExtensionStatus {
   /** Identifier based on extension (used for rest-api consistency) */
   String getID();
   /** Human readable name (from GeoServer documentation) */
   String getName();
   String getVersion();
   boolean isAvailable();
   boolean isEnabled();

   /** Optional status message */
   String getMessage();

   /** Optional relative link to user manual */
   String getDocumentation();
}

Idea: Kevin has requested the ability to control extensions in a similar fashion to how WFS, WMS and WCS can be enabled/disabled.

   boolean canUserEnable();
   boolean getUserEnabled();
   void setUserEnabled( boolean enabled );

Idea: Jody indicates getMessage() may become more concrete - benefiting from some structure for extensions that need to check multiple things.

   enum Status { OK, WARNING, INVALID };
   class Message {
        String message;
        Status status;
   }
   List<Message> getMessages();

Idea: Dave notes listing dependencies would be a useful addition.

   class Dependency {
       String name;
       List<String> jars;
       List<Dependency> dependencies;
   }
   List<Dependency> getDependencies();

marlin extension

Environment based extensions can be reported by gs-main, which would register several ExtensionStatus beans in applicationContext.xml:

<bean id="renderingEngineStatus" class="org.geoserver.web.ExtensionStatus"/>

Here is an example of reporting Java Rasterizer:

class RenderingEngineStatus implements ExtensionStatus {
    ...
    boolean isAvailable(){
        return true;
    }
    String getMessage(){
       String renderer;
       try {
            renderer = sun.java2d.pipe.RenderingEngine.getInstance().getClass().getName();
        } catch(Throwable e) {
            render "Unknown";
        }
       StringBuidler message = new StringBuilder();
       message.append("Java 2D configured with ");       
       message.append( renderer );
       message.append(".");
       ...
       return message.toString();       
       
    }
}

This can also be used to report webapp.xml settings such as speed strategy.

libjpegturbo extension

An extension such as libjpegturbo that requires native library can be tricky to configure correctly.

The status message may wish to list details of the library path in the event the service is unavailable.

gs-oracle extension

Many extensions, such as gs-oracle, just provide a maven dependency. To make use of ExtensionStatus an applicationContext.xml would be added configuring a prebuilt DataStoreExtension bean. The DataStoreExtension bean references the GeoTools DataStoreFactorySPI class used (to check the isAvailable) method, and lists several additional classes to check using Class.forName (to verify oracle driver is available).

<bean id="oracleExtension" class="org.geoserver.extension.DataStoreExtension">
   <property name="name" value="Oracle Extension"/>
   <property name="documentation" value="data/database/oracle.html"/>
   <property name="factory" value="org.geotools.data.oracle.OracleDataStoreFactorySPI"/>
   <property name="classCheck" value="oracle.jdbc.OracleDriver"/>
   <property name="classMessage" value="JDBC Driver not installed (add ojdbc7 to WEB-INF/lib directory)."/>
</bean>

Idea: We may wish to churn through DataStoreFactorySPI extension point (and list any formats that were added on the classpath) to provide a more complete list. The same approach can be taken for grid coverage format.

Status Page

Open to suggestions, recommend adding an "extension" tab to the existing status page, with extensions listed on the right alphabetically and a table on the right showing the details.

+-------------------+-+  
| Oracle Extension  |^| Name: Oracle Extension
| Rendering Engine  | | 
| 

REST API

Similar to about/manifest we propose an about/extension.xml (or json) endpoint:

<about>
   <extension>
     <id>gs-main/rendering-engine</id>
     <name>Rendering Engine</name>
     <version>0.7.3</version>
     <enabled>true</enabled>
     <status>available</status>
     <message>
         Java 2D configured with org.marlin.pisces.PicesRenderingEngine.
         System property: -Dsun.java2d.renderer=org.marlin.pisces.PiscesRenderingEngine.
         Boot classpath contains marlin-0.7.3.jar
     </message>
   </extension>
   <extension>
     <id>gs-libjpeg-turbo</id>
     <name>libjpeg-turbo Map Encoder Extension</name>
     <version>2.9.0</version>
     <status>available</status>
     <enabled>true</enabled>
     <message>
         Using lib-jepg-turbo 1.4.2.
         System property -Ddisable.turbojpeg=(unset)
     <message>
     <documentation>
         http://docs.geoserver.org/latest/en/user/extensions/libjpeg-turbo/index.html
     </documentation>
   </extension>
   <extension>
     <id>gs-oracle</id>
     <name>Oracle</name>
     <version>2.9.0</version>
     <status>unavailable</status>
     <enabled>true</enabled>
     <message>
         JDBC Driver not installed (add ojdbc7 to WEB-INF/lib directory).
     <message>
     <documentation>
        http://docs.geoserver.org/stable/en/user/data/database/oracle.html
     </documentation>
   </extension>
</about>

Backwards Compatibility

Feedback

Jody wonders if we should consider MBeans (or is that overkill).

Voting

Project Steering Committee:

• Alessio Fabiani:
• Andrea Aime:
• Ben Caradoc-Davies:
• Brad Hards:
• Christian Mueller:
• Ian Turton:
• Jody Garnett:
• Jukka Rahkonen:
• Kevin Smith:
• Simone Giannecchini:

Links

• [Bug Report] https://osgeo-org.atlassian.net/browse/GEOS-6068
• [Email Discussion]