View Javadoc

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  /**
27   * Implementations of this class would deserialize a serialized
28   * <code>Verifier</code>.
29   * <p>
30   * While using a <code>Verifier</code>, Insight would call the 
31   * {@link com.mindtree.techworks.insight.reporting.verifiers.Verifier#getDeserializer() #getDeserializer}
32   * method to get the instance of the <code>VerifierDeserializer</code> to use
33   * for (re)creating the <code>Verifier</code> instance.
34   * </p>
35   * <p>
36   * The Insight distribution provides a default implementation for the the 
37   * Interface as <code>VerifierDeserializerImpl</code>. To use the services of
38   * the default implementation, <code>Verifiers</code> need to implement the 
39   * <code>DefaultImplDeserializable</code> interface. The default implementation 
40   * uses this interface to populate the values of the fields in the 
41   * <code>Verifier</code>. Such <code>Verifiers</code> need to return an instance
42   * of the <code>VerifierDeserializerImpl</code> when the 
43   * <code>#getDeserializer()</code> is called on them. They also need to be 
44   * serialized in the exact format specified below, or deserialization might 
45   * fail.
46   * </p>
47   * <h3>Serialized Verifier</h3>
48   * <p>
49   * The suggested format to serialize a <code>Verifier</code> is as below:
50   * <pre>
51   * 	&lt;verifier&gt;
52   * 		&lt;!-- The class that implements the Verifier interface --&gt;
53   * 		&lt;class&gt;the.implementing.class.of.the.verifier&lt;/class&gt;
54   * 		&lt;!-- The display name of the verifier --&gt;
55   * 		&lt;name&gt;Verifier Display Name&lt;/name&gt;
56   * 		&lt;fields&gt;
57   * 			&lt;field&gt;
58   * 				&lt;name&gt;nonArrayField&lt;/name&gt;
59   * 				&lt;isArray&gt;false&lt;/isArray&gt;
60   * 				&lt;value&gt;Some Value&lt;/value&gt;
61   * 			&lt;/field&gt;
62   * 			&lt;field&gt;
63   * 				&lt;name&gt;arrayField&lt;/name&gt;
64   * 				&lt;isArray&gt;true&lt;/isArray&gt;
65   * 				&lt;value&gt;Some Value&lt;/value&gt;
66   * 				&lt;value&gt;Some Other Value&lt;/value&gt;
67   * 			&lt;/field&gt;
68   * 		&lt;/fields&gt;
69   * 		&lt;jobs&gt;
70   * 			&lt;job&gt;
71   * 				&lt;!-- A serialized job used by the Verifier (including the
72   * 						'job' tag above). For more details on the format here
73   * 						refer to the documentation of Jobs. --&gt;
74   * 			&lt;/job&gt;
75   * 		&lt;/jobs&gt;
76   * 	&lt;/verifier&gt;
77   * </pre>
78   * 
79   * If the <code>Verifier</code> provides its own Serializer and 
80   * <code>VerifierDeserializer</code>, then it need not follow the format 
81   * mentioned here except for the following tags:
82   * <ol>
83   * 	<li>The outer &lt;verifier/&gt; tag.</li>
84   * 	<li>The first level &lt;class/&gt; tag, required to get the 
85   * 		<code>Verifier</code> class and get its 
86   * 		<code>VerifierDeserializer</code>.</li>
87   * </ol>
88   * </p>
89   * 
90   * @see com.mindtree.techworks.insight.reporting.verifiers.VerifierDeserializerImpl
91   * @see com.mindtree.techworks.insight.reporting.verifiers.DefaultImplDeserializable
92   * @see com.mindtree.techworks.insight.reporting.verifiers.Verifier
93   * 
94   * @author <a href="mailto:bindul_bhowmik@mindtree.com">Bindul Bhowmik</a>
95   * @version $Revision: 27 $ $Date: 2007-12-16 04:58:03 -0700 (Sun, 16 Dec 2007) $
96   * @since Insight 1.5
97   */
98  public interface VerifierDeserializer {
99  	
100 	/**
101 	 * Deserializes a serialized Verifier. The specific format of the serialized
102 	 * <code>Verifier</code> or the way to deserialize a particular
103 	 * <code>Verifier</code> would depend on the implementation of the
104 	 * Verifier and its (de)serializer.
105 	 * 
106 	 * @param serializedVerifier
107 	 *            The serialized format of the <code>Verifier</code>.
108 	 * @return On successful deserialization, the <code>Verifier</code>
109 	 *         instance.
110 	 * @throws VerifierInitializationException
111 	 *             If the <code>Verifier</code> cannot be deserialized.
112 	 */
113 	public Verifier deserializeVerifier (String serializedVerifier)
114 			throws VerifierInitializationException;
115 
116 }