Source code: com/eireneh/bible/control/Task.java
1
2 package com.eireneh.bible.control;
3
4 import org.w3c.dom.*;
5
6 import com.eireneh.bible.book.*;
7 import com.eireneh.bible.util.*;
8
9 /**
10 * Action allows us to have a neutral interface that performs some general
11 * function given a set of inputs.
12 *
13 * <p>On the design of an Action:<br />
14 * Actions should have I18N built into their names.<br />
15 * We can ignore configuration matters. There is already a UI independant
16 * way of asking about the configuration and changing it.</p>
17 *
18 * <p>Since they are used from the Web the actions ought to be integrated
19 * with the State object so that they can use a default Bible.</p>
20 *
21 * <table border='1' cellPadding='3' cellSpacing='0' width="100%">
22 * <tr><td bgColor='white'class='TableRowColor'><font size='-7'>
23 * Distribution Licence:<br />
24 * Project B is free software; you can redistribute it
25 * and/or modify it under the terms of the GNU General Public License,
26 * version 2 as published by the Free Software Foundation.<br />
27 * This program is distributed in the hope that it will be useful,
28 * but WITHOUT ANY WARRANTY; without even the implied warranty of
29 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
30 * General Public License for more details.<br />
31 * The License is available on the internet
32 * <a href='http://www.gnu.org/copyleft/gpl.html'>here</a>, by writing to
33 * <i>Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
34 * MA 02111-1307, USA</i>, Or locally at the Licence link below.<br />
35 * The copyright to this program is held by it's authors.
36 * </font></td></tr></table>
37 * @see <a href='http://www.eireneh.com/servlets/Web'>Project B Home</a>
38 * @see docs.Licence
39 * @author Joe Walker
40 * @version D0.I0.T0
41 */
42 public interface Task
43 {
44 /**
45 * Get the State object that we should use to get the current users
46 * optional settings.
47 * @return The current state object
48 */
49 public State getState();
50
51 /**
52 * Set the State object that we should use to get the current users
53 * optional settings.
54 * @param state The new state object
55 */
56 public void setState(State state);
57
58 /**
59 * Get the parameters we should use in any execute methods
60 * @return current parameters
61 */
62 public String[] getParams();
63
64 /**
65 * Set the parameters we should use in any execute methods.
66 * Calculation of the answer is not done here (hence no exception)
67 * it must be deferred until one of the execute methods is called.
68 * This enables us to create a list of primed Tasks quickly and only
69 * spend CPU on one when we know it is needed.
70 * @param params parameters
71 */
72 public void setParams(String[] params);
73
74 /**
75 * Perform the action, and return the results in a String. This
76 * method does not take any notice of the users max verses setting
77 * since it only returns a reference to the answer.
78 * @return The result of the action
79 */
80 public void calculate() throws TaskException;
81
82 /**
83 * Perform the action, and return the results in a String. This
84 * method does not take any notice of the users max verses setting
85 * since it only returns a reference to the answer.
86 * @return The result of the action
87 */
88 public String getResults();
89
90 /**
91 * Perform the action, and return the results in the given Node.
92 * This method onlye returns the first n verses of the full answer
93 * given by execute() (where n is defined by the current users
94 * settings).
95 * @param node an XML node into which to insert the results
96 * @exception TaskException If there is a problem creating the DOM
97 */
98 public void getResults(Node node) throws TaskException;
99
100 /**
101 * If we are using XML output it would be good to know if we have
102 * overflowed and so the nextTask() is of particular relevance
103 * @return true if we returned more verses than specified in the users
104 * settings
105 */
106 public boolean isTrimmed();
107
108 /**
109 * What do we recommend that the user does next?. It may well be that
110 * there is no obvious logical thing to do next - in which case we
111 * should return this, however is a view passage has resulted in a
112 * truncated view then the next query would be the remaining verses.
113 * @return The next thing to do
114 */
115 public Task nextTask();
116
117 /**
118 * How many parameters does this Action expect?
119 * @return The expected number of parameters
120 */
121 public int countParameters();
122 }