udkapi/com/sun/star/container/XEnumerableMap.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ***********************************************************************/
  27
  28 #ifndef __com_sun_star_container_XEnumerableMap_idl__
  29 #define __com_sun_star_container_XEnumerableMap_idl__
  30
  31 #include <com/sun/star/container/XMap.idl>
  32 #include <com/sun/star/container/XEnumeration.idl>
  33 #include <com/sun/star/lang/NoSupportException.idl>
  34
  35 //=============================================================================
  36
  37 module com { module sun { module star { module container {
  38
  39 //=============================================================================
  40
  41 /** extends <type>XMap</type> with enumeration capabilities.
  42
  43     <p>No assumption should be made about the ordering of the elements returned by the various enumerators.
  44     In particular, you cannot assume the elements are returned in the same order as they were inserted. Also,
  45     you should not expect the <code>XMap</code> implementation to make use of a possibly existing strict ordering
  46     defined on the domain of all possible key values.</p>
  47
  48     <p>You can create enumerators for the keys of the map, its values, and its key-value pairs.</p>
  49
  50     <p>In all cases, you can create an <em>isolated</em> enumerator, which works on a copy of the
  51     map's content. Such an iterator is not affected by changes done to the map after creation of
  52     the enumerator.</p>
  53
  54     <p>On the contrary, an enumerator which is <em>non-isolated</em> works directly on the map data.
  55     This is less expensive than an <em>isolated</em> enumerator, but means that changes to the map while
  56     an enumeration is running potentially invalidate your enumerator. The concrete behavior in this
  57     case is undefined, it's up to the service implementing the <code>XEnumerableMap</code> interface
  58     to specify it in more detail.</p>
  59
  60     <p>Implementations of this interface might decide to support only <em>isolated</em> enumerators, or
  61     only <em>non-isolated</em> enumerators. Again, it's up to the service to specify this. Requesting an
  62     enumerator type which is not supported will generally result in an <type scope="com::sun::star::lang">NoSupportException</type>
  63     being thrown.</p>
  64  */
  65 interface XEnumerableMap : XMap
  66 {
  67     /** creates a enumerator for the keys of the map
  68
  69         @param Isolated
  70             controls whether the newly create enumerator should be isolated from the map.
  71
  72         @throws ::com::sun::star::lang::NoSupportException
  73             if the specified enumerator method is not supported by the implementation.
  74     */
  75     XEnumeration createKeyEnumeration( [in] boolean Isolated )
  76         raises ( ::com::sun::star::lang::NoSupportException );
  77
  78     /** creates a enumerator for the values of the map
  79
  80         @param Isolated
  81             controls whether the newly create enumerator should be isolated from the map.
  82
  83         @throws ::com::sun::star::lang::NoSupportException
  84             if the specified enumerator method is not supported by the implementation.
  85     */
  86     XEnumeration createValueEnumeration( [in] boolean Isolated )
  87         raises ( ::com::sun::star::lang::NoSupportException );
  88
  89     /** creates a enumerator for the key-value pairs of the map
  90
  91         <p>The elements returned by the enumerator are instances of <type scope="com::sun::star::beans">Pair</type>,
  92         holding the key-value-pairs which are part of the map.</p>
  93
  94         @param Isolated
  95             controls whether the newly create enumerator should be isolated from the map.
  96
  97         @throws ::com::sun::star::lang::NoSupportException
  98             if the specified enumerator method is not supported by the implementation.
  99     */
 100     XEnumeration createElementEnumeration( [in] boolean Isolated )
 101         raises ( ::com::sun::star::lang::NoSupportException );
 102 };
 103
 104 //=============================================================================
 105
 106 }; }; }; };
 107
 108 //=============================================================================
 109
 110 #endif