src/share/classes/org/omg/DynamicAny/DynamicAny.idl

Mon, 09 Mar 2009 13:28:38 -0700

author
xdono
date
Mon, 09 Mar 2009 13:28:38 -0700
changeset 49
e2f388853a9d
parent 13
c0252adbb2ab
child 158
91006f157c46
permissions
-rw-r--r--

6814575: Update copyright year
Summary: Update copyright for files that have been modified in 2009, up to 03/09
Reviewed-by: katleman, tbell, ohair

duke@1 1 /*
xdono@49 2 * Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
duke@1 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1 4 *
duke@1 5 * This code is free software; you can redistribute it and/or modify it
duke@1 6 * under the terms of the GNU General Public License version 2 only, as
duke@1 7 * published by the Free Software Foundation. Sun designates this
duke@1 8 * particular file as subject to the "Classpath" exception as provided
duke@1 9 * by Sun in the LICENSE file that accompanied this code.
duke@1 10 *
duke@1 11 * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@1 14 * version 2 for more details (a copy is included in the LICENSE file that
duke@1 15 * accompanied this code).
duke@1 16 *
duke@1 17 * You should have received a copy of the GNU General Public License version
duke@1 18 * 2 along with this work; if not, write to the Free Software Foundation,
duke@1 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1 20 *
duke@1 21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@1 22 * CA 95054 USA or visit www.sun.com if you need additional information or
duke@1 23 * have any questions.
duke@1 24 */
duke@1 25
duke@1 26 // IDL
duke@1 27 // File: DynamicAny.idl
duke@1 28
duke@1 29 #ifndef _DYNAMIC_ANY_IDL_
duke@1 30 #define _DYNAMIC_ANY_IDL_
duke@1 31
duke@1 32 #pragma prefix "omg.org"
duke@1 33 #include <orb.idl>
duke@1 34
duke@1 35 /**
duke@1 36 * An any can be passed to a program that doesn't have any static information for the
duke@1 37 type of the any (code generated for the type by an IDL compiler has not been
duke@1 38 compiled with the object implementation). As a result, the object receiving the any
duke@1 39 does not have a portable method of using it.
duke@1 40 <P>DynAnys enable traversal of the data value associated with an any at
duke@1 41 runtime and extraction of the primitive constituents of the data value. This is especially
duke@1 42 helpful for writing powerful generic servers (bridges, event channels supporting
duke@1 43 filtering).
duke@1 44 <P>Similarly, this facility enables the construction of an any at runtime, without having
duke@1 45 static knowledge of its type. This is especially helpful for writing generic clients
duke@1 46 (bridges, browsers, debuggers, user interface tools).
duke@1 47 */
duke@1 48 module DynamicAny {
duke@1 49 /**
duke@1 50 * Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
duke@1 51 * A DynAny object is associated with a data value which corresponds to a copy of the value
duke@1 52 * inserted into an any.
duke@1 53 * <P>A DynAny object may be viewed as an ordered collection of component DynAnys.
duke@1 54 * For DynAnys representing a basic type, such as long, or a type without components,
duke@1 55 * such as an empty exception, the ordered collection of components is empty.
duke@1 56 * Each DynAny object maintains the notion of a current position into its collection
duke@1 57 * of component DynAnys. The current position is identified by an index value that runs
duke@1 58 * from 0 to n-1, where n is the number of components.
duke@1 59 * The special index value -1 indicates a current position that points nowhere.
duke@1 60 * For values that cannot have a current position (such as an empty exception),
duke@1 61 * the index value is fixed at -1.
duke@1 62 * If a DynAny is initialized with a value that has components, the index is initialized to 0.
duke@1 63 * After creation of an uninitialized DynAny (that is, a DynAny that has no value but a TypeCode
duke@1 64 * that permits components), the current position depends on the type of value represented by
duke@1 65 * the DynAny. (The current position is set to 0 or -1, depending on whether the new DynAny
duke@1 66 * gets default values for its components.)
duke@1 67 * <P>The iteration operations rewind, seek, and next can be used to change the current position
duke@1 68 * and the current_component operation returns the component at the current position.
duke@1 69 * The component_count operation returns the number of components of a DynAny.
duke@1 70 * Collectively, these operations enable iteration over the components of a DynAny, for example,
duke@1 71 * to (recursively) examine its contents.
duke@1 72 * <P>A constructed DynAny object is a DynAny object associated with a constructed type.
duke@1 73 * There is a different interface, inheriting from the DynAny interface, associated with
duke@1 74 * each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array,
duke@1 75 * exception, and value type).
duke@1 76 * <P>A constructed DynAny object exports operations that enable the creation of new DynAny objects,
duke@1 77 * each of them associated with a component of the constructed data value.
duke@1 78 * As an example, a DynStruct is associated with a struct value. This means that the DynStruct
duke@1 79 * may be seen as owning an ordered collection of components, one for each structure member.
duke@1 80 * The DynStruct object exports operations that enable the creation of new DynAny objects,
duke@1 81 * each of them associated with a member of the struct.
duke@1 82 * <P>If a DynAny object has been obtained from another (constructed) DynAny object,
duke@1 83 * such as a DynAny representing a structure member that was created from a DynStruct,
duke@1 84 * the member DynAny is logically contained in the DynStruct.
duke@1 85 * Calling an insert or get operation leaves the current position unchanged.
duke@1 86 * Destroying a top-level DynAny object (one that was not obtained as a component of another DynAny)
duke@1 87 * also destroys any component DynAny objects obtained from it.
duke@1 88 * Destroying a non-top level DynAny object does nothing.
duke@1 89 * Invoking operations on a destroyed top-level DynAny or any of its descendants raises OBJECT_NOT_EXIST.
duke@1 90 * If the programmer wants to destroy a DynAny object but still wants to manipulate some component
duke@1 91 * of the data value associated with it, then he or she should first create a DynAny for the component
duke@1 92 * and, after that, make a copy of the created DynAny object.
duke@1 93 * <P>The behavior of DynAny objects has been defined in order to enable efficient implementations
duke@1 94 * in terms of allocated memory space and speed of access. DynAny objects are intended to be used
duke@1 95 * for traversing values extracted from anys or constructing values of anys at runtime.
duke@1 96 * Their use for other purposes is not recommended.
duke@1 97 * <P>Insert and get operations are necessary to handle basic DynAny objects
duke@1 98 * but are also helpful to handle constructed DynAny objects.
duke@1 99 * Inserting a basic data type value into a constructed DynAny object
duke@1 100 * implies initializing the current component of the constructed data value
duke@1 101 * associated with the DynAny object. For example, invoking insert_boolean on a
duke@1 102 * DynStruct implies inserting a boolean data value at the current position
duke@1 103 * of the associated struct data value.
duke@1 104 * A type is consistent for inserting or extracting a value if its TypeCode is equivalent to
duke@1 105 * the TypeCode contained in the DynAny or, if the DynAny has components, is equivalent to the TypeCode
duke@1 106 * of the DynAny at the current position.
duke@1 107 * <P>DynAny and DynAnyFactory objects are intended to be local to the process in which they are
duke@1 108 * created and used. This means that references to DynAny and DynAnyFactory objects cannot be exported
duke@1 109 * to other processes, or externalized with ORB.object_to_string().
duke@1 110 * If any attempt is made to do so, the offending operation will raise a MARSHAL system exception.
duke@1 111 * Since their interfaces are specified in IDL, DynAny objects export operations defined in the standard
duke@1 112 * org.omg.CORBA.Object interface. However, any attempt to invoke operations exported through the Object
duke@1 113 * interface may raise the standard NO_IMPLEMENT exception.
duke@1 114 * An attempt to use a DynAny object with the DII may raise the NO_IMPLEMENT exception.
duke@1 115 */
duke@1 116 interface DynAny {
duke@1 117 #pragma sun_localservant DynAny ""
duke@1 118 exception InvalidValue {};
duke@1 119 exception TypeMismatch {};
duke@1 120
duke@1 121 /**
duke@1 122 * Returns the TypeCode associated with this DynAny object.
duke@1 123 * A DynAny object is created with a TypeCode value assigned to it.
duke@1 124 * This TypeCode value determines the type of the value handled through the DynAny object.
duke@1 125 * Note that the TypeCode associated with a DynAny object is initialized at the time the
duke@1 126 * DynAny is created and cannot be changed during lifetime of the DynAny object.
duke@1 127 *
duke@1 128 * @return The TypeCode associated with this DynAny object
duke@1 129 */
duke@1 130 CORBA::TypeCode type();
duke@1 131
duke@1 132 /**
duke@1 133 * Initializes the value associated with a DynAny object with the value
duke@1 134 * associated with another DynAny object.
duke@1 135 * The current position of the target DynAny is set to zero for values that have components
duke@1 136 * and to -1 for values that do not have components.
duke@1 137 *
duke@1 138 * @param dyn_any
duke@1 139 * @exception TypeMismatch if the type of the passed DynAny is not equivalent to the type of target DynAny
duke@1 140 */
duke@1 141 void assign(in DynAny dyn_any)
duke@1 142 raises(TypeMismatch);
duke@1 143
duke@1 144 /**
duke@1 145 * Initializes the value associated with a DynAny object with the value contained in an any.
duke@1 146 * The current position of the target DynAny is set to zero for values that have components
duke@1 147 * and to -1 for values that do not have components.
duke@1 148 *
duke@1 149 * @exception TypeMismatch if the type of the passed Any is not equivalent to the type of target DynAny
duke@1 150 * @exception InvalidValue if the passed Any does not contain a legal value (such as a null string)
duke@1 151 */
duke@1 152 void from_any(in any value)
duke@1 153 raises(TypeMismatch, InvalidValue);
duke@1 154
duke@1 155 /**
duke@1 156 * Creates an any value from a DynAny object.
duke@1 157 * A copy of the TypeCode associated with the DynAny object is assigned to the resulting any.
duke@1 158 * The value associated with the DynAny object is copied into the any.
duke@1 159 *
duke@1 160 * @return a new Any object with the same value and TypeCode
duke@1 161 */
duke@1 162 any to_any();
duke@1 163
duke@1 164 /**
duke@1 165 * Compares two DynAny values for equality.
duke@1 166 * Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys
duke@1 167 * have equal values.
duke@1 168 * The current position of the two DynAnys being compared has no effect on the result of equal.
duke@1 169 *
duke@1 170 * @return true of the DynAnys are equal, false otherwise
duke@1 171 */
duke@1 172 boolean equal(in DynAny dyn_any);
duke@1 173
duke@1 174 /**
duke@1 175 * Destroys a DynAny object.
duke@1 176 * This operation frees any resources used to represent the data value associated with a DynAny object.
duke@1 177 * It must be invoked on references obtained from one of the creation operations on the ORB interface
duke@1 178 * or on a reference returned by DynAny.copy() to avoid resource leaks.
duke@1 179 * Invoking destroy on component DynAny objects (for example, on objects returned by the
duke@1 180 * current_component operation) does nothing.
duke@1 181 * Destruction of a DynAny object implies destruction of all DynAny objects obtained from it.
duke@1 182 * That is, references to components of a destroyed DynAny become invalid.
duke@1 183 * Invocations on such references raise OBJECT_NOT_EXIST.
duke@1 184 * It is possible to manipulate a component of a DynAny beyond the life time of the DynAny
duke@1 185 * from which the component was obtained by making a copy of the component with the copy operation
duke@1 186 * before destroying the DynAny from which the component was obtained.
duke@1 187 */
duke@1 188 void destroy();
duke@1 189
duke@1 190 /**
duke@1 191 * Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
duke@1 192 * The operation is polymorphic, that is, invoking it on one of the types derived from DynAny,
duke@1 193 * such as DynStruct, creates the derived type but returns its reference as the DynAny base type.
duke@1 194 *
duke@1 195 * @return a deep copy of the DynAny object
duke@1 196 */
duke@1 197 DynAny copy();
duke@1 198
duke@1 199 /**
duke@1 200 * Inserts a boolean value into the DynAny.
duke@1 201 *
duke@1 202 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 203 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 204 */
duke@1 205 void insert_boolean(in boolean value)
duke@1 206 raises(TypeMismatch, InvalidValue);
duke@1 207
duke@1 208 /**
duke@1 209 * Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.
duke@1 210 *
duke@1 211 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 212 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 213 */
duke@1 214 void insert_octet(in octet value)
duke@1 215 raises(TypeMismatch, InvalidValue);
duke@1 216
duke@1 217 /**
duke@1 218 * Inserts a char value into the DynAny.
duke@1 219 *
duke@1 220 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 221 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 222 */
duke@1 223 void insert_char(in char value)
duke@1 224 raises(TypeMismatch, InvalidValue);
duke@1 225
duke@1 226 /**
duke@1 227 * Inserts a short value into the DynAny.
duke@1 228 *
duke@1 229 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 230 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 231 */
duke@1 232 void insert_short(in short value)
duke@1 233 raises(TypeMismatch, InvalidValue);
duke@1 234
duke@1 235 /**
duke@1 236 * Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.
duke@1 237 *
duke@1 238 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 239 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 240 */
duke@1 241 void insert_ushort(in unsigned short value)
duke@1 242 raises(TypeMismatch, InvalidValue);
duke@1 243
duke@1 244 /**
duke@1 245 * Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.
duke@1 246 *
duke@1 247 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 248 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 249 */
duke@1 250 void insert_long(in long value)
duke@1 251 raises(TypeMismatch, InvalidValue);
duke@1 252
duke@1 253 /**
duke@1 254 * Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.
duke@1 255 *
duke@1 256 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 257 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 258 */
duke@1 259 void insert_ulong(in unsigned long value)
duke@1 260 raises(TypeMismatch, InvalidValue);
duke@1 261
duke@1 262 /**
duke@1 263 * Inserts a float value into the DynAny.
duke@1 264 *
duke@1 265 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 266 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 267 */
duke@1 268 void insert_float(in float value)
duke@1 269 raises(TypeMismatch, InvalidValue);
duke@1 270
duke@1 271 /**
duke@1 272 * Inserts a double value into the DynAny.
duke@1 273 *
duke@1 274 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 275 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 276 */
duke@1 277 void insert_double(in double value)
duke@1 278 raises(TypeMismatch, InvalidValue);
duke@1 279
duke@1 280 /**
duke@1 281 * Inserts a string value into the DynAny.
duke@1 282 * Both bounded and unbounded strings are inserted using this method.
duke@1 283 *
duke@1 284 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 285 * @exception InvalidValue if the string inserted is longer than the bound of a bounded string
duke@1 286 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 287 */
duke@1 288 void insert_string(in string value)
duke@1 289 raises(TypeMismatch, InvalidValue);
duke@1 290
duke@1 291 /**
duke@1 292 * Inserts a reference to a CORBA object into the DynAny.
duke@1 293 *
duke@1 294 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 295 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 296 */
duke@1 297 void insert_reference(in Object value)
duke@1 298 raises(TypeMismatch, InvalidValue);
duke@1 299
duke@1 300 /**
duke@1 301 * Inserts a TypeCode object into the DynAny.
duke@1 302 *
duke@1 303 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 304 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 305 */
duke@1 306 void insert_typecode(in CORBA::TypeCode value)
duke@1 307 raises(TypeMismatch, InvalidValue);
duke@1 308
duke@1 309 /**
duke@1 310 * Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.
duke@1 311 *
duke@1 312 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 313 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 314 */
duke@1 315 void insert_longlong(in long long value)
duke@1 316 raises(TypeMismatch, InvalidValue);
duke@1 317
duke@1 318 /**
duke@1 319 * Inserts a long value into the DynAny.
duke@1 320 * The IDL unsigned long long data type is mapped to the Java long data type.
duke@1 321 *
duke@1 322 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 323 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 324 */
duke@1 325 void insert_ulonglong(in unsigned long long value)
duke@1 326 raises(TypeMismatch, InvalidValue);
duke@1 327
duke@1 328 // void insert_longdouble(in long double value)
duke@1 329 // raises(TypeMismatch, InvalidValue);
duke@1 330
duke@1 331 /**
duke@1 332 * Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.
duke@1 333 *
duke@1 334 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 335 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 336 */
duke@1 337 void insert_wchar(in wchar value)
duke@1 338 raises(TypeMismatch, InvalidValue);
duke@1 339
duke@1 340 /**
duke@1 341 * Inserts a string value into the DynAny.
duke@1 342 * Both bounded and unbounded strings are inserted using this method.
duke@1 343 *
duke@1 344 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 345 * @exception InvalidValue if the string inserted is longer than the bound of a bounded string
duke@1 346 */
duke@1 347 void insert_wstring(in wstring value)
duke@1 348 raises(TypeMismatch, InvalidValue);
duke@1 349
duke@1 350 /**
duke@1 351 * Inserts an Any value into the Any represented by this DynAny.
duke@1 352 *
duke@1 353 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 354 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 355 */
duke@1 356 void insert_any(in any value)
duke@1 357 raises(TypeMismatch, InvalidValue);
duke@1 358
duke@1 359 /**
duke@1 360 * Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
duke@1 361 *
duke@1 362 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 363 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 364 */
duke@1 365 void insert_dyn_any(in DynAny value)
duke@1 366 raises(TypeMismatch, InvalidValue);
duke@1 367
duke@1 368 /**
duke@1 369 * Inserts a reference to a Serializable object into this DynAny.
duke@1 370 * The IDL ValueBase type is mapped to the Java Serializable type.
duke@1 371 *
duke@1 372 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 373 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 374 */
duke@1 375 void insert_val(in ValueBase value)
duke@1 376 raises(TypeMismatch, InvalidValue);
duke@1 377
duke@1 378 /**
duke@1 379 * Extracts the boolean value from this DynAny.
duke@1 380 *
duke@1 381 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 382 * that is not equivalent to the requested type.
duke@1 383 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 384 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 385 */
duke@1 386 boolean get_boolean()
duke@1 387 raises(TypeMismatch, InvalidValue);
duke@1 388
duke@1 389 /**
duke@1 390 * Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.
duke@1 391 *
duke@1 392 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 393 * that is not equivalent to the requested type.
duke@1 394 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 395 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 396 */
duke@1 397 octet get_octet()
duke@1 398 raises(TypeMismatch, InvalidValue);
duke@1 399
duke@1 400 /**
duke@1 401 * Extracts the char value from this DynAny.
duke@1 402 *
duke@1 403 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 404 * that is not equivalent to the requested type.
duke@1 405 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 406 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 407 */
duke@1 408 char get_char()
duke@1 409 raises(TypeMismatch, InvalidValue);
duke@1 410
duke@1 411 /**
duke@1 412 * Extracts the short value from this DynAny.
duke@1 413 *
duke@1 414 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 415 * that is not equivalent to the requested type.
duke@1 416 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 417 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 418 */
duke@1 419 short get_short()
duke@1 420 raises(TypeMismatch, InvalidValue);
duke@1 421
duke@1 422 /**
duke@1 423 * Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.
duke@1 424 *
duke@1 425 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 426 * that is not equivalent to the requested type.
duke@1 427 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 428 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 429 */
duke@1 430 unsigned short get_ushort()
duke@1 431 raises(TypeMismatch, InvalidValue);
duke@1 432
duke@1 433 /**
duke@1 434 * Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.
duke@1 435 *
duke@1 436 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 437 * that is not equivalent to the requested type.
duke@1 438 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 439 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 440 */
duke@1 441 long get_long()
duke@1 442 raises(TypeMismatch, InvalidValue);
duke@1 443
duke@1 444 /**
duke@1 445 * Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.
duke@1 446 *
duke@1 447 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 448 * that is not equivalent to the requested type.
duke@1 449 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 450 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 451 */
duke@1 452 unsigned long get_ulong()
duke@1 453 raises(TypeMismatch, InvalidValue);
duke@1 454
duke@1 455 /**
duke@1 456 * Extracts the float value from this DynAny.
duke@1 457 *
duke@1 458 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 459 * that is not equivalent to the requested type.
duke@1 460 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 461 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 462 */
duke@1 463 float get_float()
duke@1 464 raises(TypeMismatch, InvalidValue);
duke@1 465
duke@1 466 /**
duke@1 467 * Extracts the double value from this DynAny.
duke@1 468 *
duke@1 469 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 470 * that is not equivalent to the requested type.
duke@1 471 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 472 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 473 */
duke@1 474 double get_double()
duke@1 475 raises(TypeMismatch, InvalidValue);
duke@1 476
duke@1 477 /**
duke@1 478 * Extracts the string value from this DynAny.
duke@1 479 * Both bounded and unbounded strings are extracted using this method.
duke@1 480 *
duke@1 481 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 482 * that is not equivalent to the requested type.
duke@1 483 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 484 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 485 */
duke@1 486 string get_string()
duke@1 487 raises(TypeMismatch, InvalidValue);
duke@1 488
duke@1 489 /**
duke@1 490 * Extracts the reference to a CORBA Object from this DynAny.
duke@1 491 *
duke@1 492 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 493 * that is not equivalent to the requested type.
duke@1 494 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 495 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 496 */
duke@1 497 Object get_reference()
duke@1 498 raises(TypeMismatch, InvalidValue);
duke@1 499
duke@1 500 /**
duke@1 501 * Extracts the TypeCode object from this DynAny.
duke@1 502 *
duke@1 503 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 504 * that is not equivalent to the requested type.
duke@1 505 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 506 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 507 */
duke@1 508 CORBA::TypeCode get_typecode()
duke@1 509 raises(TypeMismatch, InvalidValue);
duke@1 510
duke@1 511 /**
duke@1 512 * Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.
duke@1 513 *
duke@1 514 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 515 * that is not equivalent to the requested type.
duke@1 516 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 517 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 518 */
duke@1 519 long long get_longlong()
duke@1 520 raises(TypeMismatch, InvalidValue);
duke@1 521
duke@1 522 /**
duke@1 523 * Extracts the long value from this DynAny.
duke@1 524 * The IDL unsigned long long data type is mapped to the Java long data type.
duke@1 525 *
duke@1 526 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 527 * that is not equivalent to the requested type.
duke@1 528 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 529 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 530 */
duke@1 531 unsigned long long get_ulonglong()
duke@1 532 raises(TypeMismatch, InvalidValue);
duke@1 533 // long double get_longdouble()
duke@1 534 // raises(TypeMismatch, InvalidValue);
duke@1 535
duke@1 536 /**
duke@1 537 * Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.
duke@1 538 *
duke@1 539 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 540 * that is not equivalent to the requested type.
duke@1 541 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 542 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 543 */
duke@1 544 wchar get_wchar()
duke@1 545 raises(TypeMismatch, InvalidValue);
duke@1 546
duke@1 547 /**
duke@1 548 * Extracts the string value from this DynAny.
duke@1 549 * Both bounded and unbounded strings are extracted using this method.
duke@1 550 *
duke@1 551 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 552 * that is not equivalent to the requested type.
duke@1 553 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 554 */
duke@1 555 wstring get_wstring()
duke@1 556 raises(TypeMismatch, InvalidValue);
duke@1 557
duke@1 558 /**
duke@1 559 * Extracts an Any value contained in the Any represented by this DynAny.
duke@1 560 *
duke@1 561 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 562 * that is not equivalent to the requested type.
duke@1 563 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 564 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 565 */
duke@1 566 any get_any()
duke@1 567 raises(TypeMismatch, InvalidValue);
duke@1 568
duke@1 569 /**
duke@1 570 * Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped
duke@1 571 * into a new DynAny.
duke@1 572 *
duke@1 573 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 574 * that is not equivalent to the requested type.
duke@1 575 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 576 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 577 */
duke@1 578 DynAny get_dyn_any()
duke@1 579 raises(TypeMismatch, InvalidValue);
duke@1 580
duke@1 581 /**
duke@1 582 * Extracts a Serializable object from this DynAny.
duke@1 583 * The IDL ValueBase type is mapped to the Java Serializable type.
duke@1 584 *
duke@1 585 * @exception TypeMismatch if the accessed component in the DynAny is of a type
duke@1 586 * that is not equivalent to the requested type.
duke@1 587 * @exception TypeMismatch if called on a DynAny whose current component itself has components
duke@1 588 * @exception InvalidValue if this DynAny has components but has a current position of -1
duke@1 589 */
duke@1 590 ValueBase get_val()
duke@1 591 raises(TypeMismatch, InvalidValue);
duke@1 592
duke@1 593 /**
duke@1 594 * Sets the current position to index. The current position is indexed 0 to n-1, that is,
duke@1 595 * index zero corresponds to the first component. The operation returns true if the resulting
duke@1 596 * current position indicates a component of the DynAny and false if index indicates
duke@1 597 * a position that does not correspond to a component.
duke@1 598 * Calling seek with a negative index is legal. It sets the current position to -1 to indicate
duke@1 599 * no component and returns false. Passing a non-negative index value for a DynAny that does not
duke@1 600 * have a component at the corresponding position sets the current position to -1 and returns false.
duke@1 601 */
duke@1 602 boolean seek(in long index);
duke@1 603
duke@1 604 /**
duke@1 605 * Is equivalent to seek(0).
duke@1 606 */
duke@1 607 void rewind();
duke@1 608
duke@1 609 /**
duke@1 610 * Advances the current position to the next component.
duke@1 611 * The operation returns true while the resulting current position indicates a component, false otherwise.
duke@1 612 * A false return value leaves the current position at -1.
duke@1 613 * Invoking next on a DynAny without components leaves the current position at -1 and returns false.
duke@1 614 */
duke@1 615 boolean next();
duke@1 616
duke@1 617 /**
duke@1 618 * Returns the number of components of a DynAny.
duke@1 619 * For a DynAny without components, it returns zero.
duke@1 620 * The operation only counts the components at the top level.
duke@1 621 * For example, if component_count is invoked on a DynStruct with a single member,
duke@1 622 * the return value is 1, irrespective of the type of the member.
duke@1 623 * <UL>
duke@1 624 * <LI>For sequences, the operation returns the current number of elements.
duke@1 625 * <LI>For structures, exceptions, and value types, the operation returns the number of members.
duke@1 626 * <LI>For arrays, the operation returns the number of elements.
duke@1 627 * <LI>For unions, the operation returns 2 if the discriminator indicates that a named member is active,
duke@1 628 * otherwise, it returns 1.
duke@1 629 * <LI>For DynFixed and DynEnum, the operation returns zero.
duke@1 630 * </UL>
duke@1 631 */
duke@1 632 unsigned long component_count();
duke@1 633
duke@1 634 /**
duke@1 635 * Returns the DynAny for the component at the current position.
duke@1 636 * It does not advance the current position, so repeated calls to current_component
duke@1 637 * without an intervening call to rewind, next, or seek return the same component.
duke@1 638 * The returned DynAny object reference can be used to get/set the value of the current component.
duke@1 639 * If the current component represents a complex type, the returned reference can be narrowed
duke@1 640 * based on the TypeCode to get the interface corresponding to the to the complex type.
duke@1 641 * Calling current_component on a DynAny that cannot have components,
duke@1 642 * such as a DynEnum or an empty exception, raises TypeMismatch.
duke@1 643 * Calling current_component on a DynAny whose current position is -1 returns a nil reference.
duke@1 644 * The iteration operations, together with current_component, can be used
duke@1 645 * to dynamically compose an any value. After creating a dynamic any, such as a DynStruct,
duke@1 646 * current_component and next can be used to initialize all the components of the value.
duke@1 647 * Once the dynamic value is completely initialized, to_any creates the corresponding any value.
duke@1 648 *
duke@1 649 * @exception TypeMismatch If called on a DynAny that cannot have components,
duke@1 650 * such as a DynEnum or an empty exception
duke@1 651 */
duke@1 652 DynAny current_component()
duke@1 653 raises(TypeMismatch);
duke@1 654 };
duke@1 655
duke@1 656 /**
duke@1 657 * DynFixed objects support the manipulation of IDL fixed values.
duke@1 658 * Because IDL does not have a generic type that can represent fixed types with arbitrary
duke@1 659 * number of digits and arbitrary scale, the operations use the IDL string type.
duke@1 660 */
duke@1 661 interface DynFixed : DynAny {
duke@1 662 #pragma sun_localservant DynFixed ""
duke@1 663
duke@1 664 /**
duke@1 665 * Returns the value of a DynFixed.
duke@1 666 */
duke@1 667 string get_value();
duke@1 668
duke@1 669 /**
duke@1 670 * Sets the value of the DynFixed.
duke@1 671 * The val string must contain a fixed string constant in the same format as used for IDL fixed-point literals.
duke@1 672 * However, the trailing d or D is optional. The return value is true if val can be represented as the DynFixed
duke@1 673 * without loss of precision. If val has more fractional digits than can be represented in the DynFixed,
duke@1 674 * fractional digits are truncated and the return value is false.
duke@1 675 *
duke@1 676 * @exception TypeMismatch If val does not contain a valid fixed-point literal or contains extraneous
duke@1 677 * characters other than leading or trailing white space
duke@1 678 * @exception InvalidValue If val contains a value whose scale exceeds that of the DynFixed
duke@1 679 * or is not initialized
duke@1 680 */
duke@1 681 boolean set_value(in string val)
duke@1 682 raises(TypeMismatch, InvalidValue);
duke@1 683 };
duke@1 684
duke@1 685 /**
duke@1 686 * DynEnum objects support the manipulation of IDL enumerated values.
duke@1 687 * The current position of a DynEnum is always -1.
duke@1 688 */
duke@1 689 interface DynEnum : DynAny {
duke@1 690 #pragma sun_localservant DynEnum ""
duke@1 691
duke@1 692 /**
duke@1 693 * Returns the value of the DynEnum as an IDL identifier.
duke@1 694 */
duke@1 695 string get_as_string();
duke@1 696
duke@1 697 /**
duke@1 698 * Sets the value of the DynEnum to the enumerated value whose IDL identifier is passed in the value parameter.
duke@1 699 *
duke@1 700 * @exception InvalidValue If value contains a string that is not a valid IDL identifier
duke@1 701 * for the corresponding enumerated type
duke@1 702 */
duke@1 703 void set_as_string(in string value)
duke@1 704 raises(InvalidValue);
duke@1 705
duke@1 706 /**
duke@1 707 * Returns the value of the DynEnum as the enumerated value's ordinal value.
duke@1 708 * Enumerators have ordinal values 0 to n-1, as they appear from left to right
duke@1 709 * in the corresponding IDL definition.
duke@1 710 */
duke@1 711 unsigned long get_as_ulong();
duke@1 712
duke@1 713 /**
duke@1 714 * Sets the value of the DynEnum as the enumerated value's ordinal value.
duke@1 715 *
duke@1 716 * @exception InvalidValue If value contains a value that is outside the range of ordinal values
duke@1 717 * for the corresponding enumerated type
duke@1 718 */
duke@1 719 void set_as_ulong(in unsigned long value)
duke@1 720 raises(InvalidValue);
duke@1 721 };
duke@1 722
duke@1 723 typedef string FieldName;
duke@1 724
duke@1 725 /**
duke@1 726 * NameValuePairs associate a name with an Any object.
duke@1 727 */
duke@1 728 struct NameValuePair {
duke@1 729 /**
duke@1 730 * The name associated with the Any.
duke@1 731 */
duke@1 732 FieldName id;
duke@1 733 /**
duke@1 734 * The Any value associated with the name.
duke@1 735 */
duke@1 736 any value;
duke@1 737 };
duke@1 738 typedef sequence<NameValuePair> NameValuePairSeq;
duke@1 739
duke@1 740 /**
duke@1 741 * NameDynAnyPairs associate a name with an DynAny object.
duke@1 742 */
duke@1 743 struct NameDynAnyPair {
duke@1 744 /**
duke@1 745 * The name associated with the DynAny.
duke@1 746 */
duke@1 747 FieldName id;
duke@1 748 /**
duke@1 749 * The DynAny value associated with the name.
duke@1 750 */
duke@1 751 DynAny value;
duke@1 752 };
duke@1 753 typedef sequence<NameDynAnyPair> NameDynAnyPairSeq;
duke@1 754
duke@1 755 /**
duke@1 756 * DynStruct objects support the manipulation of IDL struct and exception values.
duke@1 757 * Members of the exceptions are handled in the same way as members of a struct.
duke@1 758 */
duke@1 759 interface DynStruct : DynAny {
duke@1 760 #pragma sun_localservant DynStruct ""
duke@1 761
duke@1 762 /**
duke@1 763 * Returns the name of the member at the current position.
duke@1 764 * This operation may return an empty string since the TypeCode of the value being
duke@1 765 * manipulated may not contain the names of members.
duke@1 766 *
duke@1 767 * @exception TypeMismatch if the DynStruct represents an empty exception.
duke@1 768 * @exception InvalidValue if the current position does not indicate a member
duke@1 769 */
duke@1 770 FieldName current_member_name()
duke@1 771 raises(TypeMismatch, InvalidValue);
duke@1 772
duke@1 773 /**
duke@1 774 * Returns the TCKind associated with the member at the current position.
duke@1 775 *
duke@1 776 * @exception TypeMismatch if the DynStruct represents an empty exception.
duke@1 777 * @exception InvalidValue if the current position does not indicate a member
duke@1 778 */
duke@1 779 CORBA::TCKind current_member_kind()
duke@1 780 raises(TypeMismatch, InvalidValue);
duke@1 781
duke@1 782 /**
duke@1 783 * Returns a sequence of NameValuePairs describing the name and the value of each member
duke@1 784 * in the struct associated with a DynStruct object.
duke@1 785 * The sequence contains members in the same order as the declaration order of members
duke@1 786 * as indicated by the DynStruct's TypeCode. The current position is not affected.
duke@1 787 * The member names in the returned sequence will be empty strings if the DynStruct's TypeCode
duke@1 788 * does not contain member names.
duke@1 789 */
duke@1 790 NameValuePairSeq get_members();
duke@1 791
duke@1 792 /**
duke@1 793 * Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
duke@1 794 * The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise,
duke@1 795 * if an empty sequence is passed, the current position is set to -1.
duke@1 796 * <P>Members must appear in the NameValuePairs in the order in which they appear in the IDL specification
duke@1 797 * of the struct as indicated by the DynStruct's TypeCode or they must be empty strings.
duke@1 798 * The operation makes no attempt to assign member values based on member names.
duke@1 799 *
duke@1 800 * @exception TypeMismatch if the member names supplied in the passed sequence do not match the
duke@1 801 * corresponding member name in the DynStruct's TypeCode and they are not empty strings
duke@1 802 * @exception InvalidValue if the passed sequence has a number of elements that disagrees
duke@1 803 * with the number of members as indicated by the DynStruct's TypeCode
duke@1 804 */
duke@1 805 void set_members(in NameValuePairSeq value)
duke@1 806 raises(TypeMismatch, InvalidValue);
duke@1 807
duke@1 808 /**
duke@1 809 * Returns a sequence of NameDynAnyPairs describing the name and the value of each member
duke@1 810 * in the struct associated with a DynStruct object.
duke@1 811 * The sequence contains members in the same order as the declaration order of members
duke@1 812 * as indicated by the DynStruct's TypeCode. The current position is not affected.
duke@1 813 * The member names in the returned sequence will be empty strings if the DynStruct's TypeCode
duke@1 814 * does not contain member names.
duke@1 815 */
duke@1 816 NameDynAnyPairSeq get_members_as_dyn_any();
duke@1 817
duke@1 818 /**
duke@1 819 * Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
duke@1 820 * The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise,
duke@1 821 * if an empty sequence is passed, the current position is set to -1.
duke@1 822 * <P>Members must appear in the NameDynAnyPairs in the order in which they appear in the IDL specification
duke@1 823 * of the struct as indicated by the DynStruct's TypeCode or they must be empty strings.
duke@1 824 * The operation makes no attempt to assign member values based on member names.
duke@1 825 *
duke@1 826 * @exception TypeMismatch if the member names supplied in the passed sequence do not match the
duke@1 827 * corresponding member name in the DynStruct's TypeCode and they are not empty strings
duke@1 828 * @exception InvalidValue if the passed sequence has a number of elements that disagrees
duke@1 829 * with the number of members as indicated by the DynStruct's TypeCode
duke@1 830 */
duke@1 831 void set_members_as_dyn_any(in NameDynAnyPairSeq value)
duke@1 832 raises(TypeMismatch, InvalidValue);
duke@1 833 };
duke@1 834
duke@1 835 /**
duke@1 836 * DynUnion objects support the manipulation of IDL unions.
duke@1 837 * A union can have only two valid current positions:
duke@1 838 * <UL>
duke@1 839 * <LI>zero, which denotes the discriminator
duke@1 840 * <LI>one, which denotes the active member
duke@1 841 * </UL>
duke@1 842 * The component_count value for a union depends on the current discriminator:
duke@1 843 * it is 2 for a union whose discriminator indicates a named member, and 1 otherwise.
duke@1 844 */
duke@1 845 interface DynUnion : DynAny {
duke@1 846 #pragma sun_localservant DynUnion ""
duke@1 847
duke@1 848 /**
duke@1 849 * Returns the current discriminator value.
duke@1 850 */
duke@1 851 DynAny get_discriminator();
duke@1 852
duke@1 853 /**
duke@1 854 * Sets the discriminator of the DynUnion to the specified value.
duke@1 855 * Setting the discriminator to a value that is consistent with the currently active union member
duke@1 856 * does not affect the currently active member. Setting the discriminator to a value that is inconsistent
duke@1 857 * with the currently active member deactivates the member and activates the member that is consistent
duke@1 858 * with the new discriminator value (if there is a member for that value) by initializing the member
duke@1 859 * to its default value.
duke@1 860 * Setting the discriminator of a union sets the current position to 0 if the discriminator value
duke@1 861 * indicates a non-existent union member (has_no_active_member returns true in this case).
duke@1 862 * Otherwise, if the discriminator value indicates a named union member, the current position is set to 1
duke@1 863 * (has_no_active_member returns false and component_count returns 2 in this case).
duke@1 864 *
duke@1 865 * @exception TypeMismatch if the TypeCode of the parameter is not equivalent to the TypeCode
duke@1 866 * of the union's discriminator
duke@1 867 */
duke@1 868 void set_discriminator(in DynAny d)
duke@1 869 raises(TypeMismatch);
duke@1 870
duke@1 871 /**
duke@1 872 * Sets the discriminator to a value that is consistent with the value of the default case of a union.
duke@1 873 * It sets the current position to zero and causes component_count to return 2.
duke@1 874 *
duke@1 875 * @exception TypeMismatch if the union does not have an explicit default case
duke@1 876 */
duke@1 877 void set_to_default_member()
duke@1 878 raises(TypeMismatch);
duke@1 879
duke@1 880 /**
duke@1 881 * Sets the discriminator to a value that does not correspond to any of the unions case labels.
duke@1 882 * It sets the current position to zero and causes component_count to return 1.
duke@1 883 *
duke@1 884 * @exception TypeMismatch if the union has an explicit default case or if it uses the entire range
duke@1 885 * of discriminator values for explicit case labels
duke@1 886 */
duke@1 887 void set_to_no_active_member()
duke@1 888 raises(TypeMismatch);
duke@1 889
duke@1 890 /**
duke@1 891 * Returns true if the union has no active member, that is, the unions value consists solely
duke@1 892 * of its discriminator because the discriminator has a value that is not listed as an explicit case label.
duke@1 893 * Calling this operation on a union that has a default case returns false.
duke@1 894 * Calling this operation on a union that uses the entire range of discriminator values
duke@1 895 * for explicit case labels returns false.
duke@1 896 */
duke@1 897 boolean has_no_active_member();
duke@1 898
duke@1 899 /**
duke@1 900 * Returns the TCKind value of the discriminators TypeCode.
duke@1 901 */
duke@1 902 CORBA::TCKind discriminator_kind();
duke@1 903
duke@1 904 /**
duke@1 905 * Returns the TCKind value of the currently active members TypeCode.
duke@1 906 *
duke@1 907 * @exception InvalidValue if the union does not have a currently active member
duke@1 908 */
duke@1 909 CORBA::TCKind member_kind()
duke@1 910 raises(InvalidValue);
duke@1 911
duke@1 912 /**
duke@1 913 * Returns the currently active member. Note that the returned reference remains valid only
duke@1 914 * for as long as the currently active member does not change. Using the returned reference
duke@1 915 * beyond the life time of the currently active member raises OBJECT_NOT_EXIST.
duke@1 916 *
duke@1 917 * @exception InvalidValue if the union has no active member
duke@1 918 */
duke@1 919 DynAny member()
duke@1 920 raises(InvalidValue);
duke@1 921
duke@1 922 /**
duke@1 923 * Returns the name of the currently active member. If the unions TypeCode does not contain
duke@1 924 * a member name for the currently active member, the operation returns an empty string.
duke@1 925 *
duke@1 926 * @exception InvalidValue if the union has no active member
duke@1 927 */
duke@1 928 FieldName member_name()
duke@1 929 raises(InvalidValue);
duke@1 930 };
duke@1 931
duke@1 932 typedef sequence<any> AnySeq;
duke@1 933 typedef sequence<DynAny> DynAnySeq;
duke@1 934
duke@1 935 /**
duke@1 936 * DynSequence objects support the manipulation of IDL sequences.
duke@1 937 */
duke@1 938 interface DynSequence : DynAny {
duke@1 939 #pragma sun_localservant DynSequence ""
duke@1 940
duke@1 941 /**
duke@1 942 * Returns the current length of the sequence.
duke@1 943 */
duke@1 944 unsigned long get_length();
duke@1 945
duke@1 946 /**
duke@1 947 * Sets the length of the sequence.
duke@1 948 * Increasing the length of a sequence adds new elements at the tail without affecting the values
duke@1 949 * of already existing elements. Newly added elements are default-initialized.
duke@1 950 * Increasing the length of a sequence sets the current position to the first newly-added element
duke@1 951 * if the previous current position was -1. Otherwise, if the previous current position was not -1,
duke@1 952 * the current position is not affected.
duke@1 953 * Decreasing the length of a sequence removes elements from the tail without affecting the value
duke@1 954 * of those elements that remain. The new current position after decreasing the length of a sequence
duke@1 955 * is determined as follows:
duke@1 956 * <UL>
duke@1 957 * <LI>If the length of the sequence is set to zero, the current position is set to -1.
duke@1 958 * <LI>If the current position is -1 before decreasing the length, it remains at -1.
duke@1 959 * <LI>If the current position indicates a valid element and that element is not removed when the length
duke@1 960 * is decreased, the current position remains unaffected.
duke@1 961 * <LI>If the current position indicates a valid element and that element is removed,
duke@1 962 * the current position is set to -1.
duke@1 963 * </UL>
duke@1 964 *
duke@1 965 * @exception InvalidValue if this is a bounded sequence and len is larger than the bound
duke@1 966 */
duke@1 967 void set_length(in unsigned long len)
duke@1 968 raises(InvalidValue);
duke@1 969
duke@1 970 /**
duke@1 971 * Returns the elements of the sequence.
duke@1 972 */
duke@1 973 AnySeq get_elements();
duke@1 974
duke@1 975 /**
duke@1 976 * Sets the elements of a sequence.
duke@1 977 * The length of the DynSequence is set to the length of value. The current position is set to zero
duke@1 978 * if value has non-zero length and to -1 if value is a zero-length sequence.
duke@1 979 *
duke@1 980 * @exception TypeMismatch if value contains one or more elements whose TypeCode is not equivalent
duke@1 981 * to the element TypeCode of the DynSequence
duke@1 982 * @exception InvalidValue if the length of value exceeds the bound of a bounded sequence
duke@1 983 */
duke@1 984 void set_elements(in AnySeq value)
duke@1 985 raises(TypeMismatch, InvalidValue);
duke@1 986
duke@1 987 /**
duke@1 988 * Returns the DynAnys representing the elements of the sequence.
duke@1 989 */
duke@1 990 DynAnySeq get_elements_as_dyn_any();
duke@1 991
duke@1 992 /**
duke@1 993 * Sets the elements of a sequence using DynAnys.
duke@1 994 * The length of the DynSequence is set to the length of value. The current position is set to zero
duke@1 995 * if value has non-zero length and to -1 if value is a zero-length sequence.
duke@1 996 *
duke@1 997 * @exception TypeMismatch if value contains one or more elements whose TypeCode is not equivalent
duke@1 998 * to the element TypeCode of the DynSequence
duke@1 999 * @exception InvalidValue if the length of value exceeds the bound of a bounded sequence
duke@1 1000 */
duke@1 1001 void set_elements_as_dyn_any(in DynAnySeq value)
duke@1 1002 raises(TypeMismatch, InvalidValue);
duke@1 1003 };
duke@1 1004
duke@1 1005 /**
duke@1 1006 * DynArray objects support the manipulation of IDL arrays.
duke@1 1007 * Note that the dimension of the array is contained in the TypeCode which is accessible
duke@1 1008 * through the type attribute. It can also be obtained by calling the component_count operation.
duke@1 1009 */
duke@1 1010 interface DynArray : DynAny {
duke@1 1011 #pragma sun_localservant DynArray ""
duke@1 1012
duke@1 1013 /**
duke@1 1014 * Returns the elements of the DynArray.
duke@1 1015 */
duke@1 1016 AnySeq get_elements();
duke@1 1017
duke@1 1018 /**
duke@1 1019 * Sets the DynArray to contain the passed elements.
duke@1 1020 *
duke@1 1021 * @exception TypeMismatch if one or more elements have a type that is inconsistent with the DynArrays TypeCode
duke@1 1022 * @exception InvalidValue if the sequence does not contain the same number of elements as the array dimension
duke@1 1023 */
duke@1 1024 void set_elements(in AnySeq value)
duke@1 1025 raises(TypeMismatch, InvalidValue);
duke@1 1026
duke@1 1027 /**
duke@1 1028 * Returns the elements of the DynArray as DynAnys.
duke@1 1029 */
duke@1 1030 DynAnySeq get_elements_as_dyn_any();
duke@1 1031
duke@1 1032 /**
duke@1 1033 * Sets the DynArray to contain the passed elements.
duke@1 1034 *
duke@1 1035 * @exception TypeMismatch if one or more elements have a type that is inconsistent with the DynArrays TypeCode
duke@1 1036 * @exception InvalidValue if the sequence does not contain the same number of elements as the array dimension
duke@1 1037 */
duke@1 1038 void set_elements_as_dyn_any(in DynAnySeq value)
duke@1 1039 raises(TypeMismatch, InvalidValue);
duke@1 1040 };
duke@1 1041
duke@1 1042 /**
duke@1 1043 * DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
duke@1 1044 */
ohair@5 1045 interface DynValueCommon : DynAny {
duke@1 1046 /**
duke@1 1047 * Returns true if the DynValueCommon represents a null value type.
duke@1 1048 */
ohair@5 1049 boolean is_null();
duke@1 1050
duke@1 1051 /**
duke@1 1052 * Changes the representation of a DynValueCommon to a null value type.
duke@1 1053 */
ohair@5 1054 void set_to_null();
duke@1 1055
duke@1 1056 /**
duke@1 1057 * Replaces a null value type with a newly constructed value. Its components are initialized
duke@1 1058 * to default values as in DynAnyFactory.create_dyn_any_from_type_code.
duke@1 1059 * If the DynValueCommon represents a non-null value type, then this operation has no effect.
duke@1 1060 */
ohair@5 1061 void set_to_value();
ohair@5 1062 };
duke@1 1063
duke@1 1064 /**
duke@1 1065 * DynValue objects support the manipulation of IDL non-boxed value types.
duke@1 1066 * The DynValue interface can represent both null and non-null value types.
duke@1 1067 * For a DynValue representing a non-null value type, the DynValue's components comprise
duke@1 1068 * the public and private members of the value type, including those inherited from concrete base value types,
duke@1 1069 * in the order of definition. A DynValue representing a null value type has no components
duke@1 1070 * and a current position of -1.
duke@1 1071 * <P>Warning: Indiscriminantly changing the contents of private value type members can cause the value type
duke@1 1072 * implementation to break by violating internal constraints. Access to private members is provided to support
duke@1 1073 * such activities as ORB bridging and debugging and should not be used to arbitrarily violate
duke@1 1074 * the encapsulation of the value type.
duke@1 1075 */
duke@1 1076 interface DynValue : DynValueCommon {
duke@1 1077 #pragma sun_localservant DynValue ""
duke@1 1078
duke@1 1079 /**
duke@1 1080 * Returns the name of the member at the current position.
duke@1 1081 * This operation may return an empty string since the TypeCode of the value being
duke@1 1082 * manipulated may not contain the names of members.
duke@1 1083 *
duke@1 1084 * @exception TypeMismatch if the DynValue represents a null value type.
duke@1 1085 * @exception InvalidValue if the current position does not indicate a member
duke@1 1086 */
duke@1 1087 FieldName current_member_name()
duke@1 1088 raises(TypeMismatch, InvalidValue);
duke@1 1089
duke@1 1090 /**
duke@1 1091 * Returns the TCKind associated with the member at the current position.
duke@1 1092 *
duke@1 1093 * @exception TypeMismatch if the DynValue represents a null value type.
duke@1 1094 * @exception InvalidValue if the current position does not indicate a member
duke@1 1095 */
duke@1 1096 CORBA::TCKind current_member_kind()
duke@1 1097 raises(TypeMismatch, InvalidValue);
duke@1 1098
duke@1 1099 /**
duke@1 1100 * Returns a sequence of NameValuePairs describing the name and the value of each member
duke@1 1101 * in the value type.
duke@1 1102 * The sequence contains members in the same order as the declaration order of members
duke@1 1103 * as indicated by the DynValue's TypeCode. The current position is not affected.
duke@1 1104 * The member names in the returned sequence will be empty strings if the DynValue's TypeCode
duke@1 1105 * does not contain member names.
duke@1 1106 *
duke@1 1107 * @exception InvalidValue if this object represents a null value type
duke@1 1108 */
duke@1 1109 NameValuePairSeq get_members()
duke@1 1110 raises(InvalidValue);
duke@1 1111
duke@1 1112 /**
duke@1 1113 * Initializes the value type's members from a sequence of NameValuePairs.
duke@1 1114 * The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise,
duke@1 1115 * if an empty sequence is passed, the current position is set to -1.
duke@1 1116 * A null value type can be initialized to a non-null value type using this method.
duke@1 1117 * <P>Members must appear in the NameValuePairs in the order in which they appear in the IDL specification
duke@1 1118 * of the value type as indicated by the DynValue's TypeCode or they must be empty strings.
duke@1 1119 * The operation makes no attempt to assign member values based on member names.
duke@1 1120 *
duke@1 1121 * @exception TypeMismatch if the member names supplied in the passed sequence do not match the
duke@1 1122 * corresponding member name in the DynValue's TypeCode and they are not empty strings
duke@1 1123 * @exception InvalidValue if the passed sequence has a number of elements that disagrees
duke@1 1124 * with the number of members as indicated by the DynValue's TypeCode
duke@1 1125 */
duke@1 1126 void set_members(in NameValuePairSeq value)
duke@1 1127 raises(TypeMismatch, InvalidValue);
duke@1 1128
duke@1 1129 /**
duke@1 1130 * Returns a sequence of NameDynAnyPairs describing the name and the value of each member
duke@1 1131 * in the value type.
duke@1 1132 * The sequence contains members in the same order as the declaration order of members
duke@1 1133 * as indicated by the DynValue's TypeCode. The current position is not affected.
duke@1 1134 * The member names in the returned sequence will be empty strings if the DynValue's TypeCode
duke@1 1135 * does not contain member names.
duke@1 1136 *
duke@1 1137 * @exception InvalidValue if this object represents a null value type
duke@1 1138 */
duke@1 1139 NameDynAnyPairSeq get_members_as_dyn_any()
duke@1 1140 raises(InvalidValue);
duke@1 1141
duke@1 1142 /**
duke@1 1143 * Initializes the value type's members from a sequence of NameDynAnyPairs.
duke@1 1144 * The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise,
duke@1 1145 * if an empty sequence is passed, the current position is set to -1.
duke@1 1146 * A null value type can be initialized to a non-null value type using this method.
duke@1 1147 * <P>Members must appear in the NameDynAnyPairs in the order in which they appear in the IDL specification
duke@1 1148 * of the value type as indicated by the DynValue's TypeCode or they must be empty strings.
duke@1 1149 * The operation makes no attempt to assign member values based on member names.
duke@1 1150 *
duke@1 1151 * @exception TypeMismatch if the member names supplied in the passed sequence do not match the
duke@1 1152 * corresponding member name in the DynValue's TypeCode and they are not empty strings
duke@1 1153 * @exception InvalidValue if the passed sequence has a number of elements that disagrees
duke@1 1154 * with the number of members as indicated by the DynValue's TypeCode
duke@1 1155 */
duke@1 1156 void set_members_as_dyn_any(in NameDynAnyPairSeq value)
duke@1 1157 raises(TypeMismatch, InvalidValue);
duke@1 1158 };
duke@1 1159
duke@1 1160 /**
duke@1 1161 * DynValueBox objects support the manipulation of IDL boxed value types.
duke@1 1162 * The DynValueBox interface can represent both null and non-null value types.
duke@1 1163 * For a DynValueBox representing a non-null value type, the DynValueBox has a single component
duke@1 1164 * of the boxed type. A DynValueBox representing a null value type has no components
duke@1 1165 * and a current position of -1.
duke@1 1166 */
ohair@5 1167 interface DynValueBox : DynValueCommon {
duke@1 1168
duke@1 1169 /**
duke@1 1170 * Returns the boxed value as an Any.
duke@1 1171 *
duke@1 1172 * @exception InvalidValue if this object represents a null value box type
duke@1 1173 */
ohair@5 1174 any get_boxed_value()
duke@1 1175 raises(InvalidValue);
duke@1 1176
duke@1 1177 /**
duke@1 1178 * Replaces the boxed value with the specified value.
duke@1 1179 * If the DynBoxedValue represents a null valuetype, it is converted to a non-null value.
duke@1 1180 *
duke@1 1181 * @exception TypeMismatch if this object represents a non-null value box type and the type
duke@1 1182 * of the parameter is not matching the current boxed value type.
duke@1 1183 */
duke@1 1184 void set_boxed_value(in any boxed)
duke@1 1185 raises(TypeMismatch);
duke@1 1186
duke@1 1187 /**
duke@1 1188 * Returns the boxed value as a DynAny.
duke@1 1189 *
duke@1 1190 * @exception InvalidValue if this object represents a null value box type
duke@1 1191 */
ohair@5 1192 DynAny get_boxed_value_as_dyn_any()
duke@1 1193 raises(InvalidValue);
duke@1 1194
duke@1 1195 /**
duke@1 1196 * Replaces the boxed value with the value contained in the parameter.
duke@1 1197 * If the DynBoxedValue represents a null valuetype, it is converted to a non-null value.
duke@1 1198 *
duke@1 1199 * @exception TypeMismatch if this object represents a non-null value box type and the type
duke@1 1200 * of the parameter is not matching the current boxed value type.
duke@1 1201 */
ohair@5 1202 void set_boxed_value_as_dyn_any(in DynAny boxed)
duke@1 1203 raises(TypeMismatch);
duke@1 1204 };
duke@1 1205
duke@1 1206 /**
duke@1 1207 * DynAny objects can be created by invoking operations on the DynAnyFactory object.
duke@1 1208 * Generally there are only two ways to create a DynAny object:
duke@1 1209 * <UL>
duke@1 1210 * <LI>invoking an operation on an existing DynAny object
duke@1 1211 * <LI>invoking an operation on a DynAnyFactory object
duke@1 1212 * </UL>
duke@1 1213 * A constructed DynAny object supports operations that enable the creation of new DynAny
duke@1 1214 * objects encapsulating access to the value of some constituent.
duke@1 1215 * DynAny objects also support the copy operation for creating new DynAny objects.
duke@1 1216 * A reference to the DynAnyFactory object is obtained by calling ORB.resolve_initial_references()
duke@1 1217 * with the identifier parameter set to the string constant "DynAnyFactory".
duke@1 1218 * <P>Dynamic interpretation of an any usually involves creating a DynAny object using create_dyn_any()
duke@1 1219 * as the first step. Depending on the type of the any, the resulting DynAny object reference can be narrowed
duke@1 1220 * to a DynFixed, DynStruct, DynSequence, DynArray, DynUnion, DynEnum, or DynValue object reference.
duke@1 1221 * <P>Dynamic creation of an any involves creating a DynAny object using create_dyn_any_from_type_code(),
duke@1 1222 * passing the TypeCode associated with the value to be created. The returned reference is narrowed to one of
duke@1 1223 * the complex types, such as DynStruct, if appropriate. Then, the value can be initialized by means of
duke@1 1224 * invoking operations on the resulting object. Finally, the to_any operation can be invoked
duke@1 1225 * to create an any value from the constructed DynAny.
duke@1 1226 */
duke@1 1227 interface DynAnyFactory {
duke@1 1228 #pragma sun_localservant DynAnyFactory ""
duke@1 1229 exception InconsistentTypeCode {};
duke@1 1230
duke@1 1231 /**
duke@1 1232 * Creates a new DynAny object from an any value.
duke@1 1233 * A copy of the TypeCode associated with the any value is assigned to the resulting DynAny object.
duke@1 1234 * The value associated with the DynAny object is a copy of the value in the original any.
duke@1 1235 * The current position of the created DynAny is set to zero if the passed value has components,
duke@1 1236 * to -1 otherwise
duke@1 1237 *
duke@1 1238 * @exception InconsistentTypeCode if value has a TypeCode with a TCKind of tk_Principal,
duke@1 1239 * tk_native, or tk_abstract_interface
duke@1 1240 */
duke@1 1241 DynAny create_dyn_any(in any value)
duke@1 1242 raises(InconsistentTypeCode);
duke@1 1243
duke@1 1244 /**
duke@1 1245 * Creates a DynAny from a TypeCode. Depending on the TypeCode, the created object may be of type DynAny,
duke@1 1246 * or one of its derived types, such as DynStruct. The returned reference can be narrowed to the derived type.
duke@1 1247 * In all cases, a DynAny constructed from a TypeCode has an initial default value.
duke@1 1248 * The default values of basic types are:
duke@1 1249 * <UL>
duke@1 1250 * <LI>false for boolean
duke@1 1251 * <LI>zero for numeric types
duke@1 1252 * <LI>zero for types octet, char, and wchar
duke@1 1253 * <LI>the empty string for string and wstring
duke@1 1254 * <LI>null for object references
duke@1 1255 * <LI>a type code with a TCKind value of tk_null for type codes
duke@1 1256 * <LI>for any values, an any containing a type code with a TCKind value of tk_null type and no value
duke@1 1257 * </UL>
duke@1 1258 * For complex types, creation of the corresponding DynAny assigns a default value as follows:
duke@1 1259 * <UL>
duke@1 1260 * <LI>For DynSequence it sets the current position to -1 and creates an empty sequence.
duke@1 1261 * <LI>For DynEnum it sets the current position to -1 and sets the value of the enumerator
duke@1 1262 * to the first enumerator value indicated by the TypeCode.
duke@1 1263 * <LI>For DynFixed it sets the current position to -1 and sets the value zero.
duke@1 1264 * <LI>For DynStruct it sets the current position to -1 for empty exceptions
duke@1 1265 * and to zero for all other TypeCodes. The members (if any) are (recursively) initialized
duke@1 1266 * to their default values.
duke@1 1267 * <LI>For DynArray sets the current position to zero and (recursively) initializes elements
duke@1 1268 * to their default value.
duke@1 1269 * <LI>For DynUnion sets the current position to zero. The discriminator value is set
duke@1 1270 * to a value consistent with the first named member of the union. That member is activated and (recursively)
duke@1 1271 * initialized to its default value.
duke@1 1272 * <LI>For DynValue and DynValueBox it initializes to a null value.
duke@1 1273 * </UL>
duke@1 1274 */
duke@1 1275 DynAny create_dyn_any_from_type_code(in CORBA::TypeCode type)
duke@1 1276 raises(InconsistentTypeCode);
duke@1 1277 };
duke@1 1278 }; // module DynamicAny
duke@1 1279
duke@1 1280 #endif // _DYNAMIC_ANY_IDL_

mercurial