    001    //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/branches/2.4_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    }