This file discusses the contents and use of the examples located 
under the 'example' directory from the file jini-start-examples.zip. 

The discussion below assumes you have installed the example files, 
and modified either <install-dir>/example/scripts/urun or 
<drive>:\<install-dir>\example\scripts\wrun.bat according to the 
instructions contained in the file INSTALL.TXT.

The files located under the 'example' directory consist of scripts,
configuration files, and policy files that can be used to start any
of the contributed service implementations provided in the 2.0 
release of the Jini(TM) Technology Starter Kit (the Starter Kit).
Whereas the scripts are provided as a convenience, the configuration 
files and policy files provided here are intended to be learning aids. 
Therefore, you are encouraged to study the in-line documentation contained 
in each configuration file and each policy file.

FILE ORGANIZATION --

The example files are organized under the 'example' directory in
sub-directories with names that indicate the purpose of the files 
contained under each sub-directory. That is,

                              <install-dir>
                                    |      
                                 example   
                                    |   
    --------------------------------------------------------------------
    |    |    |      |     |     |      |         |      |       |     |
 browser |  fiddler  |  mercury  |  outrigger     |   reggie     |  sharedvm
         |           |           |                |              |
      common       mahalo       norm           phoenix        scripts

The sub-directories with names corresponding to a particular service 
implementation, daemon (Phoenix), or utility (the Browser) contain files
related to that service, daemon, or utility. Whereas the files residing under
such a sub-directory are related to only that particular service, daemon, 
or utility, the files residing under the 'common' sub-directory are related 
to ('common' to) all of the applications. For example, shared logging 
configuration files and configuration files for the Service Starter 
framework's setup VM are contained under this sub-directory.

The files residing under the 'sharedvm' sub-directory are needed when using
the ServiceStarter framework to run the services in a Shared VM. Finally,
all of the convenience scripts are located under the sub-directory named
'scripts'.

Generally, the sub-directories above are further organized according to 
specify the protocol that will be used when running the corresponding service,
daemon, or utility; that is, jrmp, Jini ERI, or secure Jini ERI/jsse 
(currently, these examples do not address kerberos). Thus, under the directory
named 'reggie', one should see the following structure:

   <install-dir>
     |-- example   
         |-- reggie
             |-- jeri
             |-- jrmp
             |-- jsse

And then, under each of the protocol-specific sub-directories, one should 
see a directory structure like the following,

   <install-dir>
     |-- example   
         |-- reggie
             |-- jeri
             |   |-- config
             |   |-- policy
             |-- jrmp
             |   |-- config
             |   |-- policy
             |-- jsse
                 |-- config
                 |-- policy

As one might expect, the files contained in the 'config' sub-directory, 
residing under the 'jeri' directory of the 'reggie' parent directory, 
are used to configure Reggie to use Jini ERI for remote communication.

Recall that, in addition to using different communication protocols, each
of the contributed service implementations can be run in one of three
modes:

  -- nonactivatable and nonpersistent (referred to as 'transient')
  -- nonactivatable and persistent    (referred to as 'nonactivatable')
  -- activatable and persistent       (referred to as 'activatable')

For each service implementation, a separate configuration file is provided 
for each of the modes just described, and for each of the possible protocols. 
Each such configuration file is classified by protocol via the particular 
sub-directory (under the service-specific parent) in which the file is 
located (jrmp, jeri, jsse); and they are further classified by mode, via 
the name of the file containing the configuration. For example, for Reggie, 
you should see the following directory structure and file names:

   <install-dir>
     |-- example   
         |-- reggie
             |-- jeri
             |   |-- config
             |   |   |
             |   |   |-- activatable-reggie.config
             |   |   |-- nonactivatable-reggie.config
             |   |   |-- transient-reggie.config
             |   |-- policy
             |   |   |-- reggie.policy
             |-- jrmp
             |   |-- config
             |   |   |-- activatable-reggie.config
             |   |   |-- nonactivatable-reggie.config
             |   |   |-- transient-reggie.config
             |   |-- policy
             |   |   |-- reggie.policy
             |-- jsse
                 |-- config
                 |   |-- activatable-reggie.config
                 |   |-- nonactivatable-reggie.config
                 |   |-- transient-reggie.config
                 |-- policy
                     |-- reggie.policy

Note that unlike the configuration files, the same policy file is used for
each mode; and thus the policy files are distinguished only by protocol, not 
by service mode.

Both the configuration files and the policy files are heavily documented.
You are encouraged to study each file to get a feel for how to configure
a service, the Phoenix daemon, or the Browser utility; and to see what sort
of permission grants are necessary to run the each such application with 
some semblance of security.

STARTING THE SERVICES --

 I. Introduction

    Although a number of the configuration files contain documentation 
    describing the particular command line that can be used to start the 
    associated service, there are scripts provided that allow you to avoid 
    having to type such a verbose command line. There are two scripts you 
    should be aware of:

    -- <install-dir>/example/scripts/urun                (if on unix)
    -- <drive>:\<install-dir>\example\scripts/wrun.bat   (if on windows)

    These scripts are intended to provide a single "entry point" to the 
    command lines one would typically use to start the services. To use 
    either of these scripts, one only has to supply a string that indicates 
    the desired protocol, mode, and service to run. For example, if you wish 
    to start a transient Outrigger that uses secure Jini ERI/jsse for remote 
    communication, then you would type one of the following (depending on 
    the OS):

    unix >> urun jsse-transient-outrigger
    win >>> wrun jsse-transient-outrigger

    (It is assumed you have changed the current working directory to 
    the directory <install-dir>/example/scripts if on unix, or to 
    <drive>:\<install-dir>\example\scripts, if on windows.)

    If you wish to run multiple services, each running in a shared VM, then 
    you would type something like,

    unix >> urun jeri-nonactivatable
    win >>> wrun jeri-nonactivatable

    which will start ALL the services, in nonactivatable mode, each using 
    Jini ERI for remote communication.

    For convenience, all of the services (and the Browser) are configured
    with the same set of lookup service group names, based on the protocol
    being used. For example, if the Browser, Reggie, and Outrigger are
    each started using Jini ERI, then the Browser is configured to 
    discover and query only those lookup services that are a member of
    either the group named "JERI_Group0", or the group named "JERI_Group1"
    (or both). Similarly, Outrigger is configured to discover and join
    only those groups. And finally, when Reggie is started, it will be
    configured to be member of those groups. In this way, the services
    will be able to find and join the appropriate lookup services, and
    the Browser will be able to display the desired information about
    the system.

   To change the groups associated with any of the entities started by these
   examples, do one of the following:

     1. change the entity's configuration file to specify the desired
        new group(s)
     2. use the administrative utility provided by the browser to change
        the group(s) of the desired entity

                             *** NOTE ***

    Unfortunately, because of limitations in the command language employed
    by the Win9x OS's, the bat file scripts that are discussed here will
    work only on versions of windows abover Win98 (for example, WinNT,
    Win2000, WinXP).

 II. The HTTP Server

    Remember that when running any of the services, you must start an HTTP 
    server. To do this, simply type,

    unix >> urun httpd
    win >>> wrun httpd

    With respect to the HTTP server, you do not have to worry about the 
    protocol or service mode. The same HTTP server can be used for any 
    transient, nonactivatable, or activatable service using jrmp, 
    Jini ERI, or secure Jini ERI/jsse.

 III. The Browser

    Although it is not necessary to use the Browser utility supplied in 
    the starter kit, it can be quite useful when doing development. As with
    the services, the Browser can be run to use JRMP, Jini ERI, or secure
    Jini ERI.  Although in general, with the appropriate configuration, 
    protocols can be mixed, for the purposes of these examples, it's best 
    to start out configuring the Browser to use the same protocol that the  
    services will use. For example, suppose you to start Reggie using JRMP.
    Then you would type the following:

    unix >> urun jrmp-browser
    win >>> wrun jrmp-browser

    If the service(s) the Browser will discover are running under Jini ERI,
    then type:

    unix >> urun jeri-browser
    win >>> wrun jeri-browser

    Finally, if the service(s) are running under secure Jini ERI, then type:

    unix >> urun jsse-browser
    win >>> wrun jsse-browser

 IV. Phoenix

    In order to start a service in activatable mode, Phoenix (rmid) must be
    running. Although in general, with the appropriate configuration, 
    protocols can be mixed, for the purposes of these examples, it's best 
    to configure Phoenix to use the same protocol that the activatable 
    service will use. For example, suppose you want to start an activatable
    Reggie using JRMP. Then you would type the following:

    unix >> urun httpd
    unix >> urun jrmp-phoenix
    unix >> urun jrmp-activatable-reggie

    win >>> wrun httpd
    win >>> wrun jrmp-phoenix
    win >>> wrun jrmp-activatable-reggie

    And to start multiple activatable services, each running in a shared VM,
    you would type something like the following:

    unix >> urun httpd
    unix >> urun jsse-phoenix
    unix >> urun jsse-activatable

    win >>> wrun httpd
    win >>> wrun jsse-phoenix
    win >>> wrun jsse-activatable

STOPPING A SERVICE OR DAEMON -

 I. Stopping The HTTP Server

    To stop the HTTP server, you can simply kill it by pressing ctr/c, 
    or you can shut it down gracefully by typing,

    unix >> urun httpd -stop
    win >>> wrun httpd -stop

 II. Stopping the Browser

    The Browser can be stopped through its Graphical User Interface (GUI). 
    To do this, click on the item in the task bar labelled, "File", and then
    click on the menu item labelled, "Exit". This is all you have to do
    to stop the Browser.

 III. Stopping Phoenix

    To stop the Phoenix daemon, type the same command you used to start 
    Phoenix, but with the additional argument, -stop. For example,

    unix >> urun jrmp-phoenix -stop
    win >>> wrun jrmp-phoenix -stop

 IV. Stopping The Services

   The best way to stop one of the contributed services when running 
   in any of the modes, under any of the protocols, is through the
   Browser's administrative GUI. To stop a service using the Browser,
   select the service you wish to stop by double-clicking on the service
   name (and folder icon) in the window labelled, "Matching Services".
   A new window should pop up labelled, "ServiceItem Editor". Click on
   the item in the task bar labelled, "Admin", and select the menu item
   labelled, "Destroy". Whe the dialog box labelled, "Query" appears,
   click on the choice button labelled, "Yes". The service will then
   gracefully destroy itself.

   The services can also be stopped from the command line. The mechanism
   used is dependent on the mode in which the service is run. Below,
   is a summary of how to stop the services from the command line.

   A. Stopping a Transient or Nonactivatable Service

    How you stop a service is dependent on the mode in which the service is
    running. If the mode of the service is either transient or nonactivatable,
    then press ctrl/c (this will work even when you've started multiple 
    services in the same VM). Also, remember that when running in 
    nonactivatable mode, a service persists its state. Killing the VM in 
    which such a service runs will leave that service's persistence directory
    (also referred to as its 'log' directory) in place. This fact may be
    important on future runs of the service.

   B. Stopping an Activatable Service

    To stop a service that is activatable, type the same command you used to 
    start the service, but with the additional argument, -stop. For example,

    unix >> urun jrmp-activatable-reggie -stop
    win >>> wrun jrmp-activatable-reggie -stop

   C. Stopping Multiple Activatable Services

    If you started multiple activatable services, each running in a shared VM,
    then to stop those services (to destroy the shared VM), you would type
    something like the following:

    unix >> urun jsse-activatable -stop
    win >>> wrun jsse-activatable -stop

   D. Notes 

    1. When using the Browser's GUI to administratively shutdown ("destroy")
       the services displayed by the Browser, the lookup service should always
       be destroyed last. This is because once the Browser loses its reference
       to the lookup service with which the other services were registered,
       it no longer displays the references to those other services. Thus,
       once the lookup service has been shutdown through the Browser, you
       will no longer be able to select the other services for shutdown.

    2. If an activatable service is gracefully shutdown using the Browser's
       administrative GUI, then that service's stored state (it's log file) is
       removed from persistent storage, and the service's processing is halted
       in the VM in which it was executing. But because the ServiceStarter
       framework registers the activatable versions of each service in a shared
       VM, the shared VM is not shutdown and the associated log file (used by
       the ServiceStarter framework) is not removed; even though the service
       is destroyed. In this case, after administratively shutting down the
       service(s), the shared VM should be destroyed as well by executing
       the appropriate script along with the '-stop' argument, as described
       above in B. and C.

    3. Unlike the nonactivatable case, when using urun or wrun.bat to stop
       Phoenix or any of the activatable services, the scripts will also
       remove the associated persistence directories in which the service
       (or Phoenix) stores its state.

    4. When running on windows, often times the persistence directory cannot
       be removed on the first try. When this occurs, you will see a message
       like the following,

        "The process cannot access the file because it is being used by
         another process."

       When this occurs, simply repeat the original stop command. Although you 
       will see a stack trace on the second try (because the service's VM has 
       already been destroyed), the persistence directories should be removed
       successfully.

CAVEATS -

Remember that the files described here are only examples. They should be
viewed as a starting point for learning how to use the latest release of 
the Starter Kit; the new protocols, the service modes, the new configuration
framework, policy files, etc. As such, you should not consider the files
described here as necessarily complete or "production ready".

Additionally, it is *** VERY IMPORTANT *** to note that the certificates 
(keystores and truststores) supplied with these examples were generated
using the 'keytool' provided in the JDK. Those certificates are self-signed, 
and should not be considered secure. They are provided for convenience,
and are intended to be tutorial in nature; to aid in learning about the
use of JSSE and SSL. For your production code, it is strongly recommended
that you obtain "real" certificates from a valid certificate authority.

ADDITIONAL NOTES -

You may notice that there is one mode/protocol combination that is not 
supported by this example set: starting a service in nonactivatable mode
using JRMP. An explanation as to why this is so may be helpful.

Although it is possible to run any of the services in nonactivatable mode 
using JRMP, it is not recommended; and thus, not supported. This is because
when a service has been configured in this way and is restarted, clients of 
the service that hold old proxies to the service that were created on a 
previous run will not be able to interact with the service through those old 
proxies; effectively making the restarted service useless to those clients.  
A proxy that was created on a previous run cannot be used to communicate with 
the restarted service because such a proxy is associated with an old object ID, 
produced when the service was previously exported; whereas the restarted 
service will be associated with a 'new', different object ID, produced when 
the service is re-exported during the restart. Note that this will be true 
even if the service is re-exported on the same port. 

The reason the restarted service cannot be re-exported with the object ID 
from its previous run is that when a service is configured to use JRMP,
the service is exported using a net.jini.jrmp.JrmpExporter, and such an 
exporter cannot be created with a pre-specified object ID. Thus, although 
the old object ID could be recovered from persisted state when the service 
is restarted, there is no way to re-export the service (under JRMP) with 
that old object ID. And so a new object ID is assigned to the service's 
inner proxy every time the service is restarted. To address this, one might 
argue that clients could always obtain a new service proxy (containing the 
new inner proxy with the new object ID) simply by re-querying the lookup 
service. But this only addresses 'primary' proxies to the service; it doesn't 
address 'secondary' proxies such as leases the service had issued to its 
clients on previous runs. Any such leases would no longer be valid, and so 
each client would need to re-register with the restarted service through 
the new primary proxy to obtain new leases. From the point of view of the 
client then, it would be as if the service was started anew.

Note that for nonactivatable, persistent services that are exported using 
Jini ERI, the above situation can be avoided. Jini ERI allows the service
to be configured to always be exported on the same port, with the same 
object ID (see the example configuration files for any of the services
being configured for nonactivatable mode using Jini ERI). Thus, any primary 
or secondary proxies a client holds that are from a prior run of the 
service, can still be used to communicate with the service when the 
service is restarted. 

Also note that the situation described above for nonactivatable, persistent
services exported under JRMP does not affect services that are registered with 
an activation system (that is, services that are 'activatable'); and this
holds for services exported under 'either' JRMP or Jini ERI. This is because 
the activation mechanism provided in Java Remote Method Invocation (Java RMI) 
provides for 'persistent references'; that is, remote references that remain 
valid after the service has crashed and been restarted. For more details, see
the "Note on RMI Activation and How it is Used in the Starter Kit" contained 
in the release notes (<jini-install-dir>/doc/release-notes/activation.html).

Finally, recall that a primary purpose for persisting state is so that the 
service can recover that state and pick up where it left off when restarted. 
For the reasons described above, when a service is configured to be persistent 
but nonactivatable, and is also configured to be exported using JRMP, that 
purpose cannot be achieved. Therefore, the use of such a configuration is 
strongly discouraged, and not directly supported in this example set. With 
this in mind, the following usage guidelines may be helpful when deciding 
how to configure a service with respect to mode, communication framework, 
and transport:

  o If state recovery is not important, then the service should be 
    configured for the transient mode using the communication framework 
    and transport of choice.
  o If state recovery is important, but JRMP is not necessary, then 
    the service should be configured for the mode of choice, but the 
    communication framework should be Jini ERI with the transport of
    choice.
  o If both state recovery and JRMP are necessary, then the service 
    should be configured to be activatable. That is, the only way to get 
    persistent, valid JRMP references is when the service is activatable.

