Metawidget User Guide and Reference Documentation

Metawidget is an object/user interface mapping tool (OIM), so first we need an object to map from - the O in OIM. Create a class in your project called Person with the following code:

package com.myapp;

public class Person {
	public String name; 
	public int age;
	public boolean retired;
}

This tutorial uses public member variables for brevity. The recommended design is to use JavaBean property getter and setter methods. Metawidget supports both approaches.

Next we need a User Interface framework - the I in OIM. Create a class in your project called Main with the following code:

package com.myapp;

import javax.swing.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		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 );
	}
}

	Note
	Many IDEs include visual UI builders for dragging and dropping widgets. Metawidget integrates with these tools and Metawidget widgets can be dragged and dropped like any other. As we shall see, however, Metawidget widgets automatically fill themselves with child widgets at runtime, saving significant development time.

If you're using an IDE, such as NetBeans, your project should look something like pictured in Figure 1.1.

Figure 1.1. Metawidget tutorial in NetBeans IDE

Run the code. You should see the screen in Figure 1.2.

Figure 1.2. SwingMetawidget rendering of Person class

The SwingMetawidget has automatically populated itself with child widgets at runtime. It has chosen JSpinner, JTextField and JCheckBox widgets based on the types of the properties of the Person class. This is the First Goal Of Metawidget:

	First Goal Of Metawidget
	Metawidget creates UI widgets by inspecting existing back-end architectures

By default, SwingMetawidget has laid out the JComponents using java.awt.GridBagLayout. Try resizing the window, and the JComponents will resize with it. If you've ever tried using java.awt.GridBagLayout yourself, either through code or a visual UI builder, you'll know how fiddly it can be. Having Metawidget do it for you is a real time-saver.

Clearly this is not a complete UI. There are no Save or Cancel buttons, for example, and the JComponents appear uncomfortably tight to the left, top and right edges of the JFrame. This is explained by the Second Goal Of Metawidget:

	Second Goal Of Metawidget
	Metawidget does not try to 'own' the entire UI - it focusses on creating native sub-widgets for slotting into existing UIs

You slot Metawidget alongside your standard UI components, often combining several Metawidgets on the same screen. We'll see how this works later.

Currently the name, age and retired fields are arranged alphabetically in the UI - their order does not match the way they are defined in the Person class. This is because field ordering information is not retained within Java class files (as per the Java Language Specification).

To correct this, Metawidget needs to gather additional information. There are several ways to do this (ie. you don't have to use annotations), but the simplest for now is to use the built-in Metawidget annotation @UiComesAfter.

	Note
	The following code uses annotations, so you'll need Java SE 5 or higher. Metawidget itself can run on J2SE 1.4, but you'll need to gather the ordering information from a different source (see Section 1.1.10, “Inspecting Different Sources”)

Annotate the Person class as shown below (lines to add are highlighted):

package com.myapp;

import org.metawidget.inspector.annotation.*;

public class Person {
	public String name;
	
	@UiComesAfter( "name" ) 
	public int age;
	
	@UiComesAfter( "age" )
	public boolean retired;
}

Such annotations can (and should) be applied to getter methods, but for brevity here they are applied directly to the member variable.

Run the code again. This time the fields appear in the correct order:

Figure 1.3. Fields in correct order

Introducing new annotations to improve the UI is not really in the spirit of the First Goal Of Metawidget. We'd much rather improve it by gathering information from existing sources. To demonstrate how Metawidget can adapt to different sources of metadata, add the following lines to Person (lines to add are highlighted):

package com.myapp;

import org.metawidget.inspector.annotation.*;

public class Person {
	public String name;
	
	@UiComesAfter( "name" )
	public int age;
	
	@UiComesAfter( "age" )
	public boolean retired;

	@UiComesAfter( "retired" )
	public Gender gender;

	public enum Gender { Male, Female }
}

Run the code again:

Figure 1.4. New Gender field, but missing a component

Metawidget finds the new gender property, and renders a JLabel for it on the left, but doesn't know what JComponent to put on the right. This is because, by default, Metawidget does not inspect Java 5 language features such as enums and generics.

To recognise the enum, Metawidget needs to use a different Inspector. Metawidget comes with multiple Inspectors, each targeting different sources of information. Change the Main class to use a Java5Inspector (lines to add are highlighted):

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.java5.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setInspector( new Java5Inspector() );
		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 );
	}
}

Run the code again. It does not yield the correct result - the gender enum appears correctly as a JComboBox but all the other fields have disappeared! What happened?

Figure 1.5. Correct Gender field, but missing other fields

Metawidget Inspectors are very targeted in what they inspect. Java5Inspector looks for Java 5 language features - such as enums - but it does not look for anything else - such as JavaBean properties. Before we explicitly specified a Java5Inspector, Metawidget had been implictly using two Inspectors for us, called PropertyTypeInspector and MetawidgetAnnotationInspector.

What we need is to combine the results of PropertyTypeInspector, MetawidgetAnnotationInspector and Java5Inspector before returning them to SwingMetawidget. We do this using CompositeInspector:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.java5.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector(),
			new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		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 );
	}
}

Run the code again. This time both the original fields and the new gender JComboBox appear:

Figure 1.6. Using multiple inspectors

This idea of combining multiple Inspectors to inspect different characteristics of your existing architecture is very powerful. Metawidget comes with many pre-written Inspectors for many different architectures - from JPA and Hibernate Validator annotations, to struts-config.xml configuration files, to Groovy and Scala properties - Metawidget will gather and combine UI information from wherever it can find it.

There are several ways to control the layout of the components. To demonstrate, Try adding the following fields to the Person class:

package com.myapp;

import org.metawidget.inspector.annotation.*;

public class Person {
	public String name;
	
	@UiComesAfter( "name" )
	public int age;
	
	@UiComesAfter( "age" )
	public boolean retired;
	
	@UiComesAfter( "retired" )
	public Gender gender;
	
	public enum Gender { Male, Female }

	@UiComesAfter( "gender" )
	@UiLarge
	public String notes;

	@UiComesAfter( "notes" )
	@UiSection( "Work" )
	public String employer;

	@UiComesAfter( "employer" )
	public String department;
}

This code produces the screen in Figure 1.7. Annotations have been used to define section headings and 'large' fields (ie. a JTextArea).

Figure 1.7. Additional fields and a section heading

	Note
	For a list of all the annotations MetawidgetAnnotationInspector recognises, see Section 4.2.6, “MetawidgetAnnotationInspector”.

By default, SwingMetawidget lays out JComponents using org.metawidget.swing.layout.GridBagLayout. You can configure this layout, or swap it for a different layout, using SwingMetawidget.setMetawidgetLayout. Modify the code to use a GridBagLayout with 2 columns.

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.java5.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.swing.*;
import org.metawidget.swing.layout.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector(),
			new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		SeparatorLayoutDecoratorConfig layoutConfig = new SeparatorLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new SeparatorLayoutDecorator( layoutConfig ));
		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 );
	}
}

Run the code. The JComponents are now arranged across two columns as in Figure 1.8.

Figure 1.8. A two-column layout

You may have noticed the GridBagLayout is nested inside a SeparatorLayoutDecorator. This is responsible for separating widgets in different sections using JSeparators. However there are other choices for separating widgets. Modify the code to use TabbedPaneLayoutDecorator instead:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.java5.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.swing.*;
import org.metawidget.swing.layout.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector(),
			new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		TabbedPaneLayoutDecoratorConfig layoutConfig = new TabbedPaneLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new TabbedPaneLayoutDecorator( layoutConfig ));
		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 );
	}
}

Run the code. The section heading is now a JTabbedPane as in Figure 1.9.

Figure 1.9. Two-column layout with a JTabbedPane

Again, if you've ever used java.awt.GridBagLayout by hand, you'll appreciate how much easier Metawidget makes all this.

There are several ways to control widget creation. One way is to drop child controls inside the SwingMetawidget. This approach works well both within code and within visual UI builders.

Modify the code to add a JComboBox to the Metawidget:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.java5.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.swing.*;
import org.metawidget.swing.layout.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector(),
			new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		TabbedPaneLayoutDecoratorConfig layoutConfig = new TabbedPaneLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new TabbedPaneLayoutDecorator( layoutConfig ));
		metawidget.setToInspect( person );
		JComboBox combo = new JComboBox();
		combo.setName( "retired" );
		metawidget.add( combo );
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code. The JComboBox appears in place of the retired JCheckBox, because it has the same name (ie. 'retired') as Metawidget would have given the JCheckbox:

Figure 1.10. The 'retired' field has been overridden

	Note
	The default algorithm looks for child controls with the same name, but you can plug in your own implementation if you need to. See Section 2.4.4, “OverriddenWidgetBuilder”.

To suppress a widget's creation entirely, simply supplying an empty JPanel named 'retired' will not work as Metawidget will still create an accompanying label in the left hand column. Instead, Metawidget includes special Stub widgets for this purpose:

package com.myapp;

import javax.swing.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.inspector.java5.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.swing.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();
		
		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig inspectorConfig = new CompositeInspectorConfig().setInspectors(
			new PropertyTypeInspector(),
			new MetawidgetAnnotationInspector(),
			new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( inspectorConfig ) );
		GridBagLayoutConfig nestedLayoutConfig = new GridBagLayoutConfig().setNumberOfColumns( 2 ); 
		TabbedPaneLayoutDecoratorConfig layoutConfig = new TabbedPaneLayoutDecoratorConfig().setLayout(
			new org.metawidget.swing.layout.GridBagLayout( nestedLayoutConfig ));
		metawidget.setMetawidgetLayout( new TabbedPaneLayoutDecorator( layoutConfig ));
		metawidget.setToInspect( person );
		metawidget.add( new Stub( "retired" ));
		
		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}
}

Run the code. The retired field and its label will not appear, as in Figure 1.11.

Figure 1.11. The 'retired' field has been suppressed

Another way is to use a @UiHidden annotation on the business class:

package com.myapp;

import org.metawidget.inspector.annotation.*;

public class Person {
	public String name;
	
	@UiComesAfter( "name" )
	public int age;
	
	@UiComesAfter( "age" )
	@UiHidden
	public boolean retired;
	
	@UiComesAfter( "retired" )
	public Gender gender;
	
	public enum Gender { Male, Female }
	
	@UiComesAfter( "gender" )
	@UiLarge
	public String notes;
	
	@UiComesAfter( "notes" )
	@UiSection( "Work" )
	public String employer;
	
	@UiComesAfter( "employer" )
	public String department;
}

In both cases, org.metawidget.swing.layout.GridBagLayout is smart enough to always give large JComponents like notes the full width of the JFrame.

So far we have been instantiating our Inspectors and Layouts in Java code. Whilst this approach is possible for all Inspectors and Layouts, many UI frameworks employ visual UI builders or intermediate languages (such as JSP) that make getting to the Java code cumbersome (ie. you have to derive custom widgets).

As an alternative, Metawidget supports external XML configuration. Create a file called metawidget.xml in the same folder as your Main class:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

	<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" />
						<java5Inspector xmlns="java:org.metawidget.inspector.java5"/>
					</array>
				</inspectors>
			</compositeInspector>
		</inspector>
		<metawidgetLayout>
			<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
				config="TabbedPaneLayoutDecoratorConfig">
				<layout>
					<gridBagLayout config="GridBagLayoutConfig">
						<numberOfColumns>
							<int>2</int>
						</numberOfColumns>
					</gridBagLayout>
				</layout>
			</tabbedPaneLayoutDecorator>
		</metawidgetLayout>	
	</swingMetawidget>

</metawidget>

Now update your Main class to use this file:

package com.myapp;

import javax.swing.*;
import org.metawidget.swing.*;

public class Main {

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

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setConfig( "com/myapp/metawidget.xml" );
		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 );
	}
}

Run the code. The output is the same as before, but this time we are configuring our Metawidget via external XML.

Visual UI builders can call SwingMetawidget.setConfig from the builder, with no coding required. Other UI frameworks (eg. JSPs, Android) have similar 'code free' approaches (eg. setting an attribute on a JSP tag, setting an attribute in an Android layout file) to setting the XML file.

It could be argued UI-oriented annotations such as @UiComesAfter sit uncomfortably on a business class from a 'separation of concerns' perspective. It has advantages in that it keeps the metadata close to the data it refers to. It is also sufficiently abstract that it does not tie the code to any particular UI framework.

However, for those needing a different approach Metawidget can use different Inspectors to gather information from almost any source. One example is to use XmlInspector. Create a file called metawidget-metadata.xml in the same folder as your Main class:

<inspection-result xmlns="http://metawidget.org/inspection-result"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"	
	xsi:schemaLocation="http://metawidget.org/inspection-result
		http://metawidget.org/xsd/inspection-result-1.0.xsd">

	<entity type="com.myapp.Person">
		<property name="name"/>
		<property name="age"/>
		<property name="retired" hidden="true"/>
		<property name="gender"/>
		<property name="notes" large="true"/>
		<property name="employer" section="Work"/>
		<property name="department"/>
	</entity>

</inspection-result>

	Note
	In XML, the comes-after attribute is optional: XML nodes are inherently ordered, and CompositeInspector combines inspection results so that later results respect the ordering of earlier results.

	Note
	The XML does not need to specify a type attribute: we will still be using PropertyTypeInspector to look up the type. It also does not need to specify a lookup attribute: we will still be using Java5Inspector to determine possible enum values.

Update your metawidget.xml to use XmlInspector instead of MetawidgetAnnotationInspector:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

	<swingMetawidget xmlns="java:org.metawidget.swing">		
		<inspector>
			<compositeInspector xmlns="java:org.metawidget.inspector.composite"
				config="CompositeInspectorConfig">
				<inspectors>
				<array>
					<xmlInspector xmlns="java:org.metawidget.inspector.xml"
						config="XmlInspectorConfig">
						<inputStream>
							<resource>com/myapp/metawidget-metadata.xml</resource>
						</inputStream>						
					</xmlInspector>
					<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"/>
					<java5Inspector xmlns="java:org.metawidget.inspector.java5"/>
				</array>
				</inspectors>
			</compositeInspector>
		</inspector>
		<metawidgetLayout>
		<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
			config="TabbedPaneLayoutDecoratorConfig">
			<layout>
				<gridBagLayout config="GridBagLayoutConfig">
					<numberOfColumns>
						<int>2</int>
					</numberOfColumns>
				</gridBagLayout>
			</layout>
		</tabbedPaneLayoutDecorator>
		</metawidgetLayout>	
	</swingMetawidget>

</metawidget>

Remove all the annotations from the Person class and run the code again. The ordering is still correct, and there is still a section heading, but this time it is being dictated by XmlInspector.

This idea of UI characteristics being derivable from different back-end sources is fundamental to Metawidget. There is a lot of metadata already lurking in back-end systems - it just needs extracting. For example, JpaInspector understands this...

import javax.persistence.Column;

public class Person {
	@Column( nullable = false )
	public String name;
}

...denotes name is a required field (could be rendered with a star after it in the UI). Equally, PropertyTypeInspector understands that...

public class Person {
	private String name;
	
	public String getName() {
		return this.name;
	}
	
	// No setter
}

...signifies name is a read-only field (could be rendered as a label in the UI).

Metawidget comes with a range of Inspectors, and it is straightforward to write your own to inspect anything from XML configuration files to database schemas to annotations. The inspection process is decoupled from the widget creation process, so the same inspector can supply information to multiple UI frameworks.

The Desktop Address Book is essentially a larger version of the Swing application developed in Part 1 - it just has more business objects and more Swing widgets.

The application is pre-built for you in examples\swing\addressbook-swing.jar or, if you've downloaded the source code distribution, you can build it yourself by changing to the examples folder of the source distribution and typing:

ant example-swing-addressbook

This is a self-executing JAR. For convenience, it has MAINFEST.MF dependencies hard-wired into it to ..\..\metawidget.jar and lib\beansbinding.jar among others, so it's best not to move it to a different folder (if you do, you'll need to manually put metawidget.jar and beansbinding.jar on your classpath).

Run the code by navigating to the examples\swing folder and typing:

java -jar addressbook-swing.jar

The opening screen displays a search filter (at the top) and lists existing Address Book entries (at the bottom) as in Figure 1.12.

Figure 1.12. Desktop Address Book opening screen

The three search filter fields (Firstname, Surname and Type) are created by SwingMetawidget based on the ContactSearch business class. This includes populating the Type dropdown based on the ContactType enum. The Search, Add Personal Contact and Add Business Contact buttons are created by SwingMetawidget based on annotated methods in the ContactDialog class.

	Note
	To view the source code for the examples, such as the code for the ContactSearch, ContactType and ContactDialog classes, download the Metawidget source code distribution or browse it online at http://metawidget.svn.sourceforge.net/viewvc/metawidget/trunk/examples/src.

Click Add Personal Contact. The screen displays a form for filling out Personal Contact information as in Figure 1.13.

Figure 1.13. Desktop Address Book 'Add Personal Contact' screen

All the form fields are created by SwingMetawidget based on the PersonalContact business class. This class is itself derived from the Contact business class. It includes some Metawidget annotations for dropdown values and section headings.

Note the code only has one JDialog class (ContactDialog), but is capable of supporting both PersonalContact and BusinessContact UIs. The fields in the UI change depending on the object passed to ContactDialog at runtime. This is the Third Goal Of Metawidget:

	Third Goal Of Metawidget
	Metawidget performs inspection at runtime, detecting types and subtypes dynamically

The Address field is created as a nested SwingMetawidget. This is the default behaviour when Metawidget encounters datatypes it does not know how to represent with any other UI widget. The Communications field has been overridden with a manually specified JTable.

In addition, JTable.setCellEditor uses SwingMetawidget to render single JComponents as CellEditors. This includes automatically populating dropdown values.

1.2.1.1 Read-Only Mode

The Desktop Address Book uses Metawidget's setReadOnly(true) method to display read-only screens. Return to the main screen, and double-click on an existing contact (such as Homer Simpson). The same ContactDialog is used, but this time all the widgets are read-only labels as in Figure 1.14.

Figure 1.14. Desktop Address Book read-only mode

Click Edit. The labels are transformed into editable widgets by using Metawidget's setReadOnly(false), as in Figure 1.15.

Figure 1.15. Desktop Address Book edit mode

As there are a large number of Java Web application frameworks to choose from, this example comes written in five of the most popular: Google Web Toolkit (GWT), Java Server Faces (JSF), Java Server Pages (JSP), Spring Web MVC and Struts. We recommend you follow along using the one most relevant to you.

Web-based applications are inherently more difficult to setup and run than desktop-based applications because they require a container application. For this tutorial, we will use Apache Tomcat 6 (Tomcat), as it is one of the easier containers to get running. Tomcat can be downloaded from http://tomcat.apache.org.

Take a fresh install of Tomcat. The Address Book WAR is pre-built for you in either examples\faces\addressbook-faces.war, examples\gwt\addressbook-gwt.war, examples\jsp\addressbook-jsp.war, examples\spring\addressbook-spring.war or examples\struts\addressbook-struts.war. If you've downloaded the source code distribution, you can build it yourself by changing to the examples folder of the source distribution and typing:

ant example-faces-addressbook

(replacing faces with gwt, jsp, spring or struts as appropriate).

	Note
	For most web environments, deploying Metawidget is as simple as adding metawidget.jar to WEB-INF\lib. For GWT, you'll also need to include metawidget.jar and examples\gwt\metawidget-gwt-client.jar in the CLASSPATH during your GWTCompiler step.

Copy the WAR into Tomcat's webapps folder, start Tomcat, and open a Web browser to http://localhost:8080/addressbook-faces. The home page displays a search filter (at the top) and lists existing Address Book entries (at the bottom) as in Figure 1.16.

Figure 1.16. Web Address Book opening screen

As with the Desktop Address Book, the three search filter fields are created by Metawidget (this time UIMetawidget, GwtMetawidget, HtmlMetawidgetTag, SpringMetawidgetTag or StrutsMetawidgetTag) based on the ContactSearch business class:

<m:metawidget value="#{contact.search}">
	...
</m:metawidget>

Again, this includes populating the Type dropdown and localizing the text. The Search, Add Personal Contact and Add Business Contact buttons are either manually specified in the JSP page (for GWT, Spring and Struts) or created by UIMetawidget based on annotated methods in the ContactBean (for JSF).

	Note
	As with the Desktop Address Book, all source code for the examples can be found in the source code distribution under examples/src/java/org/metawidget/example. All Web-specific resources (such as JSP files) can be found under examples/src/web.

The look of the Web page relies entirely on HTML and CSS technologies. These are configured in metawidget.xml:

<htmlMetawidget>
	<parameter>
		<string>tableStyleClass</string>
		<string>table-form</string>
	</parameter>
	<parameter>
		<string>columnClasses</string>
		<string>table-label-column,table-component-column,table-required-column</string>
	</parameter>
	...

Only the layout of 'one column for the label, one column for the widget' is dictated by Metawidget, and that is again pluggable and configurable.

Click Add Personal Contact. The page displays a form for filling out Personal Contact information as in Figure 1.17.

Figure 1.17. Web Address Book 'Add Personal Contact' screen

All the form fields are created by Metawidget based on the PersonalContact business class. The section headings are the same, but have this time been rendered as HTML.

The Address field is a nested Metawidget. The Communications field has been overridden in the JSP page with a manually specified table. UIMetawidget understands a manually-specified widget to override an automatic one if it has the same value binding as the automatic widget would have (GwtMetawidget, SpringMetawidget and StrutsMetawidget do something similar):

<m:metawidget value="#{contact.current}">
	...		
	<h:dataTable value="#{contact.current.communications}">
		...
	</h:dataTable>						
	...							
<m:metawidget>

JSF has built-in support for executing actions on table rows. In order to use it, however, the Set returned by Contact.getCommunications must be wrapped into a DataModel. This is handled by ContactController.getCurrentCommunications, but this presents a problem: the mapping for the HtmlDataTable must be #{contact.currentCommunications}, but the mapping required to override UIMetawidget's automatic widget creation is #{contact.current.communications}.

UIMetawidget supplies UIStub for these situations. Stubs have a binding, but do nothing with it and render nothing. They can be used either to suppress widget creation entirely (a stub with an empty body) or to replace the automatic widget creation with one or more other widgets with different bindings:

<m:metawidget value="#{contact.current}">
	...		
	<m:stub value="#{contact.current.communications}">
		<h:dataTable value="#{contact.currentCommunications}">
			...
		</h:dataTable>						
	</m:stub>						
	...							
<m:metawidget>

JSP, Spring, Struts lack some component-based features found in Swing and JSF. Specifically, whilst it is possible for tags to reference their parent (using TagSupport.findAncestorWithClass), they have no way to interrogate their children. Therefore, it is not possible to directly support arbitrary child tags within HtmlMetawidget, SpringMetawidget and StrutsMetawidget.

Instead, we wrap the overridden Communications field in Metawidget's Stub tag. Metawidget and its Stub tags have explicit support for co-ordinating the overriding of widget creation:

<m:metawidget property="contactForm">
	...		
	<m:stub property="communications">
		<table class="data-table">
			...
		</table>
	</m:stub>						
	...							
<m:metawidget>

GwtMetawidget uses stubs around GWT widgets like FlexTable, but can use the overriding widget directly if it supports the HasName interface (eg. TextBox, CheckBox, etc).

<m:metawidget property="contactForm">
	...
	<m:stub property="communications">
		<table class="data-table">
		...
		<tr>
			<jsp:useBean id="communication"
							class="org.metawidget.example.shared.addressbook.model.Communication"/>		
			<td><mh:metawidget value="communication.type" style="width: 100%" /></td>
			<td><mh:metawidget value="communication.value" style="width: 100%" /></td>
		</tr>
		...
		</table>
	</m:stub>
	...
</m:metawidget>

1.2.2.3 Alternate Widget Libraries

This section only applies to JSF.

Metawidget factors all widget creation into WidgetBuilders. Like Inspectors, multiple WidgetBuilders can be combined using a CompositeWidgetBuilder to support third-party component libraries. In this section we will override Metawidget's default and introduce a RichFacesWidgetBuilder alongside the standard JSF HtmlWidgetBuilder.

Go into Tomcat's webapps\addressbook-faces folder (the exploded WAR) and edit WEB-INF/metawidget.xml:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

<htmlMetawidget xmlns="java:org.metawidget.faces.component.html">
	...
	<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"/>
				<java5Inspector xmlns="java:org.metawidget.inspector.java5"/>
				<facesInspector xmlns="java:org.metawidget.inspector.faces"/>			
				<xmlInspector xmlns="java:org.metawidget.inspector.xml" config="XmlInspectorConfig"/>
			</array>
			</inspectors>
		</compositeInspector>
	</inspector>
	<widgetBuilder>
		<compositeWidgetBuilder xmlns="java:org.metawidget.widgetbuilder.composite"
			config="CompositeWidgetBuilderConfig">
			<widgetBuilders>
				<array>
					<overriddenWidgetBuilder xmlns="java:org.metawidget.faces.component.widgetbuilder"/>
					<readOnlyWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
					<richFacesWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder.richfaces"/>
					<htmlWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
				</array>
			</widgetBuilders>
		</compositeWidgetBuilder>
	</widgetBuilder>
	<layout>
		<outputTextLayoutDecorator xmlns="java:org.metawidget.faces.component.html.layout"
			config="OutputTextLayoutDecoratorConfig">
			<layout>
				<simpleLayout xmlns="java:org.metawidget.faces.component.layout"/>
			</layout>
			<styleClass>
				<string>section-heading</string>
			</styleClass>
		</outputTextLayoutDecorator>
	</layout>	
</htmlMetawidget>

</metawidget>

Now restart Tomcat, refresh your Web browser and click on Homer Simpson. Notice how the Date of Birth field for Personal Contacts is now a RichFaces date picker widget, and the Number of Staff field for Business Contacts is a RichFaces slider widget.

Going futher, Metawidget's pluggable layouts make it easy to support third-party layout components. Edit WEB-INF/metawidget.xml again:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="1.0"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

<htmlMetawidget xmlns="java:org.metawidget.faces.component.html">
	...
	<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"/>
				<java5Inspector xmlns="java:org.metawidget.inspector.java5"/>
				<facesInspector xmlns="java:org.metawidget.inspector.faces"/>			
				<xmlInspector xmlns="java:org.metawidget.inspector.xml" config="XmlInspectorConfig"/>
			</array>
			</inspectors>
		</compositeInspector>
	</inspector>
	<widgetBuilder>
		<compositeWidgetBuilder xmlns="java:org.metawidget.widgetbuilder.composite"
			config="CompositeWidgetBuilderConfig">
			<widgetBuilders>
				<array>
					<overriddenWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
					<readOnlyWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
					<richFacesWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder.richfaces"/>
					<htmlWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
				</array>
			</widgetBuilders>
		</compositeWidgetBuilder>
	</widgetBuilder>
	<layout>
		<tabPanelLayoutDecorator xmlns="java:org.metawidget.faces.component.html.layout.richfaces"
			config="TabPanelLayoutDecoratorConfig">
			<layout>
				<simpleLayout xmlns="java:org.metawidget.faces.component.layout"/>
			</layout>
		</tabPanelLayoutDecorator>
	</layout>	
</htmlMetawidget>

</metawidget>

Restart Tomcat, refresh your Web browser and click on Homer Simpson again. Notice how the Contact Details and Other sections are laid out as tabs within a RichFaces TabPanel as in Figure 1.18.

Figure 1.18. Web Address Book using JBoss RichFaces

This demonstrates how easy it is to leverage widget libraries with Metawidget (this example cheats a bit, as we've pre-added the RichFaces JARs into WEB-INF\lib and some lines into web.xml, but you get the idea).

For the Mobile Address Book we use the Android platform. Android has uniquely strong support for reflection and annotations, and guarantees the availability of key packages such as org.w3c.dom. This affords Metawidget excellent runtime access to inspect the O in OIM.

Like Web-based applications, Mobile applications require a container to run. Download the Android SDK (Metawidget has been tested against versions 1.1, 1.5, 1.6 and 2.0) from http://code.google.com/android/download.html. Then change to the installation directory (usually android-sdk-windows) and run the emulator by opening a command prompt and typing:

tools\android create avd -n my_avd -t 1

Replacing -t 1 with the Android version you're using (eg. -t 2 for 1.5, -t 3 for 1.6, -t 4 for 2.0). Android 1.1 doesn't use AVDs, so you can skip this step. Next type:

tools\emulator -avd my_avd

The emulator may take a little while to start. Once finished, it will display the phone's desktop. The Address Book APK is pre-built for you in examples\android\addressbook-android.apk. If you've downloaded the source code distribution, you can build it yourself by changing to the examples folder of the source distribution and typing:

ant example-android-addressbook

(ensuring your build.properties is set correctly to point to the Android SDK).

Next, open a second command prompt, change to the Android installation directory and type:

tools\adb install <metawidget folder>\examples\android\addressbook-android.apk

This deploys the APK into the emulator. To run it, click the emulator's Menu button and then choose the Address Book application. The emulator displays a search filter (at the top) and lists existing Address Book entries (at the bottom) as in Figure 1.19.

Figure 1.19. Mobile Address Book opening screen

As with the Desktop and Web Address Books, the three search filter fields are created by Metawidget (this time AndroidMetawidget) based on the ContactSearch business class. Again, this includes populating the Type dropdown.

	Note
	As with the Desktop Address Book, all source code for the examples can be found in the source code distribution under examples/src/java/org/metawidget/example. All Android-specific resources (such as XML files) can be found under examples/src/android.

The look of the screen relies entirely on Android XML layout files, styles and themes. Only the 'one column for the label, one column for the widget' layout is dictated by Metawidget, and that is pluggable and configurable.

Choose Add Personal from the Android menu. The page displays a form for filling out Personal Contact information as in Figure 1.20.

Figure 1.20. Mobile Address Book 'Add Personal Contact' screen

UIs in Android are typically defined in XML layout files, though they can also be built programmatically. AndroidMetawidget supports both approaches. For example, the Personal Contact screen is defined in contact.xml, and contains a Metawidget defined in much the same way as in JSP (including configuring section style and overriding widget creation):

<view class="org.metawidget.android.widget.AndroidMetawidget" android:id="@+id/metawidget"
	config="@raw/metawidget">
	
	<view class="org.metawidget.android.widget.Stub" tag="communications">
			
		<ListView android:id="@id+/communications" ... />
	 			
		<Button android:id="@+id/buttonAddCommunication"
			android:text="@string/addCommunication" ... />
	
	</view>
 
</view>

Within CommunicationDialog, a Metawidget is defined programatically in much the same way as in Swing:

mMetawidget = new AndroidMetawidget( activity );
mMetawidget.setConfig( R.raw.config );				
...
mMetawidget.setToInspect( mCommunication );

This produces the dialog box in Figure 1.21.

Figure 1.21. Mobile Address Book Communications Dialog

That concludes the introductory tutorial. In summary, we now:

The Swing Applet Address Book Example demonstrates using Metawidget in applets. The example is pre-built for you in examples\swing\applet\addressbook. If you've downloaded the source code distribution, you can build it yourself by changing to the examples folder of the source distribution and typing:

ant example-swing-addressbook-applet

To run the applet, open the index.html file in a Web browser. The code is identical to the Swing Address Book covered in Part 2 of this tutorial, except it uses org.metawidget.example.swing.applet.AddressBookApplet instead of org.metawidget.example.swing.addressbook.MainFrame.

The notable feature of the example is how the applet is packaged. Metawidget is highly modular and has no mandatory third-party JAR dependencies. The example-swing-addressbook-applet Ant task builds only those inspectors necessary for the Address Book application. The resulting metawidget-applet.jar is then further compressed using pack200. The small download size makes Metawidget very viable for Applet-based environments.

The Seam Booking Example demonstrates updating an existing Seam application to use Metawidget, reducing boilerplate code. The example requires you to have previously downloaded Seam 2.2.0.GA and JBoss 5.1.0.GA, and you should be familiar with the existing Seam Booking application.

The example is located in examples\faces\seam\booking. It is not pre-built. To build it, change to the examples\faces\seam\booking folder in the Metawidget binary distribution and type:

ant

To run it, type:

cd \Applications\jboss-5.1.0.GA
bin\run

Open a Web browser to http://localhost:8080/seam-booking. The updated Metawidget Seam Booking Example looks very similar to the original, as in Figure 1.22, but uses significantly less boilerplate code.

Figure 1.22. Seam Booking with Metawidget

The files modified for adding Metawidget support are in examples\faces\seam\booking. Most of the UI code in view\book.xhtml, view\confirm.xhtml and view\hotelview.xhtml has been replaced with a single Metawidget tag. Some annotations have been added to Hotel.java and Booking.java, though Metawidget also leverages the existing JPA and Hibernate Validator ones.

The example further demonstrates packaging Metawidget for multi-tier environments. The pack-as-frontend-backend Ant task in Metawidget's build.xml creates two JAR files: metawidget-frontend.jar for deployment in the WAR, and metawidget-backend.jar for deployment in the EJB layer. This ensures a clean separation between frontend and backend code, and is important for avoiding WAR/EJB classloading problems.

The Seam Groovy Booking Example demonstrates updating an existing Seam Groovy application to use Metawidget, reducing boilerplate code. The example is a more advanced version of the previous Seam section, so you should work through that first.

The example is located in examples\faces\seam\groovybooking. It is not pre-built. To build it, change to the examples\faces\seam\groovybooking folder in the Metawidget binary distribution and type:

ant

To run it, type:

cd \Applications\jboss-5.1.0.GA
bin\run

Open a Web browser to http://localhost:8080/jboss-seam-groovybooking. As with the previous section, the updated Metawidget Seam Groovy Booking Example looks very similar to the original, but uses significantly less boilerplate code. Also, this time we are using Groovy to define our business classes. The biggest impact this has is in metawidget.xml, where the inspectors have been configured to use a Groovy property style instead of a JavaBean property style.

Metawidget supports pluggable 'property styles' for JavaBean, Groovy and other property styles. Groovy properties differ from JavaBean properties in that their annotations are tied to the private member variable, rather than the getters and setters. The use of Groovy is configured per Inspector, as in examples\faces\seam\groovybooking\resources\WEB-INF\metawidget.xml:

<propertyTypeInspector config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
	<propertyStyle>
		<groovyPropertyStyle xmlns="java:org.metawidget.inspector.impl.propertystyle.groovy"/>
	</propertyStyle>
</propertyTypeInspector>

The Seam DVD Store Example demonstrates updating an existing Seam jBPM application to use Metawidget, reducing boilerplate code. The example requires you to have previously downloaded Seam 2.2.0.GA and JBoss 5.1.0.GA, and you should be familiar with the existing Seam DVD Store application.

The example is located in examples\faces\seam\dvdstore. It is not pre-built. To build it, change to the examples\faces\seam\dvdstore folder in the Metawidget binary distribution and type:

ant

To run it, type:

cd \Applications\jboss-5.1.0.GA
bin\run

Open a Web browser to http://localhost:8080/seam-dvdstore. As with the previous two sections, the updated Metawidget Seam DVD Store example looks very similar to the original, as in Figure 1.23, but uses significantly less boilerplate code.

Figure 1.23. Seam DVD Store with Metawidget

This time, as well as generating UIComponents for business objects such as com.jboss.dvd.seam.Customer, Metawidget inspects jBPM pageflow files like newuser.jpdl.xml and checkout.jpdl.xml to generate the correct UICommand buttons for each screen.

ICEfaces is an AJAX component library for Java Server Faces. This example showcases how Metawidget can work with ICEfaces (1.8.2 and above) to deliver rich AJAX applications.

The example is pre-built for you in examples\faces\penguincolony-faces.war. Copy the WAR into Tomcat's webapps folder, start Tomcat, and open a Web browser to http://localhost:8080/penguincolony-faces:

Figure 1.24. ICEfaces with Metawidget

The application manages details of penguins in a colony. To begin, click the Edit link in the first row of the table: ICEfaces and Metawidget work together to pop up an AJAX form without refreshing the page. Next, clear the form's Name box and tab to the next field: an AJAX call is made and a validation error appears. Try entering a new name and tabbing again: the validation error disappears and the new name is immediately reflected in the table behind the popup box.

The example also makes use of the @UiFacesAttribute annotation. For example, the Java code is annotated:

@UiAction
@UiFacesAttribute( name = InspectionResultConstants.HIDDEN,
	expression = "#{!empty penguin.current.condition}" )
public void addCondition() { ... }

@UiFacesAttribute( name = InspectionResultConstants.HIDDEN,
	expression = "#{empty penguin.current.condition}" )
public PenguinCondition getCondition() { ...}

Clicking the Add Condition button, or checking one of the Hobbies checkboxes, triggers an AJAX call that re-evaluates the @UiFacesAttribute annotations and dynamically reconstructs the form without requiring a page refresh. This includes removing existing buttons, creating new dropdown boxes and creating new labels.

For more details on ICEfaces support, see Section 6.2.3.2, “IceFacesWidgetBuilder”.

The Swing AppFramework Car Demo demonstrates using Metawidget with the Swing AppFramework. Metawidget can use Swing AppFramework's @Action annotation to identify actions, both amongst a business object's properties and in external controllers, and automatically generate JButtons for them.

The application is pre-built for you in examples\swing\appframework-swing.jar or, if you've downloaded the source code distribution, you can build it yourself by changing to the examples folder of the source distribution and typing:

ant example-swing-appframework

	Note
	This example uses annotations, so you'll need Java SE 5 or higher

This is a self-executing JAR. For convenience, it has MAINFEST.MF dependencies hard-wired into it to ..\..\metawidget.jar and lib\AppFramework.jar among others, so it's best not to move it to a different folder (if you do, you'll need to manually put those JARs on your classpath).

Run the code by navigating to the examples\swing folder and typing:

java -jar appframework-swing.jar

The opening screen displays two fields to allow you to enter the make and type of a car. You can also optionally add an owner by clicking the Add an Owner button, or save the car using the Save button.

The Add an Owner button is generated by Metawidget based on the addOwner method in the Car class (which has been annotated @org.jdesktop.application.Action). The Save button is generated based on the save method in the CarApplication class (also annotated @Action). Two different Metawidgets are used in the example: one pointed at the Car class, the other at the CarApplication class.

Metawidget supports pluggable 'action styles'. The use of Swing AppFramework is configured per Inspector, as in examples/src/java/org/metawidget/example/swing/appframework/metawidget.xml from the source distribution:

<metawidgetAnnotationInspector
	config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
	<actionStyle>
		<swingAppFrameworkActionStyle xmlns="java:org.metawidget.inspector.impl.actionstyle.swing">
	</actionStyle>
</metawidgetAnnotationInspector>

As a further feature, after the Add an Owner button is clicked it disappears. This is acheived by using JexlInspector to introduce an expression language for Swing similar to JSP's EL. The method is annotated...

@Action( name = "add" )
@UiJexlAttribute( name = HIDDEN, value = "${this.owner != null}" )
public void addOwner() {
	mOwner = new Owner();
	fireActionEvent( "addOwner" );
}

...such that the button gets hidden when the car has an owner.

The Scala Animal Races Example demonstrates using SwingMetawidget together with Scala and MigLayout.

The application is pre-built for you in examples\swing\animalraces-swing.jar or, if you've downloaded the source code distribution, you can build it yourself by changing to the examples folder of the source distribution and typing:

ant example-swing-animalraces

	Note
	This example uses annotations, so you'll need Java SE 5 or higher

This is a self-executing JAR. For convenience, it has MAINFEST.MF dependencies hard-wired into it to ..\..\metawidget.jar and lib\scala-library.jar among others, so it's best not to move it to a different folder (if you do, you'll need to manually put those JARs on your classpath).

Run the code by navigating to the examples\swing folder and typing:

java -jar animalraces-swing.jar

The screen displays fields to allow you to change the name, speed and type of each animal as well buttons to start and stop the race.

Figure 1.25. Scala and MigLayout with Metawidget

Animal Races' whimsical User Interface demonstrates how Metawidget's goal of not 'owning' the UI allows multiple Metawidgets to be combined for unconventional UIs. There are three Metawidgets across the top (one for each animal in the race), and a fourth Metawidget for the buttons at the bottom.

The top three Metawidgets all use MigLayout. Because Metawidget does not hide the underlying UI framework, using MigLayout allows the Animal Races code to easily pad the Metawidget:

metawidget.setMetawidgetLayout( new MigLayout() );
metawidget.setToInspect( animal );
((MigLayout) metawidget.getLayout()).setLayoutConstraints( new LC().insets( "10" ));

The Animal Races code is written purely in Scala, located at examples/src/scala/org/metawidget/example/swing/animalraces/AnimalRaces.scala. It uses ScalaPropertyStyle to allow Metawidget to inspect Scala-based business objects:

<metawidgetAnnotationInspector xmlns="java:org.metawidget.inspector.annotation"
		config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
		<propertyStyle>
			<scalaPropertyStyle xmlns="java:org.metawidget.inspector.impl.propertystyle.scala"/>
		</propertyStyle>			
	</metawidgetAnnotationInspector>

In addition, it uses BeanUtilsBindingProcessorConfig.PROPERTYSTYLE_SCALA to bind JComponents to Scala-based business objects:

val metawidget = new SwingMetawidget()
metawidget.addWidgetProcessor( new BeanUtilsBindingProcessor()
			.setPropertyStyle( BeanUtilsBindingProcessorConfig.PROPERTYSTYLE_SCALA ))
metawidget.setToInspect( animal )

By default, GwtMetawidget inspects business objects server-side using GwtRemoteInspector. This is because client-side JavaScript does not support reflections or annotations. However if you don't need reflections or annotations, and have your own way of retrieving inspection results, you can plug in your own inspector and keep everything client-side. This example implements a TextAreaInspector that retrieves inspection results from a textarea and generates the UI.

The example is pre-built for you in examples\gwt\clientside-gwt. Because everything is purely client side, there is no need for Tomcat or any other container: simply navigate to the example folder and open index.html in your Web browser:

Figure 1.26. Client-Side GwtMetawidget

The example shows a textbox on the left containing inspection results in inspection-result-1.0.xsd format. The result of generating this XML is shown on the right. Click the Sample #2 and Sample #3 buttons to preload different XML samples, and the Generate button to generate their UI. Alternatively, you can edit the XML by hand to add new properties and actions and click Generate.

Data binding and event binding are also implemented client side. Click the Save to save the data from the generated UI using a MapPropertyBinding (in a real application, this Map could be passed back to the server for persisting). Click the Add Tracks button to trigger an event binding.

Finally, this example showcases using third-party GWT component libraries. ExtGwtWidgetBuilder is used to render a date picker widget. For more details on ExtGWT support, see Section 6.2.2.1, “ExtGwtWidgetBuilder”.

The examples\gwt\addressbook-gwt.war (discussed in Part 2 of this tutorial) and the examples\gwt\clientside (discussed in Part 3 of this tutorial) demonstrates GWT running in GWT Web mode. Developers may prefer instead to run the examples in GWT hosted mode as in Figure 1.27.

Figure 1.27. Address Book Example running in GWT Hosted Mode

There are two ways to set up the hosted mode projects. For Windows developers, there is an automated Ant build included in the source distribution (not the binary distribution). To run it, type:

cd examples\src\web\gwt
ant

	Note
	You will need to either configure GWT_HOME, METAWIDGET_HOME and METAWIDGET_SRC_HOME environment variables or pass -Dgwt.home, -Dmetawidget.home and -Dmetawidget.src.home arguments to Ant. GWT_HOME should point to a GWT 1.7 installation. METAWIDGET_HOME should point to the binary Metawidget distribution. METAWIDGET_SRC_HOME should point to the source Metawidget distribution.

The build will create Eclipse projects which can be imported by using Eclipse's File->Import menu and choosing Existing Projects into Workspace (as described in the GWT Getting Started Guide). You should now be able to run the sample applications in hosted mode, including running their unit tests.

Alternatively, you can set up the hosted mode projects manually. Here are the steps for the Address Book example (for other examples, replace the phrase AddressBook as appropriate):

Once you have the samples running, you can quickly make changes and play around. For example, find the line in ContactDialog that configures a LabelLayoutDecorator (which decorates sections using Labels) and change it to a TabPanelLayoutDecorator. This will decorate sections using a GWT TabPanel, as shown in Figure 1.28.

Figure 1.28. Address Book Example using GWT TabPanel

Metawidgets are not required to extend any Java base class or implement any Java interface. This is because most UI frameworks require widgets inherit one of their base classes, such as javax.swing.JComponent or javax.faces.UIComponent, and Java does not support multiple inheritance.

In addition, while all Metawidgets support roughly the same functionality, different UI frameworks have different in-built capabilities. For example, JSF has UIComponent.setRenderer for choosing different layouts for the same widget, whereas SwingMetawidget has to roll its own setMetawidgetLayout method. This diversity of capabilities means there cannot be a common 'Metawidget Java interface' either.

However, despite not extending any common base class or interface, all Metawidgets follow roughly the same design, with roughly the same method names:

For those looking to write their own Metawidget (say, for a currently unsupported platform) there is a BasePipeline class that implements the above steps 2-7 for you, see Section 2.1.4.1, “BasePipeline”. All of the supplied Metawidgets are implemented using this class.

As much as possible, Metawidgets defer to the existing Look and Feel technology of their native UI framework. For example, HtmlMetawidget uses HTML/CSS, SwingMetawidget uses Swing Look-and-Feels, and AndroidMetawidget uses Android styles and themes.

The one visual area Metawidget does control is how the widgets it creates are laid out. Typically this is in a tabular 'one column for the label, one column for the widget' format, but this is pluggable.

Metawidgets come with different Layout classes that can arrange the widgets in different ways, and these are set on the Metawidget in a framework-specific way. For example, JSF uses <m:metawidget rendererType=""> whereas SwingMetawidget uses setMetawidgetLayout. Where possible, the layout classes defer back to the capabilities of the native framework. For example, Swing's GridBagLayout or Android's TableLayout.

Some layouts will add localized labels and section headings to the widgets, whereas other layouts may leave them unadorned. Different Layouts may support different parameters (for example, a TableLayout may support numberOfColumns). These are initialized on the Layout at construction time using a xxxLayoutConfig.

Metawidget tries to automate much of the widget creation, but provides many hooks to customize the process:

Metawidget creates widgets native to a particular UI framework. Having to implement your own Metawidget should be far less common than having to implement your own Inspector, WidgetBuilder or WidgetProcessor, but if your chosen UI framework is not supported 'out of the box' you may need to implement your own.

Metawidgets are not required to extend any base class or implement any interface. However, it is recommended developers familiarize themselves with existing Metawidgets (such as UIMetawidget) to make their API similar. Whilst there is no one Metawidget base class, a number of convenience classes are provided:

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 business object domain 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 (ie. 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. 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 a preferrable, as many binding and validation technologies (see later) 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:

<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 focussed 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 later). 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

<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 (ie. 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>

<compositeInspector xmlns="java:org.metawidget.inspector.composite"
		config="CompositeInspectorConfig">
		<inspectors>
			<array>
				<propertyTypeInspector />
				<metawidgetAnnotationInspector />
				<facesInspector />
			</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 />
				<metawidgetAnnotationInspector />
				<strutsAnnotationInspector />
				<commonsValidatorInspector
					config="CommonsValidatorInspectorConfig"/>
			</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 later) 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:

<jpaInspector xmlns="java:org.metawidget.inspector.jpa" config="JpaInspectorConfig">
	<hideIds>
		<boolean>true</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 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 retired 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.

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, FacesInspector has an annotation @UiFacesNumberConverter. This annotation certainly has technology-specific parts to it, as it names a JSF Converter that only applies in JSF environments, so it is reasonable to name the XML attribute faces-converter-class. However, NumberConverters also use other properties about the field, such as the maximum number of integer digits. Such properties are not JSF-specific (eg. we can source the same property from Hibernate Validator's @Digits annotation), so are better named 'neutrally' (eg. maximum-integer-digits).

	Config classes must override equals and hashCode
	If your Inspector has a xxxInspectorConfig class, and you want it to be cacheable and reusable by ConfigReader and metawidget.xml, the xxxInspectorConfig class must override equals and hashCode.

Generate an XML Schema

If your Inspector has an xxxInspectorConfig class, consider defining an XML Schema for it. This is optional, but allows users to validate their use of your Inspector in their metawidget.xml at development time. There is an Ant task, org.metawidget.config.XmlSchemaGeneratorTask, provided in the source distribution that can help with this by auto-generating the schema. All the existing Metawidget schemas are generated using this Ant task.

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

E processInspectionResult( E inspectionResult, M metawidget );

Where E is a DOM Element (typically org.w3c.dom.Element) containing the inspection result, and M is a Metawidget class (ie. SwingMetawidget, UIMetawidget etc).

The InspectionResultProcessor must returned the processed inspection result's DOM Element. This is typically the same as the given inspectionResult. The parent Metwidget then passes this to the next InspectionResultProcessor in the list as show in Figure 2.3.

Figure 2.3. Typical InspectionResultProcessor list

In most cases the InspectionResultProcessor will simply be modifying the given inspectionResult. However it can decide to swap it out by returning a different DOM. This new DOM will then be passed down the list. Alternatively, the InspectionResultProcessor can return null to cancel inspection entirely. No further InspectionResultProcessors will be called, as shown in Figure 2.4.

Figure 2.4. An InspectionResultProcessor can abort the inspection

Most Metawidgets have default InspectionResultProcessors. 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>

<array>
	<comesAfterInspectionResultProcessor />
</array>

<array>
	<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, business object fields based on a JComponent client property. It extends the code from the tutorial (see Section 1.1, “Part 1 - 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[]{ "age", "retired" } );
		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<Element, SwingMetawidget> {
		
		public Element processInspectionResult( Element inspectionResult, SwingMetawidget metawidget ) {
		
			String[] includes = (String[]) metawidget.getClientProperty( "include" );
			Element entity = (Element) inspectionResult.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 inspectionResult;
		}
	}
}

	Note
	We don't necessarily recommend this approach, as it requires hard-coding business property names and won't refactor well.

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

W buildWidget( String elementName, Map<String, String> attributes, M metawidget )

Where W is a widget type (such as JComponent or UIComponent) and M is a Metawidget type (such as SwingMetawidget or UIMetawidget).

Each WidgetBuilder must look to the elementName, which is typically just 'property' or 'action' from the inspection-result, and to the various attributes and instantiate an appropriate widget. WidgetBuilders can use the given metawidget to help them if needed (for example, to access a UI context with which to instantiate widgets). Typically the WidgetBuilders do not need to configure the widget beyond simply instantiating it: the job of setting ids, attaching validators, configuring bindings and so forth is done by the WidgetProcessors (see ???).

Unless explicitly specified, each Metawidget will instantiate default WidgetBuilders to match the target platform. For example, SwingMetawidget will by default instantiate an OverriddenWidgetBuilder, ReadOnlyWidgetBuilder and SwingWidgetBuilder.

This default behaviour can be overridden either in code:

metawidget.setWidgetBuilder( new MyWidgetBuilder() );

Or via metawidget.xml

<swingMetawidget xmlns="java:org.metawidget.swing">
	<widgetBuilder>
		<myWidgetBuilder xmlns="java:com.myapp"/>
	</widgetBuilder>
</swingMetawidget>

This allows easy plugging in of third-party widget libraries. Note that overriding the default means the default is no longer instantiated. In the example above, this would mean MyWidgetBuilder is used but OverriddenWidgetBuilder, ReadOnlyWidgetBuilder and SwingWidgetBuilder are not. This is usually not what you want, because MyWidgetBuilder will be focussed on a particular third party library and will want to leave widget overriding to OverriddenWidgetBuilder, read-only widgets (ie. labels) to ReadOnlyWidgetBuilder and standard widgets to SwingWidgetBuilder.

To achieve this, use CompositeWidgetBuilder.

CompositeWidgetBuilder combines the widget libraries of several WidgetBuilders. It defers widget building to an internal list of WidgetBuilders, in order, and goes with the first one that returns non-null (see figure Figure 2.5).

Figure 2.5. CompositeWidgetBuilder composes multiple WidgetBuilders into one

In this way WidgetBuilders for third party UI component libraries (that provide specialized components) can be listed first, and WidgetBuilders for the platform's standard components can be listed last (as a 'fallback' choice).

CompositeWidgetBuilder can be instantiated either in code:

metawidget.setWidgetBuilder( new CompositeWidetBuilder( new CompositeWidgetBuilderConfig()
	.setWidgetBuilders(
		new MyWidgetBuilder(), new SwingWidgetBuilder()
	)));

Or via metawidget.xml

<swingMetawidget xmlns="java:org.metawidget.swing">
	<widgetBuilder>
		<compositeWidgetBuilder
			xmlns="java:org.metawidget.widgetbuilder.composite"
			config="CompositeWidgetBuilderConfig">
			<widgetBuilders>
				<array>
					<overriddenWidgetBuilder xmlns="java:org.metawidget.swing.widgetbuilder"/>
					<readOnlyWidgetBuilder xmlns="java:org.metawidget.swing.widgetbuilder"/>
					<myWidgetBuilder xmlns="java:com.myapp"/>
					<swingWidgetBuilder xmlns="java:org.metawidget.swing.widgetbuilder"/>
				</array>
			</widgetBuilders>
		</compositeWidgetBuilder>
	</widgetBuilder>
</swingMetawidget>

The first WidgetBuilder in the CompositeWidgetBuilder chain should generally be an OverriddenWidgetBuilder. This looks for existing child widgets that override default generation. What consitutes an 'overriden widget' varies from platform to platform. For example, for Swing any child widget with the same name will be taken as the override (see Section 1.1.8, “Controlling Widget Creation”). Android uses the tag attribute, JSF uses the value binding, and so on. For details on the OverriddenWidgetBuilder for your platform see Chapter 6, Widget Builders.

You can also choose to plug-in your own WidgetBuilder that detects 'overriden widgets' based on your own criteria. Here is an example of a custom WidgetBuilder that excludes widgets based on a client property. It extends the code from the tutorial (see Section 1.1, “Part 1 - The First Metawidget Application”).

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

import java.util.*;

import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.swing.widgetbuilder.*;
import org.metawidget.widgetbuilder.composite.*;
import org.metawidget.widgetbuilder.iface.*;
import org.metawidget.util.*;

public class Main {

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

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setWidgetBuilder( new CompositeWidgetBuilder<JComponent, SwingMetawidget>(
			new CompositeWidgetBuilderConfig<JComponent, SwingMetawidget>().setWidgetBuilders(
				new ExcludingWidgetBuilder(),
				new SwingWidgetBuilder() ) ) );
		metawidget.putClientProperty( "exclude", new String[]{ "age", "retired" } );
		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 ExcludingWidgetBuilder
		implements WidgetBuilder<JComponent, SwingMetawidget> {
		public JComponent buildWidget( String elementName, Map<String, String> attributes,
										SwingMetawidget metawidget ) {
			String[] exclude = (String[]) metawidget.getClientProperty( "exclude" );

			if ( ArrayUtils.contains( exclude, attributes.get( NAME )))
				return new Stub();

			return null;
		}
	}
}

	Note
	We don't necessarily recommend this approach, as it requires hard-coding business property names and won't refactor well.

	Note
	Although you could adapt this approach to only include (instead of exclude) certain fields, you could not adapt it to include fields in the order given in the client property. This is because WidgetBuilders only operate on single widgets at a time. Instead, see Section 2.3, “Inspection Result Processors”

The second WidgetBuilder in the CompositeWidgetBuilder chain should generally be a ReadOnlyWidgetBuilder. This builds standard platform widgets (ie. labels) for fields with read-only="true".

The exception to this rule would be if you wanted to add a custom WidgetBuilder for a widget library that had its own read-only components, or if you wanted to customise the read-only handling. Here is an example of a custom WidgetBuilder that returns non-editable JTextFields (instead of JLabels) for read-only fields. It extends the code from the tutorial (see Section 1.1, “Part 1 - The First Metawidget Application”).

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

import java.util.*;

import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.swing.widgetbuilder.*;
import org.metawidget.widgetbuilder.composite.*;
import org.metawidget.widgetbuilder.iface.*;
import org.metawidget.util.*;

public class Main {

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

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setWidgetBuilder( new CompositeWidgetBuilder<JComponent, SwingMetawidget>(
			new CompositeWidgetBuilderConfig<JComponent, SwingMetawidget>().setWidgetBuilders(
				new ReadOnlyTextFieldWidgetBuilder(),
				new SwingWidgetBuilder() ) ) );
		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 ReadOnlyTextFieldWidgetBuilder
		implements WidgetBuilder<JComponent, SwingMetawidget> {
		public JComponent buildWidget( String elementName, Map<String, String> attributes,
										SwingMetawidget metawidget ) {
			if ( !WidgetBuilderUtils.isReadOnly( attributes ) )
				return null;

			if ( TRUE.equals( attributes.get( HIDDEN )))
				return null;

			Class<?> clazz = ClassUtils.niceForName( attributes.get( TYPE ) );

			if ( String.class.equals( clazz ) || clazz.isPrimitive() ) {
				JTextField textField = new JTextField();
				textField.setEditable( false );

				return textField;
			}

			return null;
		}
	}
}

All Metawidgets have default WidgetBuilders. 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 WidgetBuilder (ie. use CompositeWidgetBuilder). 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:

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<htmlWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<htmlWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<springWidgetBuilder />
			<readOnlyWidgetBuilder />
			<htmlWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<strutsWidgetBuilder />
			<readOnlyWidgetBuilder />
			<htmlWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

<compositeWidgetBuilder config="CompositeWidgetBuilderConfig">
	<widgetBuilders>
		<array>
			<overriddenWidgetBuilder />
			<readOnlyWidgetBuilder />
			<swingWidgetBuilder />
		</array>
	</widgetBuilders>
</compositeWidgetBuilder>

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

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

metawidget.setWidgetBuilder( new HtmlWidgetBuilder( new HtmlWidgetBuilderConfig()
			.setDataTableStyleClass( "data-table" )));

Or in metawidget.xml:

<htmlWidgetBuilder xmlns="java:org.metawidget.faces.component.html.widgetbuilder"
	config="HtmlWidgetBuilderConfig">
	<dataTableStyleClass>
		<boolean>data-table</boolean>
	</dataTableStyleClass>
</htmlWidgetBuilder>

The pluggable nature of WidgetBuilders makes it easy to add your own. Because CompositeWidgetBuilder can be used to chain WidgetBuilders together, you only need worry about supporting your particular component library's widgets. You can simply return null for all other types of fields and rely on another WidgetBuilder further down the chain to instantiate one of the usual widgets.

For example, RichFacesWidgetBuilder only instantiates the RichFaces components, and returns null for everything else.

Here is an example of a custom WidgetBuilder that uses two JRadioButtons, instead of the usual JCheckBox, to represent boolean properties. It extends the code from the tutorial (see Section 1.1, “Part 1 - The First Metawidget Application”).

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

import java.awt.*;
import java.util.*;
import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.swing.widgetbuilder.*;
import org.metawidget.widgetbuilder.composite.*;
import org.metawidget.widgetbuilder.impl.*;

public class Main {

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

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setWidgetBuilder( new CompositeWidgetBuilder<JComponent, SwingMetawidget>(
			new CompositeWidgetBuilderConfig<JComponent, SwingMetawidget>().setWidgetBuilders(
				new JRadioButtonWidgetBuilder(),
				new SwingWidgetBuilder() ) ) );
		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 JRadioButtonWidgetBuilder
		implements WidgetBuilder<JComponent, SwingMetawidget> {

		public JComponent buildWidget( String elementName, Map<String, String> attributes,
			SwingMetawidget metawidget ) {
			
			if ( !"boolean".equals( attributes.get( TYPE ) ) )
				return null;

			JRadioButton trueButton = new JRadioButton( "True" );
			JRadioButton falseButton = new JRadioButton( "False" );
			JPanel panel = new JPanel();
			panel.setLayout( new GridLayout( 2, 1 ) );
			panel.add( trueButton );
			panel.add( falseButton );

			ButtonGroup buttonGroup = new ButtonGroup();
			buttonGroup.add( trueButton );
			buttonGroup.add( falseButton );

			return panel;
		}
	}
}

Generate an XML Schema

If your WidgetBuilder has an xxxWidgetBuilderConfig class, consider defining an XML Schema for it. This is optional, but allows users to validate their use of your WidgetBuilder in their metawidget.xml at development time. There is an Ant task, org.metawidget.config.XmlSchemaGeneratorTask, provided in the source distribution that can help with this by auto-generating the schema. All the existing Metawidget schemas are generated using this Ant task.

All WidgetProcessors must implement the WidgetProcessor interface. This interface defines three methods:

void onStartBuild( M metawidget );
				
W processWidget( W widget, String elementName, Map<String, String> attributes, M metawidget );

void onEndBuild( M metawidget );

Figure 2.6. onStartBuild and onEndBuild are called once, processWidget is called for each widget

The first method, onStartBuild, is called at the start of the widget building process, before the WidgetBuilder is called. WidgetProcessors may wish to act on this event to initialize themselves ready for processing. However it is acceptable to do nothing. A convenience base class, BaseWidgetProcessor, is provided with a dummy implementation so that subclasses don't have to override this method.

The last method, onEndBuild, is called at the end of the widget building process, after all widgets have been built and added to the Layout. WidgetProcessors may wish to act on this event to clean themselves up following processing. However it is acceptable to do nothing. The convenience base class, BaseWidgetProcessor, has a dummy implementation so that subclasses don't have to override this method.

The middle method, processWidget is the most important. It is called for each widget. WidgetProcessors can modify the given widget according to the given elementName and various attributes. They can use the given metawidget to help them if needed (for example, to access a UI context with which to create validators).

The processWidget method must return the processed widget. This is typically the same as the given widget. The parent Metawidget then passes this to the next WidgetProcessor in the list as show in Figure 2.7.

Figure 2.7. Typical WidgetProcessor list

In most cases the WidgetProcessor will simply be modifying the given widget (adding validators, changing styles and so on). However it can decide to swap the widget out by returning a different widget. This new widget will then be passed down the list as shown in Figure 2.8. For an example use of this capability, see HiddenFieldProcessor.

Figure 2.8. WidgetProcessors can substitute widgets

Alternatively, the WidgetProcessor can decide to exclude the widget entirely by returning null. Subsequent WidgetProcessors will not be called, as shown in Figure 2.9, and no widget will be added to the Layout.

Figure 2.9. WidgetProcessors can exclude widgets

The list of WidgetProcessors is maintained by the parent Metawidget, and is changeable (this is different to say, CompositeInspector or CompositeWidgetBuilder whose lists are immutable). This capability is designed to allow easy attaching of event handlers, and scenarios such as inner classes that have connections to their parent class:

final Object someObject = ...;
				
metawidget.addWidgetProcessor( new BaseWidgetProcessor() {
	JComponent processWidget( JComponent widget, String elementName, Map<String, String> attributes,
											SwingMetawidget metawidget ) {
		...decide whether to attach event handler...
		
		widget.add( new AbstractAction() {
			public void actionPerformed( ActionEvent event ) {
				someObject.doSomething();
			}
		}	
	}
}

Most Metawidgets have default WidgetProcessors. 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>
	<requiredAttributeProcessor />
	<immediateAttributeProcessor />
	<standardBindingProcessor />
	<readableIdProcessor />
	<labelProcessor />
	<standardValidatorProcessor />
	<standardConverterProcessor />
	<cssStyleProcessor />							
</array>

<array>
	<reflectionBindingProcessor />
</array>

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

Although individual WidgetProcessors are immutable, the List they are contained in can be changed. Methods such as addWidgetProcessor allows clients to dynamically add WidgetProcessors at runtime. This is useful for adding event handlers (see Section 2.5.1, “Interface”).

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

metawidget.addWidgetProcessor( new BeansBindingProcessor( new BeansBindingProcessorConfig()
			.setUpdateStrategy( UpdateStrategy.READ_WRITE )));

Or in metawidget.xml:

<beansBindingProcessor xmlns="java:org.metawidget.swing.widgetprocessor.binding.beansbinding"
	config="BeansBindingProcessorConfig">
	<updateStrategy>
		<enum>READ_WRITE</enum>
	</updateStrategy>
</beansBindingProcessor>

Here is an example of a custom WidgetProcessor to add tooltips to add JComponents. It extends the code from the tutorial (see Section 1.1, “Part 1 - The First Metawidget Application”).

package com.myapp;
	
import static org.metawidget.inspector.InspectionResultConstants.*;
import java.util.*;
import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.widgetprocessor.impl.*;

public class Main {

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

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.addWidgetProcessor( new TooltipProcessor() );
		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 TooltipProcessor
		extends BaseWidgetProcessor<JComponent, SwingMetawidget> {
		
		public JComponent processWidget( JComponent widget, String elementName,
										 Map<String, String> attributes, SwingMetawidget metawidget ) {
			widget.setToolTipText( attributes.get( NAME ) );
			return widget;
		}
	}
}

Like Inspectors, InspectionResultProcessors, WidgetBuilders and Layouts, WidgetProcessors are required to be immutable. However you can still make them configurable by using xxxWidgetProcessorConfig classes. For example:

public class TooltipProcessorConfig {
	private String mPrefix;
	
	public TooltipProcessorConfig setPrefix( String prefix ) {
		mPrefix = prefix;
		return this;
	}

	public String getPrefix() {
		return mPrefix;
	}
	
	// ...must override equals and hashCode too...
}

These xxxWidgetProcessorConfig classes are then passed to the WidgetProcessor at construction time, and stored internally:

public class TooltipProcessor {
	private String mPrefix;
	
	public TooltipProcessor( TooltipProcessorConfig config ) {
		mPrefix = config.getPrefix();
	}
}

This mechanism can then be controlled either programmatically:

metawidget.addWidgetProcessor( new TooltipProcessor( new TooltipProcessorConfig().setPrefix("Tip:")));

Or through metawidget.xml:

<tooltipProcessor xmlns="java:com.foo" config="TooltipProcessorConfig">
	<prefix>
		<string>Tip:</string>
	</prefix>
</tooltipProcessor>

	Config classes must override equals and hashCode
	If you want your configurable WidgetProcessor to be cacheable and reusable by ConfigReader and metawidget.xml, the xxxWidgetProcessorConfig class must override equals and hashCode.

Generate an XML Schema

If you intend your WidgetProcessor to be configurable via metawidget.xml, consider defining an XML Schema for it. This is optional, but allows users to validate their use of your WidgetProcessor in their metawidget.xml at development time. There is an Ant task, org.metawidget.config.XmlSchemaGeneratorTask, provided in the source distribution that can help with this by auto-generating the schema. All the existing Metawidget schemas are generated using this Ant task.

All Layouts must implement the Layout interface. This interface defines three methods:

void startLayout(W container,M metawidget);
				
void layoutWidget(W widget,String elementName,Map<String, String> attributes,W container,M metawidget);

void endLayout(W container,M metawidget);

Figure 2.10. startLayout and endLayout are called once, layoutWidget is called for each widget

The first method, startLayout, is called to initialize the given container. It is acceptable to do nothing. A convenience base class, BaseLayout, is provided with a dummy implementation so that subclasses don't have to override this method.

The last method, endLayout, is called to finish the given container. It is acceptable to do nothing. The convenience base class, BaseLayout, has a dummy implementation so that subclasses don't have to override this method.

The middle method, layoutWidget is the most important. It is called for each widget. Layouts should add the given widget as a child of the given container, according to the given elementName and attributes. They can use the given metawidget to access additional services if needed (such as state saving).

LayoutDecorator allows you to combine multiple Layouts together in a heirarchy. Conceptually, this is similar to CompositeInspector or CompositeWidgetBuilder, but Layouts are fundamentally different in that most are 'end points' that cannot sensibly be composed into sequential lists (eg. what should happen if you try to combine a GridBagLayout with a FlowLayout?).

Rather, Layouts must be combined heirarchically, with an 'outer' Layout delegating to a single 'inner' Layout. LayoutDecorator is an abstract class that can be extended in order to decorate other Layouts. For example, GridBagLayout can be decorated using TabbedPaneLayoutDecorator to add tabbed section functionality.

<metawidgetLayout>
	<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="TabbedPaneLayoutDecoratorConfig">
		<layout>
			<gridBagLayout />
		</layout>
	</tabbedPaneLayoutDecorator>			
</metawidgetLayout>

A LayoutDecorator can also decorate another LayoutDecorator to provide fine-grained control over nested sections. For example, the business object...

public class Person {
	@UiSection( { "Person", "Name" } )
	public String firstname;
	
	public String surname;
	
	@UiSection( { "Person", "Contact Detail" } )
	public String telephone;
}

...could be rendered using nested TabbedPaneLayoutDecorators...

<metawidgetLayout>
	<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="TabbedPaneLayoutDecoratorConfig">
		<layout>
			<tabbedPaneLayoutDecorator config="TabbedPaneLayoutDecoratorConfig">
				<layout>
					<gridBagLayout />
				</layout>
			</tabbedPaneLayoutDecorator>			
		</layout>
	</tabbedPaneLayoutDecorator>			
</metawidgetLayout>

...as shown in Figure 2.11.

Figure 2.11. Nested TabbedPaneLayoutDecorators

Alternatively, it could use a TabbedPaneLayoutDecorator nested within a SeparatorLayoutDecorator...

<metawidgetLayout>
	<separatorLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="SeparatorLayoutDecoratorConfig">
		<layout>
			<tabbedPaneLayoutDecorator config="TabbedPaneLayoutDecoratorConfig">
				<layout>
					<gridBagLayout />
				</layout>
			</tabbedPaneLayoutDecorator>			
		</layout>
	</separatorLayoutDecorator>			
</metawidgetLayout>

...as shown in Figure 2.12.

Figure 2.12. TabbedPaneLayoutDecorator within a SeparatorLayoutDecorator

Or the opposite - a SeparatorLayoutDecorator nested within a TabbedPaneLayoutDecorator...

<metawidgetLayout>
	<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="TabbedPaneLayoutDecoratorConfig">
		<layout>
			<separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
				<layout>
					<gridBagLayout />
				</layout>
			</separatorLayoutDecorator>			
		</layout>
	</tabbedPaneLayoutDecorator>			
</metawidgetLayout>

...as shown in Figure 2.13.

Figure 2.13. SeparatorLayoutDecorator within a TabbedPaneLayoutDecorator

All Metawidgets have default Layouts. 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:

<textViewLayoutDecorator config="TextViewLayoutDecoratorConfig">
	<layout>
		<tableLayout />
	</layout>
</textViewLayoutDecorator>

<outputTextLayoutDecorator config="OutputTextLayoutDecoratorConfig">
		<layout>
			<simpleLayout/>
		</layout>
	</outputTextLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<htmlTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<htmlTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<htmlTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
	<layout>
		<gridBagLayout/>
	</layout>
</separatorLayoutDecorator>

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

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

metawidget.setLayout( new HtmlTableLayout( new HtmlTableLayoutConfig().setNumberOfColumns( 2 ));

Or in metawidget.xml:

<htmlTableLayout xmlns="java:org.metawidget.jsp.tagext.html.layout"
	config="HtmlTableLayoutConfig">
	<numberOfColumns>
		<int>2</int>
	</numberOfColumns>
</htmlTableLayout>

Here is an example of a custom Layout that arranges components in a bulleted HTML list. It could be useful for, say, arranging action elements that were represented by HTML anchor tags:

package com.myapp;

import java.util.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import org.metawidget.jsp.*;
import org.metawidget.jsp.tagext.*;
import org.metawidget.layout.iface.*;

public class HtmlListLayout
	implements Layout<Tag, MetawidgetTag> {
	
	public void startLayout( Tag containerTag, MetawidgetTag metawidgetTag ) {
		try	{
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "<ul>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}

	public void layoutChild( Tag tag, String elementName, Map<String, String> attributes,
		Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "<li>" );
			writer.write( JspUtils.writeTag( metawidgetTag.getPageContext(), tag, containerTag, null ) );
			writer.write( "</li>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}

	public void endLayout( Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "</ul>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}
}

Like Inspectors, WidgetBuilders and WidgetProcessors, Layouts are required to be immutable. However they will generally need to use some internal state, such as tracking the current row in a table layout. This can be achieved in two ways:

ConfigReader can construct new instances of objects. The XML element name is the Java class name and the XML namespace is the Java package. The following example constructs an org.metawidget.swing.SwingMetawidget.

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

	<swingMetawidget xmlns="java:org.metawidget.swing"/>
	
</metawidget>			

Using the XML namespace to denote the Java package allows the (optional) plugging in of XML Schema validation on a per-package basis. For example:

<swingMetawidget xmlns="java:org.metawidget.swing"
xsi:schemaLocation="java:org.metawidget.swing http://metawidget.org/xsd/org.metawidget.swing-1.0.xsd"/>

Within an object, ConfigReader can call setXXX methods. The following example calls the setOpaque method of SwingMetawidget:

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

	<swingMetawidget xmlns="java:org.metawidget.swing">
		<opaque>
			<boolean>true</boolean>
		</opaque>
	</swingMetawidget>
	
</metawidget>

Multi-parameter methods are also supported. The following example calls the setParameter method of HtmlMetawidget (it takes two arguments):

<metawidget xmlns="http://metawidget.org"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://metawidget.org http://metawidget.org/xsd/metawidget-1.0.xsd">

	<htmlMetawidget xmlns="java:org.metawidget.faces.component.html">
		<parameter>
			<string>numberOfColumns</string>
			<int>2</int>
		</parameter>		
	</htmlMetawidget>
	
</metawidget>

As alluded to in the previous section, when calling setXXX methods the XML format can specify simple types. The previous example used boolean, string and int. Also supported are:

Some environments store their resources in specialized locations that are inaccessible by normal means (ie. ClassLoader.getResource). For example, Web environments use a WEB-INF folder that must be accessed through ServletContext.getResource. Simiarly, Android environments must resolve resources using Context.getResources.

ConfigReader and its specialized subclasses, such as ServletConfigReader and AndroidConfigReader understand this distinction and provide resource resolving capability to all the objects they create. Specifically, ConfigReader implements ResourceResolver and passes itself to any xxxConfig classes that implement NeedsResourceResolver.

Metawidget dictates all Inspectors, WidgetBuilders, WidgetProcessors and Layouts be immutable. This is an important design decision as it means a single instance can be reused across an entire application. Immutabilty is enforced by not having any setXXX methods on the objects themselves. Rather, the setXXX methods are called on Config objects, which are then passed to the object's constructor. Once constructed, the object cannot be changed.

ConfigReader understands this distinction by way of a config attribute. The following example configures an immutable Inspector. The setInspectors method is called on org.metawidget.inspector.composite.CompositeInspectorConfig and then passed to CompositeInspector:

<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" />
		</array>
	</inspectors>
</compositeInspector>

Having constructed an immutable object, ConfigReader will cache the instance and reuse it. The config attribute defaults to using the same package as the xmlns (ie. org.metawidget.inspector.composite in the example above). This can be overridden if a fully qualified classname is provided.

	Config classes must override equals and hashCode
	In order to reliably cache and reuse an immutable object that uses a config attribute, the xxxConfig class must override equals and hashCode. This is important to bear in mind when implementing your own custom objects.

SwingMetawidget is a Swing component. For an introduction to SwingMetawidget, see Section 1.1, “Part 1 - The First Metawidget Application” and Section 1.2.1, “Desktop Address Book”.

GwtMetawidget is a client-side, JavaScript widget for GWT. Despite the limitations of the JavaScript environment, GwtMetawidget supports reflection, annotations, pluggable layouts and data binding. For an introduction to GwtMetawidget, see Section 1.2.2, “Web Address Book” and Section 1.3.9, “GWT Hosted Mode Examples”.

3.2.1.2 Reflection and Annotations

GwtMetawidget leverages Metawidget's separate Inspector/renderer architecture and AJAX to perform server-side inspection as in Figure 3.1. This allows GwtMetawidget to reflect properties and inspect annotations of business objects, even though JavaScript supports neither.

Figure 3.1. GwtMetawidget uses AJAX to perform server-side inspection

The process is:

1. instantiate the business object on the client-side as normal (ie. as JavaScript)

2. give the business object to GwtMetawidget (a client-side, JavaScript GWT Widget)

3. GwtMetawidget uses AJAX to pass the business object to the server

4. the server, using Java, runs all the Inspectors (including reflection and annotations)

5. the server returns the inspection results as an XML document

6. GwtMetawidget uses JavaScript to render the HTML widgets

Note that steps 3 and 5 (the AJAX call to and from the server) are the most costly in terms of performance. Techniques to improve GWT performance are discussed in Section 10.3, “Rebinding”.

public class MyClientSideInspector
	implements Inspector {
	public String inspect( Object toInspect, String type, String... names ) {
		return ...some XML string...
	}
}

myGWTMetawidget.setInspector( new MyClientSideInspector() )

UIMetawidget is a Java Server Faces component. For an introduction to UIMetawidget, see Section 1.2.2, “Web Address Book” and Section 1.3.2, “Seam Example”.

.table-component-column input { width: 100%; }

.table-component-column input[type="button"] { width: auto; }

SpringMetawidget is a Spring taglib. For an introduction to SpringMetawidget, see Section 1.2.2, “Web Address Book”.

StrutsMetawidget is a Struts taglib. For an introduction to StrutsMetawidget, see Section 1.2.2, “Web Address Book”.

AndroidMetawidget is an Android widget. For an introduction to AndroidMetawidget, see Section 1.2.3, “Mobile Address Book”.

3.3.1.1 Installation

There are two steps to installing AndroidMetawidget within an Android application:

1. Add metawidget.jar to your CLASSPATH (ie. under your project's Libraries tab in Eclipse)

2. You can (optionally) configure the Metawidget, either programmatically (as detailed in Section 1.1.5, “Inspectors”) or using a metawidget.xml file (as detailed in Section 1.1.9, “Configuring Metawidget Externally”) in your res/raw folder.

	Note
	Given the resource constraints of a mobile device, consider creating a custom metawidget.jar that only includes the classes you need (as detailed in Section 10.1, “JAR Size”).

<resources>
	<string name="dob">Date of Birth<string>
</resources>

class Person {
	...
	public Date getDob() {
		return mDob;
	}
}

<androidMetawidget>
	<bundle>
		<class>org.metawidget.example.android.addressbook.R$string</class>
	</bundle>
</androidMetawidget>

BaseObjectInspector underlies many of the Inspectors that inspect objects (as opposed to, say, XML files). It provides easy-to-override methods such as...

protected Map<String, String> inspectProperty( Property property )

...for inspecting properties, and...

protected Map<String, String> inspectAction( Action action )

...for inspecting actions, and finally...

protected Map<String, String> inspectTrait( Trait trait )

...for inspecting things that apply to both properties and actions (eg. @UiLabel). Quite what constitutes a 'property' or an 'action' is decoupled into pluggable PropertyStyles and ActionStyles.

4.1.1.1 PropertyStyle

The PropertyStyle interface allows pluggable, fine-grained control over what is considered a 'property'. Different environments may have different approaches to defining what constitutes a property. For example, JavaBean-properties are convention-based, whereas Groovy has explicit property support. Equally, some environments may have framework-specific, base class properties that should be filtered out and excluded from the list of 'real' business model properties.

The default property style is JavaBeanPropertyStyle. To change it within metawidget.xml:

<propertyTypeInspector xmlns="java:org.metawidget.inspector.propertytype"
	config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
	<propertyStyle>
		<strutsActionFormPropertyStyle xmlns="java:org.metawidget.inspector.impl.propertystyle.struts"/>
	</propertyStyle>
</propertyTypeInspector>

To change it programmatically:

BaseObjectInspectorConfig config = new BaseObjectInspectorConfig();
config.setPropertyStyle( StrutsActionFormPropertyStyle.class );
metawidget.setInspector( new PropertyTypeInspector( config ) );

4.1.1.1.1 JavaBeanPropertyStyle

The JavaBeanPropertyStyle is the default property style used by all BaseObjectInspector subclasses (which includes all annotation inspectors).

This property style recognizes JavaBean-convention getXXX, setXXX and isXXX methods, as well as public member variables. In addition, it maintains a cache of reflected classes for performance.

	Note
	When using getter methods and private members, make sure you annotate the getter not the private member. JavaBeanPropertyStyle cannot find annotations on private members, because the JavaBean specification does not define a way to determine which private members belong to which getters.

4.1.1.1.2 StrutsActionFormPropertyStyle

The StrutsActionFormPropertyStyle provides special handling for Struts ActionForms.

ActionForm properties essentially follow JavaBean-convention (this class extends JavaBeanPropertyStyle), but should not include properties from the Struts classes, (eg. getServlet, getServletWrapper and getMultipartRequestHandler in ActionForm and getDynaClass in DynaActionForm).

4.1.1.1.3 GroovyPropertyStyle

The GroovyPropertyStyle recognizes GroovyBean properties.

Groovy tries hard to make its GroovyBean properties compatible with JavaBean getters/setters, and indeed one can almost use the default JavaBeanPropertyStyle to read them. Unfortunately, GroovyBeans differ in that:

• annotations defined on properties are only attached to the (generated) private member variable, not the (generated) getter/setter methods.

• GroovyBeans define an implicit getMetaClass method which, although matching the JavaBean signature, should not be treated as a business model property.

4.1.1.1.4 JavassistPropertyStyle

The JavassistPropertyStyle extends JavaBeanPropertyStyle and makes use of Javassist for those environments that have it available.

Javassist is used to inspect the debug line numbering information embedded in JVM bytecode to sort getters/setters according to their original declaration order in the source code. This saves business objects having to use @UiComesAfter (or an XML file, or some other method) to impose an ordering.

However, a danger of this approach is that if the business objects are ever recompiled without debug line numbering information (eg. when moving from development to production) the UI fields will lose their ordering. Such a subtle bug may not be picked up, so as a safeguard JavassistPropertyStyle 'fails hard' with an InspectorException if line numbers are not available.

JavassistPropertyStyle uses the following sorting algorithm:

• superclass public fields come first, sorted by name.

• superclass methods come next, sorted by getter line number (or, if no getter, setter line number).

• public fields come next, sorted by name.

• methods come last, sorted by getter line number (or, if no getter, setter line number).

Note this algorithm is less flexible than @UiComesAfter, which can interleave superclass and subclass properties. However, it is possible to use both @UiComesAfter and JavassistPropertyStyle together to get the best of both worlds.

4.1.1.1.5 ScalaPropertyStyle

The ScalaPropertyStyle recognizes Scala properties.

Scala can make its properties compatible with JavaBean getters/setters, but only if you put special @BeanProperty annotations on them. Instead, ScalaPropertyStyle is designed to access Scala properties natively.

4.1.1.1.6 Implementing Your Own PropertyStyle

All property styles must implement the PropertyStyle interface. BasePropertyStyle assists in caching properties per class (looking them up is often expensive, involving reflection or similar techniques) and in excluding properties based on name, type or base class. Here is an example of a custom PropertyStyle that identifies fields based on ResourceBundle i18n entries. It extends the code from the tutorial (see Section 1.1, “Part 1 - The First Metawidget Application”).

package com.myapp;
				
import java.util.*;
import javax.swing.*;
import org.metawidget.inspector.iface.*;
import org.metawidget.inspector.impl.*;
import org.metawidget.inspector.impl.propertystyle.*;
import org.metawidget.inspector.impl.propertystyle.javabean.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.swing.*;
import org.metawidget.util.*;

public class Main {

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

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.setInspector( new PropertyTypeInspector( new BaseObjectInspectorConfig()
			.setPropertyStyle( new BundlePropertyStyle() ) ) );
		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 BundlePropertyStyle
		extends JavaBeanPropertyStyle {

		protected Map<String, Property> inspectProperties( Class<?> clazz ) {
			try {
				Map<String, Property> properties = CollectionUtils.newHashMap();
				ResourceBundle bundle = ResourceBundle.getBundle( "MyBundle" );

				for ( Enumeration<String> e = bundle.getKeys(); e.hasMoreElements(); ) {
					String key = e.nextElement();
					properties.put( key, new FieldProperty( key, clazz.getField( key ) ) );
				}

				return properties;
			}
			catch ( Exception ex ) {
				throw InspectorException.newException( ex );
			}
		}
	}
}

For brevity, this example extends JavaBeanPropertyStyle. Normally, you would want to extend BasePropertyStyle and, as well as overriding inspectProperties to locate the properties, implement the Property interface with mechanisms for interrogating the property.

	Note
	In this particular example, it may be useful to create a BundlePropertyStyleConfig class that implements NeedsResourceResolver (see Section 2.7.4, “Resolving Resources”). Then it could use ResourceResolver.openResource to locate the bundle in case it was in a specialized location (such as WEB-INF/).

<metawidgetAnnotationInspector config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
	<actionStyle>
		<swingAppFrameworkActionStyle xmlns="java:org.metawidget.inspector.impl.actionstyle.swing">
	</actionStyle>
</metawidgetAnnotationInspector>

BaseObjectInspectorConfig config = new BaseObjectInspectorConfig();
config.setActionStyle( SwingAppFrameworkActionStyle.class );
metawidget.setInspector( new MetawidgetAnnotationInspector( config ) );

PropertyTypeInspector extends BaseObjectInspector, and so inherits its features. In addition, it returns the following attributes for the following business properties:

Java5Inspector extends BaseObjectInspector, and so inherits its features. In addition, it returns the following attributes for the following business properties:

BeanValidationInspector inspects Bean Validation (JSR 303) annotations. It returns the following attributes for the following business properties:

FacesInspector inspects Java Server Faces-specific annotations. It returns the following attributes for the following business properties:

HibernateValidatorInspector inspects Hibernate Validator annotations. It returns the following attributes for the following business properties:

JexlInspector inspects @UiJexlAttribute annotations and sets arbitrary attributes based on the result of evaluating an Apache Commons JEXL expression. It can be used to introduce declarative UI scripting into environments that lack their own expression language (ie. JSP has an EL, Swing does not). For example:

import org.metawidget.inspector.commons.jexl.*;

public class Person {
	public boolean retired;
	@UiJexlAttribute( name = "hidden", value = "!this.retired" )
	public BigDecimal pension;
}

This code returns a hidden attribute based on evaluating the JEXL expression !this.retired (where this refers to the runtime instance of the Person being inspected). It could be used to show/hide the pension field in response to the retired checkbox being checked.

The JEXL expression language also supports branching statements. For example:

import org.metawidget.inspector.commons.jexl.*;

public class PersonController {

	@UiJexlAttribute( name = "label", value = "if ( this.readOnly ) 'Back'" )
	public void cancel() { ... }
}

This code overrides the label of an action to be either 'Back' or 'Cancel', depending on whether the Person was being edited. It is taken from the Swing Address Book sample (see Section 1.2.1, “Desktop Address Book”).

JpaInspector inspects Java Persistence Architecture annotations. It returns the following attributes for the following business properties:

As much as possible, Metawidget tries to inspect metadata from existing sources, without introducing new concepts. Where that is not sufficient, MetawidgetAnnotationInspector adds a handful of annotations:

OvalInspector inspects OVal annotations. It returns the following attributes for the following business properties:

BaseXmlInspector's config class, BaseXmlInspectorConfig, uses a setInputStream method to specify the location of the XML. This allows a variety of options for sourcing the XML. For example:

<xmlInspector xmlns="java:org.metawidget.inspector.xml"
	config="XmlInspectorConfig">
	<inputStream>
		<resource>com/myapp/metawidget-metadata.xml</resource>
	</inputStream>
</xmlInspector>

And:

<xmlInspector xmlns="java:org.metawidget.inspector.xml"
	config="XmlInspectorConfig">
	<inputStream>
		<url>http://myserver.com/my-xml.xml</url>
	</inputStream>
</xmlInspector>

As well as specifying multiple files (which will all be inspected as one):

<xmlInspector xmlns="java:org.metawidget.inspector.xml"
	config="XmlInspectorConfig">
	<inputStreams>
		<array>
			<url>http://myserver.com/my-xml-1.xml</url>
			<url>http://myserver.com/my-xml-2.xml</url>
		</array>			
	</inputStreams>
</xmlInspector>

CommonsValidatorInspector inspects Apache Commons Validator validation.xml files. It returns the following attributes for the following business properties:

HibernateInspector inspects Hibernate hibernate.cfg.xml and mapping.hbm.xml files. For the former, it iterates over <session-factory>'s <mapping> elements and inspects all mapping files. It returns the following attributes for the following business properties:

JexlXmlInspector inspects files in inspection-result-1.0.xsd format looking for XML attributes wrapped in ${...} notation. It processes these attributes as JEXL expressions before returning them. For example:

<inspection-result>

	<entity type="com.myapp.Person">
		<property name="pension" hidden="${!this.retired}"/>
	</entity>

</inspection-result>

JexlXmlInspector is effectively equivalent to JexlInspector but uses XML files instead of annotations.

PageflowInspector inspects JBoss jBPM pageflow files looking for page nodes and their associated transitions to be used as actions. For example, this pageflow.jpdl.xml file...

<page name="confirm">
	<transition name="purchase" to="complete" />
	<transition name="cancel" to="cancel" />
</page>

...would return purchase and cancel as available actions for the confirm page. For an example of PageflowInspector in use, see Section 1.3.4, “jBPM Example”.

SeamInspector inspects Seam XML files for useful metadata. Specifically:

XmlInspector inspects files in inspection-result-1.0.xsd format. It can be used when no other inspector is available for the given attribute.

Some attributes accept multiple values, such as lookup. These can be supplied as a comma-separated string. The values will be trimmed for whitespace. If the values themselves contain commas, they can be escaped with the \ character.