cvs commit: jakarta-tomcat-4.0/invocation README

[pi...@locus.apache.org]

pier        00/09/21 16:22:23

  Added:       invocation README
  Log:
  Let's describe what this Invocation stuff is.
  
  Revision  Changes    Path
  1.1                  jakarta-tomcat-4.0/invocation/README
  
  Index: README
  ===================================================================
  
  -------------------------------------------------------------------------
                          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 invoke the process.
  
      For example, it usually happens that UNIX daemons upon reception of
      the HUP signal, the service is stopper, configuration are re-read
      from disk, and the service is started againg 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-indipendant 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 dependant 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, wich 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: 1.1 $
  - $Date: 2000/09/21 23:22:22 $
  -------------------------------------------------------------------------