001 //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_testing/src/org/deegree/portal/context/MapModelAccess.java $
002 /*----------------------------------------------------------------------------
003 This file is part of deegree, http://deegree.org/
004 Copyright (C) 2001-2009 by:
005 Department of Geography, University of Bonn
006 and
007 lat/lon GmbH
008
009 This library is free software; you can redistribute it and/or modify it under
010 the terms of the GNU Lesser General Public License as published by the Free
011 Software Foundation; either version 2.1 of the License, or (at your option)
012 any later version.
013 This library is distributed in the hope that it will be useful, but WITHOUT
014 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
016 details.
017 You should have received a copy of the GNU Lesser General Public License
018 along with this library; if not, write to the Free Software Foundation, Inc.,
019 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020
021 Contact information:
022
023 lat/lon GmbH
024 Aennchenstr. 19, 53177 Bonn
025 Germany
026 http://lat-lon.de/
027
028 Department of Geography, University of Bonn
029 Prof. Dr. Klaus Greve
030 Postfach 1147, 53001 Bonn
031 Germany
032 http://www.geographie.uni-bonn.de/deegree/
033
034 e-mail: info@deegree.org
035 ----------------------------------------------------------------------------*/
036 package org.deegree.portal.context;
037
038 import java.net.URL;
039
040 import org.deegree.datatypes.QualifiedName;
041 import org.deegree.graphics.sld.StyledLayerDescriptor;
042 import org.deegree.model.spatialschema.Envelope;
043 import org.deegree.model.spatialschema.Point;
044 import org.deegree.portal.PortalException;
045
046 /**
047 * <p>
048 * This interface defines access to the model (
049 *
050 * @see org.deegree.portal.context.ViewContext ) a map based on. A concret implementation is
051 * responsible for handling the context. E.g. an implementation may adds additional
052 * capabilities like a history function.
053 * </p>
054 * <p>
055 * Several methods expects beside the name of a layer the address (URL) of the OWS that serves
056 * this layer. This is required because a ViewContext may offeres layers from more than one OWS
057 * and there is no rule that says that a layers name must be unique across several OWS. So the
058 * only way to identify a layer is to use the combination of layer name, service address and
059 * service type (maybe several services are published to the same address; e.g. deegree 2 will
060 * do this).
061 * </p>
062 * <p>
063 * Notice: All changed e.g. removeLayer just will be made to a ViewContext and not to the
064 * service providing a layer.
065 * </p>
066 *
067 * @author <a href="mailto:poth@lat-lon.de">Andreas Poth</a>
068 * @author last edited by: $Author:wanhoff$
069 *
070 * @version $Revision: 18195 $ $Date: 2009-06-18 17:55:39 +0200 (Do, 18 Jun 2009) $
071 *
072 */
073 public interface MapModelAccess {
074
075 /**
076 * The pan north constant.
077 */
078 int PAN_NORTH = 0;
079
080 /**
081 * The pan north east constant.
082 */
083 int PAN_NORTHEAST = 1;
084
085 /**
086 * The pan north west constant.
087 */
088 int PAN_NORTHWEST = 2;
089
090 /**
091 * The pan south constant.
092 */
093 int PAN_SOUTH = 3;
094
095 /**
096 * The pan south east constant.
097 */
098 int PAN_SOUTHEAST = 4;
099
100 /**
101 * The pan south west constant.
102 */
103 int PAN_SOUTHWEST = 5;
104
105 /**
106 * The pan west constant.
107 */
108 int PAN_WEST = 6;
109
110 /**
111 * The pan east constant.
112 */
113 int PAN_EAST = 7;
114
115 /**
116 * sets the layers provided by the passed OWS to a <code>ViewContext</code>. A layer may be a
117 * WMS layer, a WFS feature type or a WCS coverage.
118 *
119 * @param names
120 * names of the layer
121 * @param owsAddresses
122 * addresses of the OWS that serves the layer. each passed layername is assigned to
123 * the OWS URL at the same index position.
124 * @param type
125 * OWS type (WCS, WMS or WFS)
126 * @return modified ViewContext
127 * @throws PortalException
128 * will be thrown if of the layers already is registered to a ViewContext or the OWS
129 * does not serves one the layers or <code>names</names>
130 * and <code>owsAddresses</code> are not of the same size.
131 */
132 public ViewContext setLayers( QualifiedName[] names, URL[] owsAddresses, String type )
133 throws PortalException;
134
135 /**
136 * sets the layers to a <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature
137 * type or a WCS coverage.
138 *
139 * @param layers
140 * layers to add
141 * @return modified ViewContext
142 * @throws PortalException
143 * will be thrown if of the layers already is registered to a ViewContext.
144 */
145 public ViewContext setLayers( Layer[] layers )
146 throws PortalException;
147
148 /**
149 * adds a layer provided by the passed OWS to the end of the layer list of a
150 * <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature type or a WCS
151 * coverage.
152 *
153 * @param name
154 * name of the layer
155 * @param owsAddress
156 * address of the OWS that serves the layer
157 * @param type
158 * OWS type (WCS, WMS or WFS)
159 * @exception PortalException
160 * will be thrown if the layer already is registered to a ViewContext or the OWS
161 * does not serves a layer with this name.
162 * @return modified ViewContext
163 */
164 public ViewContext addLayer( QualifiedName name, URL owsAddress, String type )
165 throws PortalException;
166
167 /**
168 * adds a layer to the end of the layer list of a <code>ViewContext</code>. A layer may be a
169 * WMS layer, a WFS feature type or a WCS coverage.
170 *
171 * @param layer
172 * layer to add
173 * @throws PortalException
174 * will be thrown if the layer already is registered to a ViewContext.
175 * @return modified ViewContext
176 */
177 public ViewContext addLayer( Layer layer )
178 throws PortalException;
179
180 /**
181 * adds a layer provided by the passed OWS to the defined index position of the layer list of a
182 * <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature type or a WCS
183 * coverage.
184 *
185 * @param index
186 * index position where to insert the layer
187 * @param name
188 * name of the layer
189 * @param owsAddress
190 * address of the OWS that serves the layer
191 * @param type
192 * OWS type (WCS, WMS or WFS)
193 * @throws PortalException
194 * will be thrown if the layer already is registered to a ViewContext or the OWS
195 * does not serves a layer with this name or the index is < 0 or > the number
196 * of layers -1;
197 * @return modified ViewContext
198 */
199 public ViewContext addLayer( int index, QualifiedName name, URL owsAddress, String type )
200 throws PortalException;
201
202 /**
203 * adds a layer to the defined index position of the layer list of a <code>ViewContext</code>.
204 * A layer may be a WMS layer, a WFS feature type or a WCS coverage.
205 *
206 * @param index
207 * index position where to insert the layer
208 * @param layer
209 * layer to add
210 * @return modified ViewContext
211 * @throws PortalException
212 * will be thrown if the layer already is registered to a ViewContext or the index
213 * is < 0 or > the number of layers -1;
214 */
215 public ViewContext addLayer( int index, Layer layer )
216 throws PortalException;
217
218 /**
219 * adds a number of layers provided by the passed OWS to the end of the layer list of a
220 * <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature type or a WCS
221 * coverage.
222 *
223 * @param names
224 * names of the layer
225 * @param owsAddresses
226 * addresses of the OWS's that serves the layer
227 * @param type
228 * OWS type (WCS, WMS or WFS)
229 * @return modified ViewContext
230 * @throws PortalException
231 * will be thrown if of the layers already is registered to a ViewContext or the OWS
232 * does not serves one the layers or the OWS does not serves one the layers or
233 * <code>names</names>
234 * and <code>owsAddresses</code> are not of the same size.
235 */
236 public ViewContext addLayers( QualifiedName[] names, URL[] owsAddresses, String type )
237 throws PortalException;
238
239 /**
240 * adds a number of layers to the end of the layer list of a <code>ViewContext</code>. A
241 * layer may be a WMS layer, a WFS feature type or a WCS coverage.
242 *
243 * @param layers
244 * layers to add
245 * @return modified ViewContext
246 * @throws PortalException
247 * will be thrown if of the layers already is registered to a ViewContext.
248 */
249 public ViewContext addLayers( Layer[] layers )
250 throws PortalException;
251
252 /**
253 * removes a named layer served by the passsed OWS from a <code>ViewContext</code>. if a
254 * layer with this name does not exist in a context, the unchanged <code>ViewContext</code>
255 * will be returned
256 *
257 * @param name
258 * name of the layer to be removed
259 * @param owsAddress
260 * address of the OWS that serves the layer
261 * @param type
262 * OWS type (WCS, WMS or WFS)
263 * @return modified ViewContext
264 */
265 public ViewContext removeLayer( QualifiedName name, URL owsAddress, String type );
266
267 /**
268 * swaps two layers in their order. The layer identified by the passed name and OWS can be moved
269 * up or down for one position. If a layer can not be moved up or down because it is already the
270 * top or bottom most layer the unchanged <code>ViewContext</code> will be returned
271 * <p>
272 * Notice: if to layers to be swaped are served by differend OWS at least one new image-layer
273 * must be created by the client.
274 * </p>
275 *
276 * @param name
277 * name of the layer to be moved up or down in the list
278 * @param owsAddress
279 * address of the OWS that serves the layer
280 * @param type
281 * OWS type (WCS, WMS or WFS)
282 * @param up
283 * true if layer should be moved up otherwise it will be moved down.
284 * @return modified ViewContext
285 * @throws PortalException
286 * will be thrown if the layer does not exists in a ViewContext.
287 */
288 public ViewContext swapLayers( QualifiedName name, URL owsAddress, String type, boolean up )
289 throws PortalException;
290
291 /**
292 * swaps to groups in their order
293 *
294 * @see MapModelAccess#swapLayers(QualifiedName, URL, String, boolean)
295 *
296 * @param name
297 * name of the group to be moved up or down
298 * @param up
299 * true if a group should be moved up otherwise it will be moved down.
300 * @return modified ViewContext
301 * @throws PortalException
302 * will be thrown if a group with the passed name does not exist in a ViewContext
303 */
304 public ViewContext swapGroups( QualifiedName name, boolean up )
305 throws PortalException;
306
307 /**
308 * sets the active style (style to be used for rendering) of a layer
309 *
310 * @param name
311 * name of the layer a style shall be set to
312 * @param owsAddress
313 * address of the OWS that serves this layer
314 * @param type
315 * OWS type (WCS, WMS or WFS)
316 * @param styleName
317 * name of the style to be assigned
318 * @return modified ViewContext
319 * @throws PortalException
320 * will be thrown if the layer or style are not known by a ViewContext or the style
321 * is not available for this layer
322 */
323 public ViewContext setLayerActiveStyle( QualifiedName name, URL owsAddress, String type, String styleName )
324 throws PortalException;
325
326 /**
327 * adds a named style to a layer to be available within a context.
328 *
329 * @param name
330 * name of the layer
331 * @param owsAddress
332 * address of the OWS that serves this layer
333 * @param type
334 * OWS type (WCS, WMS or WFS)
335 * @param styleName
336 * name of the style to be set
337 * @return modified ViewContext
338 * @throws PortalException
339 * will be thrown if the layer is not known by a ViewContext or the style is not
340 * available for this layer
341 */
342 public ViewContext addStyleToLayer( QualifiedName name, URL owsAddress, String type, String styleName )
343 throws PortalException;
344
345 /**
346 * removes a style from the layer defined in a ViewContext. If a style with passed named is not
347 * assigned to a layer the ViewContext will be returend unchanged.
348 *
349 * @param name
350 * name of the layer
351 * @param owsAddress
352 * address of the OWS that serves this layer
353 * @param type
354 * OWS type (WCS, WMS or WFS)
355 * @param styleName
356 * name of the style to be removed
357 * @return modified ViewContext
358 */
359 public ViewContext removeStyleFromLayer( QualifiedName name, URL owsAddress, String type, String styleName );
360
361 /**
362 * assignes a SLD document instead of a style to a layer. Usually this should be a SLD
363 * containing one named layer or one user layer and one user style. But it also will be possible
364 * to have a SLD with several layers (named layers as well as user layers). But this may cause
365 * some irritations so it should be avoided.
366 *
367 * @param name
368 * name of the layer the SLD should be assigned to
369 * @param owsAddress
370 * address of the OWS that serves this layer(s) if the SLD contains named layer(s).
371 * Otherwise the parameter can be <code>null</code>
372 * @param type
373 * OWS type (WCS, WMS or WFS)
374 * @param sld
375 * SLD that shall be assigned
376 * @return modified ViewContext
377 * @throws PortalException
378 * will be thrown if the layer is not known by a ViewContext or if the SLD contains
379 * a named layer but owsAddress is passed.
380 */
381 public ViewContext assignSLDToLayer( QualifiedName name, URL owsAddress, String type, StyledLayerDescriptor sld )
382 throws PortalException;
383
384 /**
385 * set a layer to be visible or invisible
386 *
387 * @param name
388 * name of the layer
389 * @param owsAddress
390 * address of the OWS that serves this layer
391 * @param type
392 * OWS type (WCS, WMS or WFS)
393 * @param visible
394 * <code>true</code> if a layer shall be visible; <code>false</code> if not.
395 * @return modified ViewContext
396 * @throws PortalException
397 * will be thrown if the layer is not known by a ViewContext.
398 *
399 */
400 public ViewContext setLayersVisible( String name, URL owsAddress, String type, boolean visible )
401 throws PortalException;
402
403 /**
404 * sets the CRS to be used by the map created from a ViewContext.
405 *
406 * @param crs
407 * name of the CRS e.g. EPSG:4326
408 * @return modified ViewContext
409 * @throws PortalException
410 * will be thrown if the CRS is not known by all layers available through a
411 * ViewContext
412 */
413 public ViewContext setMapCRS( String crs )
414 throws PortalException;
415
416 /**
417 * Adds a CRS to a layer if a ViewContext.
418 *
419 * @param name
420 * name of the layer
421 * @param owsAddress
422 * address of the OWS that serves this layer
423 * @param type
424 * OWS type (WCS, WMS or WFS)
425 * @param crsName
426 * name of the CRS to be added (e.g. EPSG:4326)
427 * @return modified ViewContext
428 * @throws PortalException
429 * will be thrown if the layer is not known by a ViewContext or the CRS is not
430 * supported for this layer/OWS
431 */
432 public ViewContext addCRSToLayer( String name, URL owsAddress, String type, String crsName )
433 throws PortalException;
434
435 /**
436 * removes a CRS from the list of availabe CRS of a layer. If the layer or the CRS does not
437 * exist in a ViewContext the ViewContext will be returned unchanged.
438 *
439 * @param name
440 * name of the layer
441 * @param owsAddress
442 * address of the OWS that serves this layer
443 * @param type
444 * OWS type (WCS, WMS or WFS)
445 * @param crsName
446 * name of the CRS to be removed from a layers CRS list
447 * @return modified ViewContext
448 */
449 public ViewContext removeCRSFromLayer( String name, URL owsAddress, String type, String crsName );
450
451 /**
452 * sets the bounding box a map/VieContext
453 *
454 * @param boundingBox
455 * new boundingbox
456 * @return modified ViewContext
457 * @throws ContextException
458 */
459 public ViewContext setMapBoundingBox( Envelope boundingBox )
460 throws ContextException;
461
462 /**
463 * sets the width and height of a map described by a ViewContext
464 *
465 * @param width
466 * map width measured in pixel
467 * @param height
468 * map height measured in pixel
469 * @return modified ViewContext
470 * @throws PortalException
471 * will be thrown if width or height < 1 (even a width or height of 1 pixel is not
472 * really useful but formal it is valid);
473 */
474 public ViewContext setMapSize( int width, int height )
475 throws PortalException;
476
477 /**
478 * zoom in or out of the map described by a ViewContext and recenters it to the passed point.
479 * <ul>
480 * <li>factor > 0: zoomout</li>
481 * <li>factor < 0: zoomin</li>
482 * <li>factor == 0: recenter</li>
483 * </ul>
484 *
485 * @param factor
486 * zoom factor in % of the boundingbox size
487 * @param point
488 * point (pixel coordinates) of the current map that marks the new center of the map
489 * @return modified ViewContext
490 * @throws ContextException
491 */
492 public ViewContext zoom( java.awt.Point point, double factor )
493 throws ContextException;
494
495 /**
496 * zoom in or out of the map described by a ViewContext and recenters it to the passed point.
497 * <ul>
498 * <li>factor > 0: zoomout</li>
499 * <li>factor < 0: zoomin</li>
500 * <li>factor == 0: recenter</li>
501 * </ul>
502 *
503 * @param factor
504 * zoom factor in % of the boundingbox size
505 * @param point
506 * point (map coordinates) of the current map that marks the new center of the map
507 * @return modified ViewContext
508 * @throws ContextException
509 */
510 public ViewContext zoom( Point point, double factor )
511 throws ContextException;
512
513 /**
514 * centers he map described by a ViewContext to the passed point. The behavior of this method is
515 * the same as
516 *
517 * @see #zoom(java.awt.Point, double) with a passed factor == 0;
518 *
519 * @param point
520 * point (pixel coordinates) of the current map that marks the new center of the map
521 * @return modified ViewContext
522 * @throws ContextException
523 */
524 public ViewContext recenterMap( java.awt.Point point )
525 throws ContextException;
526
527 /**
528 * centers he map described by a ViewContext to the passed point. The behavior of this method is
529 * the same as
530 *
531 * @see #zoom(Point, double) with a passed factor == 0;
532 *
533 * @param point
534 * point (map coordinates) of the current map that marks the new center of the map
535 * @return modified ViewContext
536 * @throws ContextException
537 */
538 public ViewContext recenterMap( Point point )
539 throws ContextException;
540
541 /**
542 * moves the boundingbox of the map to a well known direction. Directions that are known:
543 *
544 * @see #PAN_NORTH
545 * @see #PAN_NORTHEAST
546 * @see #PAN_NORTHWEST
547 * @see #PAN_SOUTH
548 * @see #PAN_SOUTHEAST
549 * @see #PAN_SOUTHWEST
550 * @see #PAN_WEST
551 * @see #PAN_EAST
552 * @param direction
553 * direction the map view shall be moved to
554 * @param factor
555 * factor measured in % the map view shall be moved
556 * @return modified ViewContext
557 * @throws PortalException
558 * will be thrown if passed direction is not valid or factor is <= 0
559 * @throws ContextException
560 */
561 public ViewContext pan( int direction, double factor )
562 throws PortalException, ContextException;
563
564 /**
565 * moves a map view to a free definable direction with a given factor
566 *
567 * @param directionDegree
568 * direction measured in degree that map view shall be moved to
569 * @param factor
570 * factor measured in % the map view shall be moved
571 * @return modified ViewContext
572 * @throws PortalException
573 * will be thrown if factor is <= 0
574 */
575 public ViewContext pan( double directionDegree, double factor )
576 throws PortalException;
577
578 /**
579 * sets the current image format a map shall be rendered. In theory OGC WMC specification allows
580 * rendering of each layer in a different image format but this seems to be very complicated,
581 * slow and not very useful, so deegree just supports one format for each OWS.
582 *
583 * @param mimeType
584 * image format
585 * @param owsAddress
586 * address of the OWS the format shall be used for
587 * @param type
588 * OWS type
589 * @return modified ViewContext
590 * @throws PortalException
591 * will be thrown if the passed mimeType is not suported by the passed OWS or one of
592 * its layers as defined in a ViewContext
593 */
594 public ViewContext setCurrentMapFormat( String mimeType, URL owsAddress, String type )
595 throws PortalException;
596
597 /**
598 * adds a new image format to a layer of a ViewContext. This method is useful because not every
599 * image format e.g.a WMS offers must be registered to be available through a Web Map Context.
600 *
601 * @param name
602 * name of the layer
603 * @param owsAddress
604 * address of the OWS
605 * @param type
606 * OWS type (WCS, WMS or WFS)
607 * @param mimeType
608 * new format to add to the layer
609 * @return modified ViewContext
610 * @throws PortalException
611 * will be thrown if the passed mimeType is not suported by the passed OWS
612 */
613 public ViewContext addFormatToLayer( String name, URL owsAddress, String type, String mimeType )
614 throws PortalException;
615
616 /**
617 * removes a format from a layer in a ViewContext.
618 *
619 * @see #addFormatToLayer(String, URL, String, String)
620 *
621 * @param name
622 * name of the layer
623 * @param owsAddress
624 * address of the OWS
625 * @param type
626 * OWS type (WCS, WMS or WFS)
627 * @param mimeType
628 * format to be removed
629 * @return modified ViewContext
630 * @throws PortalException
631 * will be thrown if the removed format is the current format of the layer.
632 */
633 public ViewContext removeFormatFromLayer( String name, URL owsAddress, String type, String mimeType )
634 throws PortalException;
635
636 /**
637 * groups a set of layers identified by their names, the address of the OWS that provides it und
638 * its type. A group has a name that must be unique and a parent that may is <code>null</code>.
639 * If no parent is given the group will be located underneath the root node.
640 *
641 * @param layers
642 * layers to be grouped.
643 * @param owsAddresses
644 * @param types
645 * @param groupName
646 * unique name of the group
647 * @param parentGroupName
648 * name of the parent group. may be <code>null</null>
649 * @return modified ViewContext
650 * @throws PortalException will be thrown if one of the layers is not served by
651 * the assigned OWS or a layer is already member of a
652 * group
653 */
654 public ViewContext groupLayers( String[] layers, URL[] owsAddresses, String[] types, String groupName,
655 String parentGroupName )
656 throws PortalException;
657
658 /**
659 * the difference to
660 *
661 * @see #groupLayers(String[], URL[], String[], String, String) is that the layers are
662 * identified by theri index position in a ViewContext
663 *
664 * @param first
665 * zero based index of the first layer to add to the group
666 * @param last
667 * zero based index of the last layer to add to the group
668 * @param groupName
669 * unique name of the group
670 * @param parentGroupName
671 * name of the parent group. may be <code>null</null>
672 * @return modified ViewContext
673 * @throws PortalException will be thrown if first or last is < 0 or larger
674 * than the total number of layers -1 or a layer is
675 * already member of a group
676 */
677 public ViewContext groupLayers( int first, int last, String groupName, String parentGroupName )
678 throws PortalException;
679
680 /**
681 * destroys a group. If a group with the passed name does not exist a ViewContext will be
682 * returned unchanged
683 *
684 * @param groupName
685 * name of the group to be removed
686 * @return modified ViewContext
687 */
688 public ViewContext destroyGroup( String groupName );
689
690 }