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.verifiers;
25
26 import java.io.Serializable;
27
28 import com.mindtree.techworks.insight.filter.criteria.FilterCriteria;
29 import com.mindtree.techworks.insight.model.LogEventModel;
30 import com.mindtree.techworks.insight.reporting.jobs.Job;
31 import com.mindtree.techworks.insight.spi.LogEvent;
32
33 /**
34 * A '<code>Verifier</code>' as the name suggests is used to evaluate criterias
35 * on the filtered (or unfiltered) log event model.
36 * <p>
37 * Verifiers are usually configured with certain criterias and observe the
38 * execution of an (usually refining) action on the current log event model. For
39 * example, we can configure a verifier to monitor a filter action on the log
40 * event model and can trigger when the criteria configured in the verifier is
41 * met and can execute an action.
42 * <br/>
43 * Verfiers can be both quantitative (for example, can count the number of
44 * matches) and qualitative (for example, can analyze the occurances against
45 * time, or can observe the transition between namespaces).
46 * </p>
47 * <p>
48 * On meeting its criteria a Verifier usually executes an action or in Insight a
49 * {@link com.mindtree.techworks.insight.reporting.jobs.Job Job}. A <code>Job</code>
50 * performs a specific action, usually to report the action to the user (like by
51 * sending an email or showing a pop-up).
52 * <br/>
53 * A <code>Job</code> will usually be sent a <code>JobMessage</code> which will
54 * contain the information to be acted upon. There can be multiple types of
55 * messages. For more information, see
56 * {@link com.mindtree.techworks.insight.reporting.jobs.message.JobMessage JobMessage}.
57 * </p>
58 * <p>
59 * The <code>Verifier</code> framework is not aware of any actions being
60 * executed in Insight, and also of actions it is observing. For an action
61 * to be <i>verifiable</i> it needs to be aware of the Verifier framework, and
62 * should provide means to <i>register</i> Verifier(s) and also call them
63 * appropriately.
64 * </p>
65 * <p>
66 * An abstract implementation of the <code>Verifier</code> interface is provided
67 * as <code>AbstractVerifier</code>, which takes care of a number of tasks
68 * that need to be performed by a Verifier.
69 * <br/>
70 * Anyone developing a new <code>Verifier</code> should keep in mind that the
71 * {@link #verify(LogEvent, FilterCriteria, boolean) verify} method is called
72 * in the same thread that executes the action which the <code>Verifier</code>
73 * is observing. Hence, any performance bottlenecks in the code inside this
74 * method will effect the entire action desired by the action.
75 * </p>
76 * <p>
77 * A <code>Verifier</code> can be identified by the fully qualified class name
78 * of the class implementing the <code>Verifier</code>. The verifier also needs
79 * to return a display name for the <code>Verifier</code>. This would be used
80 * for easy identification of the <code>Verifier</code> by the user.
81 * </p>
82 * <p>
83 * A <code>Verifier</code> can be serialized and stored for future invocation.
84 * A factory mechanism is provided to deserialize a <code>Verifier</code>. For
85 * a format of the serialized <code>Verifier</code> see
86 * {@link com.mindtree.techworks.insight.reporting.verifiers.VerifierDeserializer VerifierDeserializer}.
87 * Every <code>Verifier</code> must provide a default constructor implementation.
88 * </p>
89 *
90 * @see com.mindtree.techworks.insight.reporting.verifiers.AbstractVerifier
91 * @see com.mindtree.techworks.insight.reporting.jobs.Job
92 * @see com.mindtree.techworks.insight.reporting.jobs.message.JobMessage
93 * @see com.mindtree.techworks.insight.reporting.verifiers.VerifierDeserializerImpl
94 *
95 * @author <a href="mailto:bindul_bhowmik@mindtree.com">Bindul Bhowmik</a>
96 * @version $Revision: 27 $ $Date: 2007-12-16 04:58:03 -0700 (Sun, 16 Dec 2007) $
97 * @since Insight 1.5
98 */
99 public interface Verifier extends Serializable {
100
101 // -------------------------------------------------------------------------
102 // Public methods
103 // -------------------------------------------------------------------------
104
105 /**
106 * Notifies the verifier that an action has started on the current log
107 * event model.
108 *
109 * @param logEventModel The log event model on which the action is being
110 * executed.
111 */
112 public void notifyStartAction (LogEventModel logEventModel);
113
114 /**
115 * Verifies and registers an action being executed on the log event model.
116 * This is the callback method that the class executing an action (eg.
117 * filter) on the log event method should call for every log event it
118 * processes.
119 * <p>
120 * At present only the filter action is supposed to be able to support
121 * <code>Verifier</code>s. Should other actions (say, search) also be
122 * modified to support <code>Verifier</code>s, the codebase should be
123 * refactored to create a super-type (RefinementCriteria?) of
124 * <code>FilterCriteria</code> and the criteria for the other action
125 * (in our example <code>SearchCriteria</code>) and the signature of this
126 * method should be changed to take the new Type as a parameter, and all
127 * implementations adjusted accordingly.
128 * </p>
129 *
130 * @param logEvent The event which was acted upon.
131 * @param filterCriteria The criteria which was executed on the event.
132 * @param success If the event meets the criteria or not.
133 */
134 public void verify (LogEvent logEvent, FilterCriteria filterCriteria,
135 boolean success);
136
137 /**
138 * Notifies the verifier that the action has ended on the current log
139 * event model.
140 * <p>
141 * For accumulator kind of verifiers, this will be the trigger to call the
142 * <code>Job</code>(s).
143 * </p>
144 *
145 * @param logEventModel The log event model on which the action is being
146 * executed.
147 */
148 public void notifyEndAction (LogEventModel logEventModel);
149
150 /**
151 * Registers a <code>Job</code> to be called on meeting the criteria
152 * specified in this <code>Verifier</code>.
153 *
154 * @param job The <code>Job</code> to be called on trigger.
155 */
156 public void registerJob (Job job);
157
158 /**
159 * Returns the string format of the <code>Verifier</code> for persistance,
160 * possibly in the preference mechanism of the application. The format in
161 * which the serialized format is returned is described in the documentation
162 * for <code>VerifierDeserializer</code>.
163 *
164 * @see VerifierDeserializer
165 *
166 * @return The <code>String</code> form of the <code>Verifier</code>.
167 */
168 public String serialize();
169
170 /**
171 * This method returns the deserializer to be used for serializing the
172 * <code>Verifier</code>. A <code>Verifier</code> may use the default
173 * implementation of <code>VerifierDeserializer</code> provided:
174 * <code>VerifierDeserializerImpl</code>, or provide their own deserializer.
175 *
176 * @return The <code>VerifierDeserializer</code> to be used for the Verifier.
177 */
178 public VerifierDeserializer getDeserializer();
179
180 /**
181 * Returns the unique identifier for this <code>Verifier</code> - the fully
182 * qualified name of the class implementing the interface.
183 *
184 * @return The unique identifier of the Verifier.
185 */
186 public String getUID();
187
188 /**
189 * Returns the display name of the verifier to be displayed in the UI of the
190 * application to the user.
191 *
192 * @return The display name of the <code>Verifier</code>.
193 */
194 public String getDisplayName();
195 }