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}