Friday, August 26, 2011

Metawidget 1.25 to 1.30 Migration Guide

The next release of Metawidget (v1.30) contains some breaking changes. We apologise for the disruption and provide this Migration Guide to help in moving from v1.25 to v1.30. All of the existing documentation and examples have already been migrated, as a reference point.

Refactored InspectionResultProcessor

Inspired by this forum post, a suggestion by Dan Allen, and Kirill's advice we have refactored InspectionResultProcessors to reduce internal complexity. By adding 3 extra parameters to their interface...

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

...we can use them to consolidate other mechanisms. Specifically, we can:

  • remove FacesXmlInspector and simplify FacesInspector, replacing them with a FacesInspectionResultProcessor

  • remove JexlInspector and JexlXmlInspector, replacing them with a JexlInspectionResultProcessor

  • simplify JspInspector, replacing it with a JspInspectionResultProcessor

  • reduce our dependency on ThreadLocals (which can be brittle)
FacesInspectionResultProcessor, JexlInspectionResultProcessor and JspInspectionResultProcessor combine and extend the previous functionality of their Inspectors. Specifically they can now:

  • Evaluate expressions from arbitrary attributes. There is no longer any need for UiFacesAttribute, UiJexlAttribute or UiJspAttribute. You can just use UiAttribute directly:
    @UiAttribute( name = LABEL, value = "#{person.readOnly ? 'Back' : 'Cancel'}" )

    Even better, you can use UiLabel directly:
    @UiLabel( "#{person.readOnly ? 'Back' : 'Cancel'}" )

  • Evaluate embedded expressions, such as:
    @UiSection( "#{}'s Details As At #{today}" )

Harmonized JSF EL

We took this opportunity to remove use of this in JSF EL expressions, in favour of _this. The former has been made a reserved word in EL 2.2 and beyond. You still declare injectThis in much the same way as before:

<facesInspectionResultProcessor xmlns="java:org.metawidget.inspectionresultprocessor.faces" config="FacesInspectionResultProcessorConfig">
   <injectThis><javaBeanPropertyStyle refId="myPropertyStyle" /></injectThis>

Improved Proxy Support

The rise of dependency injection frameworks has made it increasingly common that the object Metawidget is inspecting is, in fact, a proxy. This is troublesome because many proxied classes do not maintain annotation and/or generics information. We've refactored the way we deal with proxies to support this. Specifically:

  • We've enhanced BaseXmlInspectorConfig.setRestrictAgainstObject so that XML-based inspectors can align with Object-based inspectors in the face of proxies. However this is disabled by default so you may need to enable setRestrictAgainstObject if you are mixing XML and Object-based inspectors in your app.
  • The inspectors no longer try and determine whether a class is a proxy by pattern matching its class name. Instead, they traverse up the class hierarchy. The API names have changed slightly to reflect this.
Again, we apologise for the disruption but believe these changes will help make Metawidget cleaner and more robust than ever before.