uima-ducc-duccdocs/src/site/tex/duccbook/part2/ducc-api.tex

% 
% 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.
% 
\section{Overview Of The DUCC API}

   The DUCC API provides a simple programmatic (Java) interface to DUCC for submission and
   cancellation of work.  (Note that the DUCC CLI is implemented using the API and provides a
   model for how to use the API.)

   All the API objects are instantiated using the same arguments as the CLI.  The API
   provides three variants for supplying arguments:
   \begin{enumerate}
     \item An array of Java Strings, for example {\tt DuccJobSubmit(String[] args)}.
     \item A list of Java Strings,   for example {\tt DuccJobSubmit(List<String> args)}.
     \item A Java Properties object, for example {\tt DuccJobSubmit(Properties args)}.
   \end{enumerate}

   After instantiation of an API object, the {\tt boolean execute()} method is called.  This
   method transmits the arguments to DUCC.  If DUCC receives and accepts the args, the method
   returns ``true'', otherwise it returns ``false.  Methods are provided to retrieve relevant
   information when the {\tt execute()} returns such as IDs, messages, etc.

   In the case of jobs and managed reservations, if the specification requested debug,
   console attachment, or ``wait for completion'', the API provides methods to block
   waiting for completion.

   In the case of jobs and managed reservations, a callback object may also be passed to
   the constructor.  The callback object provides a means to direct messages to the
   API user.  If the callback is not provided, messages are written to standard output.

   The API is thread-safe, so developers may manage multiple, simultaneous requests to
   DUCC.

   Below is the ``main()'' method of DuccJobSubmit, demonstrating the use of the API:
\begin{verbatim}   
       public static void main(String[] args) {
        try {
            DuccJobSubmit ds = new DuccJobSubmit(args, null);
            boolean rc = ds.execute();
            // If the return is 'true' then as best the API can tell, the submit worked
            if ( rc ) {                
                System.out.println("Job " + ds.getDuccId() + " submitted");
                int exit_code = ds.getReturnCode();       // after waiting if requested
                System.exit(exit_code);
            } else {
                System.out.println("Could not submit job");
                System.exit(1);
            }
        }
        catch(Exception e) {
            System.out.println("Cannot initialize: " + e);
            System.exit(1);
        }
    }
\end{verbatim}

\section{Compiling and Running With the DUCC API}

   A single DUCC jar file is required for both compilation and execution of the DUCC API,
   {\tt uima-ducc-cli.jar}.  This jar is found in \duccruntime/lib.

\section{Java API}
\ifpdf
   The DUCC API is documented via Javadoc in \ducchome/webserver/root/doc/apidocs/index.html.
\else
   See the \href{api/index.html}{JavaDoc} for the DUCC Public API.
\fi