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_XMap_idl__ 29#define __com_sun_star_container_XMap_idl__ 30 31#include <com/sun/star/beans/IllegalTypeException.idl> 32#include <com/sun/star/lang/IllegalArgumentException.idl> 33#include <com/sun/star/container/NoSuchElementException.idl> 34#include <com/sun/star/lang/NoSupportException.idl> 35#include <com/sun/star/container/XElementAccess.idl> 36 37//============================================================================= 38 39module com { module sun { module star { module container { 40 41//============================================================================= 42 43/** describes a map between keys and values. 44 45 <p>Keys in the map are unique, and each key maps to exactly one value.</p> 46 47 <p>Locating elements in the map, both values and keys, requires a notion of equality of two objects. 48 In conformance with the <a href="http://udk.openoffice.org/common/man/typesystem.html">UNO type system</a>, 49 two values are said to be equal if and only if they have the same type, and both denote the same element of this 50 type's value set.</p> 51 52 @see <type>Map</type> for a default implementation of this interface 53*/ 54interface XMap 55{ 56 interface XElementAccess; 57 58 /** denotes the type of the keys in the map. 59 60 <p>Implementations are free to accept any supertype of <code>KeyType</code> as keys.</p> 61 */ 62 [attribute, readonly] type KeyType; 63 64 /** denotes the type of the values in the map. 65 66 <p>Implementations are free to accept any supertype of the <code>ValueType</code> as values.</p> 67 */ 68 [attribute, readonly] type ValueType; 69 70 /** clears the map, removing all key-value pairs from it. 71 72 @throws ::com::sun::star::beans::NoSupportException 73 if the map is not mutable. 74 */ 75 void clear() 76 raises( ::com::sun::star::lang::NoSupportException ); 77 78 /** determines whether a mapping for he given key exists in the map 79 80 @param Key 81 is the key whose presence in the map is to be tested. 82 @return 83 <TRUE/> if and only if the map contains a mapping for the given key. 84 85 @throws ::com::sun::star::beans::IllegalTypeException 86 if the given key is not of a type which is accepted by the map 87 @throws ::com::sun::star::lang::IllegalArgumentException 88 if the given key is not supported to be put into the map. It's up to the service 89 implementing the <code>XMap</code> interface to specify which special values are not 90 supported. For instances, implementations might decide to not allow <VOID/> keys, or 91 to reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic 92 behavior with respect to equality. 93 */ 94 boolean containsKey( [in] any Key ) 95 raises( ::com::sun::star::beans::IllegalTypeException, 96 ::com::sun::star::lang::IllegalArgumentException ); 97 98 /** determines whether the map contains a mapping to a given value. 99 100 @param Value 101 is the value whose presence in the map is to be tested. 102 @return 103 <TRUE/> if and only one or more keys map to the given value. 104 105 @throws ::com::sun::star::beans::IllegalTypeException 106 if the given value is not of a type which is accepted by the map. It's up to the service 107 implementing the <code>XMap</code> interface to specify which special values are not 108 supported. For instances, implementations might decide to not allow <code>Double.NaN</code> 109 (<em>not a number</em>) to due its problematic behavior with respect to equality. 110 @throws ::com::sun::star::lang::IllegalArgumentException 111 if the given value is not supported to be put into the map. 112 */ 113 boolean containsValue( [in] any Value ) 114 raises( ::com::sun::star::beans::IllegalTypeException, 115 ::com::sun::star::lang::IllegalArgumentException ); 116 117 /** gets the value to which a given key maps. 118 119 @param Key 120 they key whose associated value is to be returned. 121 @return 122 the value which is associated with the given key. 123 124 @throws ::com::sun::star::beans::IllegalTypeException 125 if the given key is not of a type which is accepted by the map 126 @throws ::com::sun::star::beans::IllegalArgumentException 127 if the given key is not supported to be put into the map. It's up to the service 128 implementing the <code>XMap</code> interface to specify which special values are not 129 supported. For instances, implementations might decide to not allow <VOID/> keys, or 130 to reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic 131 behavior with respect to equality. 132 @throws ::com::sun::star::container::NoSuchElementException 133 if there is no value associated with the given key 134 */ 135 any get( [in] any Key ) 136 raises( ::com::sun::star::beans::IllegalTypeException, 137 ::com::sun::star::lang::IllegalArgumentException, 138 ::com::sun::star::container::NoSuchElementException ); 139 140 /** associates a given key with a given value 141 142 <p>If the map already contains a mapping for the given key, then the old value is replaced by the 143 given new value.</p> 144 145 @param Key 146 is the key which the given value should be associated with 147 @param Value 148 is the value which should be associated with the given key 149 @return 150 the value which was previously associated with the given key, or <VOID/> 151 if there was no such previous association. 152 153 @throws ::com::sun::star::beans::IllegalTypeException 154 if the given key is not of a type which is accepted by the map 155 @throws ::com::sun::star::lang::IllegalArgumentException 156 if the given key, or the given value, is not supported to be put into the map. It's up to 157 the service implementing the <code>XMap</code> interface to specify which special values 158 are not supported.<br/> 159 For instances, implementations might decide to not allow <VOID/> keys or values, or to 160 reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic behavior 161 with respect to equality. 162 @throws ::com::sun::star::beans::NoSupportException 163 if the map does not support putting new mappings into it 164 */ 165 any put( [in] any Key, [in] any Value ) 166 raises( ::com::sun::star::lang::NoSupportException, 167 ::com::sun::star::beans::IllegalTypeException, 168 ::com::sun::star::lang::IllegalArgumentException ); 169 170 /** removes a key-value mapping, given by key, from the map. 171 172 @param Key 173 is the key whose mapping should be removed from the map 174 @return 175 the value which was associated with the given key before the removal 176 177 @throws ::com::sun::star::beans::IllegalTypeException 178 if the given key is not of a type which is accepted by the map 179 @throws ::com::sun::star::lang::IllegalArgumentException 180 if the given key is not supported to be put into the map. It's up to the service 181 implementing the <code>XMap</code> interface to specify which special values are not 182 supported. For instances, implementations might decide to not allow <VOID/> keys, or 183 to reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic 184 behavior with respect to equality. 185 @throws ::com::sun::star::beans::NoSupportException 186 if the map does not support removing mappings 187 @throws ::com::sun::star::container::NoSuchElementException 188 if there is no value associated with the given key 189 */ 190 any remove( [in] any Key ) 191 raises( ::com::sun::star::lang::NoSupportException, 192 ::com::sun::star::beans::IllegalTypeException, 193 ::com::sun::star::lang::IllegalArgumentException, 194 ::com::sun::star::container::NoSuchElementException ); 195}; 196 197//============================================================================= 198 199}; }; }; }; 200 201//============================================================================= 202 203#endif 204