001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2004-2006, Geotools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation; either
009: * version 2.1 of the License, or (at your option) any later version.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.data.wms.request;
017:
018: import java.util.Properties;
019:
020: import org.geotools.data.ows.CRSEnvelope;
021: import org.geotools.data.ows.Layer;
022: import org.geotools.data.ows.Request;
023: import org.opengis.layer.Style;
024:
025: /**
026: * Construct a WMS getMap request.
027: *
028: * <p>
029: * Constructs a getMapRequest based on the following property values:
030: *
031: * <ul>
032: * <li>
033: * ELEVATION
034: * </li>
035: * <li>
036: * TIME
037: * </li>
038: * <li>
039: * EXCEPTIONS
040: * </li>
041: * <li>
042: * BGCOLOR
043: * </li>
044: * <li>
045: * TRANSPARENT
046: * </li>
047: * <li>
048: * WIDTH
049: * </li>
050: * <li>
051: * HEIGHT
052: * </li>
053: * <li>
054: * SRS
055: * </li>
056: * <li>
057: * REQUEST
058: * </li>
059: * <li>
060: * LAYERS
061: * </li>
062: * <li>
063: * STYLES
064: * </li>
065: * <li>
066: * <i>vendor specific parameters</i>
067: * </li>
068: * </ul>
069: * </p>
070: *
071: * <p>
072: * Q: List availableFormats and availableExceptions - why are these here? It
073: * looks like they are designed to restrict the values used for SRS, format
074: * and exceptions. If so the code never uses them. Q: How constant is the
075: * GetMapRequest format across WMS versions? Do we need to generalize here?
076: * </p>
077: *
078: * @author Richard Gould, Refractions Research
079: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/plugin/wms/src/main/java/org/geotools/data/wms/request/GetMapRequest.java $
080: */
081: public interface GetMapRequest extends Request {
082: /** Represents the ELEVATION parameter */
083: public static final String ELEVATION = "ELEVATION"; //$NON-NLS-1$
084: /** Represents the TIME parameter */
085: public static final String TIME = "TIME"; //$NON-NLS-1$
086: /** Represents the EXCEPTIONS parameter */
087: public static final String EXCEPTIONS = "EXCEPTIONS"; //$NON-NLS-1$
088: /** Represents the BGCOLOR parameter */
089: public static final String BGCOLOR = "BGCOLOR"; //$NON-NLS-1$
090: /** Represents the TRANSPARENT parameter */
091: public static final String TRANSPARENT = "TRANSPARENT"; //$NON-NLS-1$
092: /** Represents the WIDTH parameter */
093: public static final String WIDTH = "WIDTH"; //$NON-NLS-1$
094: /** Represents the HEIGHT parameter */
095: public static final String HEIGHT = "HEIGHT"; //$NON-NLS-1$
096: /** Represents the FORMAT parameter */
097: public static final String FORMAT = "FORMAT"; //$NON-NLS-1$
098: /** Represents the BBOX parameter */
099: public static final String BBOX = "BBOX"; //$NON-NLS-1$
100: /** Represents the SRS parameter */
101: public static final String SRS = "SRS"; //$NON-NLS-1$
102: /** Represents the LAYERS parameter */
103: public static final String LAYERS = "LAYERS"; //$NON-NLS-1$
104: /** Represents the STYLES parameter */
105: public static final String STYLES = "STYLES"; //$NON-NLS-1$
106:
107: public static final String EXCEPTION_XML = "application/vnd.ogc.se_xml";
108: /** Represents the EXCEPTION_INIMAGE value */
109: public static final String EXCEPTION_INIMAGE = "application/vnd.ogc.se_inimage"; //$NON-NLS-1$
110: /** Represents the EXCEPTION_BLANK value */
111: public static final String EXCEPTION_BLANK = "application/vnd.ogc.se_blank"; //$NON-NLS-1$
112:
113: /** =============== BEGIN SLD SPECIFICATION PARAMETERS =============== **/
114: /** Represents the SLD parameter */
115: public static final String SLD = "SLD"; //$NON-NLS-1$
116: /** Represents the SLD_BODY parameter */
117: public static final String SLD_BODY = "SLD_BODY"; //$NON-NLS-1$
118: /** Represents the WFS parameter mentioned briefly in 1.1.1 */
119: public static final String WFS = "WFS"; //$NON-NLS-1$
120: /** Represents REMOTE_OWS_TYPE parameter */
121: public static final String REMOTE_OWS_TYPE = "REMOTE_OWS_TYPE"; //$NON-NLS-1$
122: /** Represents REMOTE_OWS_URL parameter */
123: public static final String REMOVE_OWS_URL = "REMOTE_OWS_URL"; //$NON-NLS-1$
124:
125: /** <code>REMOTE_OWS_WFS</code> indicates WFS as a REMOTE_OWS_TYPE */
126: public static final String REMOTE_OWS_WFS = "WFS";
127: /** <code>REMOTE_OWS_WCS</code> indicates WCS as a REMOTE_OWS_TYPE */
128: public static final String REMOTE_OWS_WCS = "WCS";
129:
130: /** =============== END SLD SPECIFICATION PARAMETERS =============== **/
131:
132: /**
133: * Sets the version number of the request.
134: *
135: * @param version A String indicting a WMS Version ("1.0.0", "1.1.0",
136: * "1.1.1", "1.3.0", etc.)
137: */
138: public void setVersion(String version);
139:
140: /**
141: * Adds a Layer to the list of layers to be requested. This layer will be drawn
142: * below any previously added layers.
143: * @param layer the Layer to use
144: * @param style the style to use. If it is null, the default style is used.
145: */
146: public void addLayer(Layer layer, Style style);
147:
148: /**
149: * Adds a Layer to the list of layers to be requested. This layer will be drawn
150: * below any previously added layers.
151: *
152: * @param layerName the Layer to use
153: * @param style the style to use. If it is null, the default style is used.
154: */
155: public void addLayer(String layerName, Style style);
156:
157: /**
158: * Adds a Layer to the list of layers to be requested. This layer will be drawn
159: * below any previously added layers.
160: * @param layerName the name of the layer to use
161: * @param styleName the style to use to draw the layer, can also be NULL, "" or "default"
162: */
163: public void addLayer(String layerName, String styleName);
164:
165: /**
166: * Adds a Layer to the list of layers to be requested. This layer will be drawn
167: * below any previously added layers.
168: * @param layer the Layer to use
169: * @param styleName the style to use to draw the layer, can also be NULL, "" or "default"
170: */
171: public void addLayer(Layer layer, String styleName);
172:
173: /**
174: * Adds a Layer to the list of layers to be requested. This layer will be drawn
175: * below any previously added layers. The style will be the default one.
176: * @param layer the Layer to use
177: */
178: public void addLayer(Layer layer);
179:
180: /**
181: * From the Web Map Service Implementation Specification: "The required SRS
182: * parameter states which Spatial Reference System applies to the values
183: * in the BBOX parameter. The value of the SRS parameter shall be on of
184: * the values defined in the character data section of an <SRS> element
185: * defined or inherited by the requested layer. The same SRS applies to
186: * all layers in a single request. If the WMS has declared SRS=NONE for a
187: * Layer, then the Layer does not have a well-defined spatial reference
188: * system and should not be shown in conjunction with other layers. The
189: * client shall specify SRS as "none" in the GetMap request and the Server
190: * may issue a Service Exception otherwise."
191: *
192: * @param srs A String indicating the Spatial Reference System to render
193: * the layers in.
194: */
195: public void setSRS(String srs);
196:
197: /**
198: * From the Web Map Service Implementation Specification: "The required
199: * BBOX parameter allows a Client to request a particular Bounding Box.
200: * The value of the BBOX parameter in a GetMap request is a list of
201: * comma-separated numbers of the form "minx,miny,maxx,maxy". If the WMS
202: * server has declared that a Layer is not subsettable, then the Client
203: * shall specify exactly the declared Bounding Box values in the GetMap
204: * request and the Server may issue a Service Exception otherwise."
205: *
206: * NOTE: In WMS 1.3.0, the specification of "EPSG:4326" has the axis
207: * swapped, so a request made in 1.1.1 using "minx,miny,maxx,maxy" would
208: * use "miny,minx,maxy,maxx" in 1.3.0. Only when using EPSG:4326!
209: *
210: * Currently it is up to the client to do this on there own.
211: * TODO Accept Envelopes and doubles instead of Strings, and perform
212: * the 1.3.0 conversion automatically. Also note that not all servers
213: * may implement this. Should provide an option to use 1.1.1 format even
214: * when using 1.3.0.
215: *
216: * @param bbox A string representing a bounding box in the format
217: * "minx,miny,maxx,maxy"
218: */
219: public void setBBox(String bbox);
220:
221: public void setBBox(CRSEnvelope box);
222:
223: /**
224: * From the Web Map Service Implementation Specification: "The required
225: * FORMAT parameter states the desired format of the response to an
226: * operation. Supported values for a GetMap request on a WMS instance are
227: * listed in one or more <Format> elements in the
228: * &;ltRequest><GetMap> element of its Capabilities XML. The entire
229: * MIME type string in <Format> is used as the value of the FORMAT
230: * parameter."
231: *
232: * @param format The desired format for the GetMap response
233: */
234: public void setFormat(String format);
235:
236: /**
237: * From the Web Map Service Implementation Specification: "The required
238: * WIDTH and HEIGHT parameters specify the size in integer pixels of the
239: * map image to be produced. WIDTH specifies the number of pixels to be
240: * used between the minimum and maximum X values (inclusive) in the BBOX
241: * parameter, while HEIGHT specifies the number of pixels between the
242: * minimum and maximum Y values. If the WMS server has declared that a
243: * Layer has fixed width and height, then the Client shall specify exactly
244: * those WIDTH and HEIGHT values in the GetMap request and the Server may
245: * issue a Service Exception otherwise."
246: *
247: * @param width
248: * @param height
249: */
250: public void setDimensions(String width, String height);
251:
252: public void setDimensions(int width, int height);
253:
254: // End required parameters, begin optional ones.
255: //TODO Implement optional parameters.
256:
257: /**
258: * From the Web Map Service Implementation Specification: "The optional
259: * TRANSPARENT parameter specifies whether the map background is to be
260: * made transparent or not. The default value is false if the parameter is
261: * absent from the request."
262: *
263: * @param transparent true for transparency, false otherwise
264: */
265: public void setTransparent(boolean transparent);
266:
267: /**
268: * Specifies the colour, in hexidecimal format, to be used as the
269: * background of the map. It is a String representing RGB values in
270: * hexidecimal format, prefixed by "0x". The format is: 0xRRGGBB. The
271: * default value is 0xFFFFFF (white)
272: *
273: * @param bgColour the background colour of the map, in the format 0xRRGGBB
274: */
275: public void setBGColour(String bgColour);
276:
277: /**
278: * The exceptions type specifies what format the server should return
279: * exceptions in.
280: *
281: * <p>
282: * Valid values are:
283: *
284: * <ul>
285: * <li>
286: * "application/vnd.ogc.se_xml" (the default)
287: * </li>
288: * <li>
289: * "application/vnd.ogc.se_inimage"
290: * </li>
291: * <li>
292: * "application/vnd.ogc.se_blank"
293: * </li>
294: * </ul>
295: * </p>
296: *
297: * @param exceptions
298: */
299: public void setExceptions(String exceptions);
300:
301: /**
302: * See the Web Map Server Implementation Specification 1.1.1, Annexes B and
303: * C
304: *
305: * @param time See the Web Map Server Implementation Specification 1.1.1,
306: * Annexes B and C
307: */
308: public void setTime(String time);
309:
310: /**
311: * See the Web Map Server Implementation Specification 1.1.1, Annex C, in
312: * particular section C.4
313: *
314: * @param elevation See the Web Map Server Implementation Specification
315: * 1.1.1, Annex C
316: */
317: public void setElevation(String elevation);
318:
319: /**
320: * See the Web Map Server Implementation Specification 1.1.1, Annex C, in
321: * particular section C.4.2
322: *
323: * <p>
324: * Example use: <code>request.setSampleDimensionValue("DIM_WAVELENGTH",
325: * "4000");</code>
326: * </p>
327: *
328: * @param name the request parameter name to set (usually with 'dim_' as
329: * prefix)
330: * @param value the value of the request parameter (value, interval or
331: * comma-separated list)
332: */
333: public void setSampleDimensionValue(String name, String value);
334:
335: /**
336: * Used to implement vendor specific parameters. Entirely optional.
337: *
338: * @param name a request parameter name
339: * @param value a value to accompany the name
340: */
341: public void setVendorSpecificParameter(String name, String value);
342:
343: /**
344: * create a request using a properties file to save time
345: */
346: public void setProperties(Properties p);
347: }
|