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