Tutorial: Creating a CORBA-based distributed application in JBuilder

Note: Only the Client/Server and Application Server versions of JBuilder ship with distributed applications features.

The Inprise Application Server enables you to develop an application from end-to-end - from the graphic user interface (GUI), through the business logic, and then all the way through to accessing databases or host data in legacy systems. Once developed, you can run the application in a framework provided by the Application Server. This framework includes a communications backbone based on the VisiBroker Object Request Broker (ORB).

This tutorial helps you become acquainted with some of the JBuilder and VisiBroker for Java development tools and explores developing a distributed, object-based application using JBuilder and VisiBroker for Java. A sample application is used to illustrate each step of the process. Tutorial: The Bank application explains how to build a sample client application and a graphical user interface (GUI) that can query on the balance in a bank account. Running and deploying the HTML client application explains how to run the banking application as an HTML client. Running and deploying the Java client application explains how to run the banking application as a Java client.

Before working through this tutorial, please read Chapter 2 of the VisiBroker for Java Programmer's Guide, "VisiBroker basics", available from the Web at http://www.borland.com/techpubs/books/vbj/vbj33, or from the \doc\books\vbj\programmer directory of your Application Server installation for an understanding of VisiBroker's distributed applications features. Also read Chapter 3, "Developing distributed applications using JBuilder,"of the Inprise Application Server User's Guide located in the \doc\books\appserver\usersguide directory for an understanding of Application Server features.

For more advanced information on using JBuilder and VisiBroker to create distributed applications, see the VisiBroker for Java Programmer's Guide at http://www.borland.com/techpubs/books/vbj/vbj33, or from the \doc\books\vbj\programmer directory of your Application Server installation. An outline of topics is available at the end of this chapter.

For more information about Common Object Request Broker Architecture (CORBA), link to


Tutorial: The Bank application

In this tutorial, you will explore a sample client application that can query on the balance in a bank account. This tutorial provides the steps necessary to create the basic files necessary to run and deploy a simple, CORBA-based distributed application.

From this example, you will learn how to

Developing applications

When you develop distributed applications, you must first identify the objects required by the application. You will then usually follow these steps:

  1. Write a specification for each object using the Interface Definition Language (IDL).
  2. Use the IDL compiler to generate the client stub code and server skeleton code.
  3. Write the client application code (or use the Application Generator to generate client application code).
  4. Write the server object code (or use the Application Generator to generate server code).
  5. Compile the client and server code.
  6. Start the server.
  7. Run the client application and/or HTML applet.

The following figure illustrates these steps.



Creating the project

This tutorial assumes that you are familiar with the JBuilder development environment. If you are new to JBuilder, refer to "The JBuilder environment" in the User's Guide for an introduction.

To create a new project in JBuilder,

  1. Select File|New Project from the JBuilder menu.
  2. Change the File field from the myprojects\untitled\untitled.jpr entry to myprojects\Bank_Tutorial\Bank_Tutorial.jpr.
  3. Optionally, fill in the Title, Author, Company, and Description fields.
  4. Click Finish.

The Bank_Tutorial project appears in the Navigation pane. It currently includes one file, Bank_Tutorial.html, which displays the information entered in the Project Wizard. The next section adds a new file, Bank_Tutorial.idl, to the project.


Defining the interface for the CORBA object

IDL is the foundation of CORBA applications. IDL interfaces define a component's boundaries. You can use IDL to define a component's attributes, the exceptions it raises, and the methods its interface supports.

The Bank_Tutorial.idl file defines the Bank_Tutorial module that contains two interfaces. The Account interface provides a method for obtaining the current balance. The AccountManager interface provides a method that opens an account with a specified name and returns an Account object reference. The Account object reference can then be used to obtain the balance in the account.

To create and enter the code for the IDL file,

  1. Select File|Open/Create.
  2. Type Bank_Tutorial.IDL in the File Name field.
  3. Select the Add To Project box.
  4. Click Open. A new, empty IDL file is created and added to the project.
  5. Add the following IDL code to this file by typing it directly into the Source window. For more information on writing IDL code, see http://www.omg.org/corba/cichpter.htm#idls&s for IDL syntax and semantics.


IDL code:
module Bank_Tutorial {
    interface Account {
        float balance();
    };
    interface AccountManager {
        Account open(in string name);
    };
};

Compiling the CORBA interface definitions to generate Java code

The VisiBroker IDL compiler, named idl2java, generates Java code from a file containing IDL specifications. Before you can compile the Bank_Tutorial.idl file, you must verify that the Application Server library is added, and you must set the Servlets properties. To do this,

  1. Select File|Project Properties.

  2. Check to ensure that Application Server 3.0 is listed under Java libraries. If it is not,
    1. Click the Add button next to Java libraries.
    2. Click Application Server 3.0.
    3. Click OK.

  3. Click the Servlets tab to set the paths to deploy the application files to the Sun Java Web Server, Inprise edition (for running and deploying the HTML client piece; this section is not necessary for running and deploying Java clients). If the Web Server is not installed, see Installing the Sun Java Web Server, Inprise Edition. You can deploy the HTML client to any Web server. Sun Java Web Server is used in this example because it is provided with JBuilder for Application Server.
    1. Set the Servlet Path to the jws\servlets directory.
    2. Set the HTML Path to the jws\public_html directory.
    3. Set the Classes Path to the jws\classes directory.

  4. Click OK to close the properties dialog.

Now that the libraries have been verified, and the output directories specified (for HTML clients), compile the Bank_Tutorial.idl file. To do this,

  1. Right-click on the Bank_Tutorial.idl file in the Navigation pane.
  2. Select Make.

If the file requires special handling, you can set IDL properties by right-clicking the IDL file in the Navigation pane, and selecting IDL Properties. The VisiBroker IDL Properties dialog enables you to specify options for compiling remote interfaces defined in the IDL.

Files generated when IDL compiled

Since Java allows only one public interface or class per file, compiling the Bank.idl file will generate several Java files. When generated through the JBuilder interface, these files are stored in a JBuilder sub-directory named myProjects\Bank_Tutorial\Bank_Tutorial, which is the module name specified in the IDL file. IDL modules are mapped to Java packages, so all of the files listed below will be part of the Bank_Tutorial package.

For more information about the Helper, Holder, and Operations classes, see the "Generated Classes" chapter in the VisiBroker for Java Reference Manual, in the \doc\books\vbj\programmer directory of your Application Server installation.


Create the client and server

Many of the files used in implementing the bank client and server are contained in the Bank_Tutorial package generated when the IDL file is compiled. However, you need to generate the client and server application files to provide the client-side program and the server-side implementation.

From the compiled IDL file, JBuilder can generate multi-tier CORBA applications with its Application Generator. Your distributed application can be a Java CORBA server with a Java CORBA client or an HTML client.

The client class implements the client application that obtains the current balance of a bank account. The server class implements the server application that invokes the virtual machine. To create these files,

  1. Right-click Bank.IDL in the Navigation pane.
  2. Select Generate Application.

The Application Generator generates multi-tier CORBA applications from a compiled IDL file. The application can be created as a Java client, an HTML client, an HTML client test servlet, a server, or a server monitor. For this application, generate a Java client, an HTML client, and a server. To do this,

  1. Select the Applications page.
  2. Add HTML Client to the list in the Generate CORBA application box to generate an HTML form connected to CORBA objects. Java client, Server, and Server monitor should be selected by default. Allow these to remain selected.
  3. Select the HTML Client Layout page.
  4. Check the Layout box in the Structures, Operations, and Attributes section for both Bank_Tutorial.Bank_Tutorial.balance and Bank_Tutorial.Bank_Tutorial.open.
  5. Select File|Generate to open the Generate dialog.
  6. Click the Generate button to generate the client and server files.
  7. Click Close to close the list of generated files.
  8. Select File|Exit to close the Application Generator.

The file Bank_TutorialAppGenFileList.html, which is added to the project, contains the list of generated files.

The generated client class does the following:

The generated server class does the following:

Refer to the VisiBroker documentation in the \doc\books\vbj\programmer directory of your Application Server installation for a description of generated files.


Providing an implementation for the CORBA interface

The application now contains a user interface that will look up a name and return a "0" value for a balance. To make the example more interesting, we could add a database of customers, account numbers, and balances that could be looked up and used to debit and credit the account with withdrawals and deposits. However, in this simple example, we will simply add an implementation to generate a balance for a given name based on the number of characters in the name. (For an example that uses the Data Modeler to add database capabilities to a distributed application, see "Creating database applications with the Data Modeler and Application Generator" in the Database Application Developer's Guide).

To implement the CORBA interface,

  1. Expand the Bank_Tutorial.Bank_Tutorial.server object in the Navigation pane to expose all files.
  2. Select the file AccountImpl.java
  3. Add and/or modify the code highlighted in bold below to match this code. Use Alt+Z to toggle the Source window larger and smaller.
    package Bank_Tutorial.Bank_Tutorial.server;
    
    import java.sql.*;
    import java.util.*;
    import java.math.*;
      
    /**
        Implementation of Account.
    */
    
    public class AccountImpl extends Bank_Tutorial._AccountImplBase {
      public static ServerMonitorInterface monitor = null;
      
         float _balance;
    
      public AccountImpl(java.lang.String name) {
        super(name);
        _balance = name.length()*100;
        if (monitor == null) {
          monitor = ServerMonitor.addPage(this, "Account");
          monitor.showObjectCounter(true);
        }
        monitor.updateObjectCounter(1);
      }
    
      public float balance()  {
        ServerMonitor.log("(" + _object_name() + ") AccountImpl.java balance()");
        return _balance;
      }
    }
    

Compile the application

To make the project, select

Any errors will be noted in the debugger window. Correct any syntax errors before continuing to the next section, or open the sample project located in \samples\borland\samples\CORBA\Bank_Tutorial\Bank_Tutorial.jpr. For more information on debugging distributed applications, see Debugging distributed applications.


Running and deploying the Java client application

To run the sample java client application,

  1. Make sure the Smart Agent is running.
  2. Start the server implementation.
  3. Start the client application.
  4. Test and deploy the application.

Starting a Smart Agent

The Smart Agent, or OsAgent, is the object location service. The client finds the server by using OsAgent and the server advertises services by using OsAgent - it's how they find each other. Ordinarily, you will want the Smart Agent to be running on at least one machine in the LAN environment for you to run your applications. The Smart Agent is described in detail in "The Smart Agent," in the \doc\books\vbj\programmer directory of your Application Server installation.

The Smart Agent is started automatically when the Application Server is started. To start the Application Server,

When the Application Server is running correctly, you will see icons on the Taskbar for the Application Server and the VisiBroker Smart Agent. Click the Application Server icon to view the status of the Application Server. When ready, this window displays the host, domain, and port for the Application Server you have just started (in this case, the Application Server on your machine).

Running the server implementation

To start the server implementation,

Running Bank_TutorialServerApp.java invokes the virtual machine and offers other special features. If the server monitor option was selected in the Application Generator, its user interface is displayed as well. For command-line options and more information, see "Programmer Tools" in the VisiBroker for Java Reference Manual.

Running a Java client

After starting the Smart Agent and the server implementation, a client can be started in a different window. To run the java client,

The running application appears. The UI for the application appears in a window. Enter a name (for example, John), click the open button, and a tab appears with that name. Click the tab, click the balance button, and the generated balance is displayed in the return from balance() field. The account balance is computed based on the number of characters in the name * 100.

Bank_Tutorial client

If the server monitor is running, it prints out a message every time it creates a new Account. You will see the following output on the server side:

Bank_Tutorial server

Deploying the application

VisiBroker is necessary in the deployment phase. This phase occurs when a developer has created client programs or server applications that have been tested and are ready for production. At this point, a system administrator is ready to deploy the client programs on end-users' desktops or server applications on server-class machines.

For deployment, the VisiBroker ORB supports client programs on the front end. You must install the ORB on each machine that runs the client program. Clients that use the ORB on the same host share the ORB. The VisiBroker ORB also supports server applications on the middle tier. You must install the full ORB on each machine that runs the server application. Server applications or objects that use the ORB on the same server machine share the ORB.

JBuilder includes a single DEVELOPMENT LICENSE of VisiBroker for Java 3.0 "Developer Version". This license must be used in conjunction with JBuilder. Additional developers will require their own VisiBroker development licenses. Deployed programs require a separate VisiBroker deployment license for each server machine.

JBuilder provides an easy method for deploying the application by publishing the project to the Application Server. The Application Server Developer Console also has features that allow you to not only deploy applications, but also to manage and monitor deployed applications. You can take .jar files created with JBuilder and use them with the Console. For more information on the Application Server Developer Console, see the Inprise Application Server User's Guide in the \doc\books\appserver\usersguide directory of your Application Server installation.

To publish a Java client application to the Application Server,

  1. Close the server implementation and Java client if they are still running from the previous steps of the tutorial.
  2. Select Tools|ORB Connection Properties. Set the Port and Domain Name for the Application Server to which you want to publish the application. Click Apply to apply the connection parameters. When the Status displays "Connection OK", click the OK button to close the dialog.
  3. Choose File|Publish To Application Server from the JBuilder menu.
  4. Edit the configuration associated with this project in the Application Server Login dialog box. Make sure the Domain Name and Domain Port match the values entered in the first step. Click OK.

    Since this project has not been previously deployed, a default configuration is created and is associated with the active project.

  5. Click Publish in the Publish Application dialog to start the deployment process.
  6. Click OK when the dialog box displays the successful deployment.


Running and deploying the HTML client application

Running the sample HTML client application involves more steps than running the Java client application, because it must be deployed onto a Web server to be run. The following sections discuss running the HTML client. For more information on running and deploying HTML client applications, see the chapter "Creating, running, and deploying an HTML client". The general steps for running this application are

  1. Make sure the Smart Agent is running.
  2. Start the server implementation.
  3. Deploy the Bank_Tutorial project to the Web Server.
  4. Start the Web Server.
  5. Open a Web browser, specify the URL of the HTML client.

The user interface for this example is created by the Application Generator. The SHTML file generated for this project looks like this:


<HTML>
<HEAD>
 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  <title>
    Bank_Tutorial.Bank_Tutorial Html Client
   </title>
</HEAD>
<body BGCOLOR="#eeeeff">

<H1>  Bank_Tutorial.Bank_Tutorial Html Client  </H1>


<FORM  method="post"
action="/servlet/Bank_Tutorial.Bank_Tutorial.clienthtml.Bank_TutorialGateway">

The action command is referencing a servlet located in the Bank_TutorialGateway file.


Installing the Sun Java Web Server, Inprise Edition

The Sun Java Web Server provides powerful, scalable HTTP engine capabilities for browser-based clients and Java servlets.You can deploy the HTML client to any Web server. The Sun Java Web Server, Inprise Edition is used in this example because it is provided with JBuilder for Application Server.

To install the Sun Java Web Server, Inprise Edition,

  1. Select Sun Java Web Server from the main installer screen for the Application Server.
  2. Specify the directory for the Web Server.
  3. Restart your computer.

Once installed, the Java Web Server contains information that can help you configure and troubleshoot the server. This documentation is contained in the Java Web Server's \doc directory.

Deploying the client files for development and testing

To deploy the HTML client for testing on the development machine, several system .jar files must be copied to a Web Server. The Web Server may be running during this process.

  1. Copy ots.jar from the JBuilder \lib directory to the Java Web Server \lib directory.
  2. Copy orbutil2.0.jar from the JBuilder \lib directory to the Java Web Server \lib directory.
  3. Copy jbcl2.0.jar from the JBuilder \lib directory to the Java Web Server \lib directory.
  4. Copy jgl3.1.0.jar from the JBuilder \lib directory to the Java Web Server \lib directory.
  5. Copy vbjapp.jar from the JBuilder \lib directory to the Java Web Server \lib directory.
  6. Copy vbjorb.jar from the JBuilder \lib directory to the Java Web Server \lib directory.
  7. Build the project by selecting Build|Make Project.

When the project is built, JBuilder copies files to the directories specified on the Servlets tab of the Project Properties dialog. If the properties are set as specified earlier in this chapter, the following files are deployed to the Web server:

Starting the Web Server

To start the Sun Java Web Server,

  1. Run the file httpd.exe from the Java Web Server \bin directory (from Explorer).
  2. Click OK to close the dialog when prompted for a Passphrase For Private Keys.

The Web Server is now running. Minimize the window in which the Web Server is running.

When you want to close the Web Server, select it from the Task Bar, and press Ctrl+C.

Running the Example

To run the HTML client from a Java-enabled browser, enter a URL of the following format:

http://<machine-name>[:<port-number>]/<file-name> 

For example, any of the following URL examples should enable you to run the HTML client.

http://wendy.neverneverland.com/FormBank_Tutorial.shtml
http://localhost/FormBank_Tutorial.shtml
http://127.0.0.1/FormBank_Tutorial.shtml

The URL is composed of the following components:

ComponentDescription
<machine-name> The name of the host that is running the HTTP server. To find the machine-name, run the ipconfig/all command from a DOS prompt on the server. The Host Name information will appear at the top of the list. To test the HTML client locally, the machine-name localhost and the IP address 127.0.0.1 will both usually work as well.
<port-number> This should be set to the port number of your HTTP server. If the port number is not specified in the URL, a default port number of 80 is used. The port can be found by running osfind from a DOS prompt (not the same one that is running the Java Web Server). The osAgent must be set to the same port for distributed objects to be found correctly. For more discussion of the importance of the osAgent port setting, see the "Starting the VisiBroker ORB" chapter.
<file-name> This should be an SHTML file, in this example FormBank_Tutorial.shtml.

The HTML Client looks like this when run from Netscape Navigator 4.0:

HTML Client

Enter a name, click the open button, click the balance button, and the generated balance displays.

Deploying the client files (production environment)

Once the application has been tested in the development environment, it can be deployed in the production environment. The Web Server must not be running when the application is deployed to it, because it looks for the .jar files when it is brought up. To deploy the application,

Once you have deployed your application, you can run the client and server on either the same machine or on different machines in the same subnet.


Other sample applications

Some sample applications using Application Server, VisiBroker, and JBuilder are provided with the product. The applications listed below are some of the samples provided in the \java_examples directory of your Application Server installation. Each sample attempts to incorporate functionality described in the VisiBroker Programmer's Guide, found at \doc\books\vbj\programmer.


For more information on VisiBroker and CORBA

For more advanced information on using JBuilder and VisiBroker to create distributed applications, see the VisiBroker for Java Programmer's Guide which can be accessed from the Inprise Web site at http://www.borland.com/techpubs/books/vbj/vbj33, or from the \doc\books\vbj\programmer directory of your Application Server installation. The programmers's guide contains the following chapters:

You can view the Inprise Application Server User's Guide in the \doc\books\appserver\usersguide directory of your Application Server installation.