# Hello Example

## Introduction

The Hello example was created to illustrate how a typical Jini(TM) network technology-based application can be configured and optionally secured using the configuration facilities new with v2.0 of the Jini Technology Starter Kit (starter kit). The applications built from the files in this directory are a server that implements a `Hello` interface with a `sayHello()` method, and a client application that finds this service and calls that method.

There are a number of scenarios under which these two very simple applications can be run. These scenarios are numbered in the sections below. The Jini extensible remote invocation (Jini ERI) facilities (also new with v2.0 of the starter kit) provide many options for configuring an application without changing a single line of Java(TM) programming language source code! The combinations of way in which these small applications can be configured are derived from options like the following:

- Secure or non-secure?
- Activatable or non-activatable?
- If non-secure then using JRMP or Jini ERI?
- If secure then secured through an SSL provider or a Kerberos provider?
- If non-secure and activatable then using a JRMP-configured Phoenix or using a Jini ERI-configured Phoenix?
- Does it use a customized invocation handler?
- etc.

Programs that just say "Hello, world!" never had so many options!

This page provides examples for how to use the `Configuration`, `Exporter`, and `ProxyPreparer` interfaces to configure programs and their use of remote communication and security. It includes references to the source files for the application as well as to the files needed to configure the applications in different ways.

You can explore the contents of the files below to provide a starting point for designing and configuring applications. Follow the directions to run the example application in different configurations.

## Files

The examples use a simple application that accesses a remote server which implements the `Hello` interface:

- `Client.java` - the client application
- `Server.java` - the server application
- `Hello.java` - the interface
- `Proxy.java` - the proxy that implements the interface `Hello`

All configurations utilize an HTTP server that can be started by one of the scripts shown below:

- `scripts/httpd.bat` - batch file to run the HTTP server on a Windows platform
- `scripts/httpd.sh` - shell script to run the HTTP server on a UNIX(TM) platform

There are three non-secure, non-activatable server configurations:

1. Server using JRMP
   - `config/jrmp-server.config` - configuration source file
   - `scripts/jrmp-server.bat` - batch file to run server
   - `scripts/jrmp-server.sh` - shell script to run server

2. Server using Jini ERI
   - `config/jeri-server.config` - configuration source file
   - `scripts/jeri-server.bat` - batch file to run server
   - `scripts/jeri-server.sh` - shell script to run server

3. Server using Jini ERI with a custom Invocation Layer (IL) factory that uses pop-up dialog windows to confirm calls
   - `config/confirming-jeri-server.config` - configuration source file
   - `scripts/confirming-jeri-server.bat` - batch file to run server
   - `scripts/confirming-jeri-server.sh` - shell script to run server
   - `ConfirmingILFactory.java` - custom IL factory
   - `ConfirmingInvocationHandler.java` - custom invocation handler

All non-secure, non-activatable servers use the same security policy file:

- `config/server.policy` - security policy file

Servers register with a Jini lookup service. The files used to configure and start a non-secure version of the Reggie lookup service implementation are listed below:

- `config/start-reggie.config` - configuration file to start Reggie using JRMP
- `config/jrmp-reggie.config` - configuration file for a JRMP-configured Reggie
- `scripts/jrmp-reggie.bat` - batch file to start a non-secure Reggie
- `scripts/jrmp-reggie.sh` - shell script to start a non-secure Reggie
- `config/start.policy` - policy file for starting non-secure Reggie
- `config/reggie.policy` - policy file for a non-secure Reggie

Note that these examples configure Reggie using JRMP to illustrate that JRMP and Jini ERI services can easily coexist.

Activatable configurations use `ActivatableServer.java` to help start the activatable server application.

There is a non-secure, activatable server, with its own security policy file:

4. Activatable server using Jini ERI
   - `config/start-activatable-jeri-server.config` - configuration source file for starting server
   - `config/activatable-jeri-server.config` - configuration source file for server
   - `config/start-activatable-server.policy` - security policy file for starting server
   - `config/activatable-server.policy` - security policy file for server
   - `scripts/activatable-jeri-server.bat` - batch file for starting server
   - `scripts/activatable-jeri-server.sh` - shell script for starting server

The non-secure, activatable server may be used with the activation system daemon supplied by either of the following two configurations of Phoenix:

- Phoenix using JRMP
  - `config/jrmp-phoenix.config` - configuration source file to start Phoenix
  - `config/jrmp-phoenix-group.config` - configuration source file used by a running Phoenix to start services in a group
  - `scripts/jrmp-phoenix.bat` - batch file to run Phoenix
  - `scripts/jrmp-phoenix.sh` - shell script to run Phoenix
- Phoenix using Jini ERI
  - `config/jeri-phoenix.config` - configuration source file to start Phoenix
  - `config/jeri-phoenix-group.config` - configuration source file used by a running Phoenix to start services in a group
  - `scripts/jeri-phoenix.bat` - batch file to run Phoenix
  - `scripts/jeri-phoenix.sh` - shell script to run Phoenix

Both non-secure Phoenix configuration use the same security policy file:

- `config/phoenix.policy` - security policy file

All non-secure servers may be used by the same client:

- `config/client.config` - configuration source file
- `config/client.policy` - security policy file
- `scripts/client.bat` - batch file to run client
- `scripts/client.sh` - shell script to run client

To add security, one can choose to use either the SSL or the Kerberos provider. When run in secure configurations, the applications do a JAAS login and run as the logged-in subject. The SSL servers read their passwords from a file; for the SSL client, type the password clientpw into the pop-up dialog window that prompts for it.

The Kerberos servers get their keys from a keytab file. The scripts and configurations supplied assume the name and location of this keytab file is `krb-servers.keytab` in the `config` directory. (You will need to create a keytab file for your environment.)

The Kerberos client prompts its user for a password so it can complete the authentication process. Once authenticated, it receives a Ticket Granting Ticket (TGT) which can be used to facilitate future secure interactions. In this case, it will be used to communicate with Reggie and the server so it may eventually call the method to print "Hello, world!". For more details on Kerberos and JAAS, see the Kerberos tutorial.

For instructions on how to create keytab files and TGT caches, see krb-setup.html.

Before invoking any script using Kerberos (scripts that have `krb` in their name), you need to update `scripts/krb-setenv.sh`, or `scripts\krb-setenv.bat` if you are using Microsoft Windows. This script is "sourced" at the beginning of all other `krb` scripts to set the relevant environment variables to the right values. The environment variables used by the Kerberos scripts are the following:

- `CLIENT` - client principal
- `SERVER` - server principal
- `PHOENIX` - phoenix principal
- `REGGIE` - reggie principal
- `REALM` - KDC default realm name
- `KDC_HOST` - DNS name or IP address of the KDC host

If any of these variables have already been defined in the environment, their values override those specified in the `krb-setenv` script.

All secure services (the server, Reggie, and Phoenix) use the following file:

- `config/dynamic-policy.security-properties` - security properties file that installs dynamic security policy provider

All secure server configurations use the following files:

- `ServerPermission.java` - server access control permission
- `MdClassAnnotationProvider.java` - preferred class provider that uses HTTPMD URLs to insure integrity of downloaded code

There are two secure, non-activatable server configurations using SSL:

5. Secure server using SSL
   - `config/ssl-server.config` - configuration source file
   - `scripts/ssl-server.bat` - batch file to run server
   - `scripts/ssl-server.sh` - shell script to run server

6. Secure server using SSL with a custom IL factory that uses pop-up dialog windows to confirm calls
   - `config/confirming-ssl-server.config` - configuration source file
   - `scripts/confirming-ssl-server.bat` - batch file to run server
   - `scripts/confirming-ssl-server.sh` - shell script to run server

Both secure, non-activatable servers using SSL use the same security policy file:

- `config/ssl-server.policy` - security policy file

The files used to configure and start a secure lookup service using SSL are listed below:

- `config/start-ssl-reggie.config` - configuration file to start a secure Reggie using SSL
- `config/ssl-reggie.config` - configuration file for a secure Reggie using SSL
- `scripts/ssl-reggie.bat` - batch file to start a secure Reggie using SSL
- `scripts/ssl-reggie.sh` - shell script to start a secure Reggie using SSL
- `config/ssl-reggie.policy` - policy file for a secure Reggie using SSL (also used by start service)
- `config/ssl-reggie.login` - JAAS login configuration file

There is one configuration for a secure, activatable server using SSL:

7. Secure activatable server using SSL
   - `config/start-activatable-ssl-server.config` - configuration source file for starting server
   - `config/activatable-ssl-server.config` - configuration source file for server
   - `config/start-activatable-ssl-server.policy` - security policy file for starting server
   - `config/activatable-ssl-server.policy` - security policy file for server
   - `scripts/activatable-ssl-server.bat` - batch file to start server
   - `scripts/activatable-ssl-server.sh` - shell script to start server

The secure, activatable server using SSL may be used with the activation system daemon supplied by the following configuration of Phoenix:

- Secure Phoenix using SSL
  - `config/ssl-phoenix.config` - configuration source file for starting Phoenix
  - `config/ssl-phoenix-group.config` - configuration source file used by Phoenix to start activation groups
  - `config/ssl-phoenix.policy` - security policy file
  - `config/ssl-phoenix.login` - JAAS login configuration file
  - `scripts/ssl-phoenix.bat` - batch file to run Phoenix
  - `scripts/ssl-phoenix.sh` - shell script to run Phoenix

All secure servers using SSL share the following file:

- `config/ssl-server.login` - JAAS login configuration file

All secure servers using SSL may be used by the same secure client using SSL:

- `config/ssl-client.config` - configuration source file
- `config/ssl-client.login` - JAAS login configuration file
- `config/ssl-client.policy` - security policy file
- `scripts/ssl-client.bat`- batch file to run client
- `scripts/ssl-client.sh` - shell script to run client

There are two secure, non-activatable server configurations using Kerberos:

8. Secure server using Kerberos
   - `config/krb-server.config` - configuration source file
   - `scripts/krb-server.bat` - batch file to run server
   - `scripts/krb-server.sh` - shell script to run server

9. Secure server using Kerberos with a custom IL factory that uses pop-up dialog windows to confirm calls
   - `config/confirming-krb-server.config` - configuration source file
   - `scripts/confirming-krb-server.bat` - batch file to run server
   - `scripts/confirming-krb-server.sh` - shell script to run server

Both secure, non-activatable servers using Kerberos use the same security policy file:

- `config/krb-server.policy` - security policy file

The files used to configure and start a secure lookup service using Kerberos are listed below:

- `config/start-krb-reggie.config` - configuration file to start a secure Reggie using Kerberos
- `config/krb-reggie.config` - configuration file for a secure Reggie using Kerberos
- `scripts/krb-reggie.bat` - batch file to start a secure Reggie using Kerberos
- `scripts/krb-reggie.sh` - shell script to start a secure Reggie using Kerberos
- `config/krb-reggie.policy` - policy file for a secure Reggie using Kerberos (also used by start service)
- `config/krb-reggie.login` - JAAS login configuration file

There is one configuration for a secure, activatable server using Kerberos:

10. Secure activatable server using Kerberos
    - `config/start-activatable-krb-server.config` - configuration source file for starting server
    - `config/activatable-krb-server.config` - configuration source file for server
    - `config/start-activatable-krb-server.policy` - security policy file for starting server
    - `config/activatable-krb-server.policy` - security policy file for server
    - `scripts/activatable-krb-server.bat` - batch file to start server
    - `scripts/activatable-krb-server.sh` - shell script to start server

The secure, activatable server using Kerberos may be used with the activation system daemon supplied by the following configuration of Phoenix:

- Secure Phoenix using Kerberos
  - `config/krb-phoenix.config` - configuration source file
  - `config/krb-phoenix-group.config` - configuration source file used by a running Phoenix to start services in a group
  - `config/krb-phoenix.policy` - security policy file
  - `config/krb-phoenix.login` - JAAS login configuration file
  - `scripts/krb-phoenix.bat` - batch file to run Phoenix
  - `scripts/krb-phoenix.sh` - shell script to run Phoenix

All secure servers using Kerberos share the following files:

- `config/krb-server.login` - JAAS login configuration file

All secure servers using Kerberos may be used by the same secure client using Kerberos:

- `config/krb-client.config` - configuration source file
- `config/krb-client.login` - JAAS login configuration file
- `config/krb-client.policy` - security policy file
- `scripts/krb-client.bat` - batch file to run client
- `scripts/krb-client.sh` - shell script to run client

The server download JAR file specifies preferred classes to be recognized by the `PreferredClassLoader` class to insure that the downloaded versions of invocation handlers and proxy classes are used. The preferred settings are specified by the following file:

- `config/META-INF/PREFERRED.LIST` - preferred classes list

The example includes prebuilt class and JAR files. If you want to experiment with modifying and rebuilding the example, the example includes the following files for rebuilding the JAR files:

- `Makefile` - `gmake` makefile for building the example
- `server.mf` - Manifest for server.jar, the non-activatable server
- `server-act.mf` - Manifest for server-act.jar, the activatable server
- `client.mf` - Manifest for client.jar

## Makefiles

The JAR files for this example come pre-built in the `lib` directory and all of the keys necessary to run the SSL configuration are also pre-built in the `prebuiltkeys` directory. Should you wish to experiment with making changes to the source and rebuilding the JAR files, a `Makefile` compatible with `gmake` is supplied. The `Makefile` can also be used to create the necessary key files as found in the `prebuiltkeys` directory.

To rebuild the JAR files, type:

      gmake -f Makefile

The files `GNUmakefile`, `GNUmakefile.jars`, and `GNUmakefile.stubs` are used by the comprehensive make system for the starter kit. If you're only rebuilding the example, you can ignore these files.

## Directions for running the example

### Installing the dynamic policy granting feature

These examples take advantage of dynamic policy granting features in the starter kit. The JAR file `jsk-policy.jar` must be installed into the Java(TM) 2 runtime environment to enable this feature. The steps below outline the process for installing this JAR file.

1. Locate the `jsk-policy.jar` file in the `lib` directory of the starter kit.
2. Locate the `jre/lib/ext` directory inside your Java(TM) 2 SDK distribution.
3. Copy the `jsk-policy.jar` file from the starter kit to the `jre/lib/ext` directory as located above. This will make the dynamic policy provider feature available.

Also make sure that the virtual machine for the Java platform associated with this `ext` directory is available in your path.

### Populating the `lib` directory

#### Copying JAR files

The JAR files for the hello examples may be found in the `lib` subdirectory of the `hello` directory. They are:

- `client.jar` - the client application
- `server.jar` - the non-activatable server application
- `server-act.jar` - the activatable server application
- `server-dl.jar` - the download JAR file for the server
- `mdprefld.jar` - the class annotation facility

These JAR files require other JAR files from the `lib` directory of the starter kit to run properly. These additional JAR files are:

- `jsk-platform.jar` - classes and interfaces that are assumed to be available in all applications used in this example
- `jsk-resources.jar` - resources used by jsk-platform.jar
- `phoenix.jar` - contains the Phoenix service implementation
- `phoenix-dl.jar` - contains the Phoenix download JAR file
- `phoenix-init.jar` - used by Phoenix to help activate services
- `phoenix-group.jar` - used by Phoenix to help activate services
- `reggie.jar` - contains the Reggie service implementation
- `reggie-dl.jar` - contains the Reggie download JAR file
- `sdm-dl.jar` - contains the Service Discovery Manager download JAR file
- `start.jar` - contains the start utility JAR file
- `tools.jar` - contains the simple HTTP server supplied with the starter kit

Copy each of the above JAR files (`jsk-platform.jar`, `jsk-resources.jar`, `phoenix.jar`, `phoenix-dl.jar`, `phoenix-init.jar`, `phoenix-group.jar`, `reggie.jar`, `reggie-dl.jar`, `sdm-dl.jar`, `start.jar`, and `tools.jar`) from the `lib` subdirectory of the starter kit to the `lib` subdirectory of the `hello` directory.

All of the JAR files necessary to run the client, server, and supporting programs are now in the `lib` directory under `hello`.

#### Creating keys

There are a number of files needed to support the secure examples. These files are:

- `client.cert`
- `client.keystore`
- `phoenix.cert`
- `phoenix.keystore`
- `phoenix.password`
- `reggie.cert`
- `reggie.keystore`
- `reggie.password`
- `server.cert`
- `server.keystore`
- `server.password`
- `truststore`

These files may be either copied from the `prebuiltkeys` directory within the `hello` directory or built using the `Makefile`. These instructions will assume that the files will be copied from the `prebuiltkeys` directory.

Copy all of the files from the `prebuiltkeys` directory into the `lib` directory located within the `hello` directory.

#### Verifying the contents of the `lib` directory

The `lib` directory should now contain the following files:

    client.cert         phoenix-group.jar   reggie.cert         server.cert
    client.jar          phoenix-init.jar    reggie.jar          server.jar
    client.keystore     phoenix.cert        reggie.keystore     server.keystore
    jsk-platform.jar    phoenix.jar         reggie.password     server.password
    jsk-resources.jar   phoenix.keystore    sdm-dl.jar          start.jar
    mdprefld.jar        phoenix.password    server-act.jar      tools.jar
    phoenix-dl.jar      reggie-dl.jar       server-dl.jar       truststore

### Running the scripts

Note: Run each command described below from the `hello` directory.

Before running any example configurations, start an HTTP server to serve up the files in the `lib` subdirectory. The `ClassServer` included in the `tools.jar` is used for this purpose.

To run the `ClassServer` on UNIX platforms:

       sh scripts/httpd.sh &

To run the `ClassServer` on Microsoft Windows platforms:

       start scripts\httpd

To run a non-activatable example configuration, start Reggie, the server, and then the client. For example, on UNIX platforms, do:

       sh scripts/jrmp-reggie.sh &
       sh scripts/confirming-jeri-server.sh &
       sh scripts/client.sh

On Microsoft Windows platforms, do:

       start scripts\jrmp-reggie
       start scripts\confirming-jeri-server
       scripts\client

To run an activatable example configuration, start Phoenix, Reggie, the server, and then the client. Make sure to wait for Phoenix to print a message saying it is ready before starting the server. Before starting Phoenix, make sure to remove the Phoenix log directory if it was produced by an earlier Phoenix run using a different configuration. For example, on UNIX platforms do:

       rm -rf lib/phoenix-log

On Microsoft Windows platforms, do:

       rmdir /S /Q lib\phoenix-log

For example, to start an activatable SSL server on UNIX, do:

       sh scripts/ssl-reggie.sh &
       sh scripts/ssl-phoenix.sh &
       sh scripts/activatable-ssl-server.sh
       sh scripts/ssl-client.sh

On Microsoft Windows platforms, do:

       start scripts\ssl-reggie
       start scripts\ssl-phoenix
       scripts\activatable-ssl-server
       scripts\ssl-client

Note that the password to use for the SSL client is clientpw.

## Additional resources

Please visit jini.org to explore the many resources provided by the Jini Community(SM).

Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.