001: //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/trunk/src/org/deegree/portal/context/MapModelAccess.java $
002: /*---------------- FILE HEADER ------------------------------------------
003:
004: This file is part of deegree.
005: Copyright (C) 2001-2008 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: 10575 $ $Date: 2008-03-13 02:55:11 -0700 (Thu, 13 Mar 2008) $
079: *
080: */
081: public interface MapModelAccess {
082:
083: /**
084: * The pan north constant.
085: */
086: int PAN_NORTH = 0;
087:
088: /**
089: * The pan north east constant.
090: */
091: int PAN_NORTHEAST = 1;
092:
093: /**
094: * The pan north west constant.
095: */
096: int PAN_NORTHWEST = 2;
097:
098: /**
099: * The pan south constant.
100: */
101: int PAN_SOUTH = 3;
102:
103: /**
104: * The pan south east constant.
105: */
106: int PAN_SOUTHEAST = 4;
107:
108: /**
109: * The pan south west constant.
110: */
111: int PAN_SOUTHWEST = 5;
112:
113: /**
114: * The pan west constant.
115: */
116: int PAN_WEST = 6;
117:
118: /**
119: * The pan east constant.
120: */
121: int PAN_EAST = 7;
122:
123: /**
124: * sets the layers provided by the passed OWS to a <code>ViewContext</code>. A layer may be a
125: * WMS layer, a WFS feature type or a WCS coverage.
126: *
127: * @param names
128: * names of the layer
129: * @param owsAddresses
130: * addresses of the OWS that serves the layer. each passed layername is assigned to
131: * the OWS URL at the same index position.
132: * @param type
133: * OWS type (WCS, WMS or WFS)
134: * @return modified ViewContext
135: * @throws PortalException
136: * will be thrown if of the layers already is registered to a ViewContext or the OWS
137: * does not serves one the layers or <code>names</names>
138: * and <code>owsAddresses</code> are not of the same size.
139: */
140: public ViewContext setLayers(QualifiedName[] names,
141: URL[] owsAddresses, String type) throws PortalException;
142:
143: /**
144: * sets the layers to a <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature
145: * type or a WCS coverage.
146: *
147: * @param layers
148: * layers to add
149: * @return modified ViewContext
150: * @throws PortalException
151: * will be thrown if of the layers already is registered to a ViewContext.
152: */
153: public ViewContext setLayers(Layer[] layers) throws PortalException;
154:
155: /**
156: * adds a layer provided by the passed OWS to the end of the layer list of a
157: * <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature type or a WCS
158: * coverage.
159: *
160: * @param name
161: * name of the layer
162: * @param owsAddress
163: * address of the OWS that serves the layer
164: * @param type
165: * OWS type (WCS, WMS or WFS)
166: * @exception PortalException
167: * will be thrown if the layer already is registered to a ViewContext or the OWS
168: * does not serves a layer with this name.
169: * @return modified ViewContext
170: */
171: public ViewContext addLayer(QualifiedName name, URL owsAddress,
172: String type) throws PortalException;
173:
174: /**
175: * adds a layer to the end of the layer list of a <code>ViewContext</code>. A layer may be a
176: * WMS layer, a WFS feature type or a WCS coverage.
177: *
178: * @param layer
179: * layer to add
180: * @throws PortalException
181: * will be thrown if the layer already is registered to a ViewContext.
182: * @return modified ViewContext
183: */
184: public ViewContext addLayer(Layer layer) throws PortalException;
185:
186: /**
187: * adds a layer provided by the passed OWS to the defined index position of the layer list of a
188: * <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature type or a WCS
189: * coverage.
190: *
191: * @param index
192: * index position where to insert the layer
193: * @param name
194: * name of the layer
195: * @param owsAddress
196: * address of the OWS that serves the layer
197: * @param type
198: * OWS type (WCS, WMS or WFS)
199: * @throws PortalException
200: * will be thrown if the layer already is registered to a ViewContext or the OWS
201: * does not serves a layer with this name or the index is < 0 or > the number
202: * of layers -1;
203: * @return modified ViewContext
204: */
205: public ViewContext addLayer(int index, QualifiedName name,
206: URL owsAddress, String type) throws PortalException;
207:
208: /**
209: * adds a layer to the defined index position of the layer list of a <code>ViewContext</code>.
210: * A layer may be a WMS layer, a WFS feature type or a WCS coverage.
211: *
212: * @param index
213: * index position where to insert the layer
214: * @param layer
215: * layer to add
216: * @return modified ViewContext
217: * @throws PortalException
218: * will be thrown if the layer already is registered to a ViewContext or the index
219: * is < 0 or > the number of layers -1;
220: */
221: public ViewContext addLayer(int index, Layer layer)
222: throws PortalException;
223:
224: /**
225: * adds a number of layers provided by the passed OWS to the end of the layer list of a
226: * <code>ViewContext</code>. A layer may be a WMS layer, a WFS feature type or a WCS
227: * coverage.
228: *
229: * @param names
230: * names of the layer
231: * @param owsAddresses
232: * addresses of the OWS's that serves the layer
233: * @param type
234: * OWS type (WCS, WMS or WFS)
235: * @return modified ViewContext
236: * @throws PortalException
237: * will be thrown if of the layers already is registered to a ViewContext or the OWS
238: * does not serves one the layers or the OWS does not serves one the layers or
239: * <code>names</names>
240: * and <code>owsAddresses</code> are not of the same size.
241: */
242: public ViewContext addLayers(QualifiedName[] names,
243: URL[] owsAddresses, String type) throws PortalException;
244:
245: /**
246: * adds a number of layers to the end of the layer list of a <code>ViewContext</code>. A
247: * layer may be a WMS layer, a WFS feature type or a WCS coverage.
248: *
249: * @param layers
250: * layers to add
251: * @return modified ViewContext
252: * @throws PortalException
253: * will be thrown if of the layers already is registered to a ViewContext.
254: */
255: public ViewContext addLayers(Layer[] layers) throws PortalException;
256:
257: /**
258: * removes a named layer served by the passsed OWS from a <code>ViewContext</code>. if a
259: * layer with this name does not exist in a context, the unchanged <code>ViewContext</code>
260: * will be returned
261: *
262: * @param name
263: * name of the layer to be removed
264: * @param owsAddress
265: * address of the OWS that serves the layer
266: * @param type
267: * OWS type (WCS, WMS or WFS)
268: * @return modified ViewContext
269: */
270: public ViewContext removeLayer(QualifiedName name, URL owsAddress,
271: String type);
272:
273: /**
274: * swaps two layers in their order. The layer identified by the passed name and OWS can be moved
275: * up or down for one position. If a layer can not be moved up or down because it is already the
276: * top or bottom most layer the unchanged <code>ViewContext</code> will be returned
277: * <p>
278: * Notice: if to layers to be swaped are served by differend OWS at least one new image-layer
279: * must be created by the client.
280: * </p>
281: *
282: * @param name
283: * name of the layer to be moved up or down in the list
284: * @param owsAddress
285: * address of the OWS that serves the layer
286: * @param type
287: * OWS type (WCS, WMS or WFS)
288: * @param up
289: * true if layer should be moved up otherwise it will be moved down.
290: * @return modified ViewContext
291: * @throws PortalException
292: * will be thrown if the layer does not exists in a ViewContext.
293: */
294: public ViewContext swapLayers(QualifiedName name, URL owsAddress,
295: String type, boolean up) throws PortalException;
296:
297: /**
298: * swaps to groups in their order
299: *
300: * @see MapModelAccess#swapLayers(QualifiedName, URL, String, boolean)
301: *
302: * @param name
303: * name of the group to be moved up or down
304: * @param up
305: * true if a group should be moved up otherwise it will be moved down.
306: * @return modified ViewContext
307: * @throws PortalException
308: * will be thrown if a group with the passed name does not exist in a ViewContext
309: */
310: public ViewContext swapGroups(QualifiedName name, boolean up)
311: throws PortalException;
312:
313: /**
314: * sets the active style (style to be used for rendering) of a layer
315: *
316: * @param name
317: * name of the layer a style shall be set to
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 assigned
324: * @return modified ViewContext
325: * @throws PortalException
326: * will be thrown if the layer or style are not known by a ViewContext or the style
327: * is not available for this layer
328: */
329: public ViewContext setLayerActiveStyle(QualifiedName name,
330: URL owsAddress, String type, String styleName)
331: throws PortalException;
332:
333: /**
334: * adds a named style to a layer to be available within a context.
335: *
336: * @param name
337: * name of the layer
338: * @param owsAddress
339: * address of the OWS that serves this layer
340: * @param type
341: * OWS type (WCS, WMS or WFS)
342: * @param styleName
343: * name of the style to be set
344: * @return modified ViewContext
345: * @throws PortalException
346: * will be thrown if the layer is not known by a ViewContext or the style is not
347: * available for this layer
348: */
349: public ViewContext addStyleToLayer(QualifiedName name,
350: URL owsAddress, String type, String styleName)
351: throws PortalException;
352:
353: /**
354: * removes a style from the layer defined in a ViewContext. If a style with passed named is not
355: * assigned to a layer the ViewContext will be returend unchanged.
356: *
357: * @param name
358: * name of the layer
359: * @param owsAddress
360: * address of the OWS that serves this layer
361: * @param type
362: * OWS type (WCS, WMS or WFS)
363: * @param styleName
364: * name of the style to be removed
365: * @return modified ViewContext
366: */
367: public ViewContext removeStyleFromLayer(QualifiedName name,
368: URL owsAddress, String type, String styleName);
369:
370: /**
371: * assignes a SLD document instead of a style to a layer. Usually this should be a SLD
372: * containing one named layer or one user layer and one user style. But it also will be possible
373: * to have a SLD with several layers (named layers as well as user layers). But this may cause
374: * some irritations so it should be avoided.
375: *
376: * @param name
377: * name of the layer the SLD should be assigned to
378: * @param owsAddress
379: * address of the OWS that serves this layer(s) if the SLD contains named layer(s).
380: * Otherwise the parameter can be <code>null</code>
381: * @param type
382: * OWS type (WCS, WMS or WFS)
383: * @param sld
384: * SLD that shall be assigned
385: * @return modified ViewContext
386: * @throws PortalException
387: * will be thrown if the layer is not known by a ViewContext or if the SLD contains
388: * a named layer but owsAddress is passed.
389: */
390: public ViewContext assignSLDToLayer(QualifiedName name,
391: URL owsAddress, String type, StyledLayerDescriptor sld)
392: throws PortalException;
393:
394: /**
395: * set a layer to be visible or invisible
396: *
397: * @param name
398: * name of the layer
399: * @param owsAddress
400: * address of the OWS that serves this layer
401: * @param type
402: * OWS type (WCS, WMS or WFS)
403: * @param visible
404: * <code>true</code> if a layer shall be visible; <code>false</code> if not.
405: * @return modified ViewContext
406: * @throws PortalException
407: * will be thrown if the layer is not known by a ViewContext.
408: *
409: */
410: public ViewContext setLayersVisible(String name, URL owsAddress,
411: String type, boolean visible) throws PortalException;
412:
413: /**
414: * sets the CRS to be used by the map created from a ViewContext.
415: *
416: * @param crs
417: * name of the CRS e.g. EPSG:4326
418: * @return modified ViewContext
419: * @throws PortalException
420: * will be thrown if the CRS is not known by all layers available through a
421: * ViewContext
422: */
423: public ViewContext setMapCRS(String crs) throws PortalException;
424:
425: /**
426: * Adds a CRS to a layer if a ViewContext.
427: *
428: * @param name
429: * name of the layer
430: * @param owsAddress
431: * address of the OWS that serves this layer
432: * @param type
433: * OWS type (WCS, WMS or WFS)
434: * @param crsName
435: * name of the CRS to be added (e.g. EPSG:4326)
436: * @return modified ViewContext
437: * @throws PortalException
438: * will be thrown if the layer is not known by a ViewContext or the CRS is not
439: * supported for this layer/OWS
440: */
441: public ViewContext addCRSToLayer(String name, URL owsAddress,
442: String type, String crsName) throws PortalException;
443:
444: /**
445: * removes a CRS from the list of availabe CRS of a layer. If the layer or the CRS does not
446: * exist in a ViewContext the ViewContext will be returned unchanged.
447: *
448: * @param name
449: * name of the layer
450: * @param owsAddress
451: * address of the OWS that serves this layer
452: * @param type
453: * OWS type (WCS, WMS or WFS)
454: * @param crsName
455: * name of the CRS to be removed from a layers CRS list
456: * @return modified ViewContext
457: */
458: public ViewContext removeCRSFromLayer(String name, URL owsAddress,
459: String type, String crsName);
460:
461: /**
462: * sets the bounding box a map/VieContext
463: *
464: * @param boundingBox
465: * new boundingbox
466: * @return modified ViewContext
467: * @throws ContextException
468: */
469: public ViewContext setMapBoundingBox(Envelope boundingBox)
470: throws ContextException;
471:
472: /**
473: * sets the width and height of a map described by a ViewContext
474: *
475: * @param width
476: * map width measured in pixel
477: * @param height
478: * map height measured in pixel
479: * @return modified ViewContext
480: * @throws PortalException
481: * will be thrown if width or height < 1 (even a width or height of 1 pixel is not
482: * really useful but formal it is valid);
483: */
484: public ViewContext setMapSize(int width, int height)
485: throws PortalException;
486:
487: /**
488: * zoom in or out of the map described by a ViewContext and recenters it to the passed point.
489: * <ul>
490: * <li>factor > 0: zoomout</li>
491: * <li>factor < 0: zoomin</li>
492: * <li>factor == 0: recenter</li>
493: * </ul>
494: *
495: * @param factor
496: * zoom factor in % of the boundingbox size
497: * @param point
498: * point (pixel coordinates) of the current map that marks the new center of the map
499: * @return modified ViewContext
500: * @throws ContextException
501: */
502: public ViewContext zoom(java.awt.Point point, double factor)
503: throws ContextException;
504:
505: /**
506: * zoom in or out of the map described by a ViewContext and recenters it to the passed point.
507: * <ul>
508: * <li>factor > 0: zoomout</li>
509: * <li>factor < 0: zoomin</li>
510: * <li>factor == 0: recenter</li>
511: * </ul>
512: *
513: * @param factor
514: * zoom factor in % of the boundingbox size
515: * @param point
516: * point (map coordinates) of the current map that marks the new center of the map
517: * @return modified ViewContext
518: * @throws ContextException
519: */
520: public ViewContext zoom(Point point, double factor)
521: throws ContextException;
522:
523: /**
524: * centers he map described by a ViewContext to the passed point. The behavior of this method is
525: * the same as
526: *
527: * @see #zoom(java.awt.Point, double) with a passed factor == 0;
528: *
529: * @param point
530: * point (pixel coordinates) of the current map that marks the new center of the map
531: * @return modified ViewContext
532: * @throws ContextException
533: */
534: public ViewContext recenterMap(java.awt.Point point)
535: throws ContextException;
536:
537: /**
538: * centers he map described by a ViewContext to the passed point. The behavior of this method is
539: * the same as
540: *
541: * @see #zoom(Point, double) with a passed factor == 0;
542: *
543: * @param point
544: * point (map coordinates) of the current map that marks the new center of the map
545: * @return modified ViewContext
546: * @throws ContextException
547: */
548: public ViewContext recenterMap(Point point) throws ContextException;
549:
550: /**
551: * moves the boundingbox of the map to a well known direction. Directions that are known:
552: * @see #PAN_NORTH
553: * @see #PAN_NORTHEAST
554: * @see #PAN_NORTHWEST
555: * @see #PAN_SOUTH
556: * @see #PAN_SOUTHEAST
557: * @see #PAN_SOUTHWEST
558: * @see #PAN_WEST
559: * @see #PAN_EAST
560: * @param direction
561: * direction the map view shall be moved to
562: * @param factor
563: * factor measured in % the map view shall be moved
564: * @return modified ViewContext
565: * @throws PortalException
566: * will be thrown if passed direction is not valid or factor is <= 0
567: * @throws ContextException
568: */
569: public ViewContext pan(int direction, double factor)
570: throws PortalException, ContextException;
571:
572: /**
573: * moves a map view to a free definable direction with a given factor
574: *
575: * @param directionDegree
576: * direction measured in degree that map view shall be moved to
577: * @param factor
578: * factor measured in % the map view shall be moved
579: * @return modified ViewContext
580: * @throws PortalException
581: * will be thrown if factor is <= 0
582: */
583: public ViewContext pan(double directionDegree, double factor)
584: throws PortalException;
585:
586: /**
587: * sets the current image format a map shall be rendered. In theory OGC WMC specification allows
588: * rendering of each layer in a different image format but this seems to be very complicated,
589: * slow and not very useful, so deegree just supports one format for each OWS.
590: *
591: * @param mimeType
592: * image format
593: * @param owsAddress
594: * address of the OWS the format shall be used for
595: * @param type
596: * OWS type
597: * @return modified ViewContext
598: * @throws PortalException
599: * will be thrown if the passed mimeType is not suported by the passed OWS or one of
600: * its layers as defined in a ViewContext
601: */
602: public ViewContext setCurrentMapFormat(String mimeType,
603: URL owsAddress, String type) throws PortalException;
604:
605: /**
606: * adds a new image format to a layer of a ViewContext. This method is useful because not every
607: * image format e.g.a WMS offers must be registered to be available through a Web Map Context.
608: *
609: * @param name
610: * name of the layer
611: * @param owsAddress
612: * address of the OWS
613: * @param type
614: * OWS type (WCS, WMS or WFS)
615: * @param mimeType
616: * new format to add to the layer
617: * @return modified ViewContext
618: * @throws PortalException
619: * will be thrown if the passed mimeType is not suported by the passed OWS
620: */
621: public ViewContext addFormatToLayer(String name, URL owsAddress,
622: String type, String mimeType) throws PortalException;
623:
624: /**
625: * removes a format from a layer in a ViewContext.
626: *
627: * @see #addFormatToLayer(String, URL, String, String)
628: *
629: * @param name
630: * name of the layer
631: * @param owsAddress
632: * address of the OWS
633: * @param type
634: * OWS type (WCS, WMS or WFS)
635: * @param mimeType
636: * format to be removed
637: * @return modified ViewContext
638: * @throws PortalException
639: * will be thrown if the removed format is the current format of the layer.
640: */
641: public ViewContext removeFormatFromLayer(String name,
642: URL owsAddress, String type, String mimeType)
643: throws PortalException;
644:
645: /**
646: * groups a set of layers identified by their names, the address of the OWS that provides it und
647: * its type. A group has a name that must be unique and a parent that may is <code>null</code>.
648: * If no parent is given the group will be located underneath the root node.
649: *
650: * @param layers
651: * layers to be grouped.
652: * @param owsAddresses
653: * @param types
654: * @param groupName
655: * unique name of the group
656: * @param parentGroupName
657: * name of the parent group. may be <code>null</null>
658: * @return modified ViewContext
659: * @throws PortalException will be thrown if one of the layers is not served by
660: * the assigned OWS or a layer is already member of a
661: * group
662: */
663: public ViewContext groupLayers(String[] layers, URL[] owsAddresses,
664: String[] types, String groupName, String parentGroupName)
665: throws PortalException;
666:
667: /**
668: * the difference to
669: *
670: * @see #groupLayers(String[], URL[], String[], String, String) is that the layers are
671: * identified by theri index position in a ViewContext
672: *
673: * @param first
674: * zero based index of the first layer to add to the group
675: * @param last
676: * zero based index of the last layer to add to the group
677: * @param groupName
678: * unique name of the group
679: * @param parentGroupName
680: * name of the parent group. may be <code>null</null>
681: * @return modified ViewContext
682: * @throws PortalException will be thrown if first or last is < 0 or larger
683: * than the total number of layers -1 or a layer is
684: * already member of a group
685: */
686: public ViewContext groupLayers(int first, int last,
687: String groupName, String parentGroupName)
688: throws PortalException;
689:
690: /**
691: * destroys a group. If a group with the passed name does not exist a ViewContext will be
692: * returned unchanged
693: *
694: * @param groupName
695: * name of the group to be removed
696: * @return modified ViewContext
697: */
698: public ViewContext destroyGroup(String groupName);
699:
700: }
|