Motivation:

A previous withdrawn proposal introduced geoapi symbology encoding 1.1 interfaces to geotools.

Contact:

Jody Garnett

Tagline:

Clean up deprecations in style interfaces

Jira:

GEOT-2468 used to report progress

This page represents the current plan; for discussion please check the tracker link above.

Description

A previous withdrawn proposal, Upgrading styles with GeoAPI Interfaces, introduced GeoAPI interfaces for Symbology Encoding into the GeoTools. This work was incomplete leaving us with many deprecated methods; and no alternative workaround.

This "proposal" (more case of technical dept) will clean up the style interfaces by:

Good ideas not included in this proposal:

While the GeoAPI interfaces will be left in the mix as super classes (providing a read-only interface) the GeoTools codebase will continue to make use of the GeoTools interfaces which will offer a read-write extension. This arrangement allows us to use the excellent work that went into producing Symbology Encoding 1.1 interfaces while preserving our current work flow.

Status

This proposal is ready to go; however there is no paid contract work behind it; as such it will need to be a community effort.

I would appreciate a timely response on this as:

This proposal has received the following votes:

Community support:

Tasks

 

no progress

(tick)

done

(error)

impeded

(warning)

lack mandate/funds/time

(question)

volunteer needed

  1. (tick) Restore Setter methods for 2.5.x; and prepair patch
  2. (tick) Apply patch to 2.6.x; and proceed with extending any geoapi classes required (this is a formal review of the geoapi interfaces so some changes to the interfaces will be requried - some of the visit method for example are inconsistent)
  3. (tick) Go over StyleFactory from geoapi and make sure it is complete; it is complete when it can completely copy an existing style using a StyleVisitor
  4. (tick) With 2.6.x cleaned up the documentation examples can be updated; the documentation examples are stored in demo

Unexpected developments:

API Changes

The following lists one example (ContrastEnhancement); the same approach will be used to update all of the interfaces including the Symbolizers and FeatureTypeStyle.

Current GeoTools 2.5 Interface

Currently all set methods are deprecated; and any method with a planned replacement is also deprecated.

public interface ContrastEnhancement {
    @Deprecated // to be replaced by ContrastMethod in 2.6
    public void setType(Expression type);

    @Deprecated // setter deprecated
    public Expression getType();

    @Deprecated // setter deprecated
    public void setGammaValue(Expression gamma);

    public Expression getGammaValue();
    ...
}

AFTER GeoTools 2.5 Change

Minimal change will be performed to line up GeoTools 2.5 with intended result; no sense deprecating a method that is going to be maintained. We also need to restore any method for which the replacement is not ready (getType in this example).

public interface ContrastEnhancement extends org.opengis.style.ContrastEnhancement{
    public void setType(Literal type);
    /**
     * Returns a literal expression (one of NORMALIZE, HISTOGRAM, NONE)
     * indicating which ContrastMethod value is to be used.
     * 
     * @deprecated Please use getMethod
     */
    public Literal getType();

    /**
     * @param gamma How much to brighten (greater than 1) or dim (less than 1) this channel; use 1.0 to indicate no change.
     */
    public void setGammaValue(Expression gamma);

    /**
     * How much to brighten (values greater than 1.0) or dim (values less than 1.0) an image. The default GammaValue is 1.0
     * (no change).
     *
     * @return Expression, if <code>null</code> a value of 1.0 is assumed indicating no change
     */
    public Expression getGammaValue();
}

AFTER: Final GeoAPI 2.6 interface

Any geoapi interfaces that need to be extended (or type narrowed) are sorted out. Any overrides are supliemented with our own javadoc (getters) and a mutibility allowed (addition of a setter method). Any honest mistakes (like getType and setType) remain deprecated.

public interface ContrastEnhancement extends org.opengis.style.ContrastEnhancement{
    /**
     * Contrast method used to enhance this channel.
     * @param method ContrastMethod used to enhance this channel
     */
    public void setMethod( ContrastMethod method );
       
    public ContrastMethod getMethod();

    @Deprecated
    public void setType(Literal type);

    /**
     * Returns a literal expression (one of NORMALIZE, HISTOGRAM, NONE)
     * indicating which ContrastMethod value is to be used.
     * 
     * @deprecated Please use getMethod
     */
    @Deprecated
    public Literal getType();

    /**
     * @param gamma How much to brighten (greater than 1) or dim (less than 1) this channel; use 1.0 to indicate no change.
     */
    public void setGammaValue(Expression gamma);

    /**
     * How much to brighten (values greater than 1.0) or dim (values less than 1.0) an image. The default GammaValue is 1.0
     * (no change).
     *
     * @return Expression, if <code>null</code> a value of 1.0 is assumed indicating no change
     */
    public Expression getGammaValue();

}

Documentation Changes

The rendering and style section of the user guide can be updated after this work is complete.