1 /*
2 * $HeadURL: $
3 * $Date: $
4 * $Revision: $
5 * $Author: $
6 *
7 * Copyright (c) 2006 MindTree Consulting Ltd.
8 *
9 * This file is part of Insight.
10 *
11 * Insight is free software: you can redistribute it and/or modify it under the
12 * terms of the GNU General Public License as published by the Free Software
13 * Foundation, either version 3 of the License, or (at your option) any later
14 * version.
15 *
16 * Insight is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
19 * Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License along with
22 * Insight. If not, see <http://www.gnu.org/licenses/>.
23 */
24 package com.mindtree.techworks.insight.reporting.jobs;
25
26 import java.io.Serializable;
27 import java.util.Map;
28
29 import com.mindtree.techworks.insight.reporting.jobs.message.JobMessage;
30
31 /**
32 * A <code>Job</code> is an action that is invoked by a <code>Verifier</code>
33 * when it meets its criteria. A <code>Job</code> is called when the Insight
34 * action the <code>Verifier</code> is monitoring meets the criterions set in
35 * the <code>Verifier</code>.
36 * <p>
37 * Jobs may be executed in <i>Synchronous (Blocking)</i> or <i>Asynchronous
38 * (Non-Blocking)</i> mode depending on the implementation of the
39 * <code>Job</code>. Hence, in particular cases where the <code>Job</code>
40 * is invoked even before the entire Insight Action (like Filtering) is
41 * completed, may block the original action for executing the <code>Job</code>.
42 * When Insight is running in the interactive GUI mode, this might not only
43 * block the user requested action, but also freeze up the UI. In such
44 * scenarios, the <code>Verifier</code> might start the job execution in its
45 * own <code>Thread</code>.
46 * </p>
47 * <p>
48 * A <code>Job</code> may support any number of <code>JobMessage</code>s,
49 * which can be checked by calling the <code>#getSupportedMessageTypes()</code>
50 * or the <code>#isMessageTypeSupported(String)</code> methods. All
51 * <code>Job</code>s must support atleast the <code>DefaultJobMessage</code>
52 * type.
53 * </p>
54 * <p>
55 * If the <code>#execute(JobMessage)</code> method is called with an
56 * unsupported message type, the method would then throw an
57 * <code>UnsupportedMessageTypeException</code>. Any exception conditions
58 * during the execution of the <code>Job</code> would cause a
59 * <code>JobExecutionException</code> to be thrown.
60 * </p>
61 * <p>
62 * All <code>Job</code>s are uniquely identified by the fully qualified class
63 * name of the implementing class and should be returned in the
64 * <code>#getUID()</code> method.
65 * </p>
66 * <p>
67 * A <code>Job</code> may be serialized (possibly as part of a
68 * <code>Verifier</code>) for later reincarnation and execution. The format
69 * for the serialized <code>Job</code> is mentioned in the documentation of
70 * {@link com.mindtree.techworks.insight.reporting.jobs.JobPersistanceHandler JobPersistanceHandler}.
71 * <code>JobPersistanceHandler</code> also handles the serialization and
72 * deserialization of the <code>Jobs</code>. It gets the fields to be
73 * serialized for the <code>Job</code> from the
74 * <code>#getSerializableFields()</code> methods and it deserializes the
75 * fields on the <code>Job</code> by calling the
76 * <code>#setDeserializedField(String, String)</code>. All <code>Job</code>s
77 * must provide a no-arguments public constructor for them to be deserialized.
78 * </p>
79 *
80 * @see com.mindtree.techworks.insight.reporting.jobs.message.JobMessage
81 * @see com.mindtree.techworks.insight.reporting.verifiers.Verifier
82 * @see com.mindtree.techworks.insight.reporting.jobs.JobPersistanceHandler
83 *
84 * @author <a href="mailto:bindul_bhowmik@mindtree.com">Bindul Bhowmik</a>
85 * @version $Revision: 27 $ $Date: 2007-12-16 04:58:03 -0700 (Sun, 16 Dec 2007) $
86 * @since Insight 1.5
87 */
88 public interface Job extends Serializable {
89
90 // -------------------------------------------------------------------------
91 // Public Methods
92 // -------------------------------------------------------------------------
93
94 /**
95 * Returns the array of all different message types supported by the
96 * <code>Job</code>. The values returned would be the same as returned by
97 * the <code>getJobMessageType()</code> methods of each of the
98 * <code>JobMessage</code> types supported by the <code>Job</code>.
99 * <p>
100 * All <code>Job</code>s are required to support atleast the
101 * <code>DefaultJobMessage</code>.
102 *
103 * @see JobMessage#getJobMessageType()
104 * @return An array of the types of the <code>JobMessage</code>s supported.
105 */
106 public String[] getSupportedMessageTypes ();
107
108 /**
109 * Checks if the particular <code>JobMessage</code>, as identified by the
110 * message type, is supported by the <code>Job</code>. The value of the
111 * parameter should be the same as that returned by
112 * <code>JobMessage#getJobMessageType()</code>.
113 *
114 * @see JobMessage#getJobMessageType()
115 * @param messageType
116 * The message type to check.
117 * @return <code>true</code> if the message type is supported or
118 * <code>false</code>
119 *
120 */
121 public boolean isMessageTypeSupported (String messageType);
122
123 /**
124 * Executes the job with the data supplied in the <code>JobMessage</code>
125 * passed to the method. The action performed on calling the method depends
126 * on the implementation of the <code>Job</code>.
127 * <p>
128 * Jobs may be executed asynchronously, or synchronously depending on the
129 * implementation of the <code>Job</code>. The method contract for a
130 * <code>Job</code> does not specify that. However, <code>Verifiers</code>
131 * calling the <code>#executeJob(JobMessage)</code> method while the
132 * action they are monitoring need to aware that <i>blocking</i> jobs may
133 * hold up (or fail) the action they are monitoring. In such scenarios, the
134 * <code>Verifier</code> may as an additional performance feature despatch
135 * all calls on the <code>Job</code>s in a seperate asynchronous
136 * <code>Thread</code>.
137 * </p>
138 *
139 * @param jobMessage
140 * The message used for executing the <code>Job</code>.
141 * @throws UnsupportedMessageTypeException
142 * If the <code>JobMessage</code> passed in is not supported
143 * by the <code>Job</code>.
144 * @throws JobExecutionException
145 * If there is problem executing the <code>Job</code>.
146 */
147 public void execute (JobMessage jobMessage)
148 throws UnsupportedMessageTypeException, JobExecutionException;
149
150 /**
151 * Returns the 'display name' of the <code>Job</code> to be displayed to the
152 * user.
153 *
154 * @return The display name of the job.
155 */
156 public String getDisplayName ();
157
158 /**
159 * Returns the unique identifier for this <code>Job</code> - the fully
160 * qualified name of the class implementing the interface.
161 *
162 * @return The unique identifier of the Job.
163 */
164 public String getUID();
165
166 /**
167 * A <code>Map</code> of all fields that might be necessary for
168 * serializing the <code>Job</code>. This data will later used for
169 * recreating a <code>Job</code> instance from the serialized data.
170 * <p>
171 * Unlike <code>Verifiers</code> the data passed in the map may not be
172 * <code>array</code>s or <code>Collection</code>s.
173 * </p>
174 *
175 * @see JobPersistanceHandler
176 * @return A map containing all fields that need to be persisted in the
177 * <code>Job</code>.
178 */
179 public Map getSerializableFields ();
180
181 /**
182 * Sets the deserialized field in the <code>Job</code>. This method would
183 * be called during the deserialization of a <code>Job</code> from the
184 * store.
185 *
186 * @see JobPersistanceHandler
187 * @param fieldName The name of the field being deserialized.
188 * @param fieldValue The value of the field being deserialized.
189 */
190 public void setDeserializedField (String fieldName, String fieldValue);
191 }