Author: challngr
Date: Fri Jun 5 21:00:50 2015
New Revision: 1683869
URL: http://svn.apache.org/r1683869
Log:
UIMA-4109 Updates for 2.0.0.
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex
URL:
http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex?rev=1683869&r1=1683868&r2=1683869&view=diff
==============================================================================
---
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex
(original)
+++
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex
Fri Jun 5 21:00:50 2015
@@ -58,15 +58,20 @@
\item Run service pingers and respond to the pinger API as needed.
\end{itemize}
- DUCC provides a ``fast-fail'' for work which references services.
Incoming work which
- references a service is canceled by the system under the following
conditions:
+ When work enters the system with a declared dependency on a service,
one of the following
+ actions is tken:
\begin{itemize}
- \item The service is not registered.
- \item The service cannot be started.
- \item The service is started, but the service pinger determines the
service is not
- viable.
+ \item If the service is not registered, the work request is
automatically canceled.
+ \item If the service is not running, the Service Manager attempts to
start it; the job
+ remains queued until the service is started and its pinger reports
good health.
+ \item If the service exists but cannot be started, the work remains
queued and error
+ status is shown in the web server. Once the service is working
again the
+ work is allowed to proceed.
+ \item If the service processes are running but the pinger reports
failure contacting the service,
+ the work remains queued with error status shown in the
webserver. Once the service
+ pinger indicates the service is functional again the work is
allowed to proceed.
\end{itemize}
-
+
\section{Service Types.}
\label{sec:services.types}
DUCC supports two types of services: UIMA-AS and CUSTOM:
@@ -77,7 +82,7 @@
for UIMA-AS services. It is legal to define a custom pinger for a
UIMA-AS service.
\item[CUSTOM] This is any arbitrary service. Developers must
provide a custom pinger
- and declare it in the service registration.
+ and declare the pinger in the service registration.
\end{description}
DUCC also supports services that are not managed by DUCC. These are
known as {\em ping-only}
@@ -85,6 +90,25 @@
support a pinger. Ping-only services must be defined as custom
services; there is no
default pinger provided for ping-only services.
+ \section{Service Instance IDs}
+ \label{sec:service.service.ids}
+ DUCC 2.0.0 introduces support for constant service instance IDs. As a
service is being
+ started, the SM assigns monotonically increasing IDs to each service
instance, starting
+ with ID 0, up the the maximum number of instances started.
+
+ If an instance exits unexpectedly, the SM respawns it (unless a failure
threshold has been
+ exceeded). The new instance is assigned the same instance ID as the
instance it replaces.
+ This insures that, for example, instance ``three'' is always started as
instance ``three'',
+ maintained constant over failures and SM restarts.
+
+ The instance ID is communicated to the process through the environment
with the key
+ {\tt DUCC\_SERVICE\_INSTANCE}. This key may also be used in service
registrations if it
+ is desired to pass the instance ID via parameters of some sort. For
example:
+\begin{verbatim}
+ service_jvm_args -DSERVICE_ID=${DUCC_SERVICE_INSTANCE}
+ process_executable_args -i ${DUCC_SERVICE_INSTANCE}
+\end{verbatim}
+
\section{Service References and Endpoints}
\label{sec:service.endpoints}
Services are identified by an entity called a {\em service endpoint}.
Jobs and other
@@ -160,7 +184,9 @@
established to keep the service alive for a while, in anticipation
that it will be needed
again soon. When the keep-alive timer expires, and there are no
more dependent jobs or
services, the reference-started service is automatically stopped to
free up its resources
- for other work.
+ for other work. The time the service is allowed to remain alive is
known as its
+ {\em linger} time and can be controlled with the {\em
service\_linger} keyword in the
+ service registration.
\item[Manually started services] A service may be started via the CLI
if it is not
already running and in the absence of references by other work. A
service which is
@@ -334,7 +360,7 @@
The following registration options are used for declaring and
configuring pingers. Any of these
may be dynamically modified with the service CLI's {\em$--$modify}
option. Dynamically changing
- these causes the current pinger to be terminated and restarted with the
configuration. See
+ these causes the current pinger to be terminated and restarted with the
new configuration. See
\hyperref[sec:cli.ducc-services]{ducc\_services} for details of the
options:
\begin{itemize}
\item service\_ping\_arguments
@@ -414,7 +440,7 @@ public class CustomPing
This section provides the information needed to use the pinger API and
build a
custom pinger.
- \paragraph{1. Establish a compiation CLASSPATH} One DUCC jar is required
in the CLASSPATH to build your pinger:
+ \paragraph{1. Establish a compilation CLASSPATH} One DUCC jar is
required in the CLASSPATH to build your pinger:
\begin{verbatim}
DUCC_HOME/lib/uima-ducc-cli.jar
\end{verbatim}
@@ -425,7 +451,8 @@ public class CustomPing
\begin{verbatim}
service_ping_dolog = true
\end{verbatim}
- This will log any output from {\tt System.out.println()} to your home
directory in
+ This will log any output from {\tt System.out.println()} to the
declared log directory
+ for the service. If not specified in the reqistration, this directory
is:
\begin{verbatim}
$HOME/ducc/logs/<serviceid>/services
\end{verbatim}
