org.opengis.filter.sort.SortBy Maven / Gradle / Ivy

/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2011, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2003-2005, Open Geospatial Consortium Inc.
 *
 *    All Rights Reserved. http://www.opengis.org/legal/
 */
package org.opengis.filter.sort;

import org.opengis.filter.expression.PropertyName;

/**
 * Defines the sort order, based on a property and ascending/descending.
 *
 * Having SortBy at the Filter level is an interesting undertaking of Filter 1.1 support. Why you
 * ask? It is at the Same level as Filter, it is not *used* by Filter itself. The services that make
 * use of Filter, such as WFS are starting to make use of SortBy in the same breath.
 *
 * 
Where is SortBy used:
 *
 * 

 *   WFS 1.1 Query
 *   
CSW 2.0.1 AbstractQuery
 * 
 *
 * There may be more ...
 *
 * What this means is that the GeoTools Query will make use of this construct. As for sorting the
 * result of an expression (where an expression matches more then one element), we will splice it in
 * to AttributeExpression as an optional parameter. Note function is defined to return a single
 * value (so we don't need to worry there).
 *
 * @see 
 * @see 
 * @since GeoAPI 2.1
 * @author Jody Garnett (Refractions Research)
 */
public interface SortBy {
    /**
     * Used to indicate lack of a sorting order.
     *
     * 
This is the default value for used when setting up a Query.
     */
    SortBy[] UNSORTED = new SortBy[0];

    /**
     * Used to indicate "natural" sorting order, usually according FID (hopefully based on Key
     * attribtues).
     *
     * 
This is the order that is most likely to be available in optimzied form, if an Attribute
     * is marked as "key" an optimized ordering should be considered avaialble.
     *
     * 
Non optimized orderings are will at the very least require as pass through the data to
     * bring it into memory, you can assume somekind of TreeSet would be used. Where the nodes in
     * the tree would indicate a list of FeatureIds assoicated with the node, in the order
     * encountered.
     *
     * 
This is a "NullObject".
     */
    SortBy NATURAL_ORDER = new NullSortBy(SortOrder.ASCENDING);

    /**
     * Indicate the reverse order, usually assoicated with "Fid".
     *
     * 
This is a "NullObject".
     */
    SortBy REVERSE_ORDER = new NullSortBy(SortOrder.DESCENDING);

    /**
     * Indicate property to sort by, specification is limited to PropertyName.
     *
     * 
Not sure if this is allowed to be a xPath expression?
     *
     * 

     *   It would be consist with our use in GeoTools
     *   
It would not seem to agree with the short hand notation used by WFS1.1 (ie. "year A,
     *       month A, day A" )
     * 

     *
     * @todo Use QName
     * @return Name of property to sort by.
     */
    PropertyName getPropertyName();

    /**
     * The the sort order - one of {@link SortOrder#ASCENDING ASCENDING} or {@link
     * SortOrder#DESCENDING DESCENDING}.
     */
    SortOrder getSortOrder();
}