Table of Contents Previous Next PDF

Architecture and Implementation

Architecture and Implementation
This appendix is a guide to the architecture and implementation of the Oracle Tuxedo Administration Console. It is meant for advanced users and developers who are familiar with the concepts and protocols of the World Wide Web and Java programs.
Architecture Overview
The Oracle Tuxedo Administration Console applet is an advanced client-server application, written in Java on the client side, and C on the server side. The client (user) machine runs a Java applet, and the Oracle Tuxedo server machine runs a gateway program that interfaces with the Oracle Tuxedo MIB (Management Information Base) via a custom protocol.
A Web (HTTP) server is not needed for the actual operation of the GUI, but is necessary for delivering the applet code to the Web browser, and for displaying the online help and snapshots. If you do not already have a Web server on your system, you can use tuxwsvr, which is delivered with the Oracle Tuxedo software.
The Web server does two things:
The gateway program run on the server machine (as mentioned previously) is called wgated. It is not run directly, but is kicked off by the Oracle Tuxedo Administration Console listener, wlisten. If you run the ps command while the GUI is running, you will see one or more wgated processes.
Both tuxwsvr and wlisten listen on distinct network ports waiting for requests to arrive. They know nothing about each other. Therefore, the GUI needs two network ports to operate. These are different from the network ports that are configured in the UBBCONFIG file for the Bridges and tlisten processes.
In order for a Web browser to run a Java applet, the browser must load an HTML file containing an <APPLET> element. The applet element contains the name of the program, and the parameters to it. It is similar to a command line in an ordinary program.
You could certainly hard-code the applet element for a particular invocation of the GUI, and then retrieve that HTML page with your Web browser. However, the flexibility of the Oracle Tuxedo Administration Console architecture makes it unnecessary for you to do so. An initialization file (or .ini file) controls the operation of the GUI. Some of the parameters in the ini file control the applet, some control the server gateway, and some are used by both.
The tuxadm CGI program mentioned above reads the ini file, and merges it with an HTML template file, generating the applet HTML on the fly. The template file, delivered with the Oracle Tuxedo software, resides in:
This is a bare bones template; customers are expected to add their corporate style to it. All that tuxadm does is replace the keyword %APPLET% with the actual applet element. You can specify an alternate location for the template by setting the TEMPLATE parameter in the server's initialization file (see the following instructions).
If you use the “View Source” feature of your Web browser while the GUI is running, you can see this expanded HTML page that is used to deliver the applet.
Before continuing, look at the following example of HTML code generated by tuxadm:
Listing A‑1 Sample HTML Code
<TITLE>BEA Administrator Console Applet Screen</TITLE>
<H1>The Applet is Loading</H1>
<APPLET ARCHIVE="bea/tuxadm/TuxApplet.jar"
WIDTH="400" HEIGHT="150" CODEBASE="/java">
<PARAM NAME="TUXDIR" VALUE="/usr/tuxedo">
<PARAM NAME="SNAPBASE" VALUE="/java/snapshot">
<PARAM NAME="TUXCONFIG0" VALUE="/home/sdo/simpapp/tuxconfig">
<PARAM NAME="TUXCONFIG1" VALUE="/home/sdo/bankapp/tuxconfig">
<B>Your browser does not appear to support JAVA.
Administration Console must be run on a JAVA capable browser.CCheck your browser's options to see if JAVA processing has been disabled.</B>

If you are using encryption for communication between the Administration Console applet and server, the HTML code generated by tuxadm contains some Javascript code. To see this generated code, use “View Source.”
Now you can see why you do not want to create this by hand.
Running the Web Server
To deliver the above HTML and the applet to the Web browser, a Web server must be running.
To run tuxwsvr, use the following command line:
tuxwsvr -l //machine:port -i ini-file
You may have to replace /dev/tcp with the pathname of the correct device name for the network device. This device will be the same one that you used for tlisten, and that you specify for the BRIDGE parameter in the UBBCONFIG file. The string machine:port is based on the standard DNS naming convention used by Oracle Tuxedo. Web servers usually run at port 80. However, because you must be root in order to use that port, we recommend selecting a different one, for example:
This is not the port number that you saw in the applet element shown previously. That port number was the one given to WLISTEN, not TUXWSVR. We haven’t discussed WLISTEN yet.
The ini-file contains the directory mappings for the Web server.
No administrator wants to open up the entire file system to outsiders. Therefore, several aliases are provided for the directory names used by the Oracle Tuxedo Administration Console:
One alias is for the main HTML page that launches the GUI. You will normally bring up the GUI by retrieving the page called webguitop.html. This page has a button that calls the tuxadm CGI program, which returns the above HTML needed to run the applet.
If you do not want the ULOG and Event snapshot files to be written in your Java directory, you may need another alias for a replacement snapshot directory.
When you installed Oracle Tuxedo software from CD, you created a Web server ini file automatically. However, if you do not care for the default values in that file, you will need to create your own ini file.
Add the following to your ini file for the Web server:
CGI /cgi-bin TUXDIR/bin
HTML /java TUXDIR/udataobj/webgui/java
HTML /TUXDIR/udataobj/webgui
TUXDIR should be replaced by the full path to the Oracle Tuxedo root directory, e.g., /usr/tuxedo. Do not put the word TUXDIR in the ini file.
What does this mean? Well, when the Web server gets the initial request to run the CGI program, it will look like /cgi-bin/tuxadm.
The above file maps this to the Oracle Tuxedo bin directory, where tuxadm resides. In a secure environment, you would not do this; you would copy tuxadm somewhere else (or you might need it to be a shell script that sets LD_LIBRARY_PATH and executes the real tuxadm). It also helps to have TUXDIR set in the environment before running tuxwsvr.
The APPLET element has an attribute called CODEBASE which, as you can see from above, is /java. When the Web browser attempts to retrieve the applet from the Web server using the path /java/bea/tuxadm/TuxApplet.class, the above ini file remaps that to the following:
The mapping of / to udataobj/webgui is used to map the top-level Web page, webguitop.html. (Because the java directory is right under the webgui directory, the mapping of /java in the tuxwsvr.ini file is not strictly needed. We have put it there for illustration purposes, in case you want to move your Java files elsewhere.)
If you have installed the Oracle Tuxedo online documentation, you will probably also have a mapping for the documentation.
The Web server’s ini file can contain multiple CGI and HTML lines, and they are processed in sequential order until a match is reached.
This is a good place to describe the difference between the webgui.ini parameters that end in DIR and BASE. DIR means a directory on the server, where wlisten was run. The server programs use files there.
BASE means the URL prefix that a Web browser uses to retrieve a document. The CODEBASE for the Java code is /java, but the server directory for the Java code is /usr/tuxedo/udataobj/webgui/java.
Configuring the Oracle Tuxedo Administration Console
The next step is to set up the webgui.ini file, which is used by tuxadm and wlisten. tuxadm will look in $TUXDIR/udataobj/webgui/webgui.ini if it is not given the INIFILE parameter (more on this later). wlisten requires the ini file path on the command line (more later). (If you have installed Oracle Tuxedo using the installation utility, you probably have a usable webgui.ini file already.)
This is a different ini file from the one described for the Web Server. Listing A-2 shows what your ini file might look like:
Listing A‑2 Sample webgui.ini File
WIDTH=400 (optional)
HEIGHT=150 (optional)
TEMPLATE=/usr/tuxedo/udataobj/webgui/webgui.html (optional)
TUXDIR is where Oracle Tuxedo is installed.
NADDR is the network address that you will use for wlisten, in the standard Oracle Tuxedo syntax (DNS, 0x, . . . or another provider-specific form).
DEVICE is the device filename for the TCP/IP device (not needed on some systems that use sockets, such as HP and IBM).
ENCRYPTBITS is 0, 40, 56, or 128. This parameter specifies the strength of encryption used in communication between the GUI applet and the Administration Console server. The default is 128-bit.
CODEBASE is the path of the directory in which the Java code can be found (i.e., the aliased path recognized by the Web server, not the physical path on the machine).
DOCBASE is where the Oracle Tuxedo help files will be found.
INIFILE is the path of this file (the real path, not the aliased path).
TEMPLATE is where the HTML template file that tuxadm uses to deliver the applet.
The DOMAIN list is optional, especially if you are using the GUI to create your domains from scratch.
For each domain in the domain list (up to 64), include a DOMAIN line that looks like:
The value of tuxconfig-path is the real path, not the aliased path.
Now you can see how the APPLET HTML code is generated by tuxadm.
Once you start using the GUI, it will add some lines to the ini file to store such information as your folder selection lists, and the options you set from the options button.
Running wlisten
Before running wlisten, you need to set the FML32 environment variables so that the programs can find the Oracle Tuxedo MIB field tables. Set the following variables as shown:
The command line for wlisten is:
wlisten -i ini-file
wlisten can operate in either of two security modes:
These modes can be used together or authentication can be used by itself.
Authentication is done based on the tlisten password file. If there is a file of passwords called, in either $TUXDIR/udataobj or $APPDIR/.adm, then the user is required to enter a username and password when the applet starts. The password must match one of the passwords in the password file, or authentication fails. The username is passed to tpinit when the GUI gateway program, wgated, connects to Oracle Tuxedo.
If encryption is also being used, then the communications that occur from then on, between the applet and the server, are encrypted using RSA encryption.
Starting the Oracle Tuxedo Administration Console (for Nonexpert Users)
Now that you have a Web server and a wlisten running, it is time to run the Oracle Tuxedo Administration Console.
The installation script places a file called webguitop.html in the directory used by the Web Server for its general HTML files. The bottom of this file has a Submit FORM, which generates the URL to run tuxadm (the CGI program).
You would normally bring up this Web page by entering the following URL:
and clicking the button at the bottom.
If you want to edit the default webguitop.html file, you should go to the very bottom, where you will see:
<FORM ACTION="http://HOST/CGI-BIN/tuxadm">
You should edit it to something like:
<FORM ACTION="/cgi-bin/tuxadm">
<INPUT TYPE=HIDDEN NAME="INIFILE" VALUE="/home/sdo/gui/webgui.ini">
where INIFILE is set to the place where you have put your GUI ini file.
Starting the Oracle Tuxedo Administration Console (for Developers)
If you have previously agreed to the software license on the webguitop.html page, you can proceed directly into the GUI by using the special URL:
The port is the port at which you ran the Web server (tuxwsvr), not the wlisten. You will get strange results if you use the wlisten port by mistake.
The tuxdir-path is the absolute path of the Oracle Tuxedo root directory on the server machine. The inifile-path is the absolute path of the ini file for the wlisten (not the Web server). INIFILE should match the INIFILE parameter within the ini file. You can leave out the entire &INIFILE= . . . if the INIFILE is in the default location of $TUXDIR/udataobj/webgui/webgui.ini.
The URL that would be used in our example is:
Using Appletviewer
This is an advanced topic not needed by most Administration Console users. However, if you are a Java programmer, you might want to know how to run the Administration Console using the Appletviewer (the standalone program for running a Java applet).
The applet code and images can be installed on a machine where the Java Appletviewer program will be run.
The HTML containing the APPLET element needs to be modified in two ways: the CODEBASE needs to point to a local directory on the machine, and you need to add a HOST parameter to give the DNS name of the machine on which wlisten is running.
In our example from above, your APPLET element would have a new PARAM tag that looks like:
This HOST parameter is undocumented, so do not look for it anywhere.
The Web server is not used in this configuration. However, since you are not using a browser, you will not be able to use the Help system, nor see the ULOG and Event snapshots. The Oracle Administration Console has not been tested on and therefore does not support Java version 1.1.

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.