Rogue Wave Server 6.1 - Java Component

You should read the following notes, especially the Running Applets section, before you use the a API of the Java component.

General
Initializing your Java Component
Running Applets
Java Data Sources
Using MvTCP

General

The Java Component API lets you develop an Rogue Wave Server client in Java. Most of the concepts used for developing C++ components are still valid with the Java component. This is why it is strongly recommended to read the Rogue Wave Server User's Manual before using this package. This package has been tested on Windows and Solaris.

The Rogue Wave Server Java Data Sources provides you an easy way to connect a graphical interface such as tables, trees or Rogue Wave JViews graphers to Rogue Wave Server applications. Refer to the Rogue Wave Server User's Manual to learn how to use this package.

The Java component API

An HTML documentation is available in the <Server distribution>/doc/java/api directory. To consult it, you can use an index file, named index.html, which lists the different packages.

This distribution contains six main packages:

ilog.server.jcomp

This is the main package making up the Java component. Most of the classes in this package are the Java equivalents of the C++ classes found in the libmvcomp library. To find the C++ version of one of these classes, just had the prefix "Ils" to the short name (i.e. without package naming) of the class.

Example: The Java class ilog.server.jcomp.MvComponent corresponds to the C++ class IlsMvComponent.

ilog.ds.*

Generic data sources that provides basis classe for the Rogue Wave Server Java Data Sources.

ilog.server.jsds.*

Rogue Wave Server implementation of the data sources, to simplify graphical integration with tables, trees, and graphs.

ilog.server.mvtcp

The Rogue Wave Server standard communication layer based on sockets

The archive files are located in the lib/java directory of this release:

mvcomp.jar

This archive file contains the ilog.server.jcomp package.

jsds.jar

This archive file contains the ilog.ds and ilog.server.jsds packages and sub packages.

mvtcp.jar

This archive file contains the ilog.server.mvtcp package and subpackages.

Java SDK support

The java component is built against the J2 SDK SE release. However you should be aware of the two following points:

As OrbixWeb3.0 is no more supported.

Because of the inclusion of ORB classes in the J2 SDK runtime, the following additional arguments must be given to the java interpreter when executing java components within J2 SDK runtime:

-Dorg.omg.CORBA.ORBClass=IE.Iona.OrbixWeb.CORBA.ORB
-Dorg.omg.CORBA.ORBSingletonClass=IE.Iona.OrbixWeb.CORBA.singletonORB

If the client is an applet, the applet tag must be completed as follows:

<param name="org.omg.CORBA.ORBClass" value="IE.Iona.OrbixWeb.CORBA.ORB">
<param name="org.omg.CORBA.ORBSingletonClass" value="IE.Iona.OrbixWeb.CORBA.ORB">

Demonstrations

Three demonstrations are available in the following directories respectively:

<Server distribution>/demo/network6/javacomponent
<Server distribution>/demo/network7/javacomponent
<Server distribution>/demo/network7/dscomponent

These demos require Rogue Wave JViews to be installed.

Usage of Server Java Data Sources is also demonstrate in Dynamic Server demonstration Gantt and Workflow:

<Server distribution>/demo/dynserver/gantt <Server distribution>/demo/dynserver/workflow

Refer to the demonstration Readme file to know how to use these demonstrations.

Initializing your Java Component

Initializing your Java component is a mandatory step because it is the only way of initializing the communication layer. To do this, two static methods are provided in the ilog.server.mvtcp.MvProcess class when using Rogue Wave Server MvTCP communication layer or in ilog.server.corba.orbix31.MvProcess class when using IONA Orbix communication layer (provided in contribution in the contrib directory).

static public boolean Initalize(String[] args)
static public boolean Initialize(Applet ap)

One of these two methods must be called before any connection to a server, depending on whether the client is running as a stand-alone component or as an applet. These methods can also be used to specify options to the Java component. The option format is slightly different in stand-alone clients versus in applets.

In a stand-alone client, options are specified as command-line arguments in a string array that the Initialize method takes as a parameter: the array is parsed and every string beginning by "ils" is analysed. The other strings are ignored.

In an applet, the applet tag is used.

The options format is the following:
Command-line argument: -ilsOPTION_NAME [value]
Applet TAG: <PARAM NAME = "ilog.server.OPTION_NAME" VALUE="value" >

Note:A parameter value is always mandatory in an applet tag, whatever the option.

The following table provides the complete list of options available with Rogue Wave Server.

Command-line Argument	Applet TAG
`-ilsconnect server[@host]`	`<param name="ilog.server.connect" value="server[@host]">`
`-ilsview object.view`	`<param name="ilog.server.view" value="object.view">`
`-ilstrace_component`	`<param name="ilog.server.trace_component" value="yes \| no">`
`-ilstrace_mapping`	`<param name="ilog.server.trace_mapping" value="yes \| no">`
`-ilstrace_component_filename filename`	`<param name="ilog.server.trace_component_filename" value="filename" >`
`-ilstrace_mapping_filename filename`	`<param name="ilog.server.trace_mapping_filename" value="filename">`
`-ilscomm_layer`	`<param name="ilog.server.comm_layer" value="classname">`
`-ilsprotocol_version version`	`<param name="ilog.server.protocol.version" value="version">`

The following table describes the various options:

Option Name	Description	Default Value
`connect`	Specifies the server you want to connect to.
`view`	Specifies the server object and the view you want to open.
`trace_component`	Enables/disables the component trace system.	No
`trace_mapping`	Enables/disables the mapping resolution trace system.	No
`trace_component_filename`	Specifies the name of the file to which the component trace is written.	Standard error
`trace_mapping_filename`	Specifies the name of the file to which the mapping resolution trace is written.	Standard error
`comm_layer`	To initialize the communication layer dynamicly.	ilog.server.mvtcp.MvProcess
`protocol_version`	Change the version of the protocol to be used.	6100

The Java system property can also be used to specify some of the options listed above as configuration options: trace_component, trace_mapping, trace_component_filename, trace_mapping_filename.

During initialization of the component, a special properties file, named mvcomp.properties, is read: each row of this file corresponds to a pair "configuration option, value ". This file is searched in the directories specified:

By the CLASSPATH variable for a standalone client.
In the codebase directory for an applet.

The configuration order is the following (in ascending order):

Default values
Properties file (mvcomp.properties)
Command-line argument or applet tag

Running Applets

With this package it is possible to write Rogue Wave Server clients as applets.

Important: To run demos in a browser, you must download them from a web server.

Once a web server is installed, do the following:

Make the <Server distribution>/demo/network[6|7]/javacomponent/ directories accessible to that web server.
Edit their index.html files.
Add an ARCHIVE attribute to the applet tag as shown below. This will allow specifying where the various archive files are located that the browser needs to download to run the applet.
<CENTER><APPLET
CODE="graph/ConnectionFrame.class"
ARCHIVE="mvcomp.jar_location, svorbixw31.jar_location,OrbixWeb_31.jar_location , jviews.jar_location"
width=600 height=200></CENTER>
...
</APPLET></CENTER>

Note: The archive files (mvcomp.jar ... ) must be accessible to the web server.

Netscape Communicator(Solaris and Windows)

The demonstrations have been tested with the following versions of netscape communicator:

COMMUNICATOR 4.08 (WINDOWS 95/NT)
COMMUNICATOR 4.5 (WINDOWS 95/NT)
COMMUNICATOR 4.08 (UNIX - Solaris)
COMMUNICATOR 4.5 (UNIX - Solaris)

Before you run any demo, the following actions are required :

Because the Visigenic runtime library is integrated in Netscape4.x (file iiop10.jar), it is necessary, in order to use OrbixWeb runtime, to pass additionnal parameters to the applet by completing its tag as follows :
OrbixWeb3.1
< APPLET ...
CODE = ...
ARCHIVE = ...
...
<param name="org.omg.CORBA.ORBClass" value="IE.Iona.OrbixWeb.CORBA.ORB">
<param name="org.omg.CORBA.ORBSingletonClass" value="IE.Iona.OrbixWeb.CORBA.ORB">

</APPLET>

Microsoft Internet Explorer (Windows)

The demonstrations have been tested with Microsoft Internet Explorer, which can be downloaded from http://www.microsoft.com. Before running a demo, you must configure the security options as follows:

Select Internet Options from the Internet Explorer View menu
Click on the Security tab to bring this panel to the front.
Select the zone corresponding to the applet origin.
Set the security level to Custom.
Click the Settings button.
Once the Security Settings panel is displayed, select the Java/Java Permissions/Custom option. This enables the Java Custom Settings button.
Click on the Java Custom Settings button.
Click on the Edit Permissions tab to bring this panel to the front and select the options Access to All Network Addresses and System Information .

Java Data Sources

Rogue Wave Server offers a feature called Java Data Sources that allow you to easily design Graphical User Interfaces using Java Swing and Rogue Wave JViews. Refer to the Getting Started and the User Manual to lean more about this feature.

Using MvTCP

When using MvTCP as the communication layer in a Java component, you should be aware of the thread policy of this communication layer and its implication on your application code.

When initializing MvTCP communication layer in a Java Component, Rogue Wave Server starts a listening thread to accept connections from the server. When a client opens a connection to a server, the server itself opens a connection to the client (the duplex connection). This duplex connection request is handled by this listening thread. If the client is identified (using -ilsn command line option), the server can open a connection on this client. This connection request is also handled by this listening thread.

When a Server to Client connection is opened (because server created a new connection or because of a duplex connection), a dedicated thread is created to read incommining data on the corresponding socket.

As a result, all incomming calls to the component will be handled by the thread in charge of the corresponding connection. You application code, especially methods of your subclasses of RpObject, as well as Representation.beginS2CTransaction() etc.., will be invoked by this connection thread. If you manipulate shared resources (such as graphical objects for instance) you must be aware of the multi-threading issues that may be raised.

If you are using Java Swing for instance, its API is not MT-Safe and data managed by Swing must be modified only by the Swing thread. Rogue Wave Server Java Data Sources, for instance, use javax.swing.SwingUtilities.invokeLater() when receiving notifications from the server to perform changes on graphical objects through the Swing thread.