GSIP 143

GSIP 143 - Module Status

Overview

Modules, plugins and extensions should be able to easily report status information: the status page would benefit from this information, and the same information could be reported via the 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 modules are configured/installed/working. As per GEOS-6068 we would like an extension point to report configuration and installation details.

Proposal

Proposed ModuleStatus interface:

interface ModuleStatus {
   /**
    * Module identifier based on artifact bundle (used for rest-api consistency).
    * Example: <code>gs-main</code>, <code>gs-oracle</code>
    */
   String getModule();
   /**
    * Component identifier if required.
    * Example: <code>rendering-engine</code>
    */
   String getComponent();
   /** 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();
}

marlin status

Functionality that is or enabled by the environment can be reported as a component. As an example gs-wms can register several ModuleStatus beans in applicationContext.xml:

<bean id="renderingEngineStatus" class="org.geoserver.wms.RenderingEngineStatus"/>

Here is an example of reporting Java Rasterizer:

class RenderingEngineStatus implements ModuleStatus {
    ...
    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 status

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 status

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="module" value="gs-oracle"/>
   <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 "module" tab to the existing status page, with a long table of the status details from installed modules.

REST API

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

<about>
   <status>
     <module>gs-wms</module >
     <component>rendering-engine</component>
     <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>
   </status>
   <status>
     <module>gs-libjpeg-turbo</module>
     <name>libjpeg-turbo Map Encoder Extension</name>
     <version>2.9.0</version>
     <status>available</status>
     <enabled>true</enabled>
     <message>
         Using lib-jpepg-turbo 1.4.2.
         System property -Ddisable.turbojpeg=(unset)
     <message>
     <documentation>
         http://docs.geoserver.org/latest/en/user/extensions/libjpeg-turbo/index.html
     </documentation>
   </status>
   <status>
     <module>gs-oracle</module>
     <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>
   </status>
</about>

Backwards Compatibility

Feedback

Idea: Kevin has requested the ability to enable/disable extensions in a similar fashion to how WFS, WMS and WCS are managed. This would be optional for those components that support being disabled. Jody wonders if long-term we should consider MBeans for this use-case.

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

Idea: Dave indicates getMessage() may become more concrete - benefiting from some structure for modules that need to check multiple things such as dependencies.

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

Voting

Project Steering Committee:

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

Community support:

• Chris Snider

Links

• GEOS-6068
• Email Discussion