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

String processInspectionResult( String inspectionResult, M metawidget, Object toInspect,
                                String type, String... names );

Where M is a Metawidget type (such as SwingMetawidget or UIMetawidget).

The InspectionResultProcessor must returned the processed inspection result as XML conforming to inspection-result-1.0.xsd. The parent Metwidget then passes this to the next InspectionResultProcessor in the list as shown in Figure 2.3.

Figure 2.3. Typical InspectionResultProcessor list

In most cases the InspectionResultProcessor will modify the given inspectionResult and return a new String. This will then be passed down the list. Alternatively, the InspectionResultProcessor can return null to cancel inspection result processing entirely. No further InspectionResultProcessors or WidgetBuilders will be called, as shown in Figure 2.4.

Figure 2.4. An InspectionResultProcessor can abort the inspection result processing

Unless explicitly specified, each Metawidget will instantiate a default InspectionResultProcessor. Typically this will be a ComesAfterInspectionResultProcessor, which sorts business properties and actions according to their comes-after attribute.

This default behaviour can be overridden either in code:

metawidget.addInspectionResultProcessor( new MyInspectionResultProcessor() );

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

<swingMetawidget xmlns="java:org.metawidget.swing">
	<inspectionResultProcessors>
		<array>
			<myInspectionResultProcessor xmlns="java:com.myapp"/>
		</array>
	</inspectionResultProcessors>
</swingMetawidget>

This allows easy plugging in of alternate InspectionResultProcessors.

Most Metawidgets have default InspectionResultProcessors. Overriding the default means the default is no longer instantiated. This may not be what you want, so you may want to instantiate the default along with your new InspectionResultProcessor. 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:

<array>
	<comesAfterInspectionResultProcessor />
</array>

new metawidget.angular.inspectionresultprocessor.AngularInspectionResultProcessor(...)

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<facesInspectionResultProcessor />
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<jspInspectionResultProcessor />
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<comesAfterInspectionResultProcessor />
</array>

All InspectionResultProcessors are required to be immutable. This means you only need a single instance of an InspectionResultProcessor for your entire application. If you are using metawidget.xml then ConfigReader takes care of this for you, but if you are instantiating InspectionResultProcessors in Java code you should reuse instances.

Here is an example of a custom InspectionResultProcessor that chooses, and sorts, domain object properties based on a JComponent client property. It extends the code from the tutorial (see Section 1.1, “Part 1 (Java version) - The First Metawidget Application”).

package com.myapp;
			
import static org.metawidget.inspector.InspectionResultConstants.*;

import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.inspectionresultprocessor.iface.*;
import org.metawidget.util.*;
import org.w3c.dom.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.addInspectionResultProcessor( new IncludingInspectionResultProcessor() );
		metawidget.putClientProperty( "include", new String[]{ "retired", "age" } );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
	
	static class IncludingInspectionResultProcessor
		implements InspectionResultProcessor<SwingMetawidget> {
		
		public String processInspectionResult( String inspectionResult, SwingMetawidget metawidget,
		                                       Object toInspect, String type, String... names ) {
		
			String[] includes = (String[]) metawidget.getClientProperty( "include" );
			Document document = XmlUtils.documentFromString( inspectionResult );
			Element entity = (Element) document.getDocumentElement().getFirstChild();			
			int propertiesToCleanup = entity.getChildNodes().getLength();

			// Pull out the names in order

			for( String include : includes ) {
			
				Element property = XmlUtils.getChildWithAttributeValue( entity, NAME, include );

				if ( property == null )
					continue;

				entity.appendChild( property );
				propertiesToCleanup--;
			}

			// Remove the rest

			for( int loop = 0; loop < propertiesToCleanup; loop++ ) {
				entity.removeChild( entity.getFirstChild() );
			}

			return XmlUtils.documentToString( document, false );
		}
	}
}

	Note
	We don't necessarily recommend this approach, as it requires hard-coding business property names into your UI screens and won't refactor well. See Chapter 9, How To's for other approaches.

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