1 /* DynAnyOperations.java -- 2 Copyright (C) 2005, 2006 Free Software Foundation, Inc. 3 This file is part of GNU Classpath. 4 5 GNU Classpath is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 2, or (at your option) 8 any later version. 9 10 GNU Classpath is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with GNU Classpath; see the file COPYING. If not, write to the 17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 18 02110-1301 USA. 19 20 Linking this library statically or dynamically with other modules is 21 making a combined work based on this library. Thus, the terms and 22 conditions of the GNU General Public License cover the whole 23 combination. 24 25 As a special exception, the copyright holders of this library give you 26 permission to link this library with independent modules to produce an 27 executable, regardless of the license terms of these independent 28 modules, and to copy and distribute the resulting executable under 29 terms of your choice, provided that you also meet, for each linked 30 independent module, the terms and conditions of the license of that 31 module. An independent module is a module which is not derived from 32 or based on this library. If you modify this library, you may extend 33 this exception to your version of the library, but you are not 34 obligated to do so. If you do not wish to do so, delete this 35 exception statement from your version. */ 36 37 38 package org.omg.DynamicAny; 39 40 import org.omg.CORBA.Any; 41 import org.omg.CORBA.TypeCode; 42 import org.omg.DynamicAny.DynAnyPackage.InvalidValue; 43 import org.omg.DynamicAny.DynAnyPackage.TypeMismatch; 44 45 import java.io.Serializable; 46 47 /** 48 * Defines the operations, applicable to {@link DynAny}. 49 * 50 * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org) 51 */ 52 public interface DynAnyOperations 53 { 54 /** 55 * Initialises the value of this DynAny with the value, stored inside the 56 * passed DynAny, making a shallow copy. 57 * 58 * @param from the DynAny to copy from. 59 * @throws TypeMismatch if the source DynAny is invalid. 60 */ assign(DynAny from)61 void assign(DynAny from) 62 throws TypeMismatch; 63 64 /** 65 * Fully clones the content of this Any, returning a deep copy. 66 */ copy()67 DynAny copy(); 68 69 /** 70 * Returns the focused component of this DynAny. The DynAny has the internal 71 * pointer (reference) that can point to one of its components. The returned 72 * DynAny can be used to get or set the value of the focused component. If the 73 * DynAny holds a primitive type with no components, this implementation 74 * returns <code>null</code>. 75 * 76 * @throws TypeMismatch if called on DynAny that cannot have active 77 * components, like {@link DynEnum}. 78 */ current_component()79 DynAny current_component() 80 throws TypeMismatch; 81 82 /** 83 * Destroys this DynAny, freeing the used resources. In java, resources are 84 * freed by the garbage collectors, so this method typically returns without 85 * action. 86 */ destroy()87 void destroy(); 88 89 /** 90 * Makes a DynAny from the {@link Any}. The passed {@link Any} becomes the 91 * enclosed instance of this DynAny, allowing to change/traverse the 92 * {@link Any} fields by the {@link DynAny} methods. 93 * 94 * @throws TypeMismatch if the type of this DynAny differs from the type of 95 * the passed Any. The DynAny cannot be reused with the enclosed type 96 * different from that it was initially created. 97 * @throws InvalidValue if the value, stored in the passed parameter, is 98 * otherwise invalid. 99 */ from_any(Any an_any)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 */ get_any()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 */ get_boolean()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 */ get_char()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 */ get_double()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 */ get_float()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 */ get_long()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 */ get_longlong()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 */ get_octet()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 */ get_reference()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 */ get_short()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 */ get_string()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 */ get_typecode()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 */ get_ulong()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 */ get_ulonglong()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 */ get_ushort()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 */ get_val()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 */ get_wchar()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 */ get_wstring()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 */ insert_any(Any an_any)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 */ insert_boolean(boolean a_x)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 */ insert_char(char a_x)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 */ insert_double(double a_x)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 */ insert_float(float a_x)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 */ insert_long(int a_x)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 */ insert_longlong(long a_x)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 */ insert_octet(byte a_x)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 */ insert_reference(org.omg.CORBA.Object a_x)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 */ insert_short(short a_x)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 */ insert_string(String a_x)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 */ insert_typecode(TypeCode a_x)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 */ insert_ulong(int a_x)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 */ insert_ulonglong(long a_x)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 */ insert_ushort(short a_x)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 */ insert_val(Serializable a_x)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 */ insert_wchar(char a_x)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 */ insert_wstring(String a_x)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 */ next()462 boolean next(); 463 464 /** 465 * Moves the internal pointer, described in the {@link #current_component}, to 466 * the first component. 467 */ rewind()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 */ seek(int p)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 */ to_any()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 */ type()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 */ insert_dyn_any(DynAny insert_it)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 */ equal(DynAny other)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 */ component_count()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 */ get_dyn_any()538 DynAny get_dyn_any() 539 throws TypeMismatch, InvalidValue; 540 } 541