001/* DynAnyOperations.java -- 002 Copyright (C) 2005, 2006 Free Software Foundation, Inc. 003This file is part of GNU Classpath. 004 005GNU Classpath is free software; you can redistribute it and/or modify 006it under the terms of the GNU General Public License as published by 007the Free Software Foundation; either version 2, or (at your option) 008any later version. 009 010GNU Classpath is distributed in the hope that it will be useful, but 011WITHOUT ANY WARRANTY; without even the implied warranty of 012MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013General Public License for more details. 014 015You should have received a copy of the GNU General Public License 016along with GNU Classpath; see the file COPYING. If not, write to the 017Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01802110-1301 USA. 019 020Linking this library statically or dynamically with other modules is 021making a combined work based on this library. Thus, the terms and 022conditions of the GNU General Public License cover the whole 023combination. 024 025As a special exception, the copyright holders of this library give you 026permission to link this library with independent modules to produce an 027executable, regardless of the license terms of these independent 028modules, and to copy and distribute the resulting executable under 029terms of your choice, provided that you also meet, for each linked 030independent module, the terms and conditions of the license of that 031module. An independent module is a module which is not derived from 032or based on this library. If you modify this library, you may extend 033this exception to your version of the library, but you are not 034obligated to do so. If you do not wish to do so, delete this 035exception statement from your version. */ 036 037 038package org.omg.DynamicAny; 039 040import org.omg.CORBA.Any; 041import org.omg.CORBA.TypeCode; 042import org.omg.DynamicAny.DynAnyPackage.InvalidValue; 043import org.omg.DynamicAny.DynAnyPackage.TypeMismatch; 044 045import java.io.Serializable; 046 047/** 048 * Defines the operations, applicable to {@link DynAny}. 049 * 050 * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org) 051 */ 052public interface DynAnyOperations 053{ 054 /** 055 * Initialises the value of this DynAny with the value, stored inside the 056 * passed DynAny, making a shallow copy. 057 * 058 * @param from the DynAny to copy from. 059 * @throws TypeMismatch if the source DynAny is invalid. 060 */ 061 void assign(DynAny from) 062 throws TypeMismatch; 063 064 /** 065 * Fully clones the content of this Any, returning a deep copy. 066 */ 067 DynAny copy(); 068 069 /** 070 * Returns the focused component of this DynAny. The DynAny has the internal 071 * pointer (reference) that can point to one of its components. The returned 072 * DynAny can be used to get or set the value of the focused component. If the 073 * DynAny holds a primitive type with no components, this implementation 074 * returns <code>null</code>. 075 * 076 * @throws TypeMismatch if called on DynAny that cannot have active 077 * components, like {@link DynEnum}. 078 */ 079 DynAny current_component() 080 throws TypeMismatch; 081 082 /** 083 * Destroys this DynAny, freeing the used resources. In java, resources are 084 * freed by the garbage collectors, so this method typically returns without 085 * action. 086 */ 087 void destroy(); 088 089 /** 090 * Makes a DynAny from the {@link Any}. The passed {@link Any} becomes the 091 * enclosed instance of this DynAny, allowing to change/traverse the 092 * {@link Any} fields by the {@link DynAny} methods. 093 * 094 * @throws TypeMismatch if the type of this DynAny differs from the type of 095 * the passed Any. The DynAny cannot be reused with the enclosed type 096 * different from that it was initially created. 097 * @throws InvalidValue if the value, stored in the passed parameter, is 098 * otherwise invalid. 099 */ 100 void from_any(Any an_any) 101 throws TypeMismatch, InvalidValue; 102 103 /** 104 * This method is used when the wrapped Any contains an instance of another 105 * Any itself. The method returns this second enclosed Any. 106 * 107 * @throws TypeMismatch if the typecode of the accessed Any is not the same as 108 * the typecode of this DynAny. 109 */ 110 Any get_any() 111 throws TypeMismatch, InvalidValue; 112 113 /** 114 * Extract the boolean value that is expected to be stored in this DynAny. 115 * 116 * @throws TypeMismatch if this DynAny holds the value of the different type. 117 */ 118 boolean get_boolean() 119 throws TypeMismatch, InvalidValue; 120 121 /** 122 * Extract the char value that is expected to be stored in this DynAny. 123 * 124 * @throws TypeMismatch if this DynAny holds the value of the different type. 125 */ 126 char get_char() 127 throws TypeMismatch, InvalidValue; 128 129 /** 130 * Extract the <code>double</code> value that is expected to be stored in 131 * this DynAny. 132 * 133 * @throws TypeMismatch if this DynAny holds the value of the different type. 134 */ 135 double get_double() 136 throws TypeMismatch, InvalidValue; 137 138 /** 139 * Extract the <code>float</code> value that is expected to be stored in 140 * this DynAny. 141 * 142 * @throws TypeMismatch if this DynAny holds the value of the different type. 143 */ 144 float get_float() 145 throws TypeMismatch, InvalidValue; 146 147 /** 148 * Extract the int (CORBA long) value that is expected to be stored in this 149 * DynAny. 150 * 151 * @throws TypeMismatch if this DynAny holds the value of the different type. 152 */ 153 int get_long() 154 throws TypeMismatch, InvalidValue; 155 156 /** 157 * Extract the long (CORBA long long) value that is expected to be stored in 158 * this DynAny. 159 * 160 * @throws TypeMismatch if this DynAny holds the value of the different type. 161 */ 162 long get_longlong() 163 throws TypeMismatch, InvalidValue; 164 165 /** 166 * Extract the byte (CORBA octet) value that is expected to be stored in this 167 * DynAny. 168 * 169 * @throws TypeMismatch if this DynAny holds the value of the different type. 170 */ 171 byte get_octet() 172 throws TypeMismatch, InvalidValue; 173 174 /** 175 * Extract the CORBA object reference that is expected to be stored in this 176 * DynAny. 177 * 178 * @throws TypeMismatch if this DynAny holds the value of the different type. 179 */ 180 org.omg.CORBA.Object get_reference() 181 throws TypeMismatch, InvalidValue; 182 183 /** 184 * Extract the <code>short</code> value that is expected to be stored in 185 * this DynAny. 186 * 187 * @throws TypeMismatch if this DynAny holds the value of the different type. 188 */ 189 short get_short() 190 throws TypeMismatch, InvalidValue; 191 192 /** 193 * Extract the string value that is expected to be stored in this DynAny. 194 * 195 * @throws TypeMismatch if this DynAny holds the value of the different type. 196 */ 197 String get_string() 198 throws TypeMismatch, InvalidValue; 199 200 /** 201 * Extract the {@link TypeCode} value that is expected to be stored in this 202 * DynAny. 203 * 204 * @throws TypeMismatch if this DynAny holds the value of the different type. 205 */ 206 TypeCode get_typecode() 207 throws TypeMismatch, InvalidValue; 208 209 /** 210 * Extract the unsigned int (CORBA ulong) value that is expected to be stored 211 * in this DynAny. 212 * 213 * @throws TypeMismatch if this DynAny holds the value of the different type. 214 */ 215 int get_ulong() 216 throws TypeMismatch, InvalidValue; 217 218 /** 219 * Extract the unsingel long (CORBA unsigned long long )value that is expected 220 * to be stored in this DynAny. 221 * 222 * @throws TypeMismatch if this DynAny holds the value of the different type. 223 */ 224 long get_ulonglong() 225 throws TypeMismatch, InvalidValue; 226 227 /** 228 * Extract the unsigned short value that is expected to be stored in this 229 * DynAny. 230 * 231 * @throws TypeMismatch if this DynAny holds the value of the different type. 232 */ 233 short get_ushort() 234 throws TypeMismatch, InvalidValue; 235 236 /** 237 * Extract the value that is expected to be stored in this DynAny. 238 * 239 * @throws TypeMismatch if this DynAny holds the value of the different type. 240 */ 241 Serializable get_val() 242 throws TypeMismatch, InvalidValue; 243 244 /** 245 * Extract the wide (usually UTF-16) character value that is expected to be 246 * stored in this DynAny. 247 * 248 * @throws TypeMismatch if this DynAny holds the value of the different type. 249 */ 250 char get_wchar() 251 throws TypeMismatch, InvalidValue; 252 253 /** 254 * Extract the wide (usually UFT-16) string that is expected to be stored in 255 * this DynAny. 256 * 257 * @throws TypeMismatch if this DynAny holds the value of the different type. 258 */ 259 String get_wstring() 260 throws TypeMismatch, InvalidValue; 261 262 /** 263 * Insert the {@link Any} value into the enclosed {@link Any} inside this 264 * DynAny. 265 * 266 * @param an_any the value being inserted. 267 * @throws InvalidValue if the value type does not match the typecode of the 268 * enclosed {@link Any}. 269 */ 270 void insert_any(Any an_any) 271 throws TypeMismatch, InvalidValue; 272 273 /** 274 * Insert the boolean value into the enclosed {@link Any} inside this DynAny 275 * 276 * @param a_x the value being inserted. 277 * @throws InvalidValue if the value type does not match the typecode of the 278 * enclosed {@link Any}. 279 */ 280 void insert_boolean(boolean a_x) 281 throws InvalidValue, TypeMismatch; 282 283 /** 284 * Insert the char value into the enclosed {@link Any} inside this DynAny 285 * 286 * @param a_x the value being inserted. 287 * @throws InvalidValue if the value type does not match the typecode of the 288 * enclosed {@link Any}. 289 */ 290 void insert_char(char a_x) 291 throws InvalidValue, TypeMismatch; 292 293 /** 294 * Insert the double value into the enclosed {@link Any} inside this DynAny 295 * 296 * @param a_x the value being inserted. 297 * @throws InvalidValue if the value type does not match the typecode of the 298 * enclosed {@link Any}. 299 */ 300 void insert_double(double a_x) 301 throws InvalidValue, TypeMismatch; 302 303 /** 304 * Insert the float value into the enclosed {@link Any} inside this DynAny 305 * 306 * @param a_x the value being inserted. 307 * @throws InvalidValue if the value type does not match the typecode of the 308 * enclosed {@link Any}. 309 */ 310 void insert_float(float a_x) 311 throws InvalidValue, TypeMismatch; 312 313 /** 314 * Insert the int (CORBA long) value into the enclosed {@link Any} inside this 315 * DynAny 316 * 317 * @param a_x the value being inserted. 318 * @throws InvalidValue if the value type does not match the typecode of the 319 * enclosed {@link Any}. 320 */ 321 void insert_long(int a_x) 322 throws InvalidValue, TypeMismatch; 323 324 /** 325 * Insert the long (CORBA long long) value into the enclosed {@link Any} 326 * inside this DynAny 327 * 328 * @param a_x the value being inserted. 329 * @throws InvalidValue if the value type does not match the typecode of the 330 * enclosed {@link Any}. 331 */ 332 void insert_longlong(long a_x) 333 throws InvalidValue, TypeMismatch; 334 335 /** 336 * Insert the byte (CORBA octet) value into the enclosed {@link Any} inside 337 * this DynAny 338 * 339 * @param a_x the value being inserted. 340 * @throws InvalidValue if the value type does not match the typecode of the 341 * enclosed {@link Any}. 342 */ 343 void insert_octet(byte a_x) 344 throws InvalidValue, TypeMismatch; 345 346 /** 347 * Insert the object reference into the enclosed {@link Any} inside this 348 * DynAny 349 * 350 * @param a_x the value being inserted. 351 * @throws InvalidValue if the value type does not match the typecode of the 352 * enclosed {@link Any}. 353 */ 354 void insert_reference(org.omg.CORBA.Object a_x) 355 throws InvalidValue, TypeMismatch; 356 357 /** 358 * Insert the <code>short</code> value into the enclosed {@link Any} inside 359 * this DynAny 360 * 361 * @param a_x the value being inserted. 362 * @throws InvalidValue if the value type does not match the typecode of the 363 * enclosed {@link Any}. 364 */ 365 void insert_short(short a_x) 366 throws InvalidValue, TypeMismatch; 367 368 /** 369 * Insert the string value into the enclosed {@link Any} inside this DynAny 370 * 371 * @param a_x the value being inserted. 372 * @throws InvalidValue if the value type does not match the typecode of the 373 * enclosed {@link Any}. 374 */ 375 void insert_string(String a_x) 376 throws InvalidValue, TypeMismatch; 377 378 /** 379 * Insert the {@link TypeCode} value into the enclosed {@link Any} inside this 380 * DynAny 381 * 382 * @param a_x the value being inserted. 383 * @throws InvalidValue if the value type does not match the typecode of the 384 * enclosed {@link Any}. 385 */ 386 void insert_typecode(TypeCode a_x) 387 throws InvalidValue, TypeMismatch; 388 389 /** 390 * Insert the int (CORBA unsinged long) value into the enclosed {@link Any} 391 * inside this DynAny 392 * 393 * @param a_x the value being inserted. 394 * @throws InvalidValue if the value type does not match the typecode of the 395 * enclosed {@link Any}. 396 */ 397 void insert_ulong(int a_x) 398 throws InvalidValue, TypeMismatch; 399 400 /** 401 * Insert the long (CORBA unsigned long long) value into the enclosed 402 * {@link Any} inside this DynAny 403 * 404 * @param a_x the value being inserted. 405 * @throws InvalidValue if the value type does not match the typecode of the 406 * enclosed {@link Any}. 407 */ 408 void insert_ulonglong(long a_x) 409 throws InvalidValue, TypeMismatch; 410 411 /** 412 * Insert the short (CORBA unsigned short) value into the enclosed {@link Any} 413 * inside this DynAny 414 * 415 * @param a_x the value being inserted. 416 * @throws InvalidValue if the value type does not match the typecode of the 417 * enclosed {@link Any}. 418 */ 419 void insert_ushort(short a_x) 420 throws InvalidValue, TypeMismatch; 421 422 /** 423 * Insert the value into the enclosed {@link Any} inside this DynAny 424 * 425 * @param a_x the value being inserted. 426 * @throws InvalidValue if the value type does not match the typecode of the 427 * enclosed {@link Any}. 428 */ 429 void insert_val(Serializable a_x) 430 throws InvalidValue, TypeMismatch; 431 432 /** 433 * Insert the wide char (usually UTF-16) value into the enclosed {@link Any} 434 * inside this DynAny 435 * 436 * @param a_x the value being inserted. 437 * @throws InvalidValue if the value type does not match the typecode of the 438 * enclosed {@link Any}. 439 */ 440 void insert_wchar(char a_x) 441 throws InvalidValue, TypeMismatch; 442 443 /** 444 * Insert the wide string (usually UTF-16) into the enclosed {@link Any} 445 * inside this DynAny 446 * 447 * @param a_x the value being inserted. 448 * @throws InvalidValue if the value type does not match the typecode of the 449 * enclosed {@link Any}. 450 */ 451 void insert_wstring(String a_x) 452 throws InvalidValue, TypeMismatch; 453 454 /** 455 * Advances the internal pointer, described in the {@link #current_component}, 456 * one position forward. 457 * 458 * @return true if the pointer now points to the new component, false if there 459 * are no more components of this DynAny holds a basic type that is not 460 * divided into components. 461 */ 462 boolean next(); 463 464 /** 465 * Moves the internal pointer, described in the {@link #current_component}, to 466 * the first component. 467 */ 468 void rewind(); 469 470 /** 471 * Moves the internal pointer, described in the {@link #current_component}, to 472 * the given position. 473 * 474 * @param p the number of the internal component on that the internal pointer 475 * must be focused. 476 * @return true on success or false if there is no component with the given 477 * number. If the DynAny holds the basic type, this method returs false p 478 * values other than 0. 479 */ 480 boolean seek(int p); 481 482 /** 483 * Returns a shallow copy of the enclosed {@link Any}, 484 * 485 * @return shallow copy of the enclosed {@link Any}. 486 */ 487 Any to_any(); 488 489 /** 490 * Returns the typecode of the object, inserted into this DynAny. 491 * 492 * @return the typecode of the inserted {@link Any} or null typecode if no 493 * {@link Any has been yet inserted}. 494 */ 495 TypeCode type(); 496 497 /** 498 * Insert a value at the current position. 499 * 500 * @param insert_it a value to insert. 501 * @throws TypeMismatch if the component at the current position has a 502 * different type. 503 * @throws InvalidValue if the current position points nowhere. 504 */ 505 void insert_dyn_any(DynAny insert_it) 506 throws TypeMismatch, InvalidValue; 507 508 /** 509 * Checks for equality with another Dynamic Any. 510 * 511 * 512 * @specnote This method is currently only implemented only for case when 513 * another DynAny was created by the factory of this implementation and is not 514 * an independent class, just implementing interface. Otherwise, a 515 * NO_IMPLEMENT minor 8148 will be thrown. General implementation is highly 516 * ineffective, but we will do if somebody would ever need it. 517 */ 518 boolean equal(DynAny other); 519 520 /** 521 * Get the number number of fields in the enclosed structure or number of 522 * memebers in the enclosed array, sequence, enumeration, etc. This method 523 * only counts elements at the top level. For instance, if invoked on a 524 * DynStruct with a single member, it returns 1, irrespective of the type of 525 * the member. 526 * 527 * @return number of components or 0 if the enclosed Any is not divideable. 528 */ 529 int component_count(); 530 531 /** 532 * Return DynAny, wrapping the second (enclosed any) that is stored in the 533 * wrapped Any. 534 * 535 * @throws TypeMismatch if the wrapped Any does not store another Any. 536 * @throws InvalidValue if the current position points nowhere. 537 */ 538 DynAny get_dyn_any() 539 throws TypeMismatch, InvalidValue; 540}