You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by cw...@apache.org on 2013/01/02 20:12:11 UTC
svn commit: r1427917 [7/8] - in
/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook: ./ images/
images/ducc-overview/ images/job-manager/ part-admin/ part-admin/admin/
part-introduction/ part-user/ part-user/cli/ unused/
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_modify.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_modify.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_modify.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_modify.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,183 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <!-- ************************************ Service Modify ********************************** -->
+ <section id="ducc.cli.service.modify" xreflabel="ducc_services --modify">
+ <title>ducc_services --modify</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_modify.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis role="bold">modify</emphasis> function dynamically updates some of the
+ attributes of a registered service.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ See the <xref linkend="ducc.cli.service.overview" /> for general usage considerations for
+ <emphasis role="bold">ducc_services</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Service Modify Options::</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--modify [service id]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This identifies the service to modify. The <emphasis role="bold">service id</emphasis>
+ is either the numeric ID assigned by DUCC when the service is registered, or the
+ service endpoint string.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --modify 23 --instances 3
+ducc_services --modify UIMA-AS:Service23:tcp://bob.com:12345 \
+ --intances 2
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--instances [integer]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This updates the number of services instances that are started when the
+ service is started. Only the registration is updated. If the <emphasis>--activate</emphasis>
+ option is also specified, running instances are stopped or started as needed to
+ match the new number.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --modify 23 --intances 5
+ducc_services --modify UIMA-AS:Service23:tcp://bob.com:12345 \
+ --instances 3 --activate
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--activate [integer]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ When specified, the number of running service instances is increased or
+ decreased to match the newly specified number.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --modify 23 --intances 5
+ducc_services --modify UIMA-AS:Service23:tcp://bob.com:12345 \
+ --instances 3 --activate
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--autostart ["true" or "false"]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This changes the <emphasis>autostart</emphasis> property for the
+ registered services. When set to "true", the service is started automatically
+ when the DUCC system is started.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 \
+ --autostart false
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_modify.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_query.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_query.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_query.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_query.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <!-- ************************************ Service Query ********************************** -->
+ <section id="ducc.cli.service.query" xreflabel="ducc_services query">
+ <title>ducc_services --query</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_query.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis role="bold">query</emphasis> function returns details about all known services
+ of all types and classes, including the DUCC ids of the service instances (for submitted
+ and registered services), the DUCC ids of the jobs using each service, and a summary of
+ each service's queue and performance statistics, when available.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ See the <xref linkend="ducc.cli.service.overview" /> for general usage considerations for
+ <emphasis role="bold">ducc_services</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Service Query Options:</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--query [service id]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This indicates that a service is to be stopped. The <emphasis role="bold">service id</emphasis>
+ is either the numeric ID assigned by DUCC when the service is registered, or the
+ service endpoint string.
+ </para>
+
+ <para>
+ If no id is given, information about all services is returned.
+ </para>
+
+ <para>
+ Example: below is a query against a system with three services.
+ </para>
+ <para>
+ The service with endpoint <emphasis role="bold">UIMA-AS:FixedSleepAE_6:tcp://bluej291:61617</emphasis>
+ is a service submitted outside of DUCC so it is marked as <emphasis>Internal</emphasis> and has
+ no implementing processes tha are known to DUCC. It is used by job 0 and is active,
+ available, and being actively pinged. The ActiveMq queue statistics are shown.
+ </para>
+
+ <para>
+ The service with endpoint <emphasis role="bold">UIMA-AS:FixedSleepAE_5:tcp://bluej291:61617</emphasis>
+ is a registered service, whose registered numeric id is <emphasis role="bold">2</emphasis>. It is
+ registered for two instnaces and no autostart. Since it is not autostarted, it will be terminated
+ when it is no longer used. It will linger for 5 seconds after the last referencing job completes, in
+ case a subsequent job that uses it enters the system (not a realistic linger time!). It is
+ currently used (referenced) by DUCC jobs 1 and 5.
+ </para>
+
+ <para>
+ The service with
+ endpoint <emphasis role="bold">UIMA-AS:FixedSleepAE_1:tcp://bluej291:61617</emphasis>
+ is a submitted service. It was submitted twice, and so has two implementors,
+ DUCC service jobs 0 and 1. It is referenced by job 7. It will continue to run
+ until somebody cancels it, even if it is not used.
+ </para>
+
+ <para>
+ <screen>
+Service: UIMA-AS:FixedSleepAE_6:tcp://bluej291:61617
+ Service Class : Implicit
+ Implementors : (N/A)
+ References : 0
+ Dependencies : none
+ Service State : Available
+ Ping Active : true
+ Autostart : false
+ Manual Stop : false
+ Queue Statistics:
+ Consum Prod Qsize minNQ maxNQ expCnt inFlgt DQ NQ Disp
+ 78 240 170 2 36414 0 0 636 806 636
+
+Service: UIMA-AS:FixedSleepAE_5:tcp://bluej291:61617
+ Service Class : Registered as ID 2 instances[2] linger[5]
+ Implementors : 9 8
+ References : 1 5
+ Dependencies : none
+ Service State : Available
+ Ping Active : true
+ Autostart : false
+ Manual Stop : false
+ Queue Statistics:
+ Consum Prod Qsize minNQ maxNQ expCnt inFlgt DQ NQ Disp
+ 52 44 0 0 3 0 0 402 402 402
+
+Service: UIMA-AS:FixedSleepAE_1:tcp://bluej291:61617
+ Service Class : Submitted
+ Implementors : 1 0
+ References : 7
+ Dependencies : none
+ Service State : Available
+ Ping Active : true
+ Autostart : false
+ Manual Stop : false
+ Queue Statistics:
+ Consum Prod Qsize minNQ maxNQ expCnt inFlgt DQ NQ Disp
+ 52 0 0 1 1504371 0 0 35 35 35
+
+ </screen>
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_query.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_register.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_register.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_register.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_register.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,608 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <!-- ************************************ Service CLI ********************************** -->
+ <section id="ducc.cli.service..cli.register">
+ <title>ducc_service --register</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/services_register.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ This <emphasis>registers</emphasis> a service with the Service Manager. A registered
+ service is retained by DUCC until it is unregistered.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ See the <xref linkend="ducc.cli.service.overview" /> for general usage considerations for
+ <emphasis role="bold">ducc_services</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Service Register Options:</emphasis>
+
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--register [properties file] [override options]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The properties file is optional. It is a standard Java properties files containing
+ all the registration options for the service. The override options are then
+ applied to define the service (taking precedence). It is possible to register a service using just a
+ properties file, just override options, or both.
+
+ </para>
+ <para>
+ The properties in the properties file are identical to the command-line parameters, but with the
+ leading "--" removed. For example:
+ <screen>
+process_environment = DUCC_LD_LIBRARY_PATH=/my/own/lib.so
+description = Test Service 0
+process_jvm_args = -Xmx100M -DdefaultBrokerURL=tcp://bluej291:61617
+process_classpath = ../../lib/ducc-test.jar
+process_memory_size = 15
+working_directory = /home/bob/service-descriptors
+process_DD = Service_FixedSleep_0.xml
+process_deployments_max = 1
+scheduling_class = fixed
+ </screen>
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--debug</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Enable debugging messages. This is primarily for debugging DUCC itself.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--description [text]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The text is any string used to describe the job. It is displayed in the Web Server. Example:
+ <screen>--description "My totaly rad service"</screen>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--help</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Prints the usage text to the console.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--instances [number-of-instances]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This defines the default number of service instances to start. If not specified,
+ the default is 1. Example: <screen>--instances 12</screen>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--jvm [path-to-java]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ States the JVM to use. If not specified, the same JVM used by the Agents is used.
+ Example:<screen>--jvm /share/jdk1.6/bin/java</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--log_directory [path-to-log directory]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the path to the directory for the user logs. If not specified,
+ the default is the user's home directory. Example:<screen>--log_directory /home/bob</screen>.
+ Within this directory DUCC creates a subdirectory for each job, using the
+ numerical ID of the job. The format of the generated log file names is
+ descripbed in <xref linkend="ducc.user.logs" />.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_classpath [ClASSPATH]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the Java CLASSPATH to use in each Job Process (JP) and must be specified.
+ Example: <screen> --process_classpath a.jar:b.jar:more.jar</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_DD [DD descriptor]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies a UIMA Deployment Descriptor (DD) for the service.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_environment [environment]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies environment parameters for the Job Processes. If present, they are added
+ to the Job Process environment as the process is spawned. It must be a quoted,
+ blank-delimeted lsit of name-value pairs. For example:
+ <screen>"--process_environment TERM=xterm DISPLAY=:1.0"</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_failures_limit [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the maximum number of individual Job Process (JP) failures that are
+ to be tolerated before killing the job. The default is 15. If this limit is
+ exceeded over the lifetime of a job DUCC terminates the entire job.
+ <screen>"--process_failures_limit 23"</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_initialization_failures_cap [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the maximum number of independent Job Process initialization
+ failures (i.e. System.exit(), kill-15...) before the number of Job Processes is
+ capped at the number in state Running currently. The default is 99.
+ Example:<screen>--process_initialization_failures_cap 62</screen>
+ </para>
+ <para>
+ Note that the job is NOT killed if there are processes that have passed initialization and
+ are running. If this limit is reached, the only action is to not start new processes
+ for the job.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_jvm_args [list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies additinal arguments to be passed to the Job Process JVM.
+ Example:<screen>--process_jvm_args -Xmx400M -Xms100M</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_memory_size [size]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the maximum amount of RAM in GB to be allocated to each Job Process. This
+ value is used by the Resource Manager to allocate resources. if this amount is
+ exceeded by a Job Process the Agent terminates the process with a ShareSizeExceeded
+ message.
+ Example:<screen>--process_memory_size 33</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--scheduling_class [classname]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the name of the scheuling class the RM will use to determine
+ the resource allocation for each process. The names of the classes are installation
+ dependent.
+ Example:<screen>--schedling_class normal</screen>
+ <note>
+ <para>
+ Note that in general one should select a non-preemptable class such as <emphasis>
+ fixed></emphasis> or <emphasis>reserve</emphasis> for services. Otherwise DUCC
+ may grow or shrink the number of processes used by the service. It IS legal and supported to
+ use a <emphasis>fair-share</emphasis> class however.
+ </para>
+ </note>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--service_custom_classpath [CLASSPATH]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the classpath to be used when starting a CUSTOM ping thread. It is primarily intended
+ for non-UIMA-AS services but it may be implemented for UIMA-AS services as well if the default
+ DUCC ping function is not sufficient.
+ Example:<screen>--service_custom_classpath A.jar:B.Jar:C.Jar</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--service_custom_endpoint [CUSTOM:string]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This provides the name of the endpoint to used for non-UIMA-AS services. In the
+ current release of DUCC this type of service must be started independently of
+ DUCC but DUCC is able to monitor it
+ if <emphasis role="bold">--service_custom_ping</emphasis> is provided. The
+ endpoint must start with the characters "CUSTOM:" followed by any unique string
+ (with no embedded blanks) that DUCC can use to identify the service.
+ Example:<screen>--service_custom_endpoint CUSTOM:jrc.service.endpoint</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--service_custom_jvm_args [list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This supplies extra arguments to the JVM for the CUSTOM ping object.
+ Example:<screen>--service_custom_jvm_args -Xmx 400M -Xms100M</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--service_custom_ping [java class]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This supplies the java class name for a CUSTOM ping object. The class must
+ the interface <emphasis role="bold">org.apache.uima.ducc.IServiceMeta</emphasis> as
+ described in the API section. DUCC wraps the customer ping object in a
+ management object with a "main" and calls the implemented interfaces
+ periodically to insure the custom service is functioning, and to gather
+ performance statistics.
+ Example:<screen>--service_custom_ping bob.net.BobsCustomPing</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--service_dependency[list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies a comma-delimeted list of services the job processes are dependent upon.
+ Each endpoint must be of the form UIMA-AS:<emphasis>endpoint</emphasis>:<emphasis>broker_url</emphasis>
+ where <emphasis>endpoint</emphasis> is the UIMA-AS service endpoint and <emphasis>broker_url</emphasis>
+ is the ActiveMQ broker URL.
+ </para>
+ <para>
+ In the example are two dependencies, one with endpoint RandomSleepAE and broker tcp:bluej682:61616, and the other
+ with endpoint OtherEp and broker URL tcp:bluej123:123.
+ Example:<literallayout>
+--service_dependency UIMA-AS:RandomSleepAE:tcp:bluej682:61616, \
+ UIMA-AS:OtherEp:tcp:bluej123:123
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--service_linger [time in seconds]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the time, in seconds, that a service should be kept alive
+ after its last reference has exited, in anticipation of new work entering
+ the system and using it. This is only applicable to services that are
+ not automatically started at boot time.
+ Example:<screen>--service_linger 300</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--working_directory</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the working directory to be set by the Job Driver and Job Process processes. If not
+ specified, the current directory is used. Example:<screen>--working_directory /Users/challngr/projects/ducc/ducc_test/bin</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_register.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_start.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_start.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_start.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_start.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <!-- ************************************ Service Start ********************************** -->
+ <section id="ducc.cli.service.start" xreflabel="ducc_services start">
+ <title>ducc_services --start</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_start.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis role="bold">start</emphasis> function instructs DUCC to alllocate resources for a service
+ and to start it in those resources. The service remains running until explictly stopped. DUCC
+ will attempt to keep the service instances running if they should fail. The <emphasis role="bold">start</emphasis>
+ function is also used to increase the number of running service instances if desired.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usate:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ See the <xref linkend="ducc.cli.service.overview" /> for general usage considerations for
+ <emphasis role="bold">ducc_services</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Service Start Options:</emphasis>
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--start [service id]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This indicates that a service is to be started. The <emphasis role="bold">service id</emphasis>
+ is either the numeric ID assigned by DUCC when the service is registered, or the
+ service endpoing string.
+ </para>
+ <para>
+ Example:
+ <screen>
+ducc_services --start 23
+ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--instances [integer]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This is the number of instances to start. If omitted, the registered number of
+ instances is started. If the number is specified, the number is <emphasis>added</emphasis>
+ to the currently number of running instances. Thus if five instances are running and
+ <emphasis>ducc_services --start 33 --instances 5</emphasis> is issued, five more
+ service instances ar started for service 33 for a totoal of ten. The registry is
+ updated only if the <emphasis>--update</emphasis> option is also specified.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --start 23 --intances 5
+ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 \
+ --instances 3 --update
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--update</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ If specified, the registry is updated to the total number of started instances.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 \
+ --instances 3 --update
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_start.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_stop.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_stop.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_stop.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_stop.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <!-- ************************************ Service Stop ********************************** -->
+ <section id="ducc.cli.service.stop" xreflabel="ducc_services stop">
+ <title>ducc_services --stop</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_stop.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis role="bold">stop</emphasis> function instructs DUCC to stop some number of service
+ instances. If no specific number is specified, all instances are stopped. This is used only
+ for registered services. Use <xref linkend="ducc.cli.service_cancel"/> to stop submitted services.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ See the <xref linkend="ducc.cli.service.overview" /> for general usage considerations for
+ <emphasis role="bold">ducc_services</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Service Stop Options:</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--stop [service id]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This indicates that a service is to be stopped. The <emphasis role="bold">service id</emphasis>
+ is either the numeric ID assigned by DUCC when the service is registered, or the
+ service endpoint string.
+ </para>
+ <para>
+ Example:
+ <screen>
+ducc_services --stop 23
+ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--instances [integer]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This is the number of instances to stop. If omitted, all instances for the
+ service are stopped. If a number is specified, then only the specified number
+ of instances are stopped. Thus if ten instances are running and
+ <emphasis>ducc_services --stop 33 --instances 5</emphasis> is issued, five (randomly selected)
+ service instances ar stopped for service 33, leaving five running. The registry is
+ updated only if the <emphasis>--update</emphasis> option is specified. The registered
+ number of instances is never reduced to 0.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --stop 23 --intances 5
+ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 \
+ --instances 3 --update
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--update</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ If specified, the registry is updated to the total number of instances remaining, but
+ is never reduced below 1.
+ </para>
+ <para>
+ Example:
+ <literallayout>
+ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 \
+ --instances 3 --modify
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_stop.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_sub_can.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_sub_can.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_sub_can.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_sub_can.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <!-- ************************************ Service Start ********************************** -->
+ <section id="ducc.cli.service.subcan" xreflabel="ducc_services submit and cancel">
+ <title>ducc_services --submit and --cancel</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_sub_can.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ As a convenience, both <link linkend="ducc.cli.service_submit">ducc_service_submit</link>
+ and <link linkend="ducc.cli.service_cancel">ducc_service_cancel</link> can be invokded
+ from ducc_services. <emphasis role="bold">Ducc_services</emphasis> is just a thin
+ wrapper around those two commands.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ See the <xref linkend="ducc.cli.service.overview" /> for general usage considerations for
+ <emphasis role="bold">ducc_services</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Service Submit Options:</emphasis>
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--submit [parameters]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The parameters are the same parameters as for <link linkend="ducc.cli.service_submit">ducc_service_submit</link>.
+ </para>
+ <para>
+ Example:
+ <screen>
+ ducc_services --submit --specification 123.service
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--cancel [parameters]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The parameters are the same parameters as for <link linkend="ducc.cli.service_cancel">ducc_service_cancel</link>.
+ </para>
+ <para>
+ Example:
+ <screen>
+ducc_services --cancel --id 4
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_sub_can.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_unregister.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_unregister.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_unregister.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services_unregister.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,850 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <!-- ************************************ Service CLI ********************************** -->
+ <section id="ducc.cli.service.cli">
+ <title>ducc_services</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_api.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+
+ <para>
+ The <emphasis>ducc_services</emphasis> CLI is used to manage service registration. It
+ has a number of functions as listed below.
+ Additionally the <emphasis>ducc_services</emphasis> CLI wraps <emphasis>ducc_service_submit</emphasis>
+ and <emphasis>ducc_service_cancel</emphasis> for convenience.
+ </para>
+
+ <para>
+ The functions include:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term> <emphasis role="bold">Register</emphasis></term>
+ <listitem>
+ <para>
+ This <emphasis>registers</emphasis> a service with the Service Manager. A registered
+ service is retained by DUCC until it is unregistered.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Unregister</emphasis></term>
+ <listitem>
+ <para>
+ This <emphasis>unregisters</emphasis> a service with the Service Manager. When a service
+ is unregistered DUCC optionally stops the service instance, if any, and discards all knowledge of it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Start</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>start</emphasis> function instructs DUCC to alllocate resources for a service
+ and to start it in those resources. The service remains running until explictly stopped. DUCC
+ will attempt to keep the service instances running if they should fail. The <emphasis>start</emphasis>
+ function is also used to increase the number of running service instances if desired.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Stop</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>stop</emphasis> function stops some or all service instances.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Query</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>query</emphasis> function returns detailed information about all known services,
+ both registerd and otherwise.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Modify</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>modify</emphasis> function allows some aspectes of a registered service to be
+ updated without re-registereing the service. It optionally alters the running service
+ instances to conform with the updates.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Submit</emphasis></term>
+ <listitem>
+ <para>
+ Use the <emphasis role="bold">ducc_service_submit</emphasis> command to submit a
+ service. This is available only through the command-line wrapper.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Cancel</emphasis></term>
+ <listitem>
+ <para>
+ Use the <emphasis role="bold">ducc_service_cancel</emphasis> command to cancel a
+ submitted service. This is available only through the command-line wrapper.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Script wrapper</emphasis></term>
+ <listitem><emphasis>$DUCC_HOME</emphasis>/bin/ducc_services</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Executble Jar</emphasis></term>
+ <listitem>java -jar <emphasis>$DUCC_HOME</emphasis>/lib/ducc-services.jar</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Java main</emphasis></term>
+ <listitem>org.apache.uima.ducc.cli.DuccServiceApi</listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ The <emphasis role="bold">ducc_services</emphasis> CLI requires one of the verbs listed above
+ as the first argument. The subsequent arguments are determned by the verb.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Register Options:</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ The first parameter must be the keyword <emphasis role="bold">--register</emphasis>, optionally
+ followed by properties file containing a full or partial specification for the service. All
+ parameters may be overridden on the commandline as described below. The properties file contains
+ registration options as shown below and may be omitted if sufficient command-line overrides are
+ supplied.
+
+ The properties in the properties file are identical to the command-line parameters, but with the
+ leading "--" removed. For example:
+ <screen>
+process_environment = AE_INIT_TIME=50 LD_LIBRARY_PATH=/yet/a/nother/dumb/path
+description = Test Service 0
+process_jvm_args = -Xmx100M -DdefaultBrokerURL=tcp://bluej291:61617
+process_classpath = ../../lib/ducc-test.jar
+process_memory_size = 15
+working_directory = /home/bob/service-descriptors
+process_DD = Service_FixedSleep_0.xml
+process_deployments_max = 1
+scheduling_class = fixed
+ </screen>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ To register a service:
+ <screen>ducc_services --register [optional properties file] [list of override options]</screen>
+ where the options include:
+ </para>
+
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--debug</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ Enable debugging messages. This is primarily for debugging DUCC itself.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--description [text]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ The text is any string used to describe the job. It is displayed in the Web Server.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--help</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ Prints the usage text to the console.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--instances [number-of-instances]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This defines the default number of service instances to start.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--jvm [path-to-java]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ States the JVM to use. If not specified, the same JVM used by the Agents is used.
+ Example:<screen>/share/jdk1.6/bin/java</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+
+
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--log_directory [path-to-log directory]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the path to the directory for the user logs. If not specified,
+ the default is the user's home directory. Example:<screen>/home/bob</screen>.
+ Within this directory DUCC creates a subdirectory for each job, using the
+ numerical ID of the job.
+ </para>
+ <note>
+ Note that <emphasis>--log_directory</emphasis> specifies only the path to
+ a directory where logs are to be stored. In order to manage multiple processes
+ running in multiple machines DUCC, sub-directory and file names are generated
+ by DUCC and may not be directly specified.
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--process_classpath [ClASSPATH]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the Java CLASSPATH to use in each Job Process (JP) and must be specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--process_DD [DD descriptor]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies a UIMA Deployment Descriptor for the job processes for DD-style
+ jobs. This is mutually exclusive with <emphasis>--process_descriptor_AE,
+ --process_descriptor_CM, and --process_descriptor_CC.</emphasis> This descriptor
+ is a resource that is searched for in the CLASSPATH and data path as described
+ in the <emphasis><link linkend="ducc.cli.notes">notes</link></emphasis>. For
+ example:<screen>--process_DD /home/billy/resource/DD_foo.xml</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--process_environment [environment]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies environment parameters for the Job Processes. If present, they are added
+ to the Job Process environment as the process is spawned. It must be a quoted,
+ blank-delimeted lsit of name-value pairs. For example:
+ <screen>"--process_environment TERM=xterm DISPLAY=:1.0"</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--process_failures_limit [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the maximum number of individual Job Process (JP) failures that are
+ to be tolerated before killing the job. The default is 15. If this limit is
+ exceeded over the lifetime of a job DUCC terminates the entire job.
+ <screen>"--process_failures_limit 23"</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--process_initialization_failures_cap [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the maximum number of independent Job Process initialization
+ failures (i.e. System.exit(), kill-15...) before the number of Job Processes is
+ capped at the number in state Running currently. The default is 99.
+ Example:<screen>--process_initialization_failures_cap 62</screen>
+ </para>
+ <para>
+ Note that the job is NOT killed if there are processes that have passed initialization and
+ are running. If this limit is reached, the only action is to not start new processes
+ for the job.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--process_jvm_args [list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies additinal arguments to be passed to the Job Process JVM.
+ Example:<screen>--process_jvm_args -Xmx400M -Xms100M</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--process_memory_size [size]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the maximum amount of RAM in GB to be allocated to each Job Process. This
+ value is used by the Resource Manager to allocate resources. if this amount is
+ exceeded by a Job Process the Agent terminates the process with a ShareSizeExceeded
+ message.
+ Example:<screen>--process_memory_size 33</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--scheduling_class [classname]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the name of the scheuling class the RM will use to determine
+ the resource allocation for each process. The names of the classes are installation
+ dependent.
+ Example:<screen>--schedling_class normal</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--service_custom_classpath [CLASSPATH]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the classpath to be used when starting a CUSTOM ping thread. It is primarily intended
+ for non-UIMA-AS services but it may be implemented for UIMA-AS services as well if the default
+ DUCC ping function is not sufficient.
+ Example:<screen>--service_custom_classpath A.jar:B.Jar:C.Jar</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--service_custom_endpoint [CUSTOM:string]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This provides the name of the endpoint to used for non-UIMA-AS services. In the
+ current release of DUCC this type of service must be started independently of
+ DUCC but DUCC is able to monitor it
+ if <emphasis role="bold">--service_custom_ping</emphasis> is provided. The
+ endpoint must start with the characters "CUSTOM:" followed by any unique string
+ (with no embedded blanks) that DUCC can use to identify the service.
+ Example:<screen>--service_custom_endpoint CUSTOM:jrc.service.endpoint</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--service_custom_jvm_args [list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This supplies extra arguments to the JVM for the CUSTOM ping object.
+ Example:<screen>--service_custom_jvm_args -Xmx 400M -Xms100M</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--service_custom_ping [java class]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This supplies the java class name for a CUSTOM ping object. The class must
+ the interface <emphasis role="bold">org.apache.uima.ducc.IServiceMega</emphasis> as
+ described in the API section. DUCC wraps the customer ping object in a
+ management object with a "main" and calls the implemented interfaces
+ periodically to insure the custom service is functioning, and to gather
+ performance statistics.
+ Example:<screen>--service_custom_ping bob.net.BobsCustomPing</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--service_dependency[list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies a comma-delimeted list of services the job processes are dependent upon.
+ Each endpoint must be of the form UIMA-AS:<emphasis>endpoint</emphasis>:<emphasis>broker_url</emphasis>
+ where <emphasis>endpoint</emphasis> is the UIMA-AS service endpoint and <emphasis>broker_url</emphasis>
+ is the ActiveMQ broker URL.
+ </para>
+ <para>
+ In the example are two dependencies, one with endpoint RandomSleepAE and broker tcp:bluej682:61616, and the other
+ with endpoint OtherEp and broker URL tcp:bluej123:123.
+ Example:<screen>--service_dependency UIMA-AS:RandomSleepAE:tcp:bluej682:61616,UIMA-AS:OtherEp:tcp:bluej123:123</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--service_linger [time in seconds]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the time, in seconds, that a service should be kept alive
+ after its last reference has exited, in anticipation of new work entering
+ the system and using it. This is only applicable to services that are
+ not automatically started at boot time.
+ Example:<screen>--service_linger 300</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--working_directory</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ This specifies the working directory to be set by the Job Driver and Job Process processes. If not
+ specified, the current directory is used. Example:<screen>--working_directory /Users/challngr/projects/ducc/ducc_test/bin</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+
+ <para>
+ <emphasis>Unregister Options:</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ The first parameter must be the keyword <emphasis role="bold">--unregister</emphasis> followed
+ by the numeric id or the enddoint string of the service to be canceled.
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <para>
+ To unregister a service
+ <screen>ducc_services --unregister [numeric service id]</screen>
+ or
+ <screen>ducc_services --unregister [service endpoint]</screen>
+ </para>
+
+ <para>
+ For example:
+ <screen>ducc_services --unregister 22</screen>
+ <screen>ducc_services --unregister UIMA-AS:AGoodEndpoint:tcp://bob.com:12345</screen>
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Start Options:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ The first parameter to <emphasis role="bold">ducc_services </emphasis> must be the
+ keyword <emphasis role="bold">--start</emphasis>, followed immediately by the service
+ id and optionally followed by parameters to indiciate the number of instances to start
+ and whether to update the registry with the new number of instnaces.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ To start a service:
+ <screen>
+ducc_services --start [numeric id] [options]
+ducc_services --start [service endpoint string] [options]
+ </screen>
+ where the options include:
+ </para>
+
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--instances [integer]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ This is the number of instances to start. If omitted, the registered number of
+ instances is started. If the number is specified, the number is <emphasis>added</emphasis>
+ to the currently number of running instances. Thus if five instances are running and
+ <emphasis>ducc_services --start 33 --instances 5</emphasis> is issued, five more
+ service instances ar started for service 33 for a totoal of ten. The registry is
+ updated only if the <emphasis>--modify</emphasis> option is also specified.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--modify</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ If specified, the registry is updated to the total number of started instances.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+
+ <para>
+ <emphasis>Stop Options:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ The first parameter to <emphasis role="bold">ducc_services </emphasis> must be the
+ keyword <emphasis role="bold">--stop</emphasis>, followed immediately by the service
+ id and optionally followed by parameters to indiciate the number of instances to stop
+ and whether to update the registry with the new number of instnaces.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ To start a service:
+ <screen>
+ducc_services --stop [numeric id] [options]
+ducc_services --stop [service endpoint string] [options]
+ </screen>
+ where the options include:
+ </para>
+
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--instances [integer]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ This is the number of instances to stop. If omitted, all currently running
+ instances are stopped. If the number is specified, only the number of instances specified
+ are stopped. Thus if ten instances are running and
+ <emphasis>ducc_services --stop 33 --instances 5</emphasis> is issued, five
+ (arbitrarily chosen) service instances ar stopped for service 33 leaving 5 active
+ . The registry is updated only if the <emphasis>--modify</emphasis> option is
+ also specified.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--modify</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ If specified, the registry is updated to the total number of instances still
+ running after the stop is issued.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+
+ <para>
+ <emphasis>Modify Options:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <para>
+ The first parameter to <emphasis role="bold">ducc_services </emphasis> must be the
+ keyword <emphasis role="bold">--modify</emphasis>, followed immediately by the service
+ id and optionally followed by parameters to indiciate the number of instances to stop
+ and whether to update the registry with the new number of instnaces.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ To start a service:
+ <screen>
+ducc_services --stop [numeric id] [options]
+ducc_services --stop [service endpoint string] [options]
+ </screen>
+ where the options include:
+ </para>
+
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--instances [integer]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ This is the number of instances to stop. If omitted, all currently running
+ instances are stopped. If the number is specified, only the number of instances specified
+ are stopped. Thus if ten instances are running and
+ <emphasis>ducc_services --stop 33 --instances 5</emphasis> is issued, five
+ (arbitrarily chosen) service instances ar stopped for service 33 leaving 5 active
+ . The registry is updated only if the <emphasis>--modify</emphasis> option is
+ also specified.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <emphasis role="bold">--modify</emphasis>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ If specified, the registry is updated to the total number of instances still
+ running after the stop is issued.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+
+ </section>
+