001    /* DynAnyOperations.java --
002       Copyright (C) 2005, 2006 Free Software Foundation, Inc.
003    This file is part of GNU Classpath.
004    
005    GNU Classpath is free software; you can redistribute it and/or modify
006    it under the terms of the GNU General Public License as published by
007    the Free Software Foundation; either version 2, or (at your option)
008    any later version.
009    
010    GNU Classpath is distributed in the hope that it will be useful, but
011    WITHOUT ANY WARRANTY; without even the implied warranty of
012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013    General Public License for more details.
014    
015    You should have received a copy of the GNU General Public License
016    along with GNU Classpath; see the file COPYING.  If not, write to the
017    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
018    02110-1301 USA.
019    
020    Linking this library statically or dynamically with other modules is
021    making a combined work based on this library.  Thus, the terms and
022    conditions of the GNU General Public License cover the whole
023    combination.
024    
025    As a special exception, the copyright holders of this library give you
026    permission to link this library with independent modules to produce an
027    executable, regardless of the license terms of these independent
028    modules, and to copy and distribute the resulting executable under
029    terms of your choice, provided that you also meet, for each linked
030    independent module, the terms and conditions of the license of that
031    module.  An independent module is a module which is not derived from
032    or based on this library.  If you modify this library, you may extend
033    this exception to your version of the library, but you are not
034    obligated to do so.  If you do not wish to do so, delete this
035    exception statement from your version. */
036    
037    
038    package org.omg.DynamicAny;
039    
040    import org.omg.CORBA.Any;
041    import org.omg.CORBA.TypeCode;
042    import org.omg.DynamicAny.DynAnyPackage.InvalidValue;
043    import org.omg.DynamicAny.DynAnyPackage.TypeMismatch;
044    
045    import java.io.Serializable;
046    
047    /**
048     * Defines the operations, applicable to {@link DynAny}.
049     *
050     * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
051     */
052    public 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    }