Changes between Initial Version and Version 1 of ValidationHook

Timestamp:

08/02/12 13:08:55 (12 years ago)

Author:

heikki

Comment:

--

ValidationHook

@@ +1 @@
+= Dependendy Injection =
+
+|| '''Date''' || 2012/08/03 ||
+|| '''Contact(s)''' || [http://wiki.osgeo.org/wiki/User:Heikki Heikki Doeleman] ||
+|| '''Last edited''' || ||
+|| '''Status''' || draft ||
+|| '''Assigned to release''' || 2.8.1 ||
+|| '''Resources''' || [http://www.agiv.be/gis/ AGIV] ||
+|| '''Code''' ||  ||
+|| '''Ticket''' || TBD ||
+
+== Overview ==
+
+Some users wish to add custom code to be invoked right after validation took place. A pluggable hook mechanism can provide for this while making it easy for them to keep their specific implementation code separate from the standard GeoNetwork code, thus easing future migration efforts for them. The pluggable validation hook mechanism is similar to the existing pluggable !StatusActions hook. No default implementation will be provided.
+
+=== Proposal Type ===
+ * '''Type''': !GeoNetwork
+ * '''App''': !GeoNetwork
+ * '''Module''': web
+
+=== Links ===
+ 
+ * '''Email discussions''':
+ * '''IRC discussions''':
+ 
+=== Voting History ===
+
+ * None as yet
+
+----
+
+== Motivations ==
+
+Pluggable 'hooks' are a mechanism that allows users to plug in their own, specific extensions to !GeoNetwork code, that will be executed at a specific point in the !GeoNetwork program flow, if any implementation is provided by the users. It makes it more easy for said users to extend !GeoNetwork without mixing up their own code with the !GeoNetwork code. This makes future migrations to new versions of !GeoNetwork easier. If users create an implementation that's deemed useful to the general audience, these might be made part of the !GeoNetwork code base, as ready-made, optional extensions.
+
+The existing !StatusActions hook is an example of such a pluggable hook in !GeoNetwork.
+
+== Proposal == 
+
+Currently, a standard post-validation is invoked from 2 places in !DataManager, 'saveValidationStatus' which saves a summary of the validation result to the database. This proposal would replace these calls with a call to a new method 'postValidation' which first does the same as does 'saveValidationStatus' now, and then invokes the pluggable Validation hook, if any is configured.
+
+It does this in a manner similar to the !StatusActions hook: a Factory class takes the class name of the hook implementation from config.xml. If none is configured, nothing happens and the program behaves exactly as without this proposal. If one is configured, reflection is used to instantiate the class, execute an 'init()' method, and execute an 'onValidate' method. 
+
+User-provided implementations of the Validation hook must conform to the contract of this interface:
+
+{{{
+public interface IValidationHook {
+
+    /**
+     * Invoked when validation has finished. The variable length Object arguments should accommodate any required
+     * input among different implementations.
+     *
+     * @param args zero or more implementation-dependent arguments
+     * @throws ValidationHookException hmm
+     */
+    public void onValidate(Object... args) throws ValidationHookException;
+
+    /**
+     * Initializes validation hook.
+     *
+     * @param context
+     * @param dbms
+     * @throws ValidationHookException
+     */
+    public void init(ServiceContext context, Dbms dbms) throws ValidationHookException;
+}
+}}}
+
+As you can see the 'onValidate' method can take any number of arguments, of any type, which should allow maximum flexibility for users' needs.
+
+
+For convenience, an abstract class implementing this interface's 'init()' method is provided in !GeoNetwork. This implementation just provides some of the usual suspects that are necessary to have at hand to do almost anything in !GeoNetwork, namely the !ServiceContext, !AccessManager, !DataManager, and Dbms. Note that user implementations of the Validation hook are not required to use this abstract base class if they have different needs; they can just implement the interface directly.
+
+The abstract base class is
+
+{{{
+public abstract class AbstractValidationHook implements IValidationHook {
+
+    private ServiceContext context;
+    private AccessManager am;
+    private DataManager dm;
+    private Dbms dbms;
+
+    /**
+     * Initializes the ValidationHook class with external info from GeoNetwork.
+     *
+     * @param context
+     * @param dbms
+     */
+    public void init(ServiceContext context, Dbms dbms) {
+        System.out.println("AbstractValidationHook init");
+        this.context = context;
+        this.dbms = dbms;
+
+        GeonetContext gc = (GeonetContext) context.getHandlerContext(Geonet.CONTEXT_NAME);
+        am = gc.getAccessManager();
+        dm = gc.getDataManager();
+    }
+
+}
+}}}
+
+
+=== Advantages: ===
+
+   * The pluggable Validation hook provides a non-intrusive extension point to !GeoNetwork where users may plug in their own implementation, should they want to.
+
+=== Use cases: ===
+
+   * At least 1 user wants to have this functionality so they can easily extend !GeoNetwork without mixing in their own code with !GeoNetwork's.
+
+=== Disadvantages: ===
+   * none
+
+
+=== Configuration ===
+
+In config.xml's appHandler element, a Validation hook implementation can be specified, as follows (example):
+
+{{{
+
+<appHandler class="org.fao.geonet.Geonetwork">
+   ...
+   <param name="validationHook" value="com.esri.geonetwork.extensions.MyValidationHook"/>
+   ...
+</appHandler>
+
+}}}
+
+
+=== Backwards Compatibility Issues ===
+
+None.
+
+== Risks ==
+
+ * none
+
+== Participants ==
+ * As above