Metawidget 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;
}

Note 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.

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

Figure 1.1. 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 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 form. 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, 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. Metawidget itself can run on J2SE 1.4, but you'll need to the ordering information from a different source (see the section called “Inspecting Different Sources”)

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

package com.myapp;

import org.metawidget.inspector.annotation.*;

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

Again, 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.2. 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, add the following lines to Person (lines to add are shown in bold):

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.3. 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 inspects only JDK 1.4-compatible features, and JDK 1.4 doesn't include enums.

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 (line to add is shown in bold):

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.4. 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 a PropertyTypeInspector for us.

What we need is to combine the results of Java5Inspector and PropertyTypeInspector 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 config = new CompositeInspectorConfig()
			.setInspectors( 
				new MetawidgetAnnotationInspector(),
				new PropertyTypeInspector(),
				new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( config ) );
		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.5. Using multiple inspectors

This idea of combining multiple Inspectors to inspect different characteristics of your existing application 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 objects - 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.6. Annotations have been used to define section headings and 'large' fields (ie. a JTextArea).

Figure 1.6. Additional fields and a section heading

By default, SwingMetawidget lays out JComponents using org.metawidget.swing.layout.GridBagLayout. You can swap this for a different layout using SwingMetawidget.setLayoutClass, or you can fine-tune the existing one using SwingMetawidget.setParameter:

package com.myapp;

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

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

		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig config = new CompositeInspectorConfig()
			.setInspectors(
				new MetawidgetAnnotationInspector(),
				new PropertyTypeInspector(),
				new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( config ) );
		metawidget.setParameter( "numberOfColumns", 2 );
		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.7.

Figure 1.7. A two-column layout

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

There are several ways to control widget creation. Creation can be overridden by dropping 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.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.swing.*;

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

		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig config = new CompositeInspectorConfig()
			.setInspectors(
				new MetawidgetAnnotationInspector(),
				new PropertyTypeInspector(),
				new Java5Inspector() );
		metawidget.setInspector( new CompositeInspector( config ) );
		metawidget.setParameter( "numberOfColumns", 2 );		
		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 (eg. 'retired') as Metawidget would have given the JCheckbox.

Figure 1.8. The 'retired' field has been overridden

To suppress a widget's creation entirely, simply supplying an empty JPanel 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.*;
import org.metawidget.inspector.annotation.*;
import org.metawidget.inspector.propertytype.*;
import org.metawidget.inspector.composite.*;
import org.metawidget.swing.*;

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

		SwingMetawidget metawidget = new SwingMetawidget();
		CompositeInspectorConfig config = new CompositeInspectorConfig()
			.setInspectors(
				new MetawidgetAnnotationInspector(),
				new PropertyTypeInspector() );
		metawidget.setInspector( new CompositeInspector( config ) );
		metawidget.setParameter( "numberOfColumns", 2 );
		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.

Figure 1.9. The 'retired' field has been suppressed

Alternatively, you can 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 in Java code. Whilst this approach is possible for all Inspectors, many UI frameworks employ visual UI builders or intermediate languages (such as JSPs) 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/metawidget-1.0.xsd">

<swingMetawidget xmlns="java:org.metawidget.swing">		
	<inspector>
		<compositeInspector xmlns="java:org.metawidget.inspector.composite"
			config="CompositeInspectorConfig">
			<inspectors>
				<list>
				<metawidgetAnnotationInspector
					xmlns="java:org.metawidget.inspector.annotation" />
				<propertyTypeInspector
					xmlns="java:org.metawidget.inspector.propertytype"/>
				<java5Inspector
					xmlns="java:org.metawidget.inspector.java5"/>
				</list>
			</inspectors>
		</compositeInspector>
	</inspector>
</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.setParameter( "numberOfColumns", 2 );
		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 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/inspection-result-1.0.xsd">

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

</inspection-result>

Note that XmlInspector does not need a comes-after attribute: XML nodes are inherently ordered, and CompositeInspector combines inspection results so that later results respect the ordering of earlier results. XmlInspector also does not need to specify a type attribute: we will still be using PropertTypeInspector to look up the types.

Update your metawidget.xml to use XmlInspector:

<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/metawidget-1.0.xsd">

<swingMetawidget xmlns="java:org.metawidget.swing">		
	<inspector>
		<compositeInspector xmlns="java:org.metawidget.inspector.composite"
			config="CompositeInspectorConfig">
			<inspectors>
				<list>
				<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"/>
			</list>
			</inspectors>
		</compositeInspector>
	</inspector>
</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 the same 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 loosely coupled 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 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.10.

Figure 1.10. 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.

	Tip
	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.11.

Figure 1.11. 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.

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.12.

Figure 1.12. 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.13.

Figure 1.13. 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 typing:

ant example-faces-addressbook

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

	Tip
	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.14.

Figure 1.14. Web Address Book opening screen

As with the Desktop Address Book, the three search filter fields are created by Metawidget (this time UIMetawidget, GwtMetawidget, 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).

	Tip
	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:

<m:metawidget value="#{contact.search}">
	<f:param name="tableStyleClass" value="table-form"/>
	<f:param name="columnClasses"
		value="table-label-column,table-component-column,required" />
	...
</m:metawidget>

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.15.

Figure 1.15. 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%" layoutClass=""/></td>
			<td><mh:metawidget value="communication.value"
				style="width: 100%" layoutClass=""/></td>
		</tr>
		...
		</table>
	</m:stub>
	...
</m:metawidget>

<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/metawidget-1.0.xsd">

<htmlMetawidget xmlns="java:org.metawidget.faces.component.html">
	<parameter>
		<string>tableStyleClass</string>
		<string>table-form</string>
	</parameter>
	<parameter>
		<string>columnClasses</string>
		<string>table-label-column,table-component-column,required</string>
	</parameter>
	<parameter>
		<string>footerStyleClass</string>
		<string>buttons</string>
	</parameter>	
	<widgetBuilder>
	<compositeWidgetBuilder
		xmlns="urn:java:org.metawidget.widgetbuilder.composite"
		config="CompositeWidgetBuilderConfig">
		<widgetBuilders>
		<list>
		<richFacesWidgetBuilder
		xmlns="java:org.metawidget.faces.component.html.widgetbuilder.richfaces"/>
		<htmlWidgetBuilder
		xmlns="java:org.metawidget.faces.component.html.widgetbuilder"/>
		</list>
		</widgetBuilders>
	</compositeWidgetBuilder>
	</widgetBuilder>
	<inspector>		
		<compositeInspector
			xmlns="java:org.metawidget.inspector.composite"
			config="CompositeInspectorConfig">
			<inspectors>
			<list>
			<metawidgetAnnotationInspector
				xmlns="java:org.metawidget.inspector.annotation"/>
			<propertyTypeInspector
				xmlns="java:org.metawidget.inspector.propertytype"/>
			<java5Inspector
				xmlns="java:org.metawidget.inspector.java5"/>
			<facesInspector
				xmlns="java:org.metawidget.inspector.faces"/>			
			<xmlInspector
				xmlns="java:org.metawidget.inspector.xml"
				config="XmlInspectorConfig"/>
			</list>
			</inspectors>
		</compositeInspector>
	</inspector>
</htmlMetawidget>

</metawidget>

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 version 1.1_r1 of the Android SDK from http://code.google.com/android/download.html. Then, change to the installation directory (usually android-sdk-windows-1.1_r1) and run the emulator by opening a command prompt and typing:

tools\emulator

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 typing:

ant example-android-addressbook

(ensuring your build.properties is setup 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, use the arrow pad on the emulator to move to the All button, then click the center of the arrow pad. Select the Address Book application and press the center of the arrow pad again. The emulator displays a search filter (at the top) and lists existing Address Book entries (at the bottom) as in Figure 1.16.

Figure 1.16. 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.

	Tip
	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.17.

Figure 1.17. 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"
	paramSectionStyle="@style/section">
	
	<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.18.

Figure 1.18. Mobile Address Book Communications Dialog

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 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 to around 50KB. This small download size makes Metawidget very viable for Applet-based environments.

The examples\gwt\addressbook-gwt.war discussed in Part 2 of this tutorial demonstrates GWT running in GWT Web mode. Developers may prefer instead to run the example in GWT hosted mode as in Figure 1.19.

Figure 1.19. Address Book Example running in GWT Hosted Mode

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

cd examples\web\gwt
ant

You will need to either configure GWT_HOME and METAWIDGET_HOME environment variables or pass -Dgwt.home and -Dmetawidget.home arguments to Ant. The build will create an Eclipse project 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).

Alternatively, to set up a hosted mode project manually:

You should now be able to run the GWT Address Book sample application in hosted mode.

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.1.1.GA and JBoss 4.2.3.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 and type:

ant

To run it, type:

cd \Applications\jboss-4.2.3.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.20, but uses significantly less boilerplate code.

Figure 1.20. 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 and type:

ant

To run it, type:

cd \Applications\jboss-4.2.3.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 and Groovy 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>
		org.metawidget.inspector.impl.propertystyle.groovy.GroovyPropertyStyle
	</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.1.1.GA and JBoss 4.2.3.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 and type:

ant

To run it, type:

cd \Applications\jboss-4.2.3.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.21, but uses significantly less boilerplate code.

Figure 1.21. 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 files like newuser.jpdl.xml and checkout.jpdl.xml to generate the correct UICommand buttons for each screen.

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 typing:

ant example-swing-appframework

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>
		org.metawidget.inspector.impl.actionstyle.swing.SwingAppFrameworkActionStyle
	</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 typing:

ant example-swing-animalraces

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.22. 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.setLayoutClass( MigLayout.class );
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>
			org.metawidget.inspector.impl.propertystyle.scala.ScalaPropertyStyle
		</propertyStyle>			
	</metawidgetAnnotationInspector>

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

val metawidget = new SwingMetawidget()
metawidget.setPropertyBindingClass( classOf[ BeanUtilsBinding ])
metawidget.setParameter( "propertyStyle", BeanUtilsBinding.PROPERTYSTYLE_SCALA )
metawidget.setToInspect( animal )

Most UI frameworks require widgets inherit one of their base classes, such as javax.swing.JComponent or javax.faces.UIComponent. As Java does not support multiple inheritance, this means there cannot be a common 'Metawidget base class' per se.

In addition, all Metawidgets support roughly the same functionality but 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 setLayout method. This means there cannot be a common 'Metawidget interface' either.

Therefore, Metawidgets are not required to extend any base class or implement any interface. However, they all 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 MetawidgetMixin class that implements the above steps 2-6 for you, see the section called “MetawidgetMixin”. 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 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 (LayoutRenderer classes for JSF) 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 setLayoutClass. Where possible, the layout classes defer back to the capabilities of the native framework. For example, Swing's GroupLayout 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) and these are passed from the Metawidget to the layout in a generic fashion. For example, JSF uses <f:param name="" value=""> tags, whereas SwingMetawidget has a setParameter(name, value) method.

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

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 Metawidget.

Unless explicitly specified, each Metawidget will instantiate a default WidgetBuilder to match the target platform. For example, SwingMetawidget will by default instantiate a 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 SwingWidgetBuilder is not. This is usually not what you want, because MyWidgetBuilder will be focussed on a particular third party library and will want to leave standard widgets to SwingWidgetBuilder.

To achieve this, use CompositeWidgetBuilder:

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

Or via metawidget.xml

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

All WidgetBuilders are required to be threadsafe and 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.

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 of the given type. Or it may ignore the toInspect and look up information on the given type from an XML file or a database schema.

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

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 MetawidgetAnnotationInspector and PropertyTypeInspector are not. This is usually not what you want, because MyInspector will be focussed on a particular type of metadata and will want to leave other metadata to other inspectors.

To achieve this, use CompositeInspector:

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

Or via metawidget.xml

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

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

The XML format can be used to 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 a 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/metawidget-1.0.xsd">

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

Within an object, the XML format can call setXXX methods. These are generally single-parameter, but multi-parameter methods are also supported. The following example calls the setOpaque and setParameter methods of SwingMetawidget. The latter 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/metawidget-1.0.xsd">

	<swingMetawidget xmlns="java:org.metawidget.swing">
		<opaque>
			<boolean>true</boolean>
		</opaque>
		<parameter>
			<string>numberOfColumns</string>
			<int>2</int>
		</parameter>		
	</swingMetawidget>
	
</metawidget>			

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

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

The XML format 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>
		<list>
			<metawidgetAnnotationInspector
				xmlns="java:org.metawidget.inspector.annotation" />
			<propertyTypeInspector
				xmlns="java:org.metawidget.inspector.propertytype"/>
		</list>
	</inspectors>
</compositeInspector>

Having constructed an immutable object, the XML format can reliably cache the instance and reuse it for future configurations.

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

myMetawidget.setActionBindingClass( myActionBinding.class );

Many Web applications store their data at the HttpServletRequest level, not at the HttpSession level. Using session-level state (or, ideally, a UI framework that supports some kind of 'conversation'-level state) is safer than passing variables to and from the client in hidden HTML fields. However, Web Metawidgets support that approach for those that need it through setCreateHiddenFields( true ).

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

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 7.2, “Rebinding”.

metawidget.setLayoutClass( TableLayout.class )

<generate-with
	class="org.metawidget.gwt.generator.propertybinding.simple.SimpleBindingAdapterGenerator">
	<when-type-assignable class="org.metawidget.example.shared.addressbook.model.Contact"/>
</generate-with>

metawidget.setPropertyBindingClass(SimpleBinding.class);
SimpleBindingAdapter<Contact> adp = (SimpleBindingAdapter<Contact>) GWT.create(Contact.class);
SimpleBinding.registerAdapter( Contact.class, adp );

myMetawidget.setActionBindingClass( myActionBinding.class );

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

myGWTMetawidget.setInspectorClass( MyClientSideInspector.class )

for( var property in myObject ) { alert( myObject[property] ); }

UIMetawidget is a Java Server Faces component. For an introduction to UIMetawidget, see the section called “Web Address Book” and the section called “Seam Example”.

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

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

public class MyDefaultedMetawidget extends HtmlMetawidget {
	...
	public MyDefaultedMetawidget() {
		getAttributes().put( "styleClass", "myStyleClass" );
		setValidatorClass( ... );
	}

	public void encodeBegin( FacesContext context )	{
		if ( FacesUtils.findParameterWithName( this, "tableStyleClass" ) == null ) {
			UIParameter parameter = new UIParameter();
			parameter.setName( "tableStyleClass" );
			parameter.setValue( "table-style" );
			getChildren().add( parameter );
		}
		
		super.encodeBegin( context );
	}
}

SpringMetawidget is a Spring taglib. For an introduction to SpringMetawidget, see the section called “Web Address Book”.

StrutsMetawidget is a Struts taglib. For an introduction to StrutsMetawidget, see the section called “Web Address Book”.

AndroidMetawidget is an Android widget. For an introduction to AndroidMetawidget, see the section called “Mobile Address Book”.

Mixins are a frequently used workaround for multiple inheritance in Java. Classes extend the mixin as an inner class and override its methods as needed.

All the built-in Metawidgets use MetawidgetMixin to ease their implementation. The mixin provides pre-built functionality such as deciding when to use single versus compound widgets, support for overriding widgets, incorporating stubs, and changing between read-only and active modes.

Android already defines a separation between Views and ViewGroups. org.metawidget.android.widget.layout.Layout and its subclasses automate the use of existing Android ViewGroups.

For frameworks based on JSF, org.metawidget.faces.component.UIMetawidget provides base widget functionality. See org.metawidget.faces.component.html.HtmlMetawidget for example usage.

JSF already defines a clean separation between widgets and their renderers. org.metawidget.faces.renderkit.LayoutRenderer and its subclasses leverage this to support different layouts.

For frameworks based on JSP, org.metawidget.jsp.tagext.MetawidgetTag and the more commonly used org.metawidget.jsp.tagext.html.BaseHtmlMetawidgetTag provide base taglib functionality. See StrutsMetawidgetTag for example usage.

MetawidgetTag also defines a clean separation between choosing widgets and laying them out. org.metawidget.jsp.tagext.Layout and its subclasses can perform the layout for all JSP-based frameworks.

Swing already defines a clean separation between widgets and layout managers. org.metawidget.swing.layout.Layout and its subclasses automate the use of existing Swing LayoutManagers.

SwingWidgetBuilder is the default WidgetBuilder for SwingMetawidget. It instantiates the following widgets for the following types of fields:

SwingXWidgetBuilder is a pluggable WidgetBuilder for the SwingX library. It is intended to be used in conjunction with the default SwingWidgetBuilder. It instantiates the following widgets for the following types of fields:

DisplayTagWidgetBuilder is a pluggable WidgetBuilder for the DisplayTag library. It is intended to be used in conjunction with the JSP HtmlWidgetBuilder, SpringWidgetBuilder or StrutsWidgetBuilder. It instantiates the following widgets for the following types of fields:

GwtWidgetBuilder is the default WidgetBuilder for GwtMetawidget. It instantiates the following widgets for the following types of fields:

HtmlWidgetBuilder is the default WidgetBuilder for the JSF HtmlMetawidget. It instantiates the following widgets for the following types of fields:

HtmlWidgetBuilder is the default WidgetBuilder for the JSP HtmlMetawidgetTag. Since JSP has only a light component model (ie. HTML tags such as <input> and <select> are just Strings, not modelled as JSP tags), HtmlWidgetBuilder simply returns String-based fragments of HTML. It returns the following fragments for the following types of fields:

RichFacesWidgetBuilder is a pluggable WidgetBuilder for the JSF UIMetawidget. It is intended to be used in conjunction with the default the JSF HtmlWidgetBuilder. For an example, see the section called “Alternate Widget Libraries”. RichFacesWidgetBuilder instantiates the following widgets for the following types of fields:

SpringWidgetBuilder is the default WidgetBuilder for SpringMetawidgetTag, albeit used in conjunction with the JSP HtmlWidgetBuilder. Like HtmlWidgetBuilder, it simply returns fragments of HTML. The JSP component model is too light to support returning tags containing child tags (ie. a SelectTag containing OptionTags). SpringWidgetBuilder returns the following widgets for the following types of fields:

StrutsWidgetBuilder is the default WidgetBuilder for StrutsMetawidgetTag, albeit used in conjunction with the JSP HtmlWidgetBuilder. Like HtmlWidgetBuilder, it simply returns fragments of HTML. The JSP component model is too light to support returning tags containing child tags (ie. a SelectTag containing OptionTags). StrutsWidgetBuilder returns the following widgets for the following types of fields:

AndroidWidgetBuilder is the default WidgetBuilder for AndroidMetawidget. It instantiates the following widgets for the following types of fields:

BaseObjectInspector underlies many of the Inspectors that inspect objects (as opposed to, say, config files). It supports pluggable PropertyStyles and ActionStyles.

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

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

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.

<metawidgetAnnotationInspector config="org.metawidget.inspector.impl.BaseObjectInspectorConfig">
	<actionStyle>
		org.metawidget.inspector.impl.actionstyle.swing.SwingAppFrameworkActionStyle
	</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:

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 the section called “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:

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>
		<list>
			<url>http://myserver.com/my-xml-1.xml</url>
			<url>http://myserver.com/my-xml-2.xml</url>
		</list>			
	</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.

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.