All Inspectors must implement the Inspector interface. This is a simple interface that defines only one method:

String inspect( Object toInspect, String type, String... names );

Each Inspector must look to the type parameter and the names array. These form a path into the domain object model. For example the type may be com.myapp.Person and the names may be address and street. This would form a path into the domain model of com.myapp.Person/address/street (i.e. return information on the street property within the address property of the Person type).

Depending on the type of inspector, it may use the given toInspect to access the runtime object for the given type. For example:

metawidget.setToInspect( myPerson );	// Will be passed to Inspector

Or it may ignore the toInspect and look up information for the given type from an XML file or a database schema. This allows Metawidget to inspect types that have no corresponding Java object. For example:

metawidget.setToInspect( null );	// No setToInspect
metawidget.setPath( "Login Form" );

This could be combined with, say, an XmlInspector and a metawidget-metadata.xml:

<entity type="Login Form">
	<property name="username"/>
	<property name="password"/>
</entity>

This approach also allows Metawidget to inspect abstract classes:

metawidget.setToInspect( null );	// No setToInspect
metawidget.setPath( MyAbstractClass.class.getName() );

	Note
	In general, a non-null setToInspect is preferrable, as many binding and validation technologies (e.g. see the section called “Property Binding”) will be expecting a concrete object.

Unless explicitly specified, each Metawidget will instantiate a default Inspector. Typically this will be a CompositeInspector composed of a PropertyTypeInspector and a MetawidgetAnnotationInspector.

This default behaviour can be overridden either in code:

metawidget.setInspector( new MyInspector() );

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<inspector>
		<myInspector xmlns="java:com.myapp"/>
	</inspector>
</swingMetawidget>

This allows easy plugging in of alternate inspectors. Note that overriding the default means the default is no longer instantiated. In the example above, this would mean MyInspector is used but the default Inspectors are not. This is usually not what you want, because MyInspector will be focused on a particular type of back-end metadata and will want to leave other metadata to other inspectors.

To achieve this, use CompositeInspector.

CompositeInspector composes the results of several Inspectors into one and returns a single, combined inspection result. As shown in Figure 2.2 CompositeInspector works by calling each Inspector in turn, combining the inspection result as it goes.

Figure 2.2. CompositeInspector composes multiple inspectors into one

All Inspectors are required to be immutable (see Section 2.2.5, “Immutability”). Therefore, although CompositeInspector maintains a list of Inspectors this must not be changeable. To enforce this, the list is set at instantation time using CompositeInspectorConfig. This can either be set in code:

metawidget.setInspector( new CompositeInspector( new CompositeInspectorConfig()
	.setInspectors(
		new PropertyTypeInspector(),
		new MetawidgetAnnotationInspector(),
		new MyInspector()
	)));

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
<inspector>
	<compositeInspector xmlns="java:org.metawidget.inspector.composite" config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"/>
				<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation" />
				<myInspector xmlns="java:com.myapp"/>
			</array>
		</inspectors>
	</compositeInspector>
</inspector>
</swingMetawidget>

All Metawidgets have default Inspectors. Overriding the default means the default is no longer instantiated. Usually this is not what you want, so you should consider instantiating the default along with your new Inspector (i.e. use CompositeInspector). You can see the default by looking in the Metawidget JAR for the file metawidget-xxx-default.xml (where xxx is your target platform, such as swing or struts).

For reference, the defaults are:

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

new metawidget.inspector.PropertyTypeInspector()

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
				<facesAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
				<jspAnnotationInspector />				
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
				<springAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector>
					<propertyStyle>
						<javaBeanPropertyStyle>
							<excludeBaseType>
								<pattern>^(java|javax|org\.apache\.struts)\..*$</pattern>
							</excludeBaseType>
						</javaBeanPropertyStyle>
					</propertyStyle>
				</propertyTypeInspector>				
				<metawidgetAnnotationInspector />
				<strutsAnnotationInspector />
				<commonsValidatorInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
			</array>
		</inspectors>
	</compositeInspector>

All Inspectors are required to be immutable. This means you only need a single instance of an Inspector for your entire application. If you are using metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”) then ConfigReader takes care of this for you, but if you are instantiating Inspectors in Java code you should reuse instances.

Note that immutable only means Inspectors cannot be changed once instantiated - it does not mean they cannot be configured. Many Inspectors have corresponding xxxConfig classes that allow them to be configured prior to instantation in a type-safe way. For example, a JpaInspector can be configured in code:

metawidget.setInspector( new JpaInspector( new JpaInspectorConfig().setHideIds( false )));

Or in metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<jpaInspector xmlns="java:org.metawidget.inspector.jpa" config="JpaInspectorConfig">
	<hideIds>
		<boolean>false</boolean>
	</hideIds>
</jpaInspector>

The inspection-result XML format is the 'glue' that holds everything together: the Metawidgets request it, the Inspectors provide it, and the WidgetBuilders base their choice of widgets on it.

It is a very simple format. As an example:

<inspection-result xmlns="http://metawidget.org/inspection-result" version="1.0">
	<entity type="com.myapp.Person">
		<property name="name" required="true"/>
		<property name="age" minimum-value="0"/>
	</entity>
</inspection-result>

Only a handful of XML attributes are mandatory (see inspection-result-1.0.xsd). Most, such as required and minimum-value, are provided at the discretion of the Inspector and recognised at the discretion of the WidgetBuilders, WidgetProcessors and Layouts. This loose coupling allows Inspectors to evolve independently for new types of metadata, WidgetBuilders to evolve independently with new types of widgets, and so on.

For JavaScript-based Metawidgets, inspection results are returned as JSON Schema:

{
	properties: {
		name: {
			required: true
		},
		age: {
			minimum-value: 0
		}
	}
}

Metawidget inspects a wide variety of back-end architectures. If your chosen back-end architecture is not supported 'out of the box', you may need to implement your own Inspector.

All Inspectors must implement the org.metawidget.inspector.Inspector interface:

public interface Inspector {
	String inspect( Object toInspect, String type, String... names );
}

The interface has only one method: inspect. Its parameters are:

The returned String must be an XML document conforming to inspection-result-1.0.xsd. To assist development, deploy your Inspector within ValidatingCompositeInspector to automatically validate the returned DOM during testing.

A number of convenience base classes are provided for different inspectors:

When implementing your own Inspector, try to avoid technology-specific XML attribute names. For example, FacesAnnotationInspector has an annotation @UiFacesNumberConverter. This annotation certainly has a technology-specific part to it, as it names a JSF Converter that only applies in JSF environments, so it is reasonable to name that XML attribute faces-converter-class. However, it also describes other parts of the property, such as the maximum number of integer digits. Such parts are not JSF-specific (i.e. we can source the same property from Hibernate Validator's @Digits annotation), so are better named 'neutrally' (i.e. maximum-integer-digits).

Like InspectionResultProcessors, WidgetBuilders, WidgetProcessors and Layouts, Inspectors are required to be immutable. However they will occasionally need to store some internal state, such as which PropertyStyle to use. This can be achieved in two ways: