1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_container_XEnumerableMap_idl__
25#define __com_sun_star_container_XEnumerableMap_idl__
26
27#include <com/sun/star/container/XMap.idl>
28#include <com/sun/star/container/XEnumeration.idl>
29#include <com/sun/star/lang/NoSupportException.idl>
30
31//=============================================================================
32
33module com { module sun { module star { module container {
34
35//=============================================================================
36
37/** extends <type>XMap</type> with enumeration capabilities.
38
39    <p>No assumption should be made about the ordering of the elements returned by the various enumerators.
40    In particular, you cannot assume the elements are returned in the same order as they were inserted. Also,
41    you should not expect the <code>XMap</code> implementation to make use of a possibly existing strict ordering
42    defined on the domain of all possible key values.</p>
43
44    <p>You can create enumerators for the keys of the map, its values, and its key-value pairs.</p>
45
46    <p>In all cases, you can create an <em>isolated</em> enumerator, which works on a copy of the
47    map's content. Such an iterator is not affected by changes done to the map after creation of
48    the enumerator.</p>
49
50    <p>On the contrary, an enumerator which is <em>non-isolated</em> works directly on the map data.
51    This is less expensive than an <em>isolated</em> enumerator, but means that changes to the map while
52    an enumeration is running potentially invalidate your enumerator. The concrete behavior in this
53    case is undefined, it's up to the service implementing the <code>XEnumerableMap</code> interface
54    to specify it in more detail.</p>
55
56    <p>Implementations of this interface might decide to support only <em>isolated</em> enumerators, or
57    only <em>non-isolated</em> enumerators. Again, it's up to the service to specify this. Requesting an
58    enumerator type which is not supported will generally result in an <type scope="com::sun::star::lang">NoSupportException</type>
59    being thrown.</p>
60 */
61interface XEnumerableMap : XMap
62{
63    /** creates a enumerator for the keys of the map
64
65        @param Isolated
66            controls whether the newly create enumerator should be isolated from the map.
67
68        @throws ::com::sun::star::lang::NoSupportException
69            if the specified enumerator method is not supported by the implementation.
70    */
71    XEnumeration createKeyEnumeration( [in] boolean Isolated )
72        raises ( ::com::sun::star::lang::NoSupportException );
73
74    /** creates a enumerator for the values of the map
75
76        @param Isolated
77            controls whether the newly create enumerator should be isolated from the map.
78
79        @throws ::com::sun::star::lang::NoSupportException
80            if the specified enumerator method is not supported by the implementation.
81    */
82    XEnumeration createValueEnumeration( [in] boolean Isolated )
83        raises ( ::com::sun::star::lang::NoSupportException );
84
85    /** creates a enumerator for the key-value pairs of the map
86
87        <p>The elements returned by the enumerator are instances of <type scope="com::sun::star::beans">Pair</type>,
88        holding the key-value-pairs which are part of the map.</p>
89
90        @param Isolated
91            controls whether the newly create enumerator should be isolated from the map.
92
93        @throws ::com::sun::star::lang::NoSupportException
94            if the specified enumerator method is not supported by the implementation.
95    */
96    XEnumeration createElementEnumeration( [in] boolean Isolated )
97        raises ( ::com::sun::star::lang::NoSupportException );
98};
99
100//=============================================================================
101
102}; }; }; };
103
104//=============================================================================
105
106#endif
107