Java Programming, Lecture Notes 644, Revised 08/22/99.
Students in Prof. Baldwin's Advanced Java Programming classes at ACC will be responsible for knowing and understanding all of the material in this lesson beginning with the spring semester of 1999.
This lesson was originally written on November 1, 1998. The sample program was tested using the JDK 1.2beta4 download package. The purpose of this lesson is to illustrate parameter passing when using an object reference to invoke an operation (method) on a servant object.
Before embarking on this lesson, you need to study and understand all of the previous lessons on CORBA and Java. This lesson builds directly upon those lessons. Unless you understand the material in those lessons, you probably won't understand what is going on here.
Also, before embarking on this lesson, you need to study and understand material on the OMG Interface Definition Language that is readily available at numerous locations on the web. Although you won't need to have expert knowledge of this material, you will need to understand the meanings of all the elements of the IDL file used with the sample program in this lesson.
Finally, before embarking on this lesson, you will need to understand how parameters are passed to a normal Java method in order to understand the differences involved in passing parameters to a method on a CORBA servant object.
Using CORBA, a client machine anywhere in the world has the capability of invoking methods on a servant object on a cooperating server anywhere in the world, and the programs at the two ends can be developed using different programming languages. One of those programming languages is Java.
Once the client code has a reference to the remote object, the invocation of methods on the remote object is very similar to the invocation of methods on local objects. Note that I said very similar and didn't say identical. This lesson will expose some of the differences.
Both the client code and the server code must have access to an IDL file that declares the methods that can be invoked remotely. This is the key to the whole process and the glue that holds it all together. The client and the server must also agree on how the server will provide an object reference to the client. In this lesson, that object reference is provided by storing a stringified version of the reference in a disk file that is accessible to both the client and the server.
This lesson will expose one of the ways in which CORBA programming differs from ordinary Java programming. When you declare a method signature in an interface in the IDL file, you must declare each parameter as being either in, out, or inout. These names are generally self-explanatory: An in parameter provides input to the method; an out parameter is an output from the method; and an inout parameter serves as an input to and an output from the method. If you forget to include these specifications when you create the method signature in the IDL file, the idltojava program will report a syntax error.
Since there is nothing in Java to correspond to the specification of in, out, or inout when creating a method signature, the idltojava program does some work on your behalf to accommodate this requirement. We will examine an interface file created by the idltojava program later to better understand this.
The sample program in this lesson will use the IDL types long and string to indicate the types of parameters being passed. These IDL types map into the Java types int and String respectively.
The application requires three separate source files and one utility program. The source files are:
The utility program is:
idltojava.exe- a program that converts the IDL file to several Java files, producing stub and skeleton source files and some other source files used by the client and the server.
I have a folder on my computer that contains the following four source files:
Only the last three files are required. The batch file is optional, but is useful for managing the whole process.
Initially, this folder doesn't have any sub folders. However, execution of the program idltojava creates a package to contain the source files that it generates. I forced the package to be in a tree that begins with a folder named junk. As a result, a junk folder is automatically generated which contains another folder named TheDateApp, which is the actual package name.
This is a Java/CORBA application that illustrates the use of IDL operation parameters of types in, out, and inout.
This server provides a servant object that has two methods. One of the methods returns the date and time as a string. More importantly, this method receives three IDL long parameters, one each of types in, out, and inout.
The in parameter is displayed on the MS-DOS screen where the server is running. The in parameter is also sent back to the calling method by way of the out parameter. The inout parameter is multiplied by 4 and then sent back to the calling method by way of the inout parameter.
The other method of this interface performs similar operations on three string parameters, one each of types in, out, and inout.
The in parameter is displayed in the MS-DOS screen where the server is running. The in parameter is also sent back to the calling method by way of the out parameter. The inout parameter is concatenated onto "zz" and sent back to the calling method by way of the inout parameter.
The program was tested using JDK 1.2beta4 under Win95.
The IDL file is the glue that holds the system of programs together and makes it possible for code in a client to invoke methods in a remote object on a basis that is both platform and language independent. This was discussed in some detail in the earlier lessons.
The IDL for this sample program is named Corba08.idl. A complete listing of all four files is provided near the end of this lesson. In addition, important parts of the IDL file are highlighted in the following code fragment.
/*File Corba08.idl
**********************************************************/
module TheDateApp{
interface TheDateInterface{
string getTheDateMethod(in long longIn,
out long longOut,
inout long longInOut);
//-----------------------------------------------------//
void passObjects(in string stringIn,
out string stringOut,
inout string stringInOut);
};//end interface TheDateInterface
};//end module TheDateApp |
This fragment shows the two different operations (methods) named getTheDateMethod and passObjects, and also shows the manner in which each of the parameters to the methods are declared to be either in, out, or inout.
In previous lessons, I haven't provided much, if any discussion of the files automatically generated by the idltojava program. However, we have now reached the point where a brief discussion of parts of some of those files is necessary.
Now let's see if we can understand the structure that is required to support in, out, and inout parameters for which there is no direct Java mapping. We learned in a previous lesson that when we define the class from which the servant object will be instantiated, we must begin that definition something like the following:
class TheDateInterfaceServant
extends _TheDateInterfaceImplBase{ |
The important point here is that this class definition extends _TheDateInterfaceImplBase, which is a class definition that is generated automatically by the idltojava program. If we are going to extend the _TheDateInterfaceImplBase class, we need to know a little more about it. If we examine the code for this class, we find that it begins as follows:
public abstract class _TheDateInterfaceImplBase
extends org.omg.CORBA.DynamicImplementation
implements junk.TheDateApp.TheDateInterface { |
For our purposes in this discussion, the important point is that this class implements an interface named junk.TheDateApp.TheDateInterface. This is an interface that is also automatically generated by the idltojava program. This means that the class that we define must satisfy the requirements imposed by implementing TheDateInterface.
The next step is to take a look at the interface definition for junk.TheDateApp.TheDateInterface. The next fragment is a complete listing of that file with some of the comments removed for brevity.
package junk.TheDateApp;
public interface TheDateInterface
extends org.omg.CORBA.Object {
String getTheDateMethod(
int longIn,
org.omg.CORBA.IntHolder longOut,
org.omg.CORBA.IntHolder longInOut);
void passObjects(
String stringIn,
org.omg.CORBA.StringHolder stringOut,
org.omg.CORBA.StringHolder stringInOut);} |
What we see here are the declarations of the two required methods named getTheDateMethod() and passObjects(). We also see that the types of the first parameter for each method is what we would have expected on the basis of the IDL type to Java type mapping described earlier. IDL long maps to Java int and IDL string maps to Java String.
The important thing to note is that the types of the second and third parameters for each method are different types, which we previously knew nothing about. The types of the second and third parameters in the first method are org.omg.CORBA.IntHolder and the types of the second and third parameters in the second method are org.omg.CORBA.StringHolder. These are types defined by classes in the JDK 1.2beta4 class library.
Examining the description of the class org.omg.CORBA.IntHolder in the JDK documentation, we find the following, which is a direct quote from the JDK 1.2beta4 documentation:
|
"A Holder class for an int that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL long as an "out" or "inout" parameter, the programmer must pass an instance of IntHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server. If myIntHolder is an instance of IntHolder, the value stored in its value field can be accessed with myIntHolder.value." |
Examination of the class named org.omg.CORBA.StringHolder provides essentially the same information for String instead of int.
Now we understand the rules. When we define the methods that implement the IDL interface, for each IDL in parameter, we simply pass a parameter of a type that is the proper mapping of IDL types to Java types (long to int, string to String, etc.).
However, for each IDL out or inout parameter, we need to pass a parameter of a holder class that is designed to accommodate that Java type in those categories. The actual class required can be determined by examining the corresponding Java interface file that is automatically generated by the idltojava program.
If you don't pass the correct type in these cases, you will get a compiler error.
The batch file for this application is named Corba08.bat. There is nothing new or significant about it. You will find a listing for the batch file near the end of this lesson.
The name of the file containing the server code is Corba08Server.java. A listing of the file is provided near the end of this lesson. I will discuss a few fragments from this file relative to the previous discussion. Much of the code is similar to code that you have seen before and I will omit a discussion of that code.
The first fragment shows part of the class definition from which the servant object that implements the IDL interface is instantiated.
First examine the signature of the method named getTheDateMethod(). You will see that it matches the signature declaration in the interface file discussed previously (as you already knew that it must).
class TheDateInterfaceServant
extends _TheDateInterfaceImplBase{
public String getTheDateMethod(
int longIn,
org.omg.CORBA.IntHolder longOut,
org.omg.CORBA.IntHolder longInOut){
System.out.println("Incoming parameter:" + longIn);
longOut.value = longIn;
longInOut.value = 4*longInOut.value;
return new Date().toString();
}//end getTheDateMethod() |
Next examine the operations performed within the method that manipulate the method parameters. As we learned earlier, the first parameter that was declared to be an in parameter in the IDL is simply an int. We can manipulate it in the normal ways. Note, however, that if you assign a new value to that parameter, the new value will not find its way back to the code that invoked the method.
The IDL out and inout parameters are a little more complicated. Although we know that in the final analysis, all three parameters represent values of Java type int, in order to accommodate the out and inout requirements of the IDL, the values of these parameters must be wrapped in an object of type org.omg.CORBA.IntHolder. That wrapper object must be passed to the method (not to be confused with the standard wrapper objects Integer, Float, etc.).
The wrapper object has a field named value where the actual int value is stored. To manipulate these parameters, we must manipulate the value field of the object. If we assign a new value to the value field of one of these parameters, that new value will find its way back to the code that invoked the method. Thus, these parameters behave a little like var parameters in Pascal or reference parameters in C++, but the analogy is very weak. (We can't simply assign a new value to the parameter; we must assign the new value to the value field of the parameter.)
This class definition also contains a method named passObjects() which provides similar behavior using String objects instead of primitive int values. Because of the similarity, I will omit a discussion of this method. You can view the method in the complete listing of the program near the end of this lesson.
The remainder of the server code is essentially the same as code that I have discussed in previous lessons, so I will not repeat that discussion here. After you view the code, if there is something that you don't understand, go back and review the discussion in previous lessons.
The file containing the client code is named Corba08Client.java. I will discuss this code in fragments. A complete listing of the program is provided near the end of the lesson.
An important aspect of understanding this program derives from understanding its output. The following output is produced on the screen where the client program is running. A small amount of output is also produced on the screen where the server program is running.
|
Before the method call: |
I will discuss this output further in conjunction with the discussion of the actual code.
The first fragment shows boilerplate code that you have seen and that I have discussed in previous lessons. I repeat it here solely for completeness.
public class Corba08Client{
public static void main(String args[]){
try{
ORB orb = ORB.init(args, null);
org.omg.CORBA.Object theGenericObjRef =
orb.string_to_object(getStringifiedObjRef());
TheDateInterface theRemoteObjRef =
TheDateInterfaceHelper.narrow(theGenericObjRef); |
Beginning at this point, the code will call the getTheDateMethod on TheDateInterface server object and pass three parameters. The code will display the parameter values before and after the call to illustrate how the code in the method modifies those parameter values. The code will also display the date value returned by the method.
The next fragment creates and initializes three variables that will be passed as parameters to the remote method when it is invoked. The first variable is a primitive int variable. The next two variables are reference variables to objects of type org.omg.CORBA.IntHolder. In the latter two cases, it is the reference variables representing the objects that will be passed to the method.
int longIn = 5;
org.omg.CORBA.IntHolder longOut =
new org.omg.CORBA.IntHolder(0);
org.omg.CORBA.IntHolder longInOut =
new org.omg.CORBA.IntHolder(10);
System.out.println("Before the method call:");
System.out.println("longIn: " + longIn);
System.out.println("longOut: " + longOut.value);
System.out.println("longInOut: " + longInOut.value); |
After the variables are created and initialized, their values are displayed which produces the following output on the screen where the client is running:
Before the method call:
longIn: 5
longOut: 0
longInOut: 10
The next fragment uses the object reference obtained earlier and named theRemoteObjRef to call the method and pass the three variables as parameters.
//call the method
String theDate = theRemoteObjRef.
getTheDateMethod(longIn,longOut,longInOut);
System.out.println("After the method call:");
System.out.println("longIn: " + longIn);
System.out.println("longOut: " + longOut.value);
System.out.println("longInOut: " + longInOut.value);
System.out.println(theDate); |
Following the call, the values of the three variables (and the value of the returned date) are displayed again, producing the following output on the screen where the client is running.
After the method call:
longIn: 5
longOut: 5
longInOut: 40
Sat Oct 31 15:56:45 CST 1998
As you will recall, the code in the method received the in parameter named longIn having a value of 5 and assigned it to the out parameter named longOut. The value field of longOut was initialized to 0 when the object was instantiated. However, following the execution of the method, the value field contained 5. As indicated earlier, the value assigned to the out parameter in the method found its way back to the code that invoked the method (that's why it is called an out parameter). In other words, the value received by the method as the in parameter was sent back to the calling code by way of the out parameter.
Similarly, the value field of the object referred to by longInOut was initialized to 10 when the object was instantiated. The code inside the method multiplied the value field of this inout parameter by a factor of four, and assigned the product back to the value field of the same parameter. Following the invocation of the method, the value field of the object referred to by the reference variable named longInOut contained 40. Thus, the code in the method received a value via the inout parameter, multiplied it by a factor of four, and sent it back to the calling code by way of the same inout parameter.
The method also returned the current date and time via a return statement. Therefore, CORBA methods can return one value via a return statement, and can also "return" or send back an unlimited number of values via out or inout parameters.
The next fragment shows essentially the same behavior applied to String objects rather than primitive int values. The code calls the passObjects() method on TheDateInterface servant object passing three String objects to in, out, and inout parameters respectively. In the latter two cases, the String object is wrapped in an object of type org.omg.CORBA.StringHolder as required. Values of the object are displayed before and after the remote method is invoked, showing the expected behavior.
The output produced by this code was shown earlier. You should compare the output with the code and make certain that you understand it.
Beyond this, there is very little that is different from the previous discussion, so I won't discuss this code any further.
String stringIn = "stringIn";
org.omg.CORBA.StringHolder stringOut =
new org.omg.CORBA.StringHolder("stringOut");
org.omg.CORBA.StringHolder stringInOut =
new org.omg.CORBA.StringHolder("stringInOut");
System.out.println("Before the method call:");
System.out.println("stringIn: " + stringIn);
System.out.println("stringOut: " + stringOut.value);
System.out.println("stringInOut: " +
stringInOut.value);
theRemoteObjRef.passObjects(
stringIn,stringOut,stringInOut);
System.out.println("After the method call:");
System.out.println("stringIn: " + stringIn);
System.out.println("stringOut: " + stringOut.value);
System.out.println("stringInOut: " +
stringInOut.value); |
The remaining code in the client program is essentially the same as code that I have discussed in previous lessons, so I won't discuss it further. You can view the entire program in the program listings that follow.
Complete listings for the IDL file, the batch file and the source code files that you must create are provided in this section. Listings are not provided for the Java source code files that are automatically generated by the idltojava program.
/*File Corba08.idl
See Corba08Server.java for information on this program.
**********************************************************/
module TheDateApp{
interface TheDateInterface{
string getTheDateMethod(in long longIn,
out long longOut,
inout long longInOut);
//-----------------------------------------------------//
void passObjects(in string stringIn,
out string stringOut,
inout string stringInOut);
};//end interface TheDateInterface
};//end module TheDateApp |
.
rem File Corba08.bat echo off rem See Corba08Server.java for description of program rem This program does not use a name service. It uses rem a stringified object reference instead. echo off echo Convert the idl file to the required set of java files idltojava -fno-cpp -p junk Corba08.idl echo Compile all of the java files javac Corba08*.java echo Start the server as a new process. start java Corba08Server echo Start the client manually to avoid race condition |
.
/*File Corba08Server.java
Revised 10/31/98
This is a Java/CORBA server that illustrates the use
of IDL operation parameters of types in, out, and inout.
This server provides a servant object that has two methods.
One of the methods returns the date and time as a string.
More importantly, this method receives three IDL long
parameters, one each of types in, out, and inout.
The in parameter is displayed on the MS-DOS screen where
the server is running. The in parameter is also sent
back to the calling method by way of the out parameter.
The inout parameter is multiplied by 4 and then sent back
to the calling method by way of the inout parameter.
The other method of this interface performs similar
operations on three string parameters, one each of
types in, out, and inout.
The in parameter is displayed in the MS-DOS screen where
the server is running. The in parameter is also sent
back to the calling method by way of the out parameter.
The inout parameter is concatenated onto "zz" and sent
back to the calling method by way of the inout parameter.
This program uses a stringified object reference to the
server's servant object rather than using the name
service.
Tested using JDK 1.2beta4 under Win95.
**********************************************************/
import junk.TheDateApp.*;
import org.omg.CORBA.*;
import java.util.Date;
import java.io.*;
class TheDateInterfaceServant
extends _TheDateInterfaceImplBase{
public String getTheDateMethod(
int longIn,
org.omg.CORBA.IntHolder longOut,
org.omg.CORBA.IntHolder longInOut){
System.out.println("Incoming parameter:" + longIn);
longOut.value = longIn;
longInOut.value = 4*longInOut.value;
return new Date().toString();
}//end getTheDateMethod()
//-----------------------------------------------------//
public void passObjects(
String stringIn,
org.omg.CORBA.StringHolder stringOut,
org.omg.CORBA.StringHolder stringInOut){
System.out.println("Incoming parameter:" + stringIn);
stringOut.value = stringIn;
stringInOut.value = stringInOut.value + "zz";
}//end passObjects()
}//end TheDateInterfaceservant class
//=======================================================//
public class Corba08Server {
public static void main(String args[]){
try{
//Create and initialize the ORB
ORB orb = ORB.init(args, null);
//Create servant and register it with the ORB
TheDateInterfaceServant theObjectReference =
new TheDateInterfaceServant();
orb.connect(theObjectReference);
//Convert the object reference to a string and store
// it in a common file for access by the client.
setStringifiedObjectRef(
orb.object_to_string(theObjectReference));
System.out.println("Server is running");
// wait for invocations from clients
java.lang.Object sync = new java.lang.Object();
synchronized (sync) {
sync.wait();
}//end synchronized block
}catch (Exception e) {
System.err.println("ERROR: " + e);
e.printStackTrace(System.out);
}//end catch block
}//end main()
//-----------------------------------------------------//
static void setStringifiedObjectRef(String stringObjRef){
//Write the stringified object ref to a file named
// junk.txt in the user's home directory
try{
String theFile = System.getProperty("user.home")
+ System.getProperty("file.separator")
+ "junk.txt";
FileOutputStream fileOutputStream =
new FileOutputStream(theFile);
PrintStream printStream =
new PrintStream(fileOutputStream);
printStream.print(stringObjRef);
printStream.close();
System.out.println("Obj ref stored in: "
+ System.getProperty("user.home")
+ System.getProperty("file.separator")
+ "junk.txt");
}catch (Exception e) {
System.err.println("ERROR: " + e);
e.printStackTrace(System.out);
}//end catch block
}//end setStringifiedObjectRef()
}//end Corba08Server class |
.
/*File Corba08Client.java
See Corba08Server.java for information on this program.
This program produces the following output on the screen
where the client is running. Some output is also produced
on the screen where the server is running as well.
Before the method call:
longIn: 5
longOut: 0
longInOut: 10
After the method call:
longIn: 5
longOut: 5
longInOut: 40
Sat Oct 31 15:56:45 CST 1998
Before the method call:
stringIn: stringIn
stringOut: stringOut
stringInOut: stringInOut
After the method call:
stringIn: stringIn
stringOut: stringIn
stringInOut: stringInOutzz
Press Ctrl-z to terminate
**********************************************************/
import junk.TheDateApp.*;
import org.omg.CORBA.*;
import java.io.*;
public class Corba08Client{
public static void main(String args[]){
try{
// create and initialize the ORB
ORB orb = ORB.init(args, null);
//Get and convert the stringified object reference
// to a generic CORBA object reference
org.omg.CORBA.Object theGenericObjRef =
orb.string_to_object(getStringifiedObjRef());
//Cast, or narrow the generic object reference to a
// true object reference.
TheDateInterface theRemoteObjRef =
TheDateInterfaceHelper.narrow(theGenericObjRef);
//Call the getTheDateMethod on TheDateInterface
// server object and pass three parameters. Display
// parameter values before and after the call. Also
// display the date value returned by the method.
int longIn = 5;
org.omg.CORBA.IntHolder longOut =
new org.omg.CORBA.IntHolder(0);
org.omg.CORBA.IntHolder longInOut =
new org.omg.CORBA.IntHolder(10);
System.out.println("Before the method call:");
System.out.println("longIn: " + longIn);
System.out.println("longOut: " + longOut.value);
System.out.println("longInOut: " + longInOut.value);
//call the method
String theDate = theRemoteObjRef.
getTheDateMethod(longIn,longOut,longInOut);
System.out.println("After the method call:");
System.out.println("longIn: " + longIn);
System.out.println("longOut: " + longOut.value);
System.out.println("longInOut: " + longInOut.value);
System.out.println(theDate);
//Call the passObjects() method on TheDateInterface
// server object and pass three parameters. Display
// parameter values before and after the call.
String stringIn = "stringIn";
org.omg.CORBA.StringHolder stringOut =
new org.omg.CORBA.StringHolder("stringOut");
org.omg.CORBA.StringHolder stringInOut =
new org.omg.CORBA.StringHolder("stringInOut");
System.out.println("Before the method call:");
System.out.println("stringIn: " + stringIn);
System.out.println("stringOut: " + stringOut.value);
System.out.println("stringInOut: " +
stringInOut.value);
theRemoteObjRef.passObjects(
stringIn,stringOut,stringInOut);
System.out.println("After the method call:");
System.out.println("stringIn: " + stringIn);
System.out.println("stringOut: " + stringOut.value);
System.out.println("stringInOut: " +
stringInOut.value);
//Delay program termination so that the console
// won't disappear from the screen when running
// under control of a batch file.
int ch1 = '0';
System.out.println("Press Ctrl-z to terminate");
while( (ch1 = System.in.read() ) != -1);
}catch (Exception e) {
System.out.println("ERROR : " + e) ;
e.printStackTrace(System.out);
}//end catch block
}//end main() method
//-----------------------------------------------------//
//This method gets a stringified object reference
// provided by the server according to a specific
// agreement as to how the reference will be delivered.
static String getStringifiedObjRef(){
String stringifiedObjectRef = "Failed to get it";
try{
//Read the stringified object ref from a file named
// junk.txt in the user's home directory
String filename = System.getProperty("user.home")
+ System.getProperty("file.separator")
+"junk.txt";
FileInputStream fileInputStream =
new FileInputStream(filename);
DataInputStream dataInputStream =
new DataInputStream(fileInputStream);
stringifiedObjectRef = dataInputStream.readLine();
}catch (Exception e) {
System.out.println("ERROR : " + e) ;
e.printStackTrace(System.out);
}//end catch block
return stringifiedObjectRef;
}//end getStringifiedObjRef()
}//end Corba08Client class |
-end-