Chapter 2
Getting Started
Setting Up
To develop applications using ISB for Java, you must have: Before you start, set up your development environment and the Enterprise Server, and set your PATH and CLASSPATH environment variables.Enterprise Server Requirements
To use CORBA, WAI-Management must be ON. Applications developed using ISB for Java require access to an Enterprise Server directory. More specifically, the server must enable Web Publishing and the directory must allow HTTP PUTs. One way to do this is to use the Administration Server to set up an additional directory to enable write access. The examples in this chapter were developed using the directoryc:\projects mapped as an additional directory on the server named myServer.nscp.com/projects with write access enabled. For details on enabling Web Publishing and setting up an additional directory, consult the Enterprise Server documentation.
Web Naming (Naming Service) security must be configured to give write access to the iiopnameservice configuration style.
More details about setting up your Enterprise Server are available at http://developer.netscape.com/docs/technote/components/corba/webnaming/webnaming.htm.
Setting Your PATH Variable
Set your PATH environment variable to point to the directory where the JDK Java binaries have been installed and to thebin directory of the ISB distribution.
95:
Assuming that both the JDK and the ISB distribution were installed in c:\ using default settings, you can set your path with the following DOS command:
prompt> set PATH=c:\jdk1.1.2\bin;c:\netscape\suitespot\wai\bin;%PATH%NT: For NT 3.51, you can use the DOS
set command to set environment variables, but it is easier to use the System Control Panel. Assuming that both the ISB and Java distributions were installed in c:\ using default settings, use the Control Panel to start the System program, enter PATH as the variable to edit and add the following directories to the path:
c:\jdk1.1.2\bin;c:\netscape\suitespot\wai\bin;For NT 4.0, use the Control Panel to start the System program and select the Environment tab from the System Properties window. Select the PATH variable from the User Variables list, then add the following to the path:
c:\jdk1.1.2\bin;c:\netscape\suitespot\wai\bin;Click the Set button to accept the new path information. U: Assuming that you installed ISB and Java in
/usr/local using default settings, update your PATH environment variable as follows:
prompt> setenv PATH /usr/local/netscape/suitespot/wai/bin:/usr/local/jdk1.1.2/bin:$PATH
Setting Your CLASSPATH Variable
TheCLASSPATH environment variable tells the Java interpreter where to look for classes. Add JDK, Enterprise Server, and WAI classes to your CLASSPATH. Note that the Communicator classes in java40.jar are needed only if you are developing a service applet that will run in the Communicator. Typically, services run as stand-alone applications, so classes in java40.jar are not needed.
W:
You could save the following commands in a batch file to set CLASSPATH for ISB development. You may need to edit paths to match your directory structure.
rem JDK classes.
set classpath=.;c:\jdk1.1.3\lib\classes.zip;
rem ES classes and WAI.
set classpath=%classpath%c:\netscape\suitespot\wai\java\nisb.zip;c:\netscape\suitespot\wai\java\wai.zip;
rem Communicator Java classes (to import netscape.security.PrivilegeManager).
rem These classes are required only if you developing a service that will run
rem in the Communicator.
rem They are not needed for services running in the Enterprise Server.
rem Note: To use the enablePrivilege call, the applet must be delivered
rem in a signed jar file, or the user preference for codebase principal
rem support must be enabled.
set classpath=%classpath%c:\proga~1\netscape\communicator\program\java\classes\java40.jar;
Developing Applications
To develop distributed applications with ISB for Java, you must first identify the objects required by the application. You will then usually follow these steps: Write a specification for each object using the Interface Definition Language (IDL).- Use
idl2javato generate the client stub code and service skeleton code. - Implement the service interface.
- Write the client application (or applet) code.
- Use
javacto compile the service interface, server application, and client application (or applet).
A Sample Application
The rest of this chapter presents a small sample application. A Java application named MsgService exposes one service, accessed via the Hello interface, that prints a message in the server window and the client window (when you run the client as an application) or the Java console (when you run it as an applet). The following figure shows the MsgService application running in a DOS window, the MsgClient application running in another DOS window, the MsgClient applet running in the Communicator, and a message displayed in the Java Console. Figure 2.2 MsgService and MsgClient windows.
This sample application was developed under Windows NT 4.0. It assumes that c:\projects\msg is its root directory, that some files reside there, some in a subdirectory named SendMsg. If you recreate this sample application using a different configuration, change code and commands accordingly.
The most important files in this application are listed in the following table. You, the programmer, will write or edit each of these files. The application also uses files generated by the idl2java compiler.
Following are the steps to develop this sample application. Defining Interfaces in IDL
Defining Interfaces in IDL
The standard way to define CORBA interfaces is to use the Interface Definition Language (IDL). For details about IDL, see "The IDL to Java Mapping" in the Netscape Internet Service Broker for Java Reference Guide. The following file (namedSendMsg.idl) defines the SendMsg module that defines the Hello interface. The interface provides one method, sayHello, that returns a string.
SendMsg.idl defines the Hello interface.
// SendMsg.idlAn IDL file begins by defining a module (which corresponds to a Java package). A module contains one or more interfaces that provide one or more methods. (ISB for Java provides additional tools and utilities, collectively known as Caffeine, that you can use to define interfaces in Java without using IDL.)
module SendMsg {
interface Hello {
string sayHello();
};
};
Running the idl2java Compiler
The ISB for Java IDL compiler is named idl2java and, as its name implies, generates Java code from a file of IDL specifications. The following command compiles the SendMsg.idl file.
c:\projects\msg> idl2java -no_tie -no_comments SendMsg.idl
The -no_tie flag tells the compiler not to generate files to support the tie mechanism (which is not used in this example), and the -no_comments flag tells the compiler not to put comments in the files it generates (which makes the files easier to read). For more information on the command line options for the idl2java compiler, see "Commands" in the Netscape Internet Service Broker for Java Reference Guide.
Generated Files
Because Java allows only one public interface or class per file, compiling SendMsg.idl generates several .java files. The idl2java compiler creates a subdirectory named SendMsg (which is the module name specified in the IDL file) and stores generated files there. IDL modules are mapped to Java packages, so all of the files listed below are part of the SendMsg package.
For more information about the Helper and Holder classes, see "Generated Classes" in the Netscape Internet Service Broker for Java Reference Guide.
Implementing Interfaces
In CORBA, interface definitions and implementations are separate and distinct. You define interfaces once, then implement them one or more times in one or more languages, depending on your application requirements. In this sample application, the service interface is implemented in Java using a file generated by idl2java.
When the idl2java compiler processes the file SendMsg.idl, it generates files named Hello.java and _example_Hello.java. The file Hello.java defines the Hello interface in Java. The file _example_Hello.java provides a code framework you can fill in to implement the Hello interface. Following is Hello.java.
package SendMsg;
Following is
public interface Hello extends org.omg.CORBA.Object {
public java.lang.String sayHello();
}_example_Hello.java. To implement the interface, add code to the method marked with the comment implement operation.
package SendMsg;
After adding code to the example file, save it using a different filename (this sample application uses the name
public class _example_Hello extends SendMsg._sk_Hello {
public _example_Hello(java.lang.String name) {
super(name);
}
public _example_Hello() {
super();
}
public java.lang.String sayHello() {
// implement operation... return null; }
}HelloImpl.java). Doing this makes clear the difference between the interface and the class that implements it. Also, it preserves your work if you run idl2java again and generate another (empty) example file.
Following is HelloImpl.java. This file defines the HelloImpl class that implements the Hello interface.
// HelloImpl.java
Use
/**
The HelloImpl class implements the Hello interface
defined in the file SendMsg.idl.
*/
package SendMsg;
public class HelloImpl extends SendMsg._sk_Hello {
/** Construct a persistently named object. */
public HelloImpl(java.lang.String name) {
super(name);
}
/** Construct a transient object. */
public HelloImpl() {
super();
}
public String sayHello() {
// Implement the operation. System.out.println("Client called sayHello."); return "Hello!"; }
}javac to compile the implementation file. The following command compiles HelloImpl.java.
c:\projects\msg> javac SendMsg\HelloImpl.java
Writing a Server Application
The server application (also called an object server) creates, activates, and registers services, making them available to clients. In this sample application, the server application is named MsgService. Many of the files used to implement MsgService are contained in the SendMsg package generated by the idl2java compiler. The MsgService.java file presented here is not generated. Normally you, the programmer, would create this file. This file provides a main method that does the following:
- Initializes the Object Request Broker (ORB).
- Initializes the Basic Object Adaptor (BOA). For more information, see Object and Implementation Activation.
- Creates and activates a HelloImpl object.
- Registers the newly created object with the ISB Naming Service.
- Waits for incoming client requests.
// MsgService.java
/**
This application initializes the BOA, activates the service implementation,
and registers the service with the Netscape Naming Service.
*/
public class MsgService {
public static void main (String[] args) {
try {
// Initialize the ORB.
org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(); // The enablePrivilege calls are only required if
// the service runs on the Communicator. Also, add the
// Communicator Java files in java40.jar to CLASSPATH.
/*
netscape.security.PrivilegeManager.enablePrivilege("UniversalAccept");
netscape.security.PrivilegeManager.enablePrivilege("UniversalConnect");
*/
// Initialize the BOA.
org.omg.CORBA.BOA boa = orb.BOA_init(); // Activate the object implementation.
SendMsg.HelloImpl hi = new SendMsg.HelloImpl("IdlExample"); // Export the newly created object.
boa.obj_is_ready(hi);
netscape.WAI.Naming.register("http://myServer.nscp.com/IdlExample", hi); System.out.println(hi + " is ready.");
// Wait for incoming requests.
boa.impl_is_ready(); }
catch(org.omg.CORBA.SystemException e) {
System.err.println(e);
}
}
}
register method.
netscape.WAI.Naming.register("http://myServer.nscp.com/IdlExample", hi);
This string value, plus "NameService" in between the hostname and object, is also used in the client application to resolve a URL and locate the service. For more information about naming and registering objects, see Naming and Binding to Objects.
Use javac to compile the server application. The following command compiles MsgService.java.
c:\projects\msg> javac MsgService.java
Writing a Client Application or Applet
The client application (or client applet) locates a service, then invokes methods that service provides. In this sample application, the server application is named MsgClient. Many of the files used to implement MsgClient are contained in the SendMsg package generated by the idl2java compiler. The MsgClient.java file presented here is not generated. Normally you, the programmer, would create this file. This client is written to run either from the command line as an application or from within the Communicator or AppletViewer as an applet. Either way, it performs the following functions:
Initializes the Object Request Broker (ORB).
- Calls the
sayHellomethod provided by the Hello service. - Prints the resulting message. MsgClient.java provides the client-side program, written in Java.
// MsgClient.java
/**
You can run this client code as an application from the command line
or as an applet from within a Java-enabled browser. It initializes the
ORB, locates the service, and calls a service method to print a message.
*/
import netscape.WAI.Naming;
public class MsgClient extends java.applet.Applet {
String _url = "http://myServer.nscp.com/NameService/IdlExample";
public void init() {
try {
// Initialize the ORB.
org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init();
// Locate a message service.
org.omg.CORBA.Object obj = Naming.resolve(_url); SendMsg.Hello hi = SendMsg.HelloHelper.narrow(obj);
// Print a message.
System.out.println(hi.sayHello());
}
catch(org.omg.CORBA.SystemException e) {
System.err.println(e);
}
}
public static void main(String args[]) {
MsgClient mc = new MsgClient();
mc._url = "http://myServer.nscp.com/IdlExample";
mc.init();
}
}
javac to compile the client application. The following command compiles MsgClient.java.
c:\projects\msg> javac MsgService.java
Starting a Server Application
To start a server application, open a console window and use thejava command with the -DDISABLE_ORB_LOCATOR flag. For example, the following command starts the MsgService application.
c:\projects\msg> java -DDISABLE_ORB_LOCATOR MsgServiceIf the application starts successfully, it will print a message like the following in the console window.
SendMsg.HelloImpl[Server,oid=PersistentId[repId=IDL:SendMsg/Hello:1.0,objectName=IdlExample]] is readyIf there is a problem, you may see a message like the following.
C:\CAFE\PROJECTS\IDLBANK>java -DDISABLE_ORB_LOCATOR MsgServiceThis message is typically caused by a statement that calls
org.omg.CORBA.INV_OBJREF[completed=MAYBE, reason=Invalid object ref returned by URL resolver]
register, for example:
netscape.WAI.Naming.register("http://myServer.nscp.com/isbBank/AcctMgr", manager);
where "myServer.nscp.com" is the name of the host and "isbBank" is the name of a document directory known to the Enterprise Server. The Enterprise Server must be configured to enable Web Publishing, and the specified document directory must be configured to allow write access. If you have other problems starting the application, refer to Troubleshooting.
Starting a Client Application
After starting the server application, open a different console window and use the java command with the -DDISABLE_ORB_LOCATOR flag. For example, the following command starts the MsgClient application.
c:\projects\msg> java -DDISABLE_ORB_LOCATOR MsgClient
If the application starts successfully, it will print the following message in the console window.
Hello!
If your development environment is not connected to a network (that is, if you are developing the application on a stand-alone system), it may take several seconds for the message to appear. Response times are generally faster on networked systems. If you have other problems starting the application, refer to Troubleshooting.
Advanced Networking Options
You can change the network address and port used by a client or server application by setting the OAPort property when you start the application. If a port number is not specified, an unused port will be selected. For example, the following command starts the MsgService application and specifies port 1234.
c:\projects\msg> java -DDISABLE_ORB_LOCATOR -DOAPort=1234 MsgService
Running a Client Applet
You can run a client applet in an HTML page using either the AppletViewer or the Communicator. The HTML page must include an APPLET tag to load the client class. For example, the following page loads the MsgClient class.
<HTML>
<BODY>
This applet prints a message in the Java Console.
<BR>
<APPLET CODE=MsgClient.class WIDTH=200 HEIGHT=100>
</applet>
</body>
</html> Communicator
Choose File - Open Page, then enter the URL for the HTML page that runs the client.
http://myServer.nscp.com/projects/msg/MsgClient.html
If the applet starts successfully, it will print the following message in the Java Console window.
Hello!
Some problems running applets in the Communicator are caused by CLASSPATH settings. It may help to empty the CLASSPATH before starting Communicator. To empty the CLASSPATH, enter the following command:
c:\> set CLASSPATH=
If you have other problems starting the applet, refer to Troubleshooting.
AppletViewer
Before testing client applets in the AppletViewer, add the following lines to the appletviewer.properties file (by default, it's in the \lib subdirectory of the JDK distribution):
DISABLE_ORB_LOCATOR=1
To run a client applet in the AppletViewer, enter the filename of an HTML file that loads the client class. For example, the following command loads MsgClient.
browser.vendor.applet=1c:\projects\msg> appletviewer MsgClient.html
[Contents] [Previous] [Next]
Last Updated: 02/04/98 13:45:49
Any sample code included above is provided for your use on an "AS IS" basis, under the Netscape License Agreement - Terms of Use