Contents

3.1 Review of OrbixWeb Programming Steps

3.2 Providing a Server

3.3 Writing a Client Applet

3.3.1 Creating the User Interface

3.3.2 Adding OrbixWeb Client Functionality

3.3.3 Creating the Applet

3.3.4 Adding the Applet to a HTML File

3.3.5 Compiling the Client Applet

3.3.6 Running the Client Applet

3.4 Learning more about OrbixWeb

The reader should be familiar with the material covered in Chapter 2, "Getting Started with Java Applications" before continuing with this chapter.

3.1 Review of OrbixWeb Programming Steps

• Define the IDL interfaces.
  
• Implement these interfaces with Java classes.
  
• Create a Java server which instantiates implementation objects. The server must inform OrbixWeb when initialisation has been done and it is ready to accept requests from clients.
  
• Register the server in the Implementation Repository, using putit.
  
• Write a client to bind to and use the server's objects.
  

A version of the sample code described in this chapter is available in the gridApplet demonstration directory of your OrbixWeb installation. However, readers should be aware that the documented code may differ slightly from the installation example.

3.2 Providing a Server

This client-server architecture is a common requirement in the Java domain, where small, dynamic client applets may be downloaded to communicate with large, powerful back-end service applications. Architectures in which full OrbixWeb servers must be coded as downloadable applets are less common, and these will not be described here.

Of course, the client applet illustrated in this chapter provides very basic functionality and much more complex client-server interaction can be achieved within a similar architecture. Subsequent parts of this guide will expand upon the functionality described here.

3.3 Writing a Client Applet

In this section, we will elaborate the following applet programming steps, relating each to a particular demonstration source file:

• Creating the User Interface (in file GridPanel.java).
  
• Adding OrbixWeb client functionality (in file GridEvents.java).
  
• Creating the applet (in file GridApplet.java).
  
• Adding the client to a HTML file (in file GridApplet.html).
  

 idl -jP gridAppletDemo grid.idl

3.3.1 Creating the User Interface

The grid applet provides a very simple user interface. This interface is divided into two sections, each with a specific objective: a "Server Details" section designed to allow users to specify a target OrbixWeb server, and an "Object Details" section which allows a Grid object to be queried and updated.

The source code for GridPanel.java simply uses the Java Abstract Windowing Toolkit package (java.awt) to create and arrange each of the elements within a java.awt.Panel container. The details of how the interface is assembled are not relevant to this description, but we will reference the individual component names in the next section:

 // Java
 // In file gridAppletDemo/GridPanel.java.
 package gridAppletDemo;
 import java.awt.*;
 
 public class GridPanel extends Panel {
 	// Button string constants.
 	final String conBStr = "Connect";
 	final String disBStr = "Disconnect";
 	final String dimBStr = "Get Grid Dimensions";
 	final String getBStr = "Get Cell Value";
 	final String setBStr = "Set Cell Value";
 
 	// Components for Server Details section
 	// _bind() labels.
 	Label nameL;
 	Label hostL;
 
 	// _bind() text fields.
 	TextField nameField;
 	TextField hostField;
 
 	// _bind() buttons.
 	Button connectButton;
 	Button disconnectButton;
 
 	// Components for Object Details section
 	// operation labels.
 	Label dL;
 	Label xL;
 	Label yL;
 	Label vL;
 
 	// Operation text fields.
 	TextField dField;
 	TextField xField;
 	TextField yField;
 	TextField vField;
 
 	// Operation buttons.
 	Button getDButton;
 	Button getVButton;
 	Button setVButton;
 
 	// Sub panels.
 	Panel bindPanel;
 	Panel botPanel;
 
 	// Constructor.
 	public GridPanel () {
 	}
 }

The text fields provide a means of obtaining and reporting operation parameter values and operation results.

To implement the functionality of the interface buttons, we add support for user interaction by detecting java.awt.Event.ACTION_EVENT events. There are several methods of achieving this, but in this example we define a subclass of GridPanel, called GridEvents, which overrides the java.awt.Component.action() method. This method allows us to receive notification of a button click event, and to determine which button in the interface received that event. We can then react by invoking the appropriate operation on a Grid proxy object.

Note that all sample code described below includes error handling as described in the section "Error Handling: Integration with Java Exceptions", but the method displayMsg() is introduced to display operation results. The functionality of this method will be explained in the next subsection.

We will now outline the source code for class GridEvents. The methods outlined here will be expanded later in this section.

 // Java
 // In file gridAppletDemo/GridEvents.java.
 package gridAppletDemo;
 
 import java.awt.*;
 import java.lang.*;
 
 import IE.Iona.Orbix2._CORBA;
 import IE.Iona.Orbix2.CORBA.SystemException;
 
 public class GridEvents 
 	extends gridAppletDemo.GridPanel {
 	// Grid proxy object.
 	public _GridRef gRef = null;
 
 	// Notify method for action event.
 	public boolean action (Event event, 
 			Object arg) {
 		if (conBStr.equals (arg)) {
 			// Connect button clicked, 
 			// so _bind to Grid object.
 			bindObject ();
 		}
 		else if (disBStr.equals (arg)) {
 			// Disconnect button clicked,
 			// so simply destroy proxy.
 			gRef = null;
 		}
 		else if (dimBStr.equals (arg)) {
 			// Get Dimensions button clicked,
 			// so call get_height() and get_width() on
 			// Grid object.
 			getHeightAndWidth ();
 		}
 		else if (getBStr.equals (arg)) {
 			// Get Cell Value button clicked,
 			// so call get() on Grid object.
 			getCellValue ();
 		}
 		else if (setBStr.equals (arg)) {
 			// Set Cell Value button clicked,
 			// so call set() on Grid object.
 			setCellValue ();
 		}
 		return true;
 }
 
 	// Connect button implementation.
 	public void bindObject () {
 		// Details will be described
 		// later in this section.
 	}
 
 	// Get Grid Dimensions button implementation.
 	public void getHeightAndWidth () {
 		// Details will be described
 		// later in this section.
 	}
 
 	// Get Cell Value button implementation.
 	public void getCellValue () {
 		// Details will be described
 		// later in this section.
 	}
 
 	// Set Cell Value button implementation.
 	public void setCellValue () {
 		// Details will be described
 		// later in this section.
 	}
 }

We will now explain in detail the functionality of each button implementation. The "Connect" button functionality is implemented in the method bindObject():

 // Connect button implementation.
 public void bindObject () {
 	String tmp;
 	String markerServer;
 	String hostName;
 
 	// Get server name from text field.
 	if ((tmp = nameField.getText ()) == null) 
 		markerServer = "";
 	else
 		markerServer = ":" + tmp;
 
 	// Get host name from text field.
 	hostName = hostField.getText ();
 
 	// Bind to server object.
 	try {
 		gRef = Grid._bind(markerServer, hostName);
 	}
 	catch (SystemException se) {
 		displayMsg ("Connect failed.\n" + 
 			"Unexpected exception:\n"
 			+ se.toString ());
 		return;
 	}
 
 	displayMsg ("Connect succeeded.");
 }

The "Disconnect" button is implemented by the following line of code:

 gRef = null;

The "Get Grid Dimensions", "Get Cell Value" and "Set Cell Value" buttons allow Grid operations to be invoked on a proxy created by the "Connect" button. Therefore, the methods which implement these buttons simply attempt invocations on the proxy member variable gRef:

 // Get Grid Dimensions button implementation.
 public void getHeightAndWidth () {
 	short h, w;
 
 	// Check that proxy exists.
 	if (gRef == null) {
 		displayMsg ("Get dimensions failed" +
 			" - not connected to server.");
 		return;
 	}
 
 	// Call attribute methods.
 	try {
 		h = gRef.get_height ();
 		w = gRef.get_width ();
 	}
 	catch (SystemException se) {
 		displayMsg ("Get dimensions failed.\n" 
 			+ "Unexpected exception:\n" 
 			+ se.toString ());
 		return;
 	}
 
 	dField.setText (Integer.toString (w) + " x " 
 		+ Integer.toString (h));
 	displayMsg ("Get dimensions succeeded.");
 }
 
 // Get Cell Value button implementation.
 public void getCellValue () {
 	short x, y; 
 	int cellVal = 0;
 
 	// Get position from text fields.
 	try {
 		x = (short) Integer.parseInt (
 			xField.getText ());
 		y = (short) Integer.parseInt (
 			yField.getText ());
 	}
 	catch (java.lang.NumberFormatException nfe) {
 		displayMsg ("Get cell value failed - " +
 			"invalid co-ordinate values.\n");
 		return;
 	}
 
 	// Call get operation.
 	try {
 		cellVal = gRef.get (x, y);
 	}
 	catch (SystemException se) {
 		displayMsg ("Get cell value failed.\n" 
 			+ "Unexpected exception:\n" 
 			+ se.toString ());
 		return;
 	}
 
 	vField.setText (Integer.toString (cellVal));
 	displayMsg ("Get cell value succeeded.");
 }
 
 // Set Cell Value button implementation
 // (error handling code included).
 public void setCellValue () {
 	short x, y; 
 	int cellVal;
 
 	// Get position and value from text fields.
 	try {
 		x = (short) Integer.parseInt (
 			xField.getText ());
 		y = (short) Integer.parseInt (
 			yField.getText ());
 		cellVal = Integer.parseInt (
 			vField.getText ());
 	}
 	catch (java.lang.NumberFormatException nfe) {
 		displayMsg ("Set cell value failed - " + 
 			"invalid co-ordinate or cell value.");
 		return;
 	}
 
 	// Call set operation.
 	try {
 		gRef.set (x, y, cellVal);
 	}
 	catch (SystemException se) {
 		displayMsg ("Set cell value failed.\n" 
 			+ "Unexpected exception:\n" 
 			+ se.toString ());
 		return;
 	}
 
 	displayMsg ("Set cell value succeeded.");
 }

 // Java
 // In file gridAppletDemo/MsgDialog.java.
 package gridAppletDemo;
 
 import java.awt.*;
 
 public class MsgDialog extends Frame {
 	protected Button button;
 	protected gridAppletDemo.Msg label;
 
 	public MsgDialog(String title, String message){
 		// Details omitted.
 	}
 
 	// Other class details omitted.
 }

 void displayMsg (String msg) {
 	gridAppletDemo.MsgDialog msgDlog 
 		= new gridAppletDemo.MsgDialog 
 		("Grid Operation Result", msg);
 	msgDlog.resize (380, 200);
 	msgDlog.show ();
 }

3.3.3 Creating the Applet

 // Java
 // In file gridAppletDemo/GridApplet.java.
 package gridAppletDemo;
 
 import java.applet.*;
 import java.awt.*;
 
 public class GridApplet extends Applet {
 	// Main display panel.
 	gridAppletDemo.GridEvents gridEvents;
 
 	public void init () {
 		gridEvents = 
 			new gridAppletDemo.GridEvents ();
 
 		// Add panel to applet.
 		this.add (gridEvents);
 	}
 }
 

 <HTML>
 <HEAD>
 <TITLE>OrbixWeb grid applet demo</TITLE>
 </HEAD>
 <BODY>
 <H1>Grid Client</H1>
 <APPLET code="gridAppletDemo/GridApplet.class" 
 	width=408 height = 500>
 </APPLET>
 </BODY>
 </HTML>

In particular, it is necessary to ensure that the Java compiler can access the Java API packages (including java.awt for this sample code), the OrbixWeb IE.Iona.Orbix2 package, and any applet-specific classes. The compiler should then be invoked on all the Java source files for the application. In this example applet, the required files are Grid.java, _GridRef.java, GridPanel.java, GridEvents.java, GridApplet.java, MsgDialog.java, and Msg.java.

The OrbixWeb gridApplet demonstration directory provides a make file which invokes the javac compiler as required. In this directory, it is simply necessary to type (on Unix):

 make

 nmake

 appletviewer GridApplet.html

If an OrbixWeb applet is loaded into the viewer from a file, then it is possible to specify the locations of required classes in the CLASSPATH environment variable before running the viewer. The classes required are identical to those for an OrbixWeb client application, as described in section 2.14.

An alternative approach, when loading the applet from a file, is to provide access (for example, via links) to all the classes the applet requires in a single directory. Then, rather than setting an environment variable, the CODEBASE attribute of the HTML flag <APPLET> could be used to indicate the location of the applet bytecode.

For example, this would involve changing the <APPLET> tag in GridApplet.html to the following:

 <APPLET codebase="/tmp/orbixweb/classes"
 	code="gridAppletDemo/GridApplet.class">

Java applets are subject to important security restrictions, imposed by the Java environment and by web browsers. The severity of these restrictions is often dependent on browser technology, but the general issues are outlined in section 10.2.3 "Security Issues for Client Applets".

3.4 Learning more about OrbixWeb

• Presents an overview of the structure of distributed applications.
  
• Introduces IDL and the corresponding mapping of IDL to the Java programming language. Both client and server programmers must be familiar with this mapping.
  
• Presents further examples of using OrbixWeb to define an interface to a system component and then writing client and server programs.
  
• Explains the use of inheritance when defining IDL interfaces, allowing one interface to be defined by extending others.
  
• Gives more details on compiling IDL definitions, registering servers, and configuring OrbixWeb to suit a particular environment.
  
• Explains that operation calls can be made in ways other than shown in the overview presented here. Some applications, such as browsers, need to be able to use all of the interfaces defined in a system–even those interfaces which did not exist when the browser was compiled. OrbixWeb supports such applications via its Dynamic Invocation Interface.
  

• Filters can be installed in the system to allow programs to monitor or control incoming or outgoing requests.
  
• A proxy is a local representative or stand-in for a remote object. A smart proxy is an intelligent stand-in. Smart proxies can be written to optimise the performance of a component as perceived by a client.
  
• To facilitate applications such as browsers, the interface of an object can be examined at runtime (using the Interface Repository).
  
• If OrbixWeb fails to find an object being sought by a client or server, it will inform loader objects, which will be given the opportunity to load the object from some persistent store. Interfacing OrbixWeb to a persistent store therefore involves writing a loader object and installing this within programs that directly use that persistent store. As a result, OrbixWeb is not tied to using any specific persistent store from a particular vendor.
  
• OrbixWeb has a built-in mechanism for searching the distributed system for a server. If this mechanism is not appropriate or if it needs to be augmented, a programmer can write a locator object and install this in preference to the default one.