1*408a4873SAndrew Rist/************************************************************** 2cdf0e10cSrcweir * 3*408a4873SAndrew Rist * Licensed to the Apache Software Foundation (ASF) under one 4*408a4873SAndrew Rist * or more contributor license agreements. See the NOTICE file 5*408a4873SAndrew Rist * distributed with this work for additional information 6*408a4873SAndrew Rist * regarding copyright ownership. The ASF licenses this file 7*408a4873SAndrew Rist * to you under the Apache License, Version 2.0 (the 8*408a4873SAndrew Rist * "License"); you may not use this file except in compliance 9*408a4873SAndrew Rist * with the License. You may obtain a copy of the License at 10*408a4873SAndrew Rist * 11*408a4873SAndrew Rist * http://www.apache.org/licenses/LICENSE-2.0 12*408a4873SAndrew Rist * 13*408a4873SAndrew Rist * Unless required by applicable law or agreed to in writing, 14*408a4873SAndrew Rist * software distributed under the License is distributed on an 15*408a4873SAndrew Rist * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16*408a4873SAndrew Rist * KIND, either express or implied. See the License for the 17*408a4873SAndrew Rist * specific language governing permissions and limitations 18*408a4873SAndrew Rist * under the License. 19*408a4873SAndrew Rist * 20*408a4873SAndrew Rist *************************************************************/ 21*408a4873SAndrew Rist 22*408a4873SAndrew Rist 23cdf0e10cSrcweir 24cdf0e10cSrcweir#ifndef __com_sun_star_container_Map_idl__ 25cdf0e10cSrcweir#define __com_sun_star_container_Map_idl__ 26cdf0e10cSrcweir 27cdf0e10cSrcweir#include <com/sun/star/beans/IllegalTypeException.idl> 28cdf0e10cSrcweir#include <com/sun/star/beans/Pair.idl> 29cdf0e10cSrcweir#include <com/sun/star/container/XEnumerableMap.idl> 30cdf0e10cSrcweir 31cdf0e10cSrcweir//============================================================================= 32cdf0e10cSrcweir 33cdf0e10cSrcweirmodule com { module sun { module star { module container { 34cdf0e10cSrcweir 35cdf0e10cSrcweir//============================================================================= 36cdf0e10cSrcweir 37cdf0e10cSrcweir/** provides a default <type>XEnumerableMap</type> implementation 38cdf0e10cSrcweir 39cdf0e10cSrcweir <p>For the keys put into the map using <member>XMap::put</member> or <member>createImmutable</member>, 40cdf0e10cSrcweir the following rules apply: 41cdf0e10cSrcweir <a name="keyrules"></a> 42cdf0e10cSrcweir <ul><li>A <VOID/> key is not allowed.</li> 43cdf0e10cSrcweir <li>If the key type is <code>BOOLEAN</code>, <code>CHAR</code>, <code>FLOAT</code>, <code>DOUBLE</code>, 44cdf0e10cSrcweir <code>STRING</code>, <code>TYPE</code>, or <code>UNSIGNED HYPER</code>, then only keys of exactly this 45cdf0e10cSrcweir type are accepted.</li> 46cdf0e10cSrcweir <li>If the key type is <code>DOUBLE</code> or <code>FLOAT</code>, then <code>Double.NaN</code> respectively 47cdf0e10cSrcweir <code>Float.NaN</code> is not accepted as key.</li> 48cdf0e10cSrcweir <li>If the key type's class is <member scope="com::sun::star::uno">TypeClass::ENUM</member>, then only keys 49cdf0e10cSrcweir of exactly this type are accepted.</li> 50cdf0e10cSrcweir <li>If the key type is any of <code>BYTE</code>, <code>SHORT</code>, <code>UNSIGNED SHORT</code>, 51cdf0e10cSrcweir <code>LONG</code>, <code>UNSIGNED LONG</code>, or <code>HYPER</code>, then all keys which can losslessly 52cdf0e10cSrcweir be converted to this type (possibly using widening conversions) are accepted.</li> 53cdf0e10cSrcweir <li>If the key type is an interface type, then all key values denoting objects which can be queried for 54cdf0e10cSrcweir the given interface are accepted.</li> 55cdf0e10cSrcweir <li>All other key types are rejected.</li> 56cdf0e10cSrcweir </ul></p> 57cdf0e10cSrcweir 58cdf0e10cSrcweir <p>For the values put into the map using <member>XMap::put</member> or <member>createImmutable</member>, 59cdf0e10cSrcweir the following rules apply: 60cdf0e10cSrcweir <a name="valuerules"></a> 61cdf0e10cSrcweir <ul><li>The <VOID/> value will be accepted to be put into the map.</p> 62cdf0e10cSrcweir <li>If the value type's class is <member scope="com::sun::star::uno">TypeClass::ANY</member>, any value 63cdf0e10cSrcweir will be accepted.</li> 64cdf0e10cSrcweir <li>If the value type is an interface type, then all values denoting objects which can be queried for 65cdf0e10cSrcweir the given interface are accepted.</li> 66cdf0e10cSrcweir <li>If the value type's class is <member scope="com::sun::star::uno">TypeClass::EXCEPTION</member> 67cdf0e10cSrcweir or <member scope="com::sun::star::uno">TypeClass::STRUCT</member>, then values whose type equals the 68cdf0e10cSrcweir value type, or is a sub class of the value type, are accepted.</li> 69cdf0e10cSrcweir <li>For all other value types, only values whose type matches exactly are accepted.</li> 70cdf0e10cSrcweir <li>If the value type is <code>DOUBLE</code> or <code>FLOAT</code>, then <code>Double.NaN</code> respectively 71cdf0e10cSrcweir <code>Float.NaN</code> is not accepted.</li> 72cdf0e10cSrcweir </ul></p> 73cdf0e10cSrcweir 74cdf0e10cSrcweir <p>The factory methods of the <code>XEnumerableMap</code> interface support both <em>isolated</em> 75cdf0e10cSrcweir and <em>non-isolated</em> enumerators. The latter one will be automatically disposed when the map changes 76cdf0e10cSrcweir after enumerator creation, so every attempt to use them will result in a 77cdf0e10cSrcweir <type scope="com::sun::star::lang">DisposedException</type> being thrown.</p> 78cdf0e10cSrcweir 79cdf0e10cSrcweir @see http://udk.openoffice.org/common/man/typesystem.html 80cdf0e10cSrcweir*/ 81cdf0e10cSrcweirservice EnumerableMap : XEnumerableMap 82cdf0e10cSrcweir{ 83cdf0e10cSrcweir /** creates an instance mapping from the given key type to the given value type 84cdf0e10cSrcweir 85cdf0e10cSrcweir @param KeyType 86cdf0e10cSrcweir denotes the type of the keys in the to-be-created map 87cdf0e10cSrcweir @param ValueType 88cdf0e10cSrcweir denotes the type of the values in the to-be-created map 89cdf0e10cSrcweir 90cdf0e10cSrcweir @throws ::com::sun::star::beans::IllegalTypeException 91cdf0e10cSrcweir if <arg>KeyType</arg> or <arg>ValueType</arg> are unsupported types. 92cdf0e10cSrcweir For values, all type classes except <member scope="com::sun::star::uno">TypeClass::VOID</member> 93cdf0e10cSrcweir and <member scope="com::sun::star::uno">TypeClass::UNKNOWN</member> are accepted. 94cdf0e10cSrcweir For keys, scalar types, strings, <type scope="com::sun::star::uno">Type</type> itself, and interface 95cdf0e10cSrcweir types are accepted. 96cdf0e10cSrcweir */ 97cdf0e10cSrcweir create( [in] type KeyType, [in] type ValueType ) 98cdf0e10cSrcweir raises( ::com::sun::star::beans::IllegalTypeException ); 99cdf0e10cSrcweir 100cdf0e10cSrcweir /** creates an instance mapping from the given key type to the given value type 101cdf0e10cSrcweir 102cdf0e10cSrcweir <p>The resulting map is immutable, so later alter operations on it will fail 103cdf0e10cSrcweir with a <type scope="com::sun::star::lang">NoSupportException</type>.</p> 104cdf0e10cSrcweir 105cdf0e10cSrcweir @param KeyType 106cdf0e10cSrcweir denotes the type of the keys in the to-be-created map 107cdf0e10cSrcweir @param ValueType 108cdf0e10cSrcweir denotes the type of the values in the to-be-created map 109cdf0e10cSrcweir @param Values 110cdf0e10cSrcweir denote the values contained in the to-be-created map 111cdf0e10cSrcweir 112cdf0e10cSrcweir @throws ::com::sun::star::beans::IllegalTypeException 113cdf0e10cSrcweir if <arg>KeyType</arg> or <arg>ValueType</arg> are unsupported types. 114cdf0e10cSrcweir For values, all type classes except <member scope="com::sun::star::uno">TypeClass::VOID</member> 115cdf0e10cSrcweir are accepted.<br/> 116cdf0e10cSrcweir For keys, scalar types, strings, <type scope="com::sun::star::uno">Type</type> itself, and interface 117cdf0e10cSrcweir types are accepted. 118cdf0e10cSrcweir @throws ::com::sun::star::lang::IllegalArgumentException 119cdf0e10cSrcweir if any of the given values or keys violates the <a href="#keyrules">key rules</a> or 120cdf0e10cSrcweir <a href="#valuerules">value rules</a>. 121cdf0e10cSrcweir */ 122cdf0e10cSrcweir createImmutable( 123cdf0e10cSrcweir [in] type KeyType, 124cdf0e10cSrcweir [in] type ValueType, 125cdf0e10cSrcweir [in] sequence< ::com::sun::star::beans::Pair< any, any > > Values 126cdf0e10cSrcweir ) 127cdf0e10cSrcweir raises( ::com::sun::star::beans::IllegalTypeException, 128cdf0e10cSrcweir ::com::sun::star::lang::IllegalArgumentException ); 129cdf0e10cSrcweir}; 130cdf0e10cSrcweir 131cdf0e10cSrcweir//============================================================================= 132cdf0e10cSrcweir 133cdf0e10cSrcweir}; }; }; }; 134cdf0e10cSrcweir 135cdf0e10cSrcweir//============================================================================= 136cdf0e10cSrcweir 137cdf0e10cSrcweir#endif 138