No I'm not talking about Harry Potter and their ilk but one of JMatter's many features, that's right, wizards that let you configure your domain classes in an easy way. If you're into Java desktop programming you owe to yourself to take a look at what the framework has to offer (hint: check the latest article by Eitan). Alright on with the topic, before the feature I'm about to introduce, the way to code wizards was pretty straight forward but as your domain class grew so did your wizard code, and it lend itself to repetition, as we are against DRY, DomainWizard was born.

This little guy will let you build a wizard in a breeze and at the same time opens the door for customization without changing a line of code. All of the labels and descriptions are pulled from the domain class metadata and a resource file, simple, easy, agile!. Let's see an example with a before/after approach, this is what a normal wizard used to look:
package com.u2d.contactmgr; import com.u2d.wizard.details.*; import com.u2d.type.composite.*; import com.u2d.model.ComplexType; import com.u2d.view.swing.FormView; import javax.swing.*; public class NewPersonWizard extends CompositeStep { private Name _name; private USAddress _address; private Contact _contact; public NewPersonWizard() { super("New Person Wizard"); createObjects(); setupSteps(); } private void createObjects() { _name = (Name) ComplexType.forClass(Name.class).instance(); _address = (USAddress) ComplexType.forClass(USAddress.class).instance(); _contact = (Contact) ComplexType.forClass(Contact.class).instance(); } private void setupSteps() { NameStep nameStep = new NameStep(); AddressStep addrStep = new AddressStep(); ContactStep contactStep = new ContactStep(); addStep(nameStep); addStep(addrStep); addStep(contactStep); ready(); } // ==================================================================== class NameStep extends BasicStep { public String title() { return "Name Information"; } public String description() { return "Enter Person's Name"; } public JComponent getView() { return new FormView(_name); } } class AddressStep extends BasicStep { public String title() { return "Address Information"; } public String description() { return "Enter Person's Physical Address"; } public JComponent getView() { return new FormView(_address); } } class ContactStep extends CommitStep { public String title() { return "Person's Contact Information"; } public String description() { return "Please specify person's contact information"; } public JComponent getView() { return new FormView(_contact); } public void commit() { PersonContact pc = new PersonContact(); pc.getName().setValue(_name); pc.getContact().setValue(_contact); pc.getContact().getAddress().setValue(_address); pc.save(); } } }
Direct to the point but notice that each composite attribute requires similar setup, surely we can do better than that, let's see DomainWizard (the after way)
DomainWizard wizard = new DomainWizard(PersonContact.class, new String[][]{{"name"},{"contact.address"},{"contact"}}); wizard.setLastPropertyCommits( true ); wizard.ready(); // last step, wrap it with a real Wizard new Wizard( wizard ); // in a properties file, usually model-metadata.properties Wizard.finish-step.title = Finish Wizard.finish-step.description = Finish Wizard.finish-step.content = Click 'Finish' to end the wizard Wizard.com.u2d.contactmgr.PersonContact.title = New Person Wizard Wizard.com.u2d.contactmgr.PersonContact.name.title = Name Information Wizard.com.u2d.contactmgr.PersonContact.name.description = Enter Person's Name Wizard.com.u2d.contactmgr.PersonContact.contact.title = Person's Contact Information Wizard.com.u2d.contactmgr.PersonContact.contact.description = Please specify person's contact information Wizard.com.u2d.contactmgr.PersonContact.contact.address.title = Address Information Wizard.com.u2d.contactmgr.PersonContact.contact.address.description = Enter Person's Physical Address
Notice it only takes 6 lines in average to do the same (albeit some lines in a properties file too). Notice also that the keys in the properties file follow a naming convention, which will help you configure properties with the same name belonging to different classes.

JMatter's wizards are a little bit more sophisticated that what we have seen so far, DomainWizard is only useful for building domain classes following the same recipe. But what if you require a different set of steps or perhaps conditional steps? JMatter provides those steps already but Groovy can help make the job easier don't you think? thanks to the power of builders we now have WizardBuilder. Let's see how the previous code looks with WizardBuilder in place
package com.u2d.contactmgr import com.u2d.type.composite.* import com.u2d.model.* import com.u2d.view.swing.FormView import com.u2d.wizard.builder.* import com.u2d.wizard.details.Wizard class PersonWizardBuilder{ static Wizard wizard(){ def _name = ComplexType.forClass(Name).instance() def _address = ComplexType.forClass(USAddress).instance() def _contact = ComplexType.forClass(Contact).instance() new WizardBuilder().wizard( "New Person Wizard" ){ step( title: "Name Information", description: "Enter Person's Name" ){ new FormView(_name) } step( title: "Address Information", description: "Enter Person's Physical Address" ){ new FormView(_address) } step( title: "Person's Contact Information", commit: true, description: "Please specify person's contact information" ){ view { new FormView(_contact) } doCommit{ PersonContact pc = new PersonContact() pc.name.setValue(_name) pc.contact.setValue(_contact) pc.contact.address.setValue(_address) pc.save() } } } } }
Just to show how conditional steps are declared let's pretend that the first two steps should belong to a group and if those steps are fulfilled then we can proceed to the last:
package com.u2d.contactmgr import com.u2d.type.composite.* import com.u2d.model.* import com.u2d.view.swing.FormView import com.u2d.wizard.details.Wizard import com.u2d.type.atom.* import com.u2d.wizard.* import groovy.swing.* class NewPersonWizard{ static Wizard wizard(){ def _name = ComplexType.forClass(Name).instance() def _address = ComplexType.forClass(USAddress).instance() def _contact = ComplexType.forClass(Contact).instance() new WizardBuilder().wizard( "New Person Wizard" ){ conditionalStep(){ step( title: "Name Information", description: "Enter Person's Name" ){ new FormView(_name) } step( title: "Address Information", description: "Enter Person's Physical Address" ){ new FormView(_address) } } step( title: "Person's Contact Information", commit: true, description: "Please specify person's contact information" ){ view { new FormView(_contact) } doCommit { PersonContact pc = new PersonContact() pc.name.setValue(_name) pc.contact.setValue(_contact) pc.contact.address.setValue(_address) pc.save() } } } } }
There are more ways to configure steps, specially the commit one, but that info belongs in the JMatter manual (note to self, get back to writing that stuff ASAP). You will find these and other exciting features at current SVN head, Eitan has been busy the last weeks but expect a new release in the following weeks (hopefully days ). Oh and by the way, there is a really sweet surprise that Eitan managed to squeeze in, let's just say for now that it will surely put JMatter "on the map"