001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.style;
033
034 import java.util.List;
035 import org.opengis.annotation.Extension;
036 import org.opengis.filter.Filter;
037 import org.opengis.annotation.UML;
038 import org.opengis.annotation.XmlElement;
039
040 import org.opengis.metadata.citation.OnlineResource;
041 import static org.opengis.annotation.Obligation.*;
042 import static org.opengis.annotation.Specification.*;
043
044 /**
045 * A rule consists of two important parts: a {@linkplain Filter filter} and a list of
046 * {@linkplain Symbol symbols}. When it is time to draw a given feature, the rendering
047 * engine examines each rule in the FeatureStyle, first checking its Filter (or ElseFilter). If the
048 * Filter passes, then every Symbolizer for that rule is applied to the given
049 * feature.
050 *
051 * @version <A HREF="http://www.opengeospatial.org/standards/symbol">Symbology Encoding Implementation Specification 1.1.0</A>
052 * @author Open Geospatial Consortium
053 * @author Johann Sorel (Geomatys)
054 * @author Chris Dillard (SYS Technologies)
055 * @since GeoAPI 2.2
056 */
057 @XmlElement("Rule")
058 @UML(identifier="PF_PortrayalRule", specification=ISO_19117)
059 public interface Rule {
060
061 /**
062 * Returns a name for this rule.
063 * This can be any string that uniquely identifies this rule within a given
064 * canvas. It is not meant to be human-friendly. (The "title" property is
065 * meant to be human friendly.)
066 * @return a name for this rule.
067 */
068 @XmlElement("Name")
069 @UML(identifier="ruleName", obligation=MANDATORY, specification=ISO_19117)
070 String getName();
071
072 /**
073 * Returns the description of this rule.
074 *
075 * @return Description with usual informations used
076 * for user interfaces.
077 */
078 @XmlElement("Description")
079 @UML(identifier="description", obligation=OPTIONAL, specification=ISO_19117)
080 Description getDescription();
081
082 /**
083 * Returns a small Graphic that could be used by the rendering engine to
084 * draw a legend window.
085 * <p>
086 * A nice user interface may want to present the user with a legend that
087 * indicates how features of a given type are being portrayed. Through its
088 * {@code LegendGraphic} property, a {@code Rule} may provide a custom picture
089 * to be used in such a legend window.
090 * @return
091 */
092 @XmlElement("LegendGraphic")
093 GraphicLegend getLegend();
094
095 /**
096 * Returns the filter that will limit the features for which this {@code Rule} will
097 * fire. This can only be non-null if {@link #isElseFilter} returns false. If this
098 * value is null and {@code isElseFilter} is false, this means that this {@code Rule}
099 * should fire for all features.
100 * @return Filter, use Filter.INCLUDES to indicate everything; or Filter.EXCLUDES for an "else" rule
101 */
102 @XmlElement("Filter")
103 @UML(identifier="queryStatement", obligation=MANDATORY, specification=ISO_19117)
104 Filter getFilter();
105
106 /**
107 * Returns true if this {@code Rule} is to fire only if no other rules in the containing
108 * style have fired yet. If this is true, then the {@linkplain #getFilter filter} must be Filter.EXCLUDES.
109 * @return true if the filter is an else filter
110 */
111 @XmlElement("ElseFilter")
112 boolean isElseFilter();
113
114 /**
115 * Returns the minimum value (inclusive) in the denominator of the current map scale
116 * at which this {@code Rule} will fire.
117 * If, for example, the {@code MinScaleDenominator} were 10000, then this rule
118 * would only fire at scales of 1:X where X is greater than 10000.
119 * A value of zero indicates that there is no minimum.
120 * @return Min scale double value
121 */
122 @XmlElement("MinScaleDenominator")
123 double getMinScaleDenominator();
124
125 /**
126 * Returns the maximum value (exclusive) in the denominator of the current map scale
127 * at which this {@code Rule} will fire.
128 * If, for example, the {@code MaxScaleDenominator} were 98765, then this rule
129 * would only fire at scales of 1:X where X is less than 98765.
130 * A value of {@link Double#POSITIVE_INFINITY} indicates that there is no maximum.
131 * @return Max scale double value
132 */
133 @XmlElement("MaxScaleDenominator")
134 double getMaxScaleDenominator();
135
136 /**
137 * This method returns the list of Symbolizer objects
138 * contained by this {@code Rule}.
139 *
140 * We use a list of <? extends Symbolizer> to enable the possibility
141 * for an implementation to return a special type of Symbolizer.
142 * This doesnt mean a Rule must return a list of PointSymbolizer or
143 * TextSymbolizer only, no. The purpose of this if to offer the solution
144 * to return different implementations like MutableSymbolizer or RichSymbolizer
145 * and then avoid redundant cast in the code.
146 * If you dont intend to use a special interface you can override this method
147 * by : List<Symbolizer> symbolizers();
148 *
149 * @return the list of Symbolizer
150 */
151 @XmlElement("Symbolizer")
152 @UML(identifier="portrayAction", obligation=MANDATORY, specification=ISO_19117)
153 List<? extends Symbolizer> symbolizers();
154
155 /**
156 * It is common to have a style coming from a external xml file, this method
157 * provide a way to get the original source if there is one.
158 * OGC SLD specification can use this method to know if a style must be
159 * written completely or if writing the online resource path is enough.
160 *
161 * @return OnlineResource or null
162 */
163 OnlineResource getOnlineResource();
164
165 /**
166 * calls the visit method of a StyleVisitor
167 *
168 * @param visitor the style visitor
169 */
170 @Extension
171 Object accept(StyleVisitor visitor, Object extraData);
172
173 }