gomp-20050608-branch/libjava/classpath/org/omg/CORBA/DynAny.java

   1 /* DynAny.java --
   2    Copyright (C) 2005 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package org.omg.CORBA;
  40
  41 import org.omg.CORBA.DynAnyPackage.Invalid;
  42 import org.omg.CORBA.DynAnyPackage.InvalidValue;
  43 import org.omg.CORBA.DynAnyPackage.TypeMismatch;
  44
  45 import java.io.Serializable;
  46
  47 /**
  48  * The DynAny interface provides possibility to access the components of
  49  * the CORBA object, stored inside the {@link Any}. The {@link Any} itself
  50  * allows to read, write and pass as parameter the stored value without
  51  * knowning its exact data type. The DynAny and derived classes additionally
  52  * allows to access the members of the sequence, structure, union and get the
  53  * data about enumeration, value type and CORBA <code>fixed</code> without
  54  * knowing the exact type at the run time. The returned members are also
  55  * wrapped into DynAny objects, allowing them to be the nested structures.
  56  *
  57  * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
  58  */
  59 public interface DynAny
  60   extends org.omg.CORBA.Object
  61 {
  62   /**
  63    * Copy one DynAny into another.
  64    *
  65    * @param from the DynAny to copy from.
  66    * @throws Invalid if the source DynAny is invalid.
  67    */
  68   void assign(DynAny from)
  69        throws Invalid;
  70
  71   /**
  72    * Clones this DynAny.
  73    */
  74   DynAny copy();
  75
  76   /**
  77    * Returns the focused component of this DynAny. The DynAny has the internal
  78    * pointer (reference) that can point to one of its components. The returned
  79    * DynAny can be used to get or set the value of the focused component.
  80    * If the DynAny holds a primitive type with no components, this
  81    * implementation returns <code>this</code>.
  82    */
  83   DynAny current_component();
  84
  85   /**
  86    * Destroys this DynAny, freeing the used resources. In java, resources
  87    * are freed by the garbage collectors, so this method typically returns
  88    * without action.
  89    */
  90   void destroy();
  91
  92   /**
  93    * Makes a DynAny from the {@link Any}. The passed {@link Any} becomes the
  94    * enclosed instance of this DynAny, allowing to change/traverse the
  95    * {@link Any} fields by the {@link DynAny} methods.
  96    */
  97   void from_any(Any an_any)
  98          throws Invalid;
  99
 100   /**
 101    * Retrieves the {@link Any}, stored inside this DynAny.
 102    *
 103    * @throws TypeMismatch if the typecode of the accessed Any
 104    * is not the same as the typecode of this DynAny.
 105    */
 106   Any get_any()
 107        throws TypeMismatch;
 108
 109   /**
 110    * Extract the boolean value that is expected to be
 111    * stored in this DynAny.
 112    *
 113    * @throws TypeMismatch if this DynAny holds the value of the
 114    * different type.
 115    */
 116   boolean get_boolean()
 117                throws TypeMismatch;
 118
 119   /**
 120    * Extract the char value that is expected to be
 121    * stored in this DynAny.
 122    *
 123    * @throws TypeMismatch if this DynAny holds the value of the
 124    * different type.
 125    */
 126   char get_char()
 127          throws TypeMismatch;
 128
 129   /**
 130    * Extract the <code>double</code> value that is expected to be
 131    * stored in this DynAny.
 132    *
 133    * @throws TypeMismatch if this DynAny holds the value of the
 134    * different type.
 135    */
 136   double get_double()
 137              throws TypeMismatch;
 138
 139   /**
 140    * Extract the <code>float</code> value that is expected to be
 141    * stored in this DynAny.
 142    *
 143    * @throws TypeMismatch if this DynAny holds the value of the
 144    * different type.
 145    */
 146   float get_float()
 147            throws TypeMismatch;
 148
 149   /**
 150    * Extract the int (CORBA long) value that is expected to be
 151    * stored in this DynAny.
 152    *
 153    * @throws TypeMismatch if this DynAny holds the value of the
 154    * different type.
 155    */
 156   int get_long()
 157         throws TypeMismatch;
 158
 159   /**
 160    * Extract the long (CORBA long long) value that is expected to be
 161    * stored in this DynAny.
 162    *
 163    * @throws TypeMismatch if this DynAny holds the value of the
 164    * different type.
 165    */
 166   long get_longlong()
 167              throws TypeMismatch;
 168
 169   /**
 170    * Extract the byte (CORBA octet) value that is expected to be
 171    * stored in this DynAny.
 172    *
 173    * @throws TypeMismatch if this DynAny holds the value of the
 174    * different type.
 175    */
 176   byte get_octet()
 177           throws TypeMismatch;
 178
 179   /**
 180    * Extract the CORBA object reference that is expected to be
 181    * stored in this DynAny.
 182    *
 183    * @throws TypeMismatch if this DynAny holds the value of the
 184    * different type.
 185    */
 186   Object get_reference()
 187                 throws TypeMismatch;
 188
 189   /**
 190    * Extract the <code>short</code> value that is expected to be
 191    * stored in this DynAny.
 192    *
 193    * @throws TypeMismatch if this DynAny holds the value of the
 194    * different type.
 195    */
 196   short get_short()
 197            throws TypeMismatch;
 198
 199   /**
 200    * Extract the string value that is expected to be
 201    * stored in this DynAny.
 202    *
 203    * @throws TypeMismatch if this DynAny holds the value of the
 204    * different type.
 205    */
 206   String get_string()
 207              throws TypeMismatch;
 208
 209   /**
 210    * Extract the {@link TypeCode} value that is expected to be
 211    * stored in this DynAny.
 212    *
 213    * @throws TypeMismatch if this DynAny holds the value of the
 214    * different type.
 215    */
 216   TypeCode get_typecode()
 217                  throws TypeMismatch;
 218
 219   /**
 220    * Extract the unsigned int (CORBA ulong) value that is expected to be
 221    * stored in this DynAny.
 222    *
 223    * @throws TypeMismatch if this DynAny holds the value of the
 224    * different type.
 225    */
 226   int get_ulong()
 227          throws TypeMismatch;
 228
 229   /**
 230    * Extract the unsingel long (CORBA unsigned long long )value that
 231    * is expected to be stored in this DynAny.
 232    *
 233    * @throws TypeMismatch if this DynAny holds the value of the
 234    * different type.
 235    */
 236   long get_ulonglong()
 237               throws TypeMismatch;
 238
 239   /**
 240    * Extract the unsigned short value that is expected to be
 241    * stored in this DynAny.
 242    *
 243    * @throws TypeMismatch if this DynAny holds the value of the
 244    * different type.
 245    */
 246   short get_ushort()
 247             throws TypeMismatch;
 248
 249   /**
 250    * Extract the value that is expected to be
 251    * stored in this DynAny.
 252    *
 253    * @throws TypeMismatch if this DynAny holds the value of the
 254    * different type.
 255    */
 256   Serializable get_val()
 257                 throws TypeMismatch;
 258
 259   /**
 260    * Extract the wide (usually UTF-16) character value that is expected to be
 261    * stored in this DynAny.
 262    *
 263    * @throws TypeMismatch if this DynAny holds the value of the
 264    * different type.
 265    */
 266   char get_wchar()
 267           throws TypeMismatch;
 268
 269   /**
 270    * Extract the wide (usually UFT-16) string that is expected to be
 271    * stored in this DynAny.
 272    *
 273    * @throws TypeMismatch if this DynAny holds the value of the
 274    * different type.
 275    */
 276   String get_wstring()
 277               throws TypeMismatch;
 278
 279   /**
 280    * Insert the {@link Any} value into the enclosed
 281    * {@link Any} inside this DynAny.
 282    *
 283    * @param a_x the value being inserted.
 284    * @throws InvalidValue if the value type does not match the
 285    * typecode of the enclosed {@link Any}.
 286    */
 287   void insert_any(Any an_any)
 288            throws InvalidValue;
 289
 290   /**
 291    * Insert the boolean value into the enclosed
 292    * {@link Any} inside this DynAny
 293    * @param a_x the value being inserted.
 294    * @throws InvalidValue if the value type does not match the
 295    * typecode of the enclosed {@link Any}.
 296    */
 297   void insert_boolean(boolean a_x)
 298                throws InvalidValue;
 299
 300   /**
 301    * Insert the char value into the enclosed
 302    * {@link Any} inside this DynAny
 303    * @param a_x the value being inserted.
 304    * @throws InvalidValue if the value type does not match the
 305    * typecode of the enclosed {@link Any}.
 306    */
 307   void insert_char(char a_x)
 308             throws InvalidValue;
 309
 310   /**
 311    * Insert the double value into the enclosed
 312    * {@link Any} inside this DynAny
 313    * @param a_x the value being inserted.
 314    * @throws InvalidValue if the value type does not match the
 315    * typecode of the enclosed {@link Any}.
 316    */
 317   void insert_double(double a_x)
 318               throws InvalidValue;
 319
 320   /**
 321    * Insert the float value into the enclosed
 322    * {@link Any} inside this DynAny
 323    * @param a_x the value being inserted.
 324    * @throws InvalidValue if the value type does not match the
 325    * typecode of the enclosed {@link Any}.
 326    */
 327   void insert_float(float a_x)
 328              throws InvalidValue;
 329
 330   /**
 331    * Insert the int (CORBA long) value into the enclosed
 332    * {@link Any} inside this DynAny
 333    * @param a_x the value being inserted.
 334    * @throws InvalidValue if the value type does not match the
 335    * typecode of the enclosed {@link Any}.
 336    */
 337   void insert_long(int a_x)
 338             throws InvalidValue;
 339
 340   /**
 341    * Insert the long (CORBA long long) value into the enclosed
 342    * {@link Any} inside this DynAny
 343    * @param a_x the value being inserted.
 344    * @throws InvalidValue if the value type does not match the
 345    * typecode of the enclosed {@link Any}.
 346    */
 347   void insert_longlong(long a_x)
 348                 throws InvalidValue;
 349
 350   /**
 351    * Insert the byte (CORBA octet) value into the enclosed
 352    * {@link Any} inside this DynAny
 353    * @param a_x the value being inserted.
 354    * @throws InvalidValue if the value type does not match the
 355    * typecode of the enclosed {@link Any}.
 356    */
 357   void insert_octet(byte a_x)
 358              throws InvalidValue;
 359
 360   /**
 361    * Insert the object reference into the enclosed
 362    * {@link Any} inside this DynAny
 363    * @param a_x the value being inserted.
 364    * @throws InvalidValue if the value type does not match the
 365    * typecode of the enclosed {@link Any}.
 366    */
 367   void insert_reference(Object a_x)
 368                  throws InvalidValue;
 369
 370   /**
 371    * Insert the <code>short</code> value into the enclosed
 372    * {@link Any} inside this DynAny
 373    * @param a_x the value being inserted.
 374    * @throws InvalidValue if the value type does not match the
 375    * typecode of the enclosed {@link Any}.
 376    */
 377   void insert_short(short a_x)
 378              throws InvalidValue;
 379
 380   /**
 381    * Insert the string value into the enclosed
 382    * {@link Any} inside this DynAny
 383    * @param a_x the value being inserted.
 384    * @throws InvalidValue if the value type does not match the
 385    * typecode of the enclosed {@link Any}.
 386    */
 387   void insert_string(String a_x)
 388               throws InvalidValue;
 389
 390   /**
 391    * Insert the {@link TypeCode} value into the enclosed
 392    * {@link Any} inside this DynAny
 393    * @param a_x the value being inserted.
 394    * @throws InvalidValue if the value type does not match the
 395    * typecode of the enclosed {@link Any}.
 396    */
 397   void insert_typecode(TypeCode a_x)
 398                 throws InvalidValue;
 399
 400   /**
 401    * Insert the int (CORBA unsinged long) value into the enclosed
 402    * {@link Any} inside this DynAny
 403    * @param a_x the value being inserted.
 404    * @throws InvalidValue if the value type does not match the
 405    * typecode of the enclosed {@link Any}.
 406    */
 407   void insert_ulong(int a_x)
 408              throws InvalidValue;
 409
 410   /**
 411    * Insert the long (CORBA unsigned long long) value into the enclosed
 412    * {@link Any} inside this DynAny
 413    * @param a_x the value being inserted.
 414    * @throws InvalidValue if the value type does not match the
 415    * typecode of the enclosed {@link Any}.
 416    */
 417   void insert_ulonglong(long a_x)
 418                  throws InvalidValue;
 419
 420   /**
 421    * Insert the short (CORBA unsigned short) value into the enclosed
 422    * {@link Any} inside this DynAny
 423    * @param a_x the value being inserted.
 424    * @throws InvalidValue if the value type does not match the
 425    * typecode of the enclosed {@link Any}.
 426    */
 427   void insert_ushort(short a_x)
 428               throws InvalidValue;
 429
 430   /**
 431    * Insert the value into the enclosed
 432    * {@link Any} inside this DynAny
 433    * @param a_x the value being inserted.
 434    * @throws InvalidValue if the value type does not match the
 435    * typecode of the enclosed {@link Any}.
 436    */
 437   void insert_val(Serializable a_x)
 438            throws InvalidValue;
 439
 440   /**
 441    * Insert the wide char (usually UTF-16) value into the enclosed
 442    * {@link Any} inside this DynAny
 443    * @param a_x the value being inserted.
 444    * @throws InvalidValue if the value type does not match the
 445    * typecode of the enclosed {@link Any}.
 446    */
 447   void insert_wchar(char a_x)
 448              throws InvalidValue;
 449
 450   /**
 451    * Insert the wide string (usually UTF-16) into the enclosed
 452    * {@link Any} inside this DynAny
 453    * @param a_x the value being inserted.
 454    * @throws InvalidValue if the value type does not match the
 455    * typecode of the enclosed {@link Any}.
 456    */
 457   void insert_wstring(String a_x)
 458                throws InvalidValue;
 459
 460   /**
 461    * Advances the internal pointer, described in the {@link current_component},
 462    * one position forward.
 463    *
 464    * @return true if the pointer now points to the new component,
 465    * false if there are no more components of this DynAny holds
 466    * a basic type that is not divided into components.
 467    */
 468   boolean next();
 469
 470   /**
 471    * Moves the internal pointer, described in the {@link current_component},
 472    * to the first component.
 473    */
 474   void rewind();
 475
 476   /**
 477    * Moves the internal pointer, described in the {@link current_component},
 478    * to the given position.
 479    *
 480    * @param p the number of the internal component on that the internal
 481    * pointer must be focused.
 482    *
 483    * @return true on success or false if there is no component with the
 484    * given number. If the DynAny holds the basic type, this method returs
 485    * false p values other than 0.
 486    */
 487   boolean seek(int p);
 488
 489   /**
 490    * Returns the enclosed {@link Any}.
 491    *
 492    * @return the enclosed {@link Any}.
 493    */
 494   Any to_any()
 495       throws Invalid;
 496
 497   /**
 498    * Returns the typecode of the object, inserted into this
 499    * DynAny.
 500    *
 501    * @return the typecode of the inserted {@link Any} or null typecode
 502    * if no {@link Any has been yet inserted}.
 503    */
 504   TypeCode type();
 505 }