32 --> |
32 --> |
33 </HEAD> |
33 </HEAD> |
34 <BODY BGCOLOR="#FFFFFF"> |
34 <BODY BGCOLOR="#FFFFFF"> |
35 Provides the mapping of the OMG CORBA APIs to the Java<SUP><FONT |
35 Provides the mapping of the OMG CORBA APIs to the Java<SUP><FONT |
36 SIZE=-2>TM</FONT></SUP> |
36 SIZE=-2>TM</FONT></SUP> |
37 programming language, including the class <TT>ORB</TT>, which is implemented |
37 programming language, including the class <code>ORB</code>, which is implemented |
38 so that a programmer can use it as a fully-functional Object Request Broker |
38 so that a programmer can use it as a fully-functional Object Request Broker |
39 (ORB). |
39 (ORB). |
40 |
40 |
41 <P>For a precise list of supported sections of official CORBA specifications with which |
41 <P>For a precise list of supported sections of official CORBA specifications with which |
42 the Java[TM] Platform, Standard Edition 6 complies, see <A |
42 the Java[TM] Platform, Standard Edition 6 complies, see <A |
43 HREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in |
43 HREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in |
44 Java[TM] SE 6</em></A>. |
44 Java[TM] SE 6</em></A>. |
45 |
45 |
46 |
46 |
47 <H1>General Information</H1> |
47 <H1>General Information</H1> |
48 The information in this section is information relevant to someone who |
48 The information in this section is information relevant to someone who |
49 compiles Interface Definition Language (IDL) files and uses the |
49 compiles Interface Definition Language (IDL) files and uses the |
50 ORB to write clients and servers. |
50 ORB to write clients and servers. |
51 |
51 |
52 <P>The classes and interfaces described in this section can be put into |
52 <P>The classes and interfaces described in this section can be put into |
53 four groups: <tt>ORB classes</tt>, Exceptions, <tt>Helper</tt> classes, |
53 four groups: <code>ORB classes</code>, Exceptions, <code>Helper</code> classes, |
54 and <tt>Holder</tt> classes. |
54 and <code>Holder</code> classes. |
55 |
55 |
56 <H2> |
56 <H2> |
57 The <tt>ORB</tt> Class</H2> |
57 The <code>ORB</code> Class</H2> |
58 |
58 |
59 <P>An ORB handles (or brokers) method invocations between a client and |
59 <P>An ORB handles (or brokers) method invocations between a client and |
60 the method's implementation on a server. Because the client and server |
60 the method's implementation on a server. Because the client and server |
61 may be anywhere on a network, and because the invocation and implementation |
61 may be anywhere on a network, and because the invocation and implementation |
62 may be written in different programming languages, an ORB does a great |
62 may be written in different programming languages, an ORB does a great |
63 deal of work behind the scenes to accomplish this communication. |
63 deal of work behind the scenes to accomplish this communication. |
64 |
64 |
65 <P>Most of what an ORB does is completely transparent to the user, and a major |
65 <P>Most of what an ORB does is completely transparent to the user, and a major |
66 portion of the <TT>CORBA</TT> package consists of classes used by the ORB |
66 portion of the <code>CORBA</code> package consists of classes used by the ORB |
67 behind the scenes. The result is that most programmers will use only a |
67 behind the scenes. The result is that most programmers will use only a |
68 small part of this package directly. In fact, most programmers will use |
68 small part of this package directly. In fact, most programmers will use |
69 only a few methods from the <TT>ORB</TT> class, some exceptions, and |
69 only a few methods from the <code>ORB</code> class, some exceptions, and |
70 occasionally, |
70 occasionally, |
71 a holder class. |
71 a holder class. |
72 <H3> |
72 <H3> |
73 <TT>ORB</TT> Methods</H3> |
73 <code>ORB</code> Methods</H3> |
74 |
74 |
75 <P>Before an application can enter the CORBA environment, it must first: |
75 <P>Before an application can enter the CORBA environment, it must first: |
76 <UL> |
76 <UL> |
77 <LI>Be initialized into the ORB and possibly the object adapter (POA) environments. |
77 <LI>Be initialized into the ORB and possibly the object adapter (POA) environments. |
78 <LI>Get references to ORB object (for use in future ORB operations) |
78 <LI>Get references to ORB object (for use in future ORB operations) |
79 and perhaps other objects (including the root POA or some Object Adapter objects). |
79 and perhaps other objects (including the root POA or some Object Adapter objects). |
80 </UL> |
80 </UL> |
81 <P>The following operations are provided to initialize applications and obtain |
81 <P>The following operations are provided to initialize applications and obtain |
82 the appropriate object references: |
82 the appropriate object references: |
83 <UL> |
83 <UL> |
84 <LI>Operations providing access to the ORB, which are discussed in this |
84 <LI>Operations providing access to the ORB, which are discussed in this |
85 section. |
85 section. |
86 <LI>Operations providing access to Object Adapters, Interface Repository, |
86 <LI>Operations providing access to Object Adapters, Interface Repository, |
87 Naming Service, and other Object Services. These operations are described |
87 Naming Service, and other Object Services. These operations are described |
88 in <a href="#adv"><em>Other Classes</em></a>. |
88 in <a href="#adv"><em>Other Classes</em></a>. |
89 </UL> |
89 </UL> |
90 <P> |
90 <P> |
91 When an application requires a CORBA environment it needs a mechanism to |
91 When an application requires a CORBA environment it needs a mechanism to |
92 get an ORB object reference and possibly an OA object reference |
92 get an ORB object reference and possibly an OA object reference |
93 (such as the root POA). This serves two purposes. First, it initializes |
93 (such as the root POA). This serves two purposes. First, it initializes |
94 an application into the ORB and OA environments. Second, it returns the |
94 an application into the ORB and OA environments. Second, it returns the |
95 ORB object reference and the OA object reference to the application |
95 ORB object reference and the OA object reference to the application |
96 for use in future ORB and OA operations. |
96 for use in future ORB and OA operations. |
97 |
97 |
98 <P>In order to obtain an ORB object reference, applications call |
98 <P>In order to obtain an ORB object reference, applications call |
99 the <tt>ORB.init</tt> operation. The parameters to the call can comprise an |
99 the <code>ORB.init</code> operation. The parameters to the call can comprise an |
100 identifier for the ORB for which the object reference is required, |
100 identifier for the ORB for which the object reference is required, |
101 and an arg_list, which is used to allow environment-specific data to be |
101 and an arg_list, which is used to allow environment-specific data to be |
102 passed into the call. |
102 passed into the call. |
103 |
103 |
104 <P>These are the <TT>ORB</TT> methods |
104 <P>These are the <code>ORB</code> methods |
105 that provide access to the ORB: |
105 that provide access to the ORB: |
106 <UL> |
106 <UL> |
107 <LI> |
107 <LI> |
108 <TT><b>init</b>()</TT> |
108 <code><b>init</b>()</code> |
109 |
109 |
110 <LI> |
110 <LI> |
111 <TT><b>init</b>(String [] args, Properties props)</TT> |
111 <code><b>init</b>(String [] args, Properties props)</code> |
112 |
112 |
113 <LI> |
113 <LI> |
114 <TT><b>init</b>(Applet app, Properties props)</TT> |
114 <code><b>init</b>(Applet app, Properties props)</code> |
115 </UL> |
115 </UL> |
116 |
116 |
117 <P>Using the <tt>init()</tt> method without parameters initiates |
117 <P>Using the <code>init()</code> method without parameters initiates |
118 a singleton ORB, which can only |
118 a singleton ORB, which can only |
119 give typecode creation <tt>any</tt>s needed in code generated |
119 give typecode creation <code>any</code>s needed in code generated |
120 in Helper classes by <tt>idlj</tt>. |
120 in Helper classes by <code>idlj</code>. |
121 |
121 |
122 <P>Applications require a portable means by which to obtain their |
122 <P>Applications require a portable means by which to obtain their |
123 initial object references. References are required for the root |
123 initial object references. References are required for the root |
124 POA, POA Current, Interface Repository, and various Object Services |
124 POA, POA Current, Interface Repository, and various Object Services |
125 instances. The functionality required by the application is similar |
125 instances. The functionality required by the application is similar |
126 to that provided by the Naming Service. However, the OMG does not |
126 to that provided by the Naming Service. However, the OMG does not |
127 want to mandate that the Naming Service be made available to all |
127 want to mandate that the Naming Service be made available to all |
128 applications in order that they may be portably initialized. |
128 applications in order that they may be portably initialized. |
129 Consequently, the operations shown in this section provide a |
129 Consequently, the operations shown in this section provide a |
130 simplified, local version of the Naming Service that applications |
130 simplified, local version of the Naming Service that applications |
131 can use to obtain a small, defined set of object references which |
131 can use to obtain a small, defined set of object references which |
132 are essential to its operation. Because only a small well-defined |
132 are essential to its operation. Because only a small well-defined |
133 set of objects are expected with this mechanism, the naming context |
133 set of objects are expected with this mechanism, the naming context |
134 can be flattened to be a single-level name space. This simplification |
134 can be flattened to be a single-level name space. This simplification |
135 results in only two operations being defined to achieve the functionality |
135 results in only two operations being defined to achieve the functionality |
136 required. |
136 required. |
137 |
137 |
138 <P>Initial references are obtained via two operations provided in |
138 <P>Initial references are obtained via two operations provided in |
139 the ORB object interface, providing facilities to list and |
139 the ORB object interface, providing facilities to list and |
140 resolve initial object references. These are: |
140 resolve initial object references. These are: |
141 <UL> |
141 <UL> |
142 <LI> |
142 <LI> |
143 <TT><b>resolve_initial_references</b>(String name)</TT> |
143 <code><b>resolve_initial_references</b>(String name)</code> |
144 <LI> |
144 <LI> |
145 <TT><b>list_initial_services</b>()</TT> |
145 <code><b>list_initial_services</b>()</code> |
146 <LI> |
146 <LI> |
147 <TT><b>register_initial_reference</b>(String id, |
147 <code><b>register_initial_reference</b>(String id, org.omg.CORBA.Object obj)</code> |
148 org.omg.CORBA.Object obj)</TT> |
148 </UL> |
149 </UL> |
149 |
150 |
150 <P>An example that uses some of these methods is <A |
151 <P>An example that uses some of these methods is <A |
|
152 HREF="{@docRoot}/../technotes/guides/idl/GShome.html"> |
151 HREF="{@docRoot}/../technotes/guides/idl/GShome.html"> |
153 <em>Getting Started with Java IDL</em></A>. |
152 <em>Getting Started with Java IDL</em></A>. |
154 |
153 |
155 <H2> |
154 <H2> |
156 Exceptions</H2> |
155 Exceptions</H2> |
157 Exceptions in Java IDL are similar to those in any code written in the |
156 Exceptions in Java IDL are similar to those in any code written in the |
158 Java programming language. If a method is defined to throw an exception, |
157 Java programming language. If a method is defined to throw an exception, |
159 then any code using that method must have a <TT>try</TT>/<TT>catch</TT> |
158 then any code using that method must have a <code>try</code>/<code>catch</code> |
160 block and handle that exception when it is thrown. |
159 block and handle that exception when it is thrown. |
161 |
160 |
162 <P>The documentation on <A |
161 <P>The documentation on <A |
163 HREF="{@docRoot}/../technotes/guides/idl/jidlExceptions.html"><em>Java |
162 HREF="{@docRoot}/../technotes/guides/idl/jidlExceptions.html"><em>Java |
164 IDL exceptions</em></A> has more information and explains the difference between |
163 IDL exceptions</em></A> has more information and explains the difference between |
165 system exceptions and user-defined exceptions. |
164 system exceptions and user-defined exceptions. |
166 |
165 |
167 <P>The following is a list of the system exceptions (which are unchecked |
166 <P>The following is a list of the system exceptions (which are unchecked |
168 exceptions inheriting through <TT><a href="SystemException.html"> |
167 exceptions inheriting through <code><a href="SystemException.html"> |
169 org.omg.CORBA.SystemException</a></TT> from |
168 org.omg.CORBA.SystemException</a></code> from |
170 <TT>java.lang.RuntimeException</TT>) that are defined in the package |
169 <code>java.lang.RuntimeException</code>) that are defined in the package |
171 <TT>org.omg.CORBA</TT>: |
170 <code>org.omg.CORBA</code>: |
172 <PRE><code> |
171 <PRE><code> |
173 BAD_CONTEXT |
172 BAD_CONTEXT |
174 BAD_INV_ORDER |
173 BAD_INV_ORDER |
175 BAD_OPERATION |
174 BAD_OPERATION |
176 BAD_PARAM |
175 BAD_PARAM |
201 TRANSIENT |
200 TRANSIENT |
202 UNKNOWN |
201 UNKNOWN |
203 </code></PRE> |
202 </code></PRE> |
204 <P> |
203 <P> |
205 The following is a list of user-defined exceptions defined in the package |
204 The following is a list of user-defined exceptions defined in the package |
206 <TT>org.omg.CORBA</TT>. |
205 <code>org.omg.CORBA</code>. |
207 <PRE><code> |
206 <PRE><code> |
208 Bounds |
207 Bounds |
209 UnknownUserException |
208 UnknownUserException |
210 WrongTransaction |
209 WrongTransaction |
211 PolicyError |
210 PolicyError |
212 </code></PRE> |
211 </code></PRE> |
213 |
212 |
214 <H2>Subpackages</H2> |
213 <H2>Subpackages</H2> |
215 There are some packages inside the <TT>CORBA</TT> package with |
214 There are some packages inside the <code>CORBA</code> package with |
216 "Package" as part of their names. These packages are generally quite small |
215 "Package" as part of their names. These packages are generally quite small |
217 because all they do is provide exceptions or classes for use by interfaces |
216 because all they do is provide exceptions or classes for use by interfaces |
218 and classes in the <TT>CORBA</TT> package. |
217 and classes in the <code>CORBA</code> package. |
219 |
218 |
220 <P>For example, the package <TT><a href="TypeCodePackage/package-summary.html"> |
219 <P>For example, the package <code><a href="TypeCodePackage/package-summary.html"> |
221 org.omg.CORBA.TypeCodePackage</a></TT> contains |
220 org.omg.CORBA.TypeCodePackage</a></code> contains |
222 two exceptions thrown by methods in the class <TT>TypeCode</TT>. These |
221 two exceptions thrown by methods in the class <code>TypeCode</code>. These |
223 exceptions are: |
222 exceptions are: |
224 <UL> |
223 <UL> |
225 <LI> |
224 <LI> |
226 <TT>BadKind</TT> |
225 <code>BadKind</code> |
227 |
226 |
228 <LI> |
227 <LI> |
229 <TT>Bounds</TT> |
228 <code>Bounds</code> |
230 </UL> |
229 </UL> |
231 The package <TT><a href="ORBPackage/package-summary.html"> |
230 The package <code><a href="ORBPackage/package-summary.html"> |
232 org.omg.CORBA.ORBPackage</a></TT> contains two exceptions: |
231 org.omg.CORBA.ORBPackage</a></code> contains two exceptions: |
233 <UL> |
232 <UL> |
234 <LI> |
233 <LI> |
235 <TT>InvalidName</TT> |
234 <code>InvalidName</code> |
236 |
235 |
237 <LI> |
236 <LI> |
238 <TT>InconsistentTypeCode</TT> |
237 <code>InconsistentTypeCode</code> |
239 </UL> |
238 </UL> |
240 |
239 |
241 <P>Another package that is a subpackage of <tt>CORBA</tt> is the <tt> |
240 <P>Another package that is a subpackage of <code>CORBA</code> is the |
242 <a href="portable/package-summary.html">portable</a></tt> package. It |
241 <code><a href="portable/package-summary.html">portable</a></code> |
243 provides a set of ORB APIs that makes it |
242 package. It provides a set of ORB APIs that makes it |
244 possible for code generated by one vendor's IDL compiler to run |
243 possible for code generated by one vendor's IDL compiler to run |
245 on another vendor's ORB. |
244 on another vendor's ORB. |
246 |
245 |
247 |
246 |
248 |
247 |
249 |
248 |
250 <H2> |
249 <H2> |
251 Holder classes</H2> |
250 Holder classes</H2> |
252 |
251 |
253 |
252 |
254 <P>Support for out and inout parameter passing modes requires the use of |
253 <P>Support for out and inout parameter passing modes requires the use of |
255 additional <em><a href="doc-files/generatedfiles.html#holder">holder |
254 additional <em><a href="doc-files/generatedfiles.html#holder">holder |
256 classes</a></em>. Because the Java programming language does not support out or |
255 classes</a></em>. Because the Java programming language does not support out or |
257 inout parameters, holder classes are needed as a means of passing a parameter |
256 inout parameters, holder classes are needed as a means of passing a parameter |
258 that can be modified. To support portable stubs and skeletons, holder classes also implement |
257 that can be modified. To support portable stubs and skeletons, |
259 the <tt><a href="portable/Streamable.html">org.omg.CORBA.portable.Streamable</a> |
258 holder classes also implement the |
260 </tt> interface. |
259 <code><a href="portable/Streamable.html">org.omg.CORBA.portable.Streamable</a></code> |
|
260 interface. |
261 |
261 |
262 <P>Holder classes are named by appending "Holder" to the name of the type. |
262 <P>Holder classes are named by appending "Holder" to the name of the type. |
263 The name of the type refers to its name in the Java programming language. For |
263 The name of the type refers to its name in the Java programming language. For |
264 example, a holder class for the interface named <tt>Account</tt> in the Java programming |
264 example, a holder class for the interface named <code>Account</code> |
265 language would be named <tt>AccountHolder</tt>. |
265 in the Java programming |
|
266 language would be named <code>AccountHolder</code>. |
266 |
267 |
267 |
268 |
268 <P>Holder classes are available for all of the basic IDL |
269 <P>Holder classes are available for all of the basic IDL |
269 datatypes in the <tt>org.omg.CORBA</tt> package. So, for example, |
270 datatypes in the <code>org.omg.CORBA</code> package. So, for example, |
270 there are already-defined classes for <tt>LongHolder</tt>, <tt>ShortHolder</tt>, |
271 there are already-defined classes for <code>LongHolder</code>, <code>ShortHolder</code>, |
271 <tt>FloatHolder</tt>, and so on. Classes are also generated for |
272 <code>FloatHolder</code>, and so on. Classes are also generated for |
272 all named user-defined IDL types except those defined by <tt>typedefs</tt>. |
273 all named user-defined IDL types except those defined by <code>typedefs</code>. |
273 (Note that in this context user defined includes types that are |
274 (Note that in this context user defined includes types that are |
274 defined in OMG specifications such as those for the Interface |
275 defined in OMG specifications such as those for the Interface |
275 Repository, and other OMG services.) |
276 Repository, and other OMG services.) |
276 |
277 |
277 |
278 |
278 <P>Each holder class has: |
279 <P>Each holder class has: |
279 <UL> |
280 <UL> |
280 <LI>a constructor from an instance |
281 <LI>a constructor from an instance |
281 <LI>a default constructor |
282 <LI>a default constructor |
282 <LI>a public instance member, <tt>value</tt> which is the typed value. |
283 <LI>a public instance member, <code>value</code> which is the typed value. |
283 <LI>a method for reading an input stream and assigning the contents to the |
284 <LI>a method for reading an input stream and assigning the contents to the |
284 type's <tt>value</tt> field |
285 type's <code>value</code> field |
285 <LI>a method for writing the value of the <tt>value</tt> field to an output stream |
286 <LI>a method for writing the value of the <code>value</code> field to an output stream |
286 <LI>a method for getting the typecode of the type |
287 <LI>a method for getting the typecode of the type |
287 </UL> |
288 </UL> |
288 |
289 |
289 <P>The default constructor sets the value field to the default value for the |
290 <P>The default constructor sets the value field to the default value for the |
290 type as defined by the Java language: |
291 type as defined by the Java language: |
291 <UL> |
292 <UL> |
292 <LI><tt>false</tt> for boolean |
293 <LI><code>false</code> for boolean |
293 <LI><tt>0</tt> for numeric and char types |
294 <LI><code>0</code> for numeric and char types |
294 <LI><tt>null</tt> for strings and object references |
295 <LI><code>null</code> for strings and object references |
295 </UL> |
296 </UL> |
296 |
297 |
297 |
298 |
298 |
299 |
299 <P> |
300 <P> |
300 As an example, if the interface <code>Account</code>, defined in OMG IDL, |
301 As an example, if the interface <code>Account</code>, defined in OMG IDL, |
301 were mapped to the Java programming language, the following holder class |
302 were mapped to the Java programming language, the following holder class |
302 would be generated: |
303 would be generated: |
303 <PRE> |
304 <PRE> |
304 public final class AccountHolder implements |
305 public final class AccountHolder implements |
305 org.omg.CORBA.portable.Streamable |
306 org.omg.CORBA.portable.Streamable |
306 { |
307 { |
307 // field that holds an Account object |
308 // field that holds an Account object |
308 public Account value = null; |
309 public Account value = null; |
309 |
310 |
340 </PRE> |
341 </PRE> |
341 |
342 |
342 <P>For more information on Holder classes, see Chapter 1.4, <em>Mapping for |
343 <P>For more information on Holder classes, see Chapter 1.4, <em>Mapping for |
343 Basic Types</em> in the <a href="http://www.omg.org/cgi-bin/doc?ptc/00-01-08"> |
344 Basic Types</em> in the <a href="http://www.omg.org/cgi-bin/doc?ptc/00-01-08"> |
344 <em>OMG IDL to Java Language Mapping</em></a>. The Holder classes defined |
345 <em>OMG IDL to Java Language Mapping</em></a>. The Holder classes defined |
345 in the package <TT>org.omg.CORBA</TT> are: |
346 in the package <code>org.omg.CORBA</code> are: |
346 <PRE> |
347 <PRE><code> |
347 <TT>AnyHolder |
348 AnyHolder |
348 </TT> <TT>AnySeqHolder |
349 AnySeqHolder |
349 </TT> <TT>BooleanHolder |
350 BooleanHolder |
350 </TT> <TT>BooleanSeqHolder |
351 BooleanSeqHolder |
351 </TT> <TT>ByteHolder |
352 ByteHolder |
352 </TT> <TT>CharHolder |
353 CharHolder |
353 </TT> <TT>CharSeqHolder |
354 CharSeqHolder |
354 </TT> <TT>CurrentHolder |
355 CurrentHolder |
355 </TT> <TT>DoubleHolder |
356 DoubleHolder |
356 </TT> <TT>DoubleSeqHolder |
357 DoubleSeqHolder |
357 </TT> <TT>FixedHolder |
358 FixedHolder |
358 </TT> <TT>FloatHolder |
359 FloatHolder |
359 </TT> <TT>FloatSeqHolder |
360 FloatSeqHolder |
360 </TT> <TT>IntHolder |
361 IntHolder |
361 </TT> <TT>LongHolder |
362 LongHolder |
362 </TT> <TT>LongLongSeqHolder |
363 LongLongSeqHolder |
363 </TT> <TT>LongSeqHolder |
364 LongSeqHolder |
364 </TT> <TT>ObjectHolder |
365 ObjectHolder |
365 </TT> <TT>OctetSeqHolder |
366 OctetSeqHolder |
366 </TT> <TT>ParameterModeHolder |
367 ParameterModeHolder |
367 </TT> <TT>PolicyErrorHolder |
368 PolicyErrorHolder |
368 </TT> <TT>PolicyListHolder |
369 PolicyListHolder |
369 </TT> <TT>PrincipalHolder |
370 PrincipalHolder |
370 </TT> <TT>ServiceInformationHolder |
371 ServiceInformationHolder |
371 </TT> <TT>ShortHolder |
372 ShortHolder |
372 </TT> <TT>ShortSeqHolder |
373 ShortSeqHolder |
373 </TT> <TT>StringHolder |
374 StringHolder |
374 </TT> <TT>StringSeqHolder |
375 StringSeqHolder |
375 </TT> <TT>TypeCodeHolder |
376 TypeCodeHolder |
376 </TT> <TT>ULongLongSeqHolder |
377 ULongLongSeqHolder |
377 </TT> <TT>ULongSeqHolder |
378 ULongSeqHolder |
378 </TT> <TT>UnknownUserExceptionHolder |
379 UnknownUserExceptionHolder |
379 </TT> <TT>UShortSeqHolder |
380 UShortSeqHolder |
380 </TT> <TT>ValueBaseHolder |
381 ValueBaseHolder |
381 </TT> <TT>WCharSeqHolder |
382 WCharSeqHolder |
382 </TT> <TT>WrongTransactionHolder |
383 WrongTransactionHolder |
383 </TT> <TT>WStringSeqHolder</TT> |
384 WStringSeqHolder |
384 |
385 </code></PRE> |
385 </PRE> |
|
386 |
386 |
387 <h2>Helper Classes </h2> |
387 <h2>Helper Classes </h2> |
388 <P>Helper files supply several static methods needed to manipulate the type. |
388 <P>Helper files supply several static methods needed to manipulate the type. |
389 These include: |
389 These include: |
390 <UL> |
390 <UL> |
391 <LI><tt>Any</tt> insert and extract operations for the type |
391 <LI><code>Any</code> insert and extract operations for the type |
392 <LI>getting the repository id |
392 <LI>getting the repository id |
393 <LI>getting the typecode |
393 <LI>getting the typecode |
394 <LI>reading and writing the type from and to a stream |
394 <LI>reading and writing the type from and to a stream |
395 <LI>implement the <code>ValueHelper</code> interface (if it is a user-defined |
395 <LI>implement the <code>ValueHelper</code> interface (if it is a user-defined |
396 value type) |
396 value type) |
397 </UL> |
397 </UL> |
398 |
398 |
399 <P>The helper class for a mapped IDL interface or abstract interface |
399 <P>The helper class for a mapped IDL interface or abstract interface |
400 also include narrow operation(s). The static narrow method allows |
400 also include narrow operation(s). The static narrow method allows |
401 an <tt>org.omg.CORBA.Object</tt> to be narrowed to the object reference |
401 an <code>org.omg.CORBA.Object</code> to be narrowed to the object reference |
402 of a more specific type. The IDL exception <tt>CORBA.BAD_PARAM</tt> |
402 of a more specific type. The IDL exception <code>CORBA.BAD_PARAM</code> |
403 is thrown if the narrow fails because the object reference does not |
403 is thrown if the narrow fails because the object reference does not |
404 support the requested type. A different system exception is raised |
404 support the requested type. A different system exception is raised |
405 to indicate other kinds of errors. Trying to narrow a <tt>null</tt> will always |
405 to indicate other kinds of errors. Trying to narrow a <code>null</code> will always |
406 succeed with a return value of <tt>null</tt>. Generally, the only helper method an application programmer uses is |
406 succeed with a return value of <code>null</code>. |
|
407 Generally, the only helper method an application programmer uses is |
407 the <code>narrow</code> method. The other methods are normally used behind |
408 the <code>narrow</code> method. The other methods are normally used behind |
408 the scenes and are transparent to the programmer. |
409 the scenes and are transparent to the programmer. |
409 |
410 |
410 <P>Helper classes |
411 <P>Helper classes |
411 fall into two broad categories, <a href="#value">helpers for value types</a> and |
412 fall into two broad categories, <a href="#value">helpers for value types</a> and |
412 <a href="#basic">helpers for non value types</a>. Because all of the helper |
413 <a href="#basic">helpers for non value types</a>. Because all of the helper |
413 classes in one category |
414 classes in one category |
414 provide the same methods, one generic explanation of each |
415 provide the same methods, one generic explanation of each |
415 category of helper classes is presented here. |
416 category of helper classes is presented here. |
416 |
417 |
417 <P> |
418 <P> |
418 When OMG IDL is mapped to the Java programming language, |
419 When OMG IDL is mapped to the Java programming language, |
419 a "helper" class is generated for each user-defined type. |
420 a "helper" class is generated for each user-defined type. |
420 This generated class will have the name of the user-defined type with |
421 This generated class will have the name of the user-defined type with |
421 the suffix <code>Helper</code> appended. For example, if the |
422 the suffix <code>Helper</code> appended. For example, if the |
422 interface <code>Account</code> is defined in OMG IDL, the |
423 interface <code>Account</code> is defined in OMG IDL, the |
423 <code>idlj</code> compiler will automatically generate a class named |
424 <code>idlj</code> compiler will automatically generate a class named |
424 <code>AccountHelper</code>. The <code>AccountHelper</code> class |
425 <code>AccountHelper</code>. The <code>AccountHelper</code> class |
425 will contain the static methods needed for manipulating instances of the type, |
426 will contain the static methods needed for manipulating instances of the type, |
426 in this case, <code>Account</code> objects. |
427 in this case, <code>Account</code> objects. |
427 |
428 |
428 |
429 |
429 <a name="narrow"></a> |
430 <a name="narrow"></a> |
430 <h3>The <code>narrow</code> Method</h3> |
431 <h3>The <code>narrow</code> Method</h3> |
431 When an object is the return value for a method, it is returned in the |
432 When an object is the return value for a method, it is returned in the |
624 |
623 |
625 |
624 |
626 } |
625 } |
627 </pre> |
626 </pre> |
628 |
627 |
629 <P>The Helper classes defined in the package <TT>org.omg.CORBA</TT> are: |
628 <P>The Helper classes defined in the package <code>org.omg.CORBA</code> are: |
630 <PRE><code> |
629 <PRE><code> |
631 <TT>AnySeqHelper |
630 AnySeqHelper |
632 </TT> <TT>BooleanSeqHelper |
631 BooleanSeqHelper |
633 </TT> <TT>CharSeqHelper |
632 CharSeqHelper |
634 </TT> <TT>CompletionStatusHelper |
633 CompletionStatusHelper |
635 </TT> <TT>CurrentHelper |
634 CurrentHelper |
636 </TT> <TT>DefinitionKindHelper |
635 DefinitionKindHelper |
637 </TT> <TT>DoubleSeqHelper |
636 DoubleSeqHelper |
638 </TT> <TT>FieldNameHelper |
637 FieldNameHelper |
639 </TT> <TT>FloatSeqHelper |
638 FloatSeqHelper |
640 </TT> <TT>IdentifierHelper |
639 IdentifierHelper |
641 </TT> <TT>IDLTypeHelper |
640 IDLTypeHelper |
642 </TT> <TT>LongLongSeqHelper |
641 LongLongSeqHelper |
643 </TT> <TT>LongSeqHelper |
642 LongSeqHelper |
644 </TT> <TT>NameValuePairHelper |
643 NameValuePairHelper |
645 </TT> <TT>ObjectHelper |
644 ObjectHelper |
646 </TT> <TT>OctetSeqHelper |
645 OctetSeqHelper |
647 </TT> <TT>ParameterModeHelper |
646 ParameterModeHelper |
648 </TT> <TT>PolicyErrorCodeHelper |
647 PolicyErrorCodeHelper |
649 </TT> <TT>PolicyErrorHelper |
648 PolicyErrorHelper |
650 </TT> <TT>PolicyHelper |
649 PolicyHelper |
651 </TT> <TT>PolicyListHelper |
650 PolicyListHelper |
652 </TT> <TT>PolicyTypeHelper |
651 PolicyTypeHelper |
653 </TT> <TT>RepositoryIdHelper |
652 RepositoryIdHelper |
654 </TT> <TT>ServiceDetailHelper |
653 ServiceDetailHelper |
655 </TT> <TT>ServiceInformationHelper |
654 ServiceInformationHelper |
656 </TT> <TT>SetOverrideTypeHelper |
655 SetOverrideTypeHelper |
657 </TT> <TT>ShortSeqHelper |
656 ShortSeqHelper |
658 </TT> <TT>StringSeqHelper |
657 StringSeqHelper |
659 </TT> <TT>StringValueHelper |
658 StringValueHelper |
660 </TT> <TT>StructMemberHelper |
659 StructMemberHelper |
661 </TT> <TT>ULongLongSeqHelper |
660 ULongLongSeqHelper |
662 </TT> <TT>ULongSeqHelper |
661 ULongSeqHelper |
663 </TT> <TT>UnionMemberHelper |
662 UnionMemberHelper |
664 </TT> <TT>UnknownUserExceptionHelper |
663 UnknownUserExceptionHelper |
665 </TT> <TT>UShortSeqHelper |
664 UShortSeqHelper |
666 </TT> <TT>ValueBaseHelper |
665 ValueBaseHelper |
667 </TT> <TT>ValueMemberHelper |
666 ValueMemberHelper |
668 </TT> <TT>VersionSpecHelper |
667 VersionSpecHelper |
669 </TT> <TT>VisibilityHelper |
668 VisibilityHelper |
670 </TT> <TT>WCharSeqHelper |
669 WCharSeqHelper |
671 </TT> <TT>WrongTransactionHelper |
670 WrongTransactionHelper |
672 </TT> <TT>WStringSeqHelper |
671 WStringSeqHelper |
673 </TT> <TT>WStringValueHelper</TT> |
672 WStringValueHelper |
674 |
|
675 </code></PRE> |
673 </code></PRE> |
676 <a name="adv"></a> |
674 <a name="adv"></a> |
677 <H1> |
675 <H1> |
678 Other Classes</H1> |
676 Other Classes</H1> |
679 The other classes and interfaces in the <TT>CORBA</TT> package, which are |
677 The other classes and interfaces in the <code>CORBA</code> package, which are |
680 used behind the scenes, can be put into four groups. Three of the groups |
678 used behind the scenes, can be put into four groups. Three of the groups |
681 are used with requests in some capacity, and the fourth group, concerning |
679 are used with requests in some capacity, and the fourth group, concerning |
682 the Interface Repository, is a category by itself. |
680 the Interface Repository, is a category by itself. |
683 <H2> |
681 <H2> |
684 Classes Created by an ORB</H2> |
682 Classes Created by an ORB</H2> |
685 The first group contains classes that are created by an ORB and contain |
683 The first group contains classes that are created by an ORB and contain |
686 information used in request operations. |
684 information used in request operations. |
687 <UL> |
685 <UL> |
688 <LI> |
686 <LI> |
689 <TT>TCKind</TT> -- indicates the kind (datatype) for a <TT>TypeCode</TT> |
687 <code>TCKind</code> -- indicates the kind (datatype) for a <code>TypeCode</code> |
690 object |
688 object |
691 |
689 |
692 <LI> |
690 <LI> |
693 <TT>TypeCode</TT> -- indicates a datatype and possibly other information |
691 <code>TypeCode</code> -- indicates a datatype and possibly other information |
694 |
692 |
695 <LI> |
693 <LI> |
696 <TT>Any</TT> -- contains a value and its typecode |
694 <code>Any</code> -- contains a value and its typecode |
697 |
695 |
698 <LI> |
696 <LI> |
699 <TT>NamedValue</TT> -- contains a name, an <TT>Any</TT> object, and an |
697 <code>NamedValue</code> -- contains a name, an <code>Any</code> object, and an |
700 argument mode flag. <TT>NamedValue</TT> objects contain information about |
698 argument mode flag. <code>NamedValue</code> objects contain information about |
701 method arguments, method return values, or a context. |
699 method arguments, method return values, or a context. |
702 |
700 |
703 <LI> |
701 <LI> |
704 <TT>ContextList</TT> -- a list of strings that describe the contexts that |
702 <code>ContextList</code> -- a list of strings that describe the contexts that |
705 need to be resolved and sent with an invocation |
703 need to be resolved and sent with an invocation |
706 |
704 |
707 <LI> |
705 <LI> |
708 <TT>ExceptionList</TT> -- a list of <TT>TypeCode</TT>s for exceptions that |
706 <code>ExceptionList</code> -- a list of <code>TypeCode</code>s for exceptions that |
709 may be thrown by a method |
707 may be thrown by a method |
710 |
708 |
711 <LI> |
709 <LI> |
712 <TT>Environment</TT> -- a container for the exception thrown during a method |
710 <code>Environment</code> -- a container for the exception thrown during a method |
713 invocation |
711 invocation |
714 |
712 |
715 <LI> |
713 <LI> |
716 <TT>Context</TT> -- a list of <TT>NamedValue</TT> objects used to pass |
714 <code>Context</code> -- a list of <code>NamedValue</code> objects used to pass |
717 auxiliary information from client to server |
715 auxiliary information from client to server |
718 |
716 |
719 <LI> |
717 <LI> |
720 <TT>NVList</TT> -- a list of <TT>NamedValue</TT> objects, used to pass |
718 <code>NVList</code> -- a list of <code>NamedValue</code> objects, used to pass |
721 arguments or get results |
719 arguments or get results |
722 </UL> |
720 </UL> |
723 |
721 |
724 <H2> |
722 <H2> |
725 Classes That Deal with Requests</H2> |
723 Classes That Deal with Requests</H2> |
726 The second group of classes deals with requests: |
724 The second group of classes deals with requests: |
727 <UL> |
725 <UL> |
728 <LI> |
726 <LI> |
729 <TT>Object</TT> -- the base class for all CORBA object references |
727 <code>Object</code> -- the base class for all CORBA object references |
730 |
728 |
731 <LI> |
729 <LI> |
732 <TT>Request</TT> -- the main class in the DII, which contains methods for |
730 <code>Request</code> -- the main class in the DII, which contains methods for |
733 adding arguments to the request, for accessing information about the method |
731 adding arguments to the request, for accessing information about the method |
734 being invoked (the method name, its arguments, exceptions it throws, and |
732 being invoked (the method name, its arguments, exceptions it throws, and |
735 so on), and for making invocations on the request |
733 so on), and for making invocations on the request |
736 |
734 |
737 <LI> |
735 <LI> |
738 <TT>DynamicImplementation</TT> -- the base class for server implementations |
736 <code>DynamicImplementation</code> -- the base class for server implementations |
739 using the DSI. It has the method <TT>invoke</TT>, which is used by an |
737 using the DSI. It has the method <code>invoke</code>, which is used by an |
740 implementation |
738 implementation |
741 of this class to determine the state of a <TT>ServerRequest</TT> object |
739 of this class to determine the state of a <code>ServerRequest</code> object |
742 and to set its result or exception |
740 and to set its result or exception |
743 |
741 |
744 <LI> |
742 <LI> |
745 <TT>ServerRequest</TT> -- captures the explicit state of a request for |
743 <code>ServerRequest</code> -- captures the explicit state of a request for |
746 the Dynamic Skeleton Interface |
744 the Dynamic Skeleton Interface |
747 </UL> |
745 </UL> |
748 |
746 |
749 <H2> |
747 <H2> |
750 Interfaces That Serve as Constants</H2> |
748 Interfaces That Serve as Constants</H2> |
751 The third group contains interfaces that serve as constants. The IDL-to-Java |
749 The third group contains interfaces that serve as constants. The IDL-to-Java |
752 mapping mandates that IDL enums are mapped to a Java class with the enumerated |
750 mapping mandates that IDL enums are mapped to a Java class with the enumerated |
753 values represented as public static final fields in that class (e.g. |
751 values represented as public static final fields in that class (e.g. |
754 DefinitionKind). |
752 DefinitionKind). |
755 On the other hand IDL constants defined outside of an IDL interface are |
753 On the other hand IDL constants defined outside of an IDL interface are |
756 mapped to a Java interface for each constant. |
754 mapped to a Java interface for each constant. |
757 |
755 |
758 <P>This is why several interfaces in the <TT>org.omg.CORBA</TT> package |
756 <P>This is why several interfaces in the <code>org.omg.CORBA</code> package |
759 consist of a single field, <TT>value</TT>, which is a <TT>short</TT>. This |
757 consist of a single field, <code>value</code>, which is a <code>short</code>. This |
760 field is a constant used for such things as an error code or value modifier. |
758 field is a constant used for such things as an error code or value modifier. |
761 For example, the <TT>value</TT> field of the interface <TT>BAD_POLICY</TT> |
759 For example, the <code>value</code> field of the interface <code>BAD_POLICY</code> |
762 is one of the possible reasons for the exception <TT>PolicyError</TT> to |
760 is one of the possible reasons for the exception <code>PolicyError</code> to |
763 be thrown. To specify this error code, you would use <TT>BAD_POLICY.value</TT>. |
761 be thrown. To specify this error code, you would use <code>BAD_POLICY.value</code>. |
764 |
762 |
765 <P>The exception <TT>PolicyError</TT> uses the <TT>value</TT> field of |
763 <P>The exception <code>PolicyError</code> uses the <code>value</code> field of |
766 the following interfaces as its possible error codes. |
764 the following interfaces as its possible error codes. |
767 <UL> |
765 <UL> |
768 <LI> |
766 <LI> |
769 <TT>BAD_POLICY</TT> |
767 <code>BAD_POLICY</code> |
770 |
768 |
771 <LI> |
769 <LI> |
772 <TT>BAD_POLICY_TYPE</TT> |
770 <code>BAD_POLICY_TYPE</code> |
773 |
771 |
774 <LI> |
772 <LI> |
775 <TT>BAD_POLICY_VALUE</TT> |
773 <code>BAD_POLICY_VALUE</code> |
776 |
774 |
777 <LI> |
775 <LI> |
778 <TT>UNSUPPORTED_POLICY</TT> |
776 <code>UNSUPPORTED_POLICY</code> |
779 |
777 |
780 <LI> |
778 <LI> |
781 <TT>UNSUPPORTED_POLICY_VALUE</TT> |
779 <code>UNSUPPORTED_POLICY_VALUE</code> |
782 </UL> |
780 </UL> |
783 The method <TT>TypeCode.type_modifier</TT> returns the <TT>value</TT> field |
781 The method <code>TypeCode.type_modifier</code> returns the <code>value</code> field |
784 of one of the following interfaces. The <TT>VM</TT> in the names of these |
782 of one of the following interfaces. The <code>VM</code> in the names of these |
785 interfaces stands for "value modifier." |
783 interfaces stands for "value modifier." |
786 <UL> |
784 <UL> |
787 <LI> |
785 <LI> |
788 <TT>VM_NONE</TT> |
786 <code>VM_NONE</code> |
789 |
787 |
790 <LI> |
788 <LI> |
791 <TT>VM_ABSTRACT</TT> |
789 <code>VM_ABSTRACT</code> |
792 |
790 |
793 <LI> |
791 <LI> |
794 <TT>VM_CUSTOM</TT> |
792 <code>VM_CUSTOM</code> |
795 |
793 |
796 <LI> |
794 <LI> |
797 <TT>VM_TRUNCATABLE</TT> |
795 <code>VM_TRUNCATABLE</code> |
798 </UL> |
796 </UL> |
799 The following constants are returned by a <code>ValueMember</code> object's |
797 The following constants are returned by a <code>ValueMember</code> object's |
800 access method to denote the visibility of the <code>ValueMember</code> object. |
798 access method to denote the visibility of the <code>ValueMember</code> object. |
801 <UL> |
799 <UL> |
802 <LI> |
800 <LI> |
803 <TT>PRIVATE_MEMBER</TT> |
801 <code>PRIVATE_MEMBER</code> |
804 |
802 |
805 <LI> |
803 <LI> |
806 <TT>PUBLIC_MEMBER</TT> |
804 <code>PUBLIC_MEMBER</code> |
807 </UL> |
805 </UL> |
808 These flags, used in <TT>NamedValue</TT> objects or as parameters to methods, |
806 These flags, used in <code>NamedValue</code> objects or as parameters to methods, |
809 are defined in the following interfaces: |
807 are defined in the following interfaces: |
810 <UL> |
808 <UL> |
811 <LI> |
809 <LI> |
812 <TT>ARG_IN</TT> |
810 <code>ARG_IN</code> |
813 |
811 |
814 <LI> |
812 <LI> |
815 <TT>ARG_INOUT</TT> |
813 <code>ARG_INOUT</code> |
816 |
814 |
817 <LI> |
815 <LI> |
818 <TT>ARG_OUT</TT> |
816 <code>ARG_OUT</code> |
819 |
817 |
820 <LI> |
818 <LI> |
821 <TT>CTX_RESTRICT_SCOPE</TT> |
819 <code>CTX_RESTRICT_SCOPE</code> |
822 </UL> |
820 </UL> |
823 |
821 |
824 <H2> |
822 <H2> |
825 Interface Repository Interfaces and Classes</H2> |
823 Interface Repository Interfaces and Classes</H2> |
826 A fourth group contains the Interface Repository interfaces and classes, |
824 A fourth group contains the Interface Repository interfaces and classes, |
827 which are generated by the <TT>idlj</TT> compiler from the OMG IDL |
825 which are generated by the <code>idlj</code> compiler from the OMG IDL |
828 interface <TT>ir.idl</TT>. The purpose of the Interface Repository is to |
826 interface <code>ir.idl</code>. The purpose of the Interface Repository is to |
829 identify the interfaces stored in it so that they can be accessed by an |
827 identify the interfaces stored in it so that they can be accessed by an |
830 ORB. Each module, type, interface, attribute, operation, parameter, exception, |
828 ORB. Each module, type, interface, attribute, operation, parameter, exception, |
831 constant, and so on is described completely by the Interface Repository |
829 constant, and so on is described completely by the Interface Repository |
832 API. |
830 API. |
833 |
831 |