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 &lt; 0 or &gt; 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 &lt; 0 or &gt; 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    }