| % |
| % 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 |