Facilities Guide

CHAPTER 5

SilverJ2EEClient

This chapter describes SilverJ2EEClient, the facility provided with the Novell exteNd Application Server to host Java-based clients for J2EE applications. Topics include:

• About SilverJ2EEClient

• Installing SilverJ2EEClient

• Starting SilverJ2EEClient

• Using startup options

• Passing application arguments

• Supporting access to secured EJBs

About SilverJ2EEClient

If your production environment includes J2EE application clients, the user machines running them will need to install and use SilverJ2EEClient. SilverJ2EEClient is a low-administration J2EE application client container that hosts your clients with a robust set of supporting J2EE services (including deployment, JNDI namespace access, and security authentication).

    For information on developing J2EE application clients, see the exteNd Director help.

SilverJ2EEClient features

Users invoke SilverJ2EEClient to run J2EE application clients you've deployed to the application server. The features SilverJ2EEClient provides to support these clients include:

Installing SilverJ2EEClient

To minimize administration effort, the Novell exteNd Application Server can host installers that users then download to set up the current version of SilverJ2EEClient. The server also offers an install page that users can browse to for easy selection of the appropriate installer flavor (Windows, UNIX, or Linux).

Hosting the SilverJ2EEClient installers on your server

The SilverJ2EEClient installers are not included when you install the Novell exteNd Application Server from the product CD. If you want to host these installers on your application server, you must obtain them from the Novell developer Web site and store them in the appropriate server directory.

To host the installers:

1. Download the SilverJ2EEClient installer files from developer.novell.com/ndk/j2eeclient.htm

2. Copy the downloaded installer files to the following Novell exteNd directory on your application server machine:

     AppServer\Resources\SilverJ2EEClientInstall
   

When you complete these steps, the SilverJ2EEClient installers will be ready for users to access from your server.

Going to the SilverJ2EEClient install page

By default, the SilverJ2EEClient install page is available from your server at the following URL:

  http://servername/SilverStream/Pages/SilverJ2EEClient.html

You can instruct users to type this URL directly in their browsers, or you can supply a page that links to it for easier access.

Using the install page   Once displayed, the SilverJ2EEClient install page provides links that users can click to download:

• A Windows version of the SilverJ2EEClient installer

• UNIX or Linux versions of the SilverJ2EEClient installer (for supported platforms)

This page also includes instructions for using the installers and for starting SilverJ2EEClient once installed.

Providing direct access to the installers   You may want to let users download a SilverJ2EEClient installer directly, without going to the SilverJ2EEClient install page first. In that case you can instruct them to type one of the following URLs, or you can link to it from your own pages:

These URLs all begin with:

  http://servername/SilverStream/SilverJ2EEClientInstall/

NetWare support for the installers   On Novell NetWare, the application server can host the SilverJ2EEClient installers for Windows, UNIX, and Linux clients. To download these installers, users can access the SilverJ2EEClient install page from the application server. Because NetWare is a server platform, there isn't a NetWare version of the SilverJ2EEClient installer for users to download.

SilverJ2EEClient itself is automatically installed on the NetWare machine when you install the application server. Also, you can use the Novell Clients Software CD that accompanies NetWare to install Novell exteNd Application Server Clients (which includes SilverJ2EEClient) on Microsoft Windows machines.

    For more information on NetWare install issues, see Installing Novell exteNd.

Installing on Windows

Once you download the Windows version of the SilverJ2EEClient installer, you'll have the following file on your local machine:

  SilverJ2EEClientInstall.exe

Run this file to install SilverJ2EEClient and the supporting components it requires.

What gets installed   When the installer is done, you'll have a directory for SilverJ2EEClient on your local machine that contains:

• SilverJ2EEClient executable (SilverJ2EEClient.exe)

• exteNd runtime files (ZIPs and JARs of API packages and supporting files)

• Java 2 Runtime Environment (JRE)

• Java HotSpot Performance Engine

• Novell exteNd ORB (a Java-based CORBA ORB, set up as the default ORB for the machine)

SilverJ2EEClient should now be ready to use on this machine.

Installing on UNIX or Linux

Once you download a UNIX or Linux version of the SilverJ2EEClient installer, you'll have the following file on your local machine: SilverJ2EEClientInstallPlatform.sh. Run this file to install SilverJ2EEClient and the supporting components it requires.

For example:

• In Solaris, type sh SilverJ2EEClientInstallSolaris.sh

• In Linux, type sh SilverJ2EEClientInstallLinux.sh

What gets installed   When the installer is done, you'll have a directory for SilverJ2EEClient on your local machine that contains:

• SilverJ2EEClient executable (SilverJ2EEClient)

• exteNd runtime files (ZIPs and JARs of API packages and supporting files)

• Java 2 Runtime Environment (JRE)

• exteNd ORB (a Java-based CORBA ORB, set up as the default ORB for the machine)

SilverJ2EEClient should now be ready to use on this machine.

    For detailed information about UNIX or Linux platform support, see the Release Notes.

Installing from the product CD

Another way to install SilverJ2EEClient is to use the Novell exteNd installation program from your product CD. This program enables you to install SilverJ2EEClient (and supporting files) alone or along with other application server components.

Installing SilverJ2EEClient this way is primarily for developers. The result is the same as accessing the SilverJ2EEClient install page (SilverJ2EEClient.html) from the server to do the installation.

    For more information on using the Novell exteNd installation program, see Installing Novell exteNd.

If you're using Novell NetWare, see NetWare support for the installers.

Starting SilverJ2EEClient

You can start SilverJ2EEClient in several different ways, depending on the platform you're using (Windows, NetWare, UNIX, or Linux).

Running on Windows

In Windows, you can start SilverJ2EEClient by doing either of the following:

• Using the executable

  OR

• Using SJC files

Using the executable   You can start SilverJ2EEClient from the command prompt by invoking the executable program SilverJ2EEClient.exe. Enter:

  installdirectory\bin\SilverJ2EEClient [options] 
     [protocol://]hostname[:port] databasename clientname [appargs]

where:

  c:\SilverJ2EEClient

  -as_username=sam -as_password=icecream

  corporate

  8080

  sales

  quotaclient

  myarg -myswitch -y 2003

For example:

  c:\SilverJ2EEClient\bin\SilverJ2EEClient 
     -as_username=sam -as_password=icecream 
     http://corporate:8080 sales quotaclient 
     myarg -myswitch -y 2003

If you don't want to type the command every time, you can create a batch (BAT) file to issue it.

Using SJC files   Another alternative to starting SilverJ2EEClient from the command prompt is to use SJC files. SJCs are SilverJ2EEClient application files in which you store all the arguments you'd otherwise type. Opening an SJC file automatically invokes the SilverJ2EEClient executable SilverJ2EEClient.exe and uses those arguments.

The association between the SJC file extension and SilverJ2EEClient.exe is automatically set up in Windows when you install SilverJ2EEClient.

To create an SJC file:

1. Open a new text file in an editor of your choice.

2. Type the following on a single line:

     [options] [protocol://]hostname[:port] databasename clientname 
        [appargs]
   

   For example:

     -as_username=sam -as_password=icecream 
        http://corporate:8080 sales quotaclient 
        myarg -myswitch -y 2003
   

3. Save this text file with the extension SJC. For example:

     quota.sjc
   

Once you have an SJC file, you can:

• Create a Windows shortcut to launch it

• Send it to someone in e-mail

• Link to it from any HTML page—for instance:

    <a href="quota.sjc">Quota Client</a>
  

Running on NetWare

In NetWare, you can start SilverJ2EEClient from the system console by invoking the executable program SilverJ2EEClient.nlm (installed in SYS:\exteNd\AppServer\bin). Enter:

  SilverJ2EEClient [options] [protocol://]hostname[:port] 
     databasename clientname [appargs]

where:

  -as_username=sam -as_password=icecream

  corporate

  83

  sales

  quotaclient

  myarg -myswitch -y 2003

For example:

  SilverJ2EEClient -as_username=sam -as_password=icecream 
     http://corporate:83 sales quotaclient 
     myarg -myswitch -y 2003

If you don't want to type the command every time, you can create an NCF file to issue it.

Running on UNIX or Linux

In UNIX or Linux, you can start SilverJ2EEClient from the command prompt by invoking the executable program SilverJ2EEClient. Enter:

  installdirectory/bin/SilverJ2EEClient [options] 
     [protocol://]hostname[:port] databasename clientname [appargs]

where:

  /export/home/sam/SilverJ2EEClient

  -as_username=sam -as_password=icecream

  corporate

  8888

  sales

  quotaclient

  myarg -myswitch -y 2003

For example:

  /export/home/sam/SilverJ2EEClient/bin/SilverJ2EEClient 
     -as_username=sam -as_password=icecream 
     http://corporate:8888 sales quotaclient 
     myarg -myswitch -y 2003

If you prefer to work in the desktop environment, you can set up an icon to issue the command or run from your file manager.

Displaying a console window

This section describes how developers can display console information on the screen when running SilverJ2EEClient in Windows.

Using the console version of SilverJ2EEClient   The Novell exteNd Application Server development environment on Windows provides a way to display standard output and error messages from SilverJ2EEClient. SilverJ2EEClient_c.exe (in the server's \bin directory) is a console version of SilverJ2EEClient that you can invoke instead of the usual end-user executable (SilverJ2EEClient.exe). You can start it from the command prompt by typing:

  serverdirectory\bin\SilverJ2EEClient_c [options] 
     [protocol://]hostname[:port] databasename clientname [appargs]

For example:

  c:\Program Files\Novell\exteNdn\AppServer\bin\SilverJ2EEClient_c 
     -as_username=sam -as_password=icecream 
     http://corporate:8080 sales quotaclient 
     myarg -myswitch -y 2003

Any standard output and error messages from SilverJ2EEClient then display in the command prompt window you're running from. That includes messages related to startup issues.

Displaying your own splash screen

SilverJ2EEClient enables you to specify a JPG file of your choice as the splash screen to display whenever it starts up.

To specify the splash screen image:

1. Install your JPG file on the user machine in one of the following ways:

   • In the file system, on a path that ends with:

       com\sssw\jrunner\Splash.jpg
     

   • In a JAR or ZIP file containing that path

2. Set the AGCLASSPATH environment variable to specify either:

   • The path leading up to the com directory

       set AGCLASSPATH=c:\myapp
     

   • The path of the JAR or ZIP file

       set AGCLASSPATH=c:\myapp\mysplash.jar
     

SilverJ2EEClient in the development environment

When you invoke SilverJ2EEClient (or SilverJ2EEClient_c) in your development environment to test a client deployment, make sure the current directory is not the one containing your local development version of that client (compiled classes, JARs, and so on). Doing so causes classpath confusion that may prevent the client from running properly.

Using startup options

There are two kinds of options you can provide when starting SilverJ2EEClient:

• - options    These are options specific to the Novell exteNd Application Server environment. (They are passed to the JRunner class.)

• + options    (Windows only) Some of these options are passed directly to the Java interpreter (at which time the + characters are changed to - characters). Others are handled by the SilverJ2EEClient executable to launch the Java interpreter.

Using - options

The following tables describe the - options you can provide when starting SilverJ2EEClient:

  -as_username=sam

  -as_password=icecream

  -as_proxy=corpproxy
  -as_proxy=corpproxy:8080

  SilverJ2EEClient -as_proxy=corpproxy
     https://finance payroll salaryclient

Client certificate options   You can specify one of the following sets of options for client certificate support:

Using + options

The following table describes + options you can provide when starting SilverJ2EEClient in Windows:

You can also pass standard VM options directly to the Java interpreter by specifying them as + options. The + character is automatically converted to - as the option is passed.

For example, specifying:

  +verbose

passes this option to the Java interpreter as:

  -verbose

Passing application arguments

When developing a J2EE application client, you can code it to look for one or more application-specific arguments at runtime and then perform some processing based on those arguments. To help you do that, this section describes how to:

1. Pass application arguments to a client when starting SilverJ2EEClient

2. Enable the client to access and use those arguments

Specifying the arguments to pass

When starting SilverJ2EEClient, add any application arguments to the end of the command (after the name of the client to run). For instance, to pass the arguments -dollars and 2 to the client named rateclient (in the service database on the custserv server), you specify:

  SilverJ2EEClient custserv service rateclient -dollars 2

Here are some additional rules to keep in mind:

• Arguments before the client name are assumed to be startup options and are not passed to the client.

• Arguments that begin with -as_ are assumed to be startup options and are not passed to the client (even if they are after the client name).

• Startup options not beginning with -as_ must be before the client name. Otherwise, they are assumed to be application arguments and are passed to the client.

    For more information on the command syntax, see Starting SilverJ2EEClient.

Accessing the arguments from a client

When SilverJ2EEClient starts a client, it invokes the main() method of the client's main class and passes any application arguments to that method as a String array. You can then read them just as you would in any Java application.

Supporting access to secured EJBs

An Enterprise JavaBean (EJB) deployed on the Novell exteNd Application Server may be secured so that an IIOP over SSL connection is automatically used when someone tries to access it. To support this kind of connection, SilverJ2EEClient includes the following JAR file of CA (Certificate Authority) certificates: agrootca.jar (located in the SilverJ2EEClient \Common\lib directory).

If you need to use a CA certificate that isn't in this file, you must add it. Use the JAR editing tool of your choice (such as the Sun JAR utility or WinZip).

    For more information on secured connections to EJBs, see the chapter on setting up security in the Administrator's Guide.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...