org.metawidget.inspector.iface.Inspector Maven / Gradle / Ivy
// Metawidget
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
package org.metawidget.inspector.iface;
import org.metawidget.iface.Immutable;
/**
* Common interface implemented by all Inspectors. Inspectors decouple the process of generating
* inspection results out of back-end metadata.
*
* Inspectors must be immutable (or, at least, appear that way to clients. They can have caches or
* configuration settings internally, as long as they are threadsafe).
*
*
Note to Implementors
*
* This interface is designed to work for the majority of use cases, but not every
* use case. Inevitably there are tradeoffs. For example, the toInspect parameter is
* redundant for XML-based Inspectors (note, however, that the type parameter is
* not redundant for Object-based Inspectors).
*
* In particular, this interface does not pass an M metawidget or any other kind of
* 'helper context' as the other interfaces do. This is because Inspectors are meant to exist
* independent of any particular UI framework. Indeed, they can exist on back-end tiers where no UI
* framework is available at all. This seems to work for most use cases encountered so far.
* Theoretically, though, if you find yourself needing access to a context, consider:
*
* - passing it in a Thread local (
JspAnnotationInspector does this); or
* - passing an
Object[] containing the object to be inspected and the
* context to toInspect, and build something like CompositeInspector to
* strip that context back out before calling the regular Inspectors; or
* - use an
InspectionResultProcessor.
*
*
* @author Richard Kennard
*/
public interface Inspector
extends Immutable {
//
// Methods
//
/**
* Inspect the given Object according to the given path, and return the result as a String
* conforming to inspection-result-1.0.xsd.
*
* Note: the method returns a String, rather than a DOM, to support the use of hetergenous
* technologies between the Inspectors and the Metawidgets. For example, GwtMetawidget is
* written in JavaScript but its Inspectors are written in Java.
*
* @param toInspect
* runtime object to inspect. May be null
* @param type
* match type attribute in inspection-result.xml
* @param names
* match name attributes under type
* @return XML conforming to inspection-result-1.0.xsd
*/
String inspect( Object toInspect, String type, String... names );
}