Clean up KMLVectorTransformer before it becomes more unmanageable than it already is. Motivation Proposal Backwards Compatability Feedback Voting Links

1.7.0

Under Discussion

KMLVectorTransformer.java is currently over 1200 lines of code, with various features being written directly into the class over time.  By refactoring it we can make it more maintainable and more extensible, even creating the potential for plugins to customize the KML output.  This proposal is really a conglomeration of several suggestions for changes to be made to KMLVectorTransformer which can be implemented incrementally.

There are currently quite a few lines of code in KMLVectorTransformer converting Freemarker date formats to xsd:datetime elements.  This seems a concern that extends beyond that of the KML transformer and should live in a place where it is more accessible for reuse.

The current code that determines the scale of an element (for SLD styling of KML) simply hard-codes a scale of 1, but a setter and getter are implemented along with a commented-out call to code in GeoTools to actually calculate the scale based on a hard-coded pixel size.  I believe this second approach should be reinstated to allow SLD styling of KML to have different effects depending on zoomlevel.

KMLVectorTransformer currently dedicates several lines of code to determining whether a Style contains any Rules that apply to a particular feature at a given scale.  This should be factored out into a utility class available to other transformers (or even better, replaced with a call to a method provided by the geotools rendering API).

Classification, or dividing up a KML map into several KML Document elements, would allow easier browsing for endusers by dividing the KML treeview up by some salient attribute of the data (ie, the treeview would have sections for major roads, minor roads, bike lanes, and duck crossings).  A KMLClassifier interface could be defined as:

/**
 * The KMLClassifier interface should be implemented by classes that wish to provide extra
 * organizational divisions to a KML map.
 */
public interface KMLClassifier {
  /**
   * Return the name of this classification strategy.  This will be matched, case-insensitive, when
   * looking for a strategy based on user specification.
   */
  public String getName();

  /**
   * The getSortBy() method should return some set of attributes by which to sort the data.
   */
  public SortBy[] getSortBy(WMSMapRequest request, MapLayerInfo layer);

  /**
   * The terminate() method will be called for each feature in the order of their insertion into the map,
   * which will follow the sort order dictated by getSortBy().  This method should return true when its
   * argument is the first feature of a new Document within the KML.
   */
  public boolean terminate(SimpleFeature f);
}

Classifiers could then be registered via spring and automagically inserted by plugins.  A format_option like: “classifyOn:discrete” could specify to classify data such that all categories contain the same value of some attribute, etc.

Rather than the current placemark encoding technique of having a single method that simply hardcodes the set of information that goes into a placemark, we could create an interface like so:

public interface KMLPlacemarkListener {
    /**
     * Add content to a KML Placemark.
     * @param translator the TranslatorSupport instance that is writing the XML for the KML document
     * @param f the feature being represented in the placemark
     */
    public void addContent(TranslatorSupport translator, SimpleFeature f);
}

The vector transformer could find all implementations of this interface in the application context when rendering a KML document, or we could allow a format_option like placemarkContents:style,geometry,atom (ie, a comma-delimited list of names of content providers) to allow a run-time customizable set of elements for the Placemarks.

For applications such as the GeoSearch indexing service, it is useful to add extra elements to the Document node as well.  A similar approach to that proposed for Placemark elements could be taken, with the interface looking like: \\

public interface KMLDocumentListener {
    /**
     * Add content to a KML Document.
     * @param translator the TranslatorSupport instance that is writing the XML for the KML document
     * @param layer the configuration object for the layer
     */
    public void addContent(TranslatorSupport translator, MapLayerInfo layer);
}

For applications such as automated KML regionating, it is useful to hide some features based on criteria that cannot be expressed by a simple WMS query.  An extension point to allow customization of this behavior could be created based on the RegionatingStrategy interface already defined for this purpose.   The current iteration of RegionatingStrategy can be seen at [http://svn.codehaus.org/geoserver/trunk/geoserver/community/geosearch/src/main/java/org/vfny/geoserver/wms/responses/map/kml/RegionatingStrategy.java] .   Again, by adding a format_option and a name attribute for content filters, these could be specified at runtime by end-users.

This section should contain feedback provided by PSC members who may have a problem with the proposal.

Since the current mechanism for customizing the KML output format (beyond user-configurable Freemarker templates) is to override methods from the vector transformer, any existing code will fail to inherit the enhancements provided by this refactoring.  Therefore, these changes require the hand-conversion of any pre-existing KML plugins.  However, from the end-user point of view all functionality will remain the same aside from any format_options added.  Any such options will retain a default that is identical to the previous behavior.

Andrea Aime: Alessio Fabiani Justin Deoliveira: Jody Garnett: Saul Farber: Rob Atkinson:

JIRA Task Email Discussion Wiki Page