View Javadoc

1   /*
2    * $Id: Application.java,v 1.6 2004/09/20 16:40:43 pah Exp $
3    *
4    * Created on 14 October 2003 by Paul Harrison
5    * Copyright 2003 AstroGrid. All rights reserved.
6    *
7    * This software is published under the terms of the AstroGrid
8    * Software License version 1.2, a copy of which has been included
9    * with this distribution in the LICENSE.txt file.
10   */
11  
12  package org.astrogrid.applications;
13  
14  import org.astrogrid.applications.beans.v1.cea.castor.MessageType;
15  import org.astrogrid.applications.beans.v1.cea.castor.ResultListType;
16  import org.astrogrid.applications.beans.v1.parameters.ParameterValue;
17  import org.astrogrid.applications.description.ApplicationDescription;
18  import org.astrogrid.applications.description.ApplicationInterface;
19  import org.astrogrid.applications.description.exception.ParameterDescriptionNotFoundException;
20  import org.astrogrid.applications.description.exception.ParameterNotInInterfaceException;
21  import org.astrogrid.community.User;
22  
23  import java.util.Observer;
24  
25  
26  /***
27   A single execution of an application
28    <p />
29  This interface represents the application of a {@link org.astrogrid.workflow.beans.v1.Tool} to an {@link org.astrogrid.applications.description.ApplicationDescription} - 
30  and models a single application execution / invocation / call.
31  <p />
32  This is the core interface to be implemented by CEA provider back-ends.
33  The functionality splits into the following sections.
34  <h2>Static info</h2>
35  The {@link #getInputParameters()}, {@link #getID()}, {@link #getUser()}, {@link #getJobStepID()}, {@link #getApplicationDescription()}, {@link #getApplicationInterface()}
36   methods return information provided when the application was created. This data does not change though the life of the application.
37  
38  <h2>State Changers</h2>
39  {@link #execute()} starts the application running. (The application is initialized on creation of an instance of this class)<br>
40  {@link #attemptAbort()} will attempt to abort the application. Not all providers are expected to support this.
41  
42  <h2>Dynamic Info</h2>
43  {@link #getResult()} will access the results (so far computed) of the application execution.
44  {@link #getStatus()} will return the current current state of the application execution.
45  
46  <h2>Callback Interface</h2>
47  This interface follows the {@link java.util.Observable} pattern - interested parties can register as observers {@link #addObserver(Observer)} and then 
48  receive notifications when the execution state changes, messages are produced, or results ready.
49  
50  The {@link #createTemplateMessage()} shoud be overridden by implementors to return a custom <tt>MessageType</tt> object, with fields pre-populated. This is used by the system
51  as the basis for messages sent to the observers of the application.
52  
53  @author Paul Harrison
54  @author Noel Winstanley
55  @see org.astrogrid.applications.AbstractApplication
56  @see java.util.Observer
57  @see org.astrogrid.workflow.beans.v1.Tool
58  @see org.astrogrid.applications.beans.v1.cea.castor.MessageType
59  @see org.astrogrid.applications.beans.v1.parameters.ParameterValue
60  @see org.astrogrid.applications.beans.v1.cea.castor.ResultListType
61  @see org.astrogrid.applications.Status
62   */
63  public interface Application  {
64     /***
65      * Start the execution of an application.<p> 
66      * This is the main entry point for the application, and is expected to return quickly, with the application continuing execution in another thread if needed.
67      * @return true if the application has successfully been started executing.
68      * @throws CeaException
69      * @deprecated - use {@link #createExecutionTask} instead
70      */
71     boolean execute() throws CeaException;
72     
73     /*** return a runnable that will perform the execution of the application
74      * main new entry point for the application. expectred to return quickly, with main processing suspended within the runnable object.
75      * @return
76      */
77     Runnable createExecutionTask() throws CeaException;
78     
79    /*** @return results of the application execution- will be empty / semipopulated if the application has not yet completed. */
80     public ResultListType getResult();
81     /*** get the input parameters to this application execution 
82      * @return the inputs to this execution*/
83      public ParameterValue[] getInputParameters();
84  
85      /*** access the cea-id for this application. will be unique on this server, possibly worldwide 
86       * @return unique cea-id*/
87      public String getID();
88      /*** access the user this application is running for 
89       * @return the user*/
90     public User getUser() ;
91     /*** access the particular interface of the application description that this application conforms to
92      * @return an interface object belonging to {@link #getApplicationDescription()} */
93     public ApplicationInterface getApplicationInterface() ;
94     /*** @return the description of this application */
95     public ApplicationDescription getApplicationDescription() ;
96     /*** @return the user-assigned if for this application */
97     public String getJobStepID();
98     /*** @return the current status of the application 
99      * @see Status for the expected sequence of statuses.
100     * */
101    public Status getStatus();
102    /*** try to abort / cancel execution of the application 
103     * @return true if the attempt was successful*/
104    public boolean attemptAbort();
105    
106    /***
107     * Checks that all the parameters have been specified properly. 
108     * 
109     * It will throw exception at the first error.
110     * @throws ParameterNotInInterfaceException
111     * @throws MandatoryParameterNotPassedException
112     * @throws ParameterDescriptionNotFoundException
113     */
114    public boolean checkParameterValues() throws ParameterNotInInterfaceException,
115    MandatoryParameterNotPassedException, ParameterDescriptionNotFoundException;
116 
117    
118    /*** create  a template message, prepopulated as much as possible - this is used for reporting
119     * back to listeners on the application progress
120     * @return a pre-populated message object
121     */
122    public MessageType createTemplateMessage();
123    
124    /*** add an observer to this application.
125     * 
126     * <p />
127     * an application can have 0 or more observers. These will be notified when
128     * <ul>
129     * <li>The application changes state (i.e. the value of {@link getStatus()} changes
130     * <li> When an execution error occurs
131     * <li>Other application-defined things of interest happen - arbitrary messages
132     * @todo document types passed into observer.
133     * @param obs
134     */
135    public void addObserver(Observer obs);
136 }
137