Copyright (c) 2002, 2006 Insightful, Inc.  All rights reserved.


S-PLUS EJB Sample Code

This directory contains a simple example of accessing S-PLUS as a stateless
session EJB.  It is intended to show that S-PLUS Analytic Server along with
its CONNECT/Java interface may be employed to provide middle-tier access to
S-PLUS within an enterprise system.

We do not recommend the deployment of this sample code in an enterprise
production environment due to several limitations discussed below.  It is
meant as an example only.  With suitable modifications, it can serve as the
basis of your enterprise solution.

If you need a middle-tier solution for accessing S-PLUS in a production
environment, please contact your Insightful sales representative.  We are
currently planning for development of middle-tier add-ons to S-PLUS Analytic
Server, and your input will help us identify which features will be most
important.


RUNNING THE SAMPLE CODE

This sample is configured to run under the jboss application server,
version 2.4.4.  The following instructions assume that you have downloaded
and installed the jboss application server (you can find this at
http://www.jboss.org).

Note that jboss will need a Java 2 Runtime Environment (JRE).  The code
here was tested using the JRE installed with SplusAS (JRE 1.3.0).  Before
invoking jboss, you can set the environmental variable, JAVA_HOME, to
indicate which JRE you wish to use if it is different from the default JRE
available on your computer.  See step (4) below for an example of how to
set environmental variables.  If you wish to use the JRE that comes with
S-PLUS, the path should be `SplusAS SHOME`/java/jre.

In configuring and running this example, we distinguish between the client
host, the jboss host, and the analytic server host.  These may all be the
same machine, or they may all be different machines on a common network.  In
general, all the hosts will need access to a Java installation, and
access to S-PLUS and jboss.  These instructions assume that the installation
directories have been cross-mounted using NFS.

1)  CONFIGURE JBOSS

Before running this example with jboss, you must configure the jboss
properties to indicate the path to an installation (client or server) of
S-PLUS Analytic Server.  On the jboss host, edit the file:

	$JBOSS_HOME/conf/default/jboss.properties

and add a line like:

	splus.shome=/your/path/to/splus/analytic/server

to the end of the file.  You can find the correct path to use by typing:

	> SplusAS SHOME

or

	> SplusClient SHOME

on the command line.  Note that this must be a valid path on the jboss host.

2)  DEPLOY JAR FILES

Copy the SplusEngine.jar file to the $JBOSS_HOME/deploy directory.  Later,
if you rebuild this example, this deployment will happen automatically in
the build process.  This jar file contains the core S-PLUS EJB
implementation.

Copy the client/QueryTester.jar file to the $JBOSS_HOME/lib/ext directory.
Again, this deployment happens automatically if you later rebuild this
example.  This jar file contains the S-PLUS EJB client implementation.  This
deployment provide stub and skeleton classes to jboss that allow the S-PLUS
EJB to call back to the client to obtain login information.

3)  MAKE SURE S-PLUS ANALYTIC SERVER IS RUNNING

Start up S-PLUS Analytic Server as you would normally if it is not already
running.  If Analytic Server is to be run on the same host as jboss, you
must start Analytic server on a port other than 1099.  The jboss application
server uses port 1099 by default.  If Analytic Server is running on a host
other than the jboss host, it may be started on any available
port including the default RMI port 1099.

4)  START THE JBOSS APPLICATION SERVER

You will need to set the environmental variable, JBOSS_CLASSPATH, to include
the Splus.jar file from your S-PLUS Analytic Server installation.  Type:

	> setenv JBOSS_CLASSPATH `SplusAS SHOME`/java/Splus.jar

if you use csh or tcsh.  Otherwise type:

	> JBOSS_CLASSPATH=`SplusAS SHOME`/java/Splus.jar
	> export JBOSS_CLASSPATH

if you use sh, ksh or bash.  Note that if the jboss host has an S-PLUS
client installation, the Splus.jar file is located at
`SplusClient SHOME`/java/jre/lib/ext/Splus.jar.

Normally jboss will be started from a Unix command-line as follows:

	> cd $JBOSS_HOME/bin
	> ./run.sh

5)  VERIFY THAT SplusEngine WAS DEPLOYED SUCCESSFULLY

Start up a browser such as Netscape Navigator, and go to the URL:

	hostname:8082

where "hostname" is the name of your server.  This should show you the admin
screen for jboss.  Check that "jndiName=SplusEngine" is showing in the
"Management" section.

6)  START A CLIENT

a)  Method 1

On a client host, if the directory containing this README is visible,
change directory into the client subdirectory. Set the environmental
variables, SHOME, JAVA_HOME, and JBOSS_HOME to indicate the path to your
S-PLUS installation, the path to your Java 2 SDK, and the path to your jboss
installation respectively.  Then run

	> ./client.sh

from the command line.

b)  Method 2

Alternatively, on the client host, create a client directory and copy into
it the following jar files:

	QueryTester.jar
	SplusEngine.jar
	jboss-j2ee.jar
	jnp-client.jar
	jboss-client.jar
	jbosssx-client.jar
	Splus.jar

and set your CLASSPATH environmental variable to contain all of these jar
files with a command like (for tcsh):

	> setenv CLASSPATH QueryTester.jar:SplusEngine.jar:......

Then you can launch a client using a command like:

	> $JAVA_HOME/bin/java QueryTester ejbhost:1099

7)  RUN AN INITIAL QUERY

The "Query Tester Example" window should now be showing on the client host.
The connection to S-PLUS is not made, however, until an initial query is
submitted.  Type an S-PLUS command into the "S-PLUS input" pane of the Query
Tester, and click on the "send to S-PLUS" button.

A login dialog should appear prompting you to specify the host, username, and
password for the S-PLUS session.  Enter this information, and click the
"Login" button.  The host should indicate the Analytic Server host, and if
you are running Analytic Server on a port other than 1099, you should enter
the correct port as well:

	S-PLUS Host:  ashost:1199
	User Name:  yourname
	Password:  ********

The login takes 5-10 seconds, and then the result of the query should
appear in the "S-PLUS output" pane of the application.

8)  HAVE FUN

All subsequent queries that you submit should be processed immediately
because the S-PLUS login persists for the lifetime of the EJB container.

If you open a second or third client application, jboss will try to service
all of these using this initial S-PLUS session.

If the initial session is busy servicing a client application, and a second
client request is submitted, the EJB container will automatically try to start
another session, and you will again be prompted for login information, as
in step (7).

9)  QUITTING

Be sure to click the "quit" button in the client windows to close them.
Otherwise they may not terminate cleanly.

To close down the S-PLUS sessions created by the EJB container, you need to
stop the jboss server.  A more thoughtful implementation would be needed
in a production environment.



REBUILDING THIS EJB EXAMPLE FROM SOURCE

To rebuild the sample code, you will need a Java Development Kit  (Java 2
SDK), not just a JRE.  The class files that are included in SplusEngine.jar
were compiled using SDK 1.3.0.  You can download an SDK from

	http://java.sun.com/products.

It is assumed that any rebuild will be done on the Analytic Server host, and
that the jboss installation directories on the jboss host are visible from
the Analytic Server host.  If this is not the case, you may need to modify
the build.sh scripts to indicate an alternate CLASS_PATH value and/or change
the copying (deployment) of the rebuilt jar files.

1)  Set the environmental variables, SHOME, JAVA_HOME, and JBOSS_HOME to
indicate the path to your S-PLUS installation, the path to your Java 2 SDK,
and the path to your jboss installation respectively.

2)  From the top-level directory (where this README file is located) run
the shell script, build.sh.  This will recompile the EJB class
files, rebuild the SplusEngine.jar file, and copy it to the jboss
deployment directory.

3)  Change directory (cd) to the client subdirectory and run the shell
script, build.sh.  This will recompile the EJB client class files, rebuild
the QueryTester.jar file, and copy it the lib/ext subdirectory of your
jboss installation.  Note that you must first complete step (2) above -
that is rebuilding the main EJB implementation - before you attempt this
step.  The QueryTester.jar file must grab one of the class files produced
in step (2).

4)  Once the rebuild is complete you may remove any or all of the *.class
files produced during the build process, as well as the client/ejbsplus
subdirectory.


LIMITATIONS OF THIS SAMPLE CODE

1)  Statelessness

An S-PLUS session is intrinsically "stateful".  Variables may be stored,
accessed and modified in the working directory (database).  Files may be
created and modified in the working directory.  If two or more users are
active in a single database, they might easily interfere with eachother in
saving data objects and files.

To provide a truly "stateless" S-PLUS session, some work must be done to
ensure that the working directory is "scrubbed" of by-products at the finish
of each query.

Similarly, multiple instances of sessions should be configured to employ
separate working directories.  In this sample code, no provision has been
made for this, and such configuration must be accomplished manually.

2)  Security

S-PLUS Analytic Server relies on standard Unix security mechanisms.  Each
user must provide a username/password and is bound by the limitations of his
login account.

In a multi-tier enterprise system, a simple Unix security model may no
longer be adequate.  Moreover, the J2EE environment includes an integrated,
fine-grained security model (JAAS) which is tailored for multi-tier
applications.

This sample application side-steps any issues of how security should be
configured in a J2EE application server, and instead propagates the Unix
authentication back to the client as needed.  The major security problem
introduced by this scheme is that once an initial client has provided login
information and a session has been created, subsequently any client may
access that session without any further authentication being done.

3)  Reliability

S-PLUS provides almost unlimited access of system resources to its users,
and an inevitable side-effect of this is that it is possible to hang or
crash the S-PLUS engine by exercising ill-behaved programs.

In an enterprise system where reliability is paramount, some provision
should be made in managing S-PLUS sessions to detect and recover from engine
malfunctions.  No such provision has been made in this example.

4)  Efficiency

No effort has been made in this example to optimize the query processing for
fast response times or low network traffic.  Such optimizations would be
important in a system designed for heavy utilization.
