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