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

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