gomp-20050608-branch/libjava/classpath/org/omg/DynamicAny/DynAnyOperations.java

   1 /* DynAnyOperations.java --
   2    Copyright (C) 2005 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    */
  61   void assign(DynAny from)
  62        throws TypeMismatch;
  63
  64   /**
  65    * Fully clones the content of this Any, returning a deep copy.
  66    */
  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    */
  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    */
  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    */
 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 a_x 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 }