-------------------------------------------------------------------------
                        APACHE INVOCATION README
-------------------------------------------------------------------------

Abstract:
---------

    Invocation is an abstraction of a generic invocation mechanism for
    Java based services. It is composed of two major parts: a set of Java
    classes (interfaces and exceptions) to be implemented by the service
    provider, and some native code dealing with the underlying operating
    system, accessing to the service thru JNI.

The Java portion of Invocation:
-------------------------------

    While the usual main(String args[]) method is well suited for generic
    applications, having only one entry point when developing networked
    services is not enough.

    In UNIX based operating systems, for example, a set of signals to be
    sent to running processes expands the invocation paradigm, so that,
    after the service process is usually started with a call to the
    main(int argc, char *argv[]) function, signal handling provides
    alternate ways to trigger events inside the process.

    For example, it usually happens that UNIX daemons upon reception of
    the HUP signal, the service is stopped, configuration is re-read
    from disk, and the service is started again with the new
    configurations, or, upon reception of a TERM signal, the service is
    stopped (freeing all resources allocated) and the process is
    terminated.

    The org.apache.invocation.InvocationAbstraction interface works in
    the same way. It defines three major entry points:

    - start(String args[])  is the parallel to the main(String args[])
                            method used by applications. Command line
                            parameters are passed to the instance and the
                            service is started.

    - restart()  this method is called when the service must be stopped,
                 configurations re-read from the disk, and the service
                 brought back on line with the new configuration. It's
                 behaviour is similar to the usual behaviour of the HUP
                 signal in unix daemons.

    - stop()  this method is called before the Java VM is terminated. The
              service should release all resources allocated during its
              execution, save temporary data, and be prepared to exit.
              It's behaviour is similar to the usual behaviour of the
              TERM signal in unix daemons.

    For more information on the behaviour of those methods and how they
    work, please consult the JavaDOC documentation included into the
    org.apache.invocation package.

The native portion of Invocation:
---------------------------------

    The native portion of Invocation is made of two major components:

    A system-independent library based on JNI handling the creation and
    destruction of the Java Virtual Machine and providing an easy way to
    access to the service start(String argv[]), restart() and stop()
    methods as described above.

    An Operating-System dependent set of sources dealing with calls from
    the underlying operating system:

    - in UNIX operating systems we listen for TERM and HUP sinals, and
      appropriate calls are made in the system-indipendant library to
      access to the appropriate Java method in the service. This will
      make the Java service behave like a standard UNIX daemon.

    - in Microsoft Windows operating systems we provide two different
      modes of operation: a GUI based one that will allow the user to
      access to the above-mentioned methods thru a standard tray-icon
      menu (there's no console allocated for the Java Process, which is
      for most of us Windows users a major pain). Another mode to operate
      under Windows is thru the Win32 Service API (WinNT and Win2K only)
      thru the standard Control-Panel Service tab.

Future Plans:
-------------

    Fix, debug and correct (that's the first major issue), and think
    about ports to different operating systems (MacOS/9, IBM...).

-------------------------------------------------------------------------
Copyright (c) 2000  The Apache Software Foundation.  All rights reserved.
$Revision$ $Date$
-------------------------------------------------------------------------