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 }