udkapi/com/sun/star/container/EnumerableMap.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_Map_idl__
  29 #define __com_sun_star_container_Map_idl__
  30
  31 #include <com/sun/star/beans/IllegalTypeException.idl>
  32 #include <com/sun/star/beans/Pair.idl>
  33 #include <com/sun/star/container/XEnumerableMap.idl>
  34
  35 //=============================================================================
  36
  37 module com { module sun { module star { module container {
  38
  39 //=============================================================================
  40
  41 /** provides a default <type>XEnumerableMap</type> implementation
  42
  43     <p>For the keys put into the map using <member>XMap::put</member> or <member>createImmutable</member>,
  44     the following rules apply:
  45     <a name="keyrules"></a>
  46     <ul><li>A <VOID/> key is not allowed.</li>
  47         <li>If the key type is <code>BOOLEAN</code>, <code>CHAR</code>, <code>FLOAT</code>, <code>DOUBLE</code>,
  48             <code>STRING</code>, <code>TYPE</code>, or <code>UNSIGNED HYPER</code>, then only keys of exactly this
  49             type are accepted.</li>
  50         <li>If the key type is <code>DOUBLE</code> or <code>FLOAT</code>, then <code>Double.NaN</code> respectively
  51             <code>Float.NaN</code> is not accepted as key.</li>
  52         <li>If the key type's class is <member scope="com::sun::star::uno">TypeClass::ENUM</member>, then only keys
  53             of exactly this type are accepted.</li>
  54         <li>If the key type is any of <code>BYTE</code>, <code>SHORT</code>, <code>UNSIGNED SHORT</code>,
  55             <code>LONG</code>, <code>UNSIGNED LONG</code>, or <code>HYPER</code>, then all keys which can losslessly
  56             be converted to this type (possibly using widening conversions) are accepted.</li>
  57         <li>If the key type is an interface type, then all key values denoting objects which can be queried for
  58             the given interface are accepted.</li>
  59         <li>All other key types are rejected.</li>
  60     </ul></p>
  61
  62     <p>For the values put into the map using <member>XMap::put</member> or <member>createImmutable</member>,
  63     the following rules apply:
  64     <a name="valuerules"></a>
  65     <ul><li>The <VOID/> value will be accepted to be put into the map.</p>
  66         <li>If the value type's class is <member scope="com::sun::star::uno">TypeClass::ANY</member>, any value
  67             will be accepted.</li>
  68         <li>If the value type is an interface type, then all values denoting objects which can be queried for
  69             the given interface are accepted.</li>
  70         <li>If the value type's class is <member scope="com::sun::star::uno">TypeClass::EXCEPTION</member>
  71             or <member scope="com::sun::star::uno">TypeClass::STRUCT</member>, then values whose type equals the
  72             value type, or is a sub class of the value type, are accepted.</li>
  73         <li>For all other value types, only values whose type matches exactly are accepted.</li>
  74         <li>If the value type is <code>DOUBLE</code> or <code>FLOAT</code>, then <code>Double.NaN</code> respectively
  75             <code>Float.NaN</code> is not accepted.</li>
  76     </ul></p>
  77
  78     <p>The factory methods of the <code>XEnumerableMap</code> interface support both <em>isolated</em>
  79     and <em>non-isolated</em> enumerators. The latter one will be automatically disposed when the map changes
  80     after enumerator creation, so every attempt to use them will result in a
  81     <type scope="com::sun::star::lang">DisposedException</type> being thrown.</p>
  82
  83     @see http://udk.openoffice.org/common/man/typesystem.html
  84 */
  85 service EnumerableMap : XEnumerableMap
  86 {
  87     /** creates an instance mapping from the given key type to the given value type
  88
  89         @param KeyType
  90             denotes the type of the keys in the to-be-created map
  91         @param ValueType
  92             denotes the type of the values in the to-be-created map
  93
  94         @throws ::com::sun::star::beans::IllegalTypeException
  95             if <arg>KeyType</arg> or <arg>ValueType</arg> are unsupported types.
  96             For values, all type classes except <member scope="com::sun::star::uno">TypeClass::VOID</member>
  97             and <member scope="com::sun::star::uno">TypeClass::UNKNOWN</member> are accepted.
  98             For keys, scalar types, strings, <type scope="com::sun::star::uno">Type</type> itself, and interface
  99             types are accepted.
 100     */
 101     create( [in] type KeyType, [in] type ValueType )
 102         raises( ::com::sun::star::beans::IllegalTypeException );
 103
 104     /** creates an instance mapping from the given key type to the given value type
 105
 106         <p>The resulting map is immutable, so later alter operations on it will fail
 107         with a <type scope="com::sun::star::lang">NoSupportException</type>.</p>
 108
 109         @param KeyType
 110             denotes the type of the keys in the to-be-created map
 111         @param ValueType
 112             denotes the type of the values in the to-be-created map
 113         @param Values
 114             denote the values contained in the to-be-created map
 115
 116         @throws ::com::sun::star::beans::IllegalTypeException
 117             if <arg>KeyType</arg> or <arg>ValueType</arg> are unsupported types.
 118             For values, all type classes except <member scope="com::sun::star::uno">TypeClass::VOID</member>
 119             are accepted.<br/>
 120             For keys, scalar types, strings, <type scope="com::sun::star::uno">Type</type> itself, and interface
 121             types are accepted.
 122         @throws ::com::sun::star::lang::IllegalArgumentException
 123             if any of the given values or keys violates the <a href="#keyrules">key rules</a> or
 124             <a href="#valuerules">value rules</a>.
 125     */
 126     createImmutable(
 127         [in] type KeyType,
 128         [in] type ValueType,
 129         [in] sequence< ::com::sun::star::beans::Pair< any, any > > Values
 130     )
 131         raises( ::com::sun::star::beans::IllegalTypeException,
 132                 ::com::sun::star::lang::IllegalArgumentException );
 133 };
 134
 135 //=============================================================================
 136
 137 }; }; }; };
 138
 139 //=============================================================================
 140
 141 #endif