Konstantin's Blog

Announcing Sapphire 0.4 Release

2011-12-01T06:53:00.001-08:00

It is with great pleasure that I announce availability of Sapphire 0.4 release. This release includes major enhancements, such as API improvements in services and XML binding, more powerful Sapphire EL and ability to use it in more places, content proposals in text fields, split form, regular multi-section form editor page for cases where master-details presentation isn't appropriate, and much more.

Enhancements
Migration Guide
Developer Guide
Downloads

Java Language Puzzle 3

2011-11-19T17:38:00.001-08:00

Given the following source listing, explain why the compiler is producing a warning at invocation to the list method and give a solution for removing the warning without resorting to @SuppressWarnings annotation.

public class JavaLanguagePuzzle3
{
    public static void main( String[] args )
    {
        list( "1", 2, new BigDecimal( "3.5" ) );
    }
    
    private static <T> List<T> list( T... items )
    {
        return Arrays.asList( items );
    }
}

Warning:

Type safety: A generic array of Object&Serializable&Comparable<?> is created for a varargs parameter

Announcing Sapphire 0.3.1 Release

2011-10-07T21:21:00.001-07:00

It is with great pleasure that I announce availability of Sapphire 0.3.1 release. This maintenance release includes 64 bug fixes and enhancements. Adopters of 0.3 release can expect full backwards compatibility. No migration guide is being published.

Enhancements
Developer Guide
Downloads

Using Sapphire to Work with Java Types

2011-08-24T22:41:00.001-07:00

This article covers an intermediate topic related to Sapphire. Those unfamiliar with Sapphire should first read the introduction.

When implementing Eclipse tooling that works with Java projects, a frequent requirement is to deliver models and UI that reference Java types (classes, interfaces, enumerations and annotations). Implementing this from scratch, even using the excellent API provided by JDT is a challenge. Fortunately, Sapphire's JDT integration makes this quite easy.

The first step is the model.

@Type( base = JavaTypeName.class )
@Reference( target = JavaType.class )
@Label( standard = "filter" )
@JavaTypeConstraint( kind = { JavaTypeKind.CLASS, JavaTypeKind.INTERFACE }, type = "java.io.FileFilter" )
@MustExist
@Required

ValueProperty PROP_FILTER = new ValueProperty( TYPE, "Filter" );

ReferenceValue<JavaTypeName,JavaType> getFilter();
void setFilter( String value );
void setFilter( JavaTypeName value );

Here we utilize reference value construct which states that the property holds a JavaTypeName which is resolvable to a JavaType. The resolution is provided by the framework and works as long as the model is loaded in the context of a Java project.

The @JavaTypeConstraint annotation specifies that the referenced type must be a class or an interface and that it must derive from java.io.FileFilter type.

The @MustExist annotation specifies that the named type must be present in the project.

The @Required annotation specifies that the property must have a value (null is not ok).

The next step is the UI definition. Here we create an editor section with a single property editor, but the property editor is, of course, not limited to editor sections. It can be used in any form context.

<section>
    <content>
        <property-editor>Filter</property-editor>
    </content>
</section>

That is all that is necessary to define a model property that references a Java type and to present that property in the UI. Once this example is executed, you will see a property editor that is composed of a label, a text box, two action buttons and a validation feedback marker.

Clicking on the validation feedback marker shows the problem message along with wealth of semantic information about the property.

The browse button provides the means to select from among existing Java types using JDT's type selection dialog. The framework automatically constraints the contents of the dialog based on @JavaTypeConstraint annotation.

The create button provides the means to define a new Java type if the specified type name cannot be resolved.

Since @JavaTypeConstraint annotation in this example specifies that the property can reference either a class or an interface, the user is presented with a choice after clicking on the create button.

Once the appropriate option is selected, the new type is created and opened in the Java editor. The created type derives from the type specified in @JavaTypeConstraint annotation and is formatted according to user's format preferences.

Note that this article covers features in 0.3.1 and 0.4 releases of Sapphire, which at the time of this writing are still in development. A subset of the described features is available in version 0.3, which is the latest released version. Please direct all questions to the forum.

From XML to Form to Diagram with Sapphire

2011-08-01T18:18:00.001-07:00

Many of the systems that developers and administrators interact with on the daily basis are configured via a menagerie of XML files. Even armed with a schema and a good XML editor, users have a hard time editing these files by hand. A good tooling strategy to address this difficulty is to create a multi-page editor where a user can flip back-n-forth between XML source view and a higher level form-based view. Going a notch further, certain relationships can be presented with one or more diagrams on separate pages.

Unfortunately, building such multi-page editor using basic Eclipse platform facilities is a daunting challenge. It can take many months to create something half-decent for even smaller schemas. Sapphire can make this a much less daunting task by focusing developer attention on modeling semantics of the data rather than wiring individual widgets.

I have proposed a talk for EclipseCon Europe 2011 to present Sapphire as a whole and the new diagram editing features in Sapphire 0.3 (Indigo) release. You can comment and vote on the proposal if you are interested.

Proposed Talk: From XML to Form to Diagram with Sapphire

Sapphire is a relatively new project at Eclipse started with an initial contribution from Oracle. It is a UI building framework that allows developers to specify UI in terms of higher level constructs like property editors instead of widgets and layouts. This paradigm results in several orders of magnitude improvement in developer productivity while simultaneously delivering better quality UI that is easier to maintain.

Sapphire 0.4 : FactsService

2011-07-01T15:23:00.001-07:00

This is the first in what I hope to be a series of blog posts highlighting new features in the upcoming Sapphire 0.4 release.

When a property is described to a user in documentation one does it with a series of short statements that define its semantics, such as "must be specified" or "maximum value is 100". When a property is described to Sapphire one does it with a series of annotations, such as @Required or @NumericRange. This duplicate specification is a maintenance problem.

A FactsService provides a means to dynamically derive statements about property's semantics based on property's metadata. The derived facts can then be presented to the user as part of documentation, property editor information popup and in other relevant places.

A single facts service can produce multiple facts and multiple facts services can be active concurrently for a given property. FactsAggregationServices provides an easier way to consume all facts.

Sapphire includes a number of FactsService implementations.

ID	Description
Sapphire.FactsService.JavaTypeConstraint	Creates fact statements about Java type property's constraints by using semantical information specified by @JavaTypeConstraints annotation.
Sapphire.FactsService.Static	Creates fact statements about property by using static content specified in @Fact and @Facts annotations.
Sapphire.FactsService.DefaultValue	Creates fact statements about property's default value by using semantical information specified by DefaultValueService and @DefaultValue annotation.
Sapphire.FactsService.NumericRange	Creates fact statements about numeric value property's range by using semantical information specified by @NumericRange annotation.
Sapphire.FactsService.Required	Creates fact statements about property's optionality by using semantical information specified by @Required annotation.
Sapphire.FactsService.ReadOnly	Creates fact statements about property's read-only state by using semantical information specified by @ReadOnly annotation.
Sapphire.FactsService.CountConstraint	Creates fact statements about list property's count constraint by using semantical information specified by @CountConstraint annotation.
Sapphire.FactsService.AbsolutePath	Creates fact statements about property's absolute path requirement by using semantical information specified by @AbsolutePath annotation.
Sapphire.FactsService.MustExist	Creates fact statements about existence requirement on the entity referenced by property's value by using semantical information specified by @MustExist annotation.
Sapphire.FactsService.NoDuplicates	Creates fact statements about value property's uniqueness constraint by using semantical information specified by @NoDuplicates annotation.
Sapphire.FactsService.ValidFileExtensions	Creates fact statements about valid file extensions for property's value by using semantical information specified by @ValidFileExtensions annotation.
Sapphire.FactsService.ValidFileSystemResourceType	Creates fact statements about valid file system resource type (file or folder) for property's value by using semantical information specified by @ValidFileSystemResourceType annotation.
Sapphire.FactsService.ProjectRelativePath	Creates fact statements about property's relative to the project path requirement by using semantical information specified by @ProjectRelativePath annotation.
Sapphire.FactsService.WorkspaceRelativePath	Creates fact statements about property's relative to the workspace path requirement by using semantical information specified by @WorkspaceRelativePath annotation.

Example

This screen capture shows user experience with some of the provided FactsService implementation. See if you can match facts in the screen capture to service implementations above.

Adopters can provide custom FactService implementations either globally using Sapphire extension system or at the property level using @Service annotation.

Example

A simple global FactsService implementation that is triggered by a hypothetical @Since property annotation.

public class SinceVersionFactsService extends FactsService
{
    @Override
    protected void facts( List facts )
    {
        Since since = property().getAnnotation( Since.class );
        facts.add( "Since version " + since.version() + "." );
    }

    public static class Factory extends ModelPropertyServiceFactory
    {
        @Override
        public boolean applicable( IModelElement element,
                                   ModelProperty property,
                                   Class<? extends ModelPropertyService> service )
        {
            return property.hasAnnotation( Since.class );
        }
    
        @Override
        public ModelPropertyService create( IModelElement element,
                                            ModelProperty property,
                                            Class<? extends ModelPropertyService> service )
        {
            return new SinceVersionFactsService();
        }
    }
}

The service implementation is registered in META-INF/sapphire-extension.xml file.

<extension xmlns="http://www.eclipse.org/sapphire/xmlns/extension">
    <model-property-service>
        <id>Example.SinceVersionFactsService</id>
        <type>org.eclipse.sapphire.services.FactsService</type>
        <factory>example.SinceVersionFactsService$Factory</factory>
    </model-property-service>
</extension>

Facts can also be statically specified for a given property by using @Fact annotation. Use @Facts annotation to specify multiple facts. The facts contained in these annotations are surfaced by an included FactsService implementation (id:Sapphire.FactsService.Static).

Example

// *** ExampleOne ***
    
@Fact( statement = "Important fact.")
    
ValueProperty PROP_EXAMPLE_ONE = new ValueProperty( TYPE, "ExampleOne" );
    
Value getExampleOne();
void setExampleOne( String value );

// *** ExampleMultiple ***
    
@Facts( { @Fact( statement = "First important fact." ), @Fact( statement = "Second important fact." ) } )
    
ValueProperty PROP_EXAMPLE_MULTIPLE = new ValueProperty( TYPE, "ExampleMultiple" );
    
Value getExampleMultiple();
void setExampleMultiple( String value );

Please direct your comments and questions to Sapphire adopter forum.

Java Language Puzzle 2

2011-06-27T11:28:00.001-07:00

Given the following source listing, explain why InstantiationException is thrown when running (via the main method entry point) and how the code should be fixed.

package puzzle;

public class Entity
{
    private Entity()
    {
    }
    
    public class Factory
    {
        public Entity create()
        {
            return new Entity();
        }
    }
    
    public static void main( String[] args ) throws Exception
    {
        Factory.class.newInstance();
    }
}

Exception in thread "main" java.lang.InstantiationException: puzzle.Entity$Factory
	at java.lang.Class.newInstance0(Unknown Source)
	at java.lang.Class.newInstance(Unknown Source)
	at puzzle.Entity.main(Entity.java:19)

ANSWER: It looks like everyone who responded correctly identified the fact that Factory class is not defined as static as the cause of this exception. The solution is to add the static keyword. I would imagine that vast majority of Java developers are pretty comfortable with static/non-static inner classes semantics. What raises this to a puzzle level is a rather unhelpful exception.

Announcing Sapphire 0.3 Release

2011-06-22T15:56:00.001-07:00

It is with great pleasure that I announce on-time availability of Sapphire 0.3 release. This release includes numerous enhancements, some of which I will briefly describe. Current users of 0.2.x line will want to consult the migration guide.

Before we get to the new features, it is important to take a few minutes to thank all the people who made this release possible. Shenxue Zhou is a new committer on the project and has been working hard to bring us diagram editing support. A key new features in this release. The community around Sapphire has grown substantially in the last few months. Many of the enhancements that you will find in this release are based on ideas and requirements brought by the new adopters. All of the adopters deserve a thank you, but I will call out one by name. Greg Amerson (Liferay) has progressed very quickly from an adopter to a contributors. Five patches from Greg are in the 0.3 release. Greg has the distinction of being the first non-Oracle contributor to Sapphire. Last but not least, several members of Oracle QA has pitched in to verify enhancements and fixed bugs.

Without further ado, I present the enhancements in the 0.3 release…

Diagram Editing – Define diagram UI just as easily as a form. Sapphire declarative UI language has been expanded to cover basic diagram concepts. This feature opens the door for very sophisticated editors that provide diagram, form and source views on the same data. Yet, no matter how many diagram, form and source views on the data you define, Sapphire keeps everything in sync with n-way synchronization.

Properties View Integration – Easily attach properties view content to diagram nodes, connections, form outline nodes, etc. using the same UI definition facilities as the editor. Sapphire will automatically inject that content into the standard Eclipse properties view when that part has selection.

UI Definition Editor – Spend less time trying to get sdef syntax right with the new form-based editor for Sapphire UI Definition files. The editor is, of course, itself built using Sapphire.

Expression Language Enhancements – Use EL in more areas of model and UI specification than before. The EL itself is now even more powerful with better handling of collections and support for custom type casts among other features.

Modularity Improvements – Use Sapphire in more scenarios than before. The core modeling framework now only requires Java. Add integration with OSGi, Eclipse platform resources, JDT, etc. by installing separate modules.

Miscellaneous Enhancements – Embed snippets of HTML into a form, show related content next to a property editor, choose from three layouts for a checkbox, specify editor header image, define collapsible sections, the list goes on. Head over to the enhancements guide for all the details.

Of course, no release of a UI framework would be complete without screen captures. Here are a few to wet your appetite…

Enhancements
Migration Guide
Developer Guide
Downloads

Concurrently with 0.3, we are also shipping 0.2.3 release to bring support for Indigo to adopters who still rely on the 0.2.x line.

Java EE Module Configuration Editors Draft Proposal

2011-06-17T12:11:00.001-07:00

I am working on a proposal for Java EE Module Configuration Editors project. The goal is to create a new project under WTP Java EE Tools project and build there editors for web.xml, application.xml, ejb-jar.xml and possibly all the rest of the module configuration files. The editors would be built using Sapphire and work across various versions of Java EE spec. For Java EE 5 or newer, the editors would be able to also edit Java annotations instead of the XML configuration file from the same interface.

Draft Proposal

While I am working on the getting the new project created to hold this work, I’ve started implementing the web.xml editor in Sapphire repository as a sample. You can get a feel for what’s there now and what the final result will look like in the screencast that I put together.

Screencast

To take the editor for a spin yourself, install everything from the following repository. Don't try to go to a newer build as this plugin has been removed from the Sapphire build in preparation for the 0.3 release.

https://hudson.eclipse.org/hudson/job/sapphire-0.3.x/408/artifact/build/repository/

To access the source code, point your Eclipse at the following location in CVS. Note that you will need WTP + Sapphire in your target platform and Sapphire SDK in your dev eclipse. The latter part is very important as the Sapphire SDK contains the code generate necessary to build this plugin.

Source Code

If you are interested in this work, leave a comment with your name on this blog post or send a note to wtp-dev mailing list so that I can add you to the list of interested parties in the project proposal. If you are interested in helping to implement these editors, state as much as well and we will discuss.

State of Sapphire for Spring 2011

2011-03-18T17:15:00.001-07:00

It has been a busy five months for the Sapphire team since the project was created in October of 2010. The initial code contribution from Oracle has gone through the Eclipse Foundation’s IP review, we have source in CVS, bugs in Bugzilla and builds running on every commit. Even though the current project team is only staffed by Oracle employees, we make it a point to communicate in the open on the adopter forum and the developer mailing list.

Releases

Two feature releases and two service releases shipped so far.

Version 0.1

The initial stable code contribution from Oracle, but refactored for eclipse.org namespace, build and legal requirements.

Version 0.1.1

Some infrastructure work was still ongoing when 0.1 shipped. Version 0.1.1 delivered the binaries in signed form.

Version 0.2

Major enhancements, such as a powerful resource abstraction for models, expression language, transient properties, derived properties, new property editors and many more. Despite shipping concurrently with the 0.1 release, version 0.2 represents roughly six months of new feature work that was happening as we were waiting on the project creation process.

Version 0.2.1

No major release can happen without at least a few bugs getting through.

Adoption

You might ask… This technology does look promising, but how do I really know if it is ready for production?

Sapphire may be young at Eclipse, but it has been in development since at least 2007 as part of BEA’s and later Oracle’s Eclipse tooling efforts. Oracle Enterprise Pack for Eclipse (OEPE) heavily leverages Sapphire to create a variety of form based user interfaces across the product. During the transition to Eclipse, we worked quickly to close the feedback loop between the new Sapphire project and its big adopter. To that end, OEPE 11.1.1.7 shipped with Sapphire 0.1.1 and upcoming OEPE 11.1.1.7.1 will ship with Sapphire 0.2.1 release. The tight feedback loop from OEPE has enabled us to quickly stabilize the major new features delivered in the 0.2 release.

We are also getting ready to announce a major new endeavor to, in part, promote adoption of Sapphire across Eclipse. In the next few weeks, we will formally propose a project under WTP to use Sapphire to create editors for standard Java EE deployment descriptors.

Little Miss Sapphire

On February 8th, Sapphire family grew by one with the birth of Little Miss Sapphire or Amelia as she is known when she is not voicing opinions on architectural issues.

I am still mastering the art of typing with one hand. My Das Keyboard doesn’t make this easy, but I like a good challenge.

Release 0.3 and Indigo

The next major Sapphire release is scheduled to go out concurrently with Indigo in June of 2011. We are pushing improvements on two fronts.

First, we are adding support for creating diagram editors, defined and wired to the model in a similar way that forms are today. The current diagram parts renderer uses Graphiti, but the application developer will not interact with Graphiti directly, allowing renderer implementation to be changed or swapped out in the future.

By the time 0.3 ships, you will be able to create slick three-page editors showing source, form and diagram views on the same data. Bi-directional editing is so yesterday. Welcome to tri-directional editing!

Second, we are making a major push on improving the facilities provided by the SDK to make developing with Sapphire even easier. The big new feature is an editor for Sapphire UI definitions (aka sdef files). All the content assist and validation isn’t finished yet, but the editor is already much better than editing XML markup by hand. The editor is, naturally, built using Sapphire. Yesterday, I spent a good portion of the day using the sdef editor from a previous build to work on new editor features for the next build. Extreme dogfooding!

Shenxue Zhou Becomes a Committer

Shenxue has been involved with Sapphire as a consumer for a long time, but over the last several months, she has progressed to contributor status with her work on the diagram editing support. After a number of high quality patches, we welcomed Shenxue as the first elected committer on the project.

EclipseCon 2011

I am going to be giving a 20 minute talk on Sapphire at this year’s EclipseCon. No slides to bore you with. Just a live demo of building a project using Sapphire. If you are at all interested in this technology, come see the demo. It should be entertaining (one way or another).

If you cannot make it to the talk, I will be at the conference all four days, so flag me down between sessions or at the bar. Another Sapphire committer, Ling Hao, will also be attending EclipseCon this year.

Announcing Sapphire logo

2011-02-22T11:49:00.001-08:00

Every noteworthy project requires a cool logo, so I am very pleased to announce that Sapphire now joins that distinguished circle with a brand new logo. The new logo is a contribution of Jean Yao, a talented graphics designer at Oracle. I think you will agree that she has done a great job.

The new logo is already featured on the project home page and you can also spot it in recent 0.2.1 and 0.3.0 builds.

Java Language Puzzle 1

2010-09-14T17:35:00.001-07:00

From the domain of stuff that makes you wonder if your debugger is lying to you, I give you a little puzzle. How many times does the following code print the line “Creating crumble…” and why?

public class JavaLanguagePuzzle1
{
    private static abstract class CookieBase
    {
        public CookieBase()
        {
            init();
        }
        
        protected void init() {}
    }
    
    private static class Cookie extends CookieBase
    {
        private Crumble crumble = null;

        protected void init()
        {
            crumble();
        }
        
        public Crumble crumble()
        {
            if( this.crumble == null )
            {
                this.crumble = new Crumble();
            }
            
            return crumble;
        }
    }
    
    private static class Crumble
    {
        public Crumble()
        {
            System.err.println( "Creating crumble..." );
        }
    }
    
    public static void main( final String[] args )
    {
        ( new Cookie() ).crumble();
    }
}

SOLUTION: Pretty much everyone who responded came up with the correct answer of two times. Most correctly explained why that happens. Part of the reason is that explicit member variable initialization in a class happens after the superclass constructor has executed. The part that might be tricky to realize is that explicitly initializing a member variable to null does not have the same runtime behavior as leaving it uninitialized. Removing explicit initialization of crumble to null makes this code behave as it appears to on the surface.

Inconvenient process? Let’s fix it.

2010-08-26T18:57:00.001-07:00

Some of you may have noticed the debate happening regarding proper entry expectations for WTP incubator project following Holger’s veto of a committer election. Holger is acting well within the power granted to him by Eclipse Development Process (EDP), but is it a right and proper action?

Every committer on a project has the veto power in an election. By extension, any entry criteria for a project (whether written or unwritten) is nothing more than a social convention. The reality is that every committer can choose to levy their own personal expectations. Most of the time it’s not a problem, except when it is.

Here are some quotes from this particular event:

“I found only some bug reports but not a single code contribution from any of the four nominated persons. Please attach the planned code contribution to a bug report. I'd like to vote for each of the nominated persons as soon as I know that the code is readable and covered by JUnit tests.”

“Have [snip] been asked if they like to become committers as individuals (and not only as employees of SAP)? Are these authors of the code or what is their motivation to maintain and enhance these editors?”

In a regular project with established code base, established team and well-defined scope, you can argue that giving every committer veto power over elections is appropriate. After all, there is an established code base to protect. The same considerations do not apply when a new component is proposed in an incubator.

The WTP incubator project was started with the intention to provide a low entry barrier playground for people to come and experiment on new ideas while gaining experience and proving their merit to committers on the core projects that will eventually be asked to admit matured functions. Incubators make sense because they provide a quicker way to get started than a separate project proposal. Unfortunately incubators have to rely on a social convention that existing committers act in a welcoming fashion to newcomers. Most of the time that happens, except when it doesn’t.

I would posit that there is no legitimate purpose served by holding a committer election when a new component is proposed for an incubator. The situation is supposed to be very similar to new project creation and we don’t hold elections there. The party proposing a project gets to designate a group of individuals to be the initial committers without anyone questioning their credentials or motives. A similar process is needed to make incubators work better.

The last revision of EDP has formalized the concept of a persistent incubator. I propose that we build on those revisions and amend EDP to remove the committer vote requirement for incubator projects when a new component is being proposed. The project’s PMC would still have the oversight and ability to decline a new component proposal. This change would also fix the rather awkward problem of having to have “seeder” committers when creating incubator projects.

Note that my suggestion is for persistent incubator projects rather than normal projects during incubation phase. I am also not suggesting that we remove committer vote entirely from incubators. Anyone wishing to join existing effort already underway in the incubator should still be subject to committer vote.

Thoughts?

PS.1 : This situation has served to highlight a process problem and it is the process that I seek to improve. I have no beef with Holger. I am sure he is acting on what he believes in.

PS.2 : I am further confident that this particular storm will blow over, Holger’s objections will be met, another election held, etc. That doesn’t mean we shouldn’t try to improve the process so that such situations do not happen again and we continue to have vibrant incubator projects at Eclipse.

Update: At Wayne’s request I created a bug to track this proposed improvement to Eclipse Development Process.

Oracle JVM 6u21 and Eclipse

2010-07-14T08:54:00.001-07:00

A number of users have encountered frequent Eclipse crashes since the recent Oracle JVM 6u21 update. The crash cause is listed as follows:

java.lang.OutOfMemoryError: PermGen space

The underlying problem if that in 6u21 (version 1.6.0_21), the vendor was changed from Sun to Oracle. Eclipse launcher reads the JVM vendor and if it detects a Sun JVM, it adds an extra –XX:MaxPermSize setting that is necessary for Eclipse to function. With the vendor change in 6u21, the launcher is no longer adding the necessary parameter on launch.

There is an Eclipse Platform bug open, but so far it doesn't look like there is going to be an attempt to resolve this until Helios SR1 scheduled for September.

https://bugs.eclipse.org/bugs/show_bug.cgi?id=319514

Fortunately, there is an easy workaround. Open the eclipse.ini file in an editor. You will see something similar to this:

-startup
plugins/org.eclipse.equinox.launcher_1.1.0.v20100307.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.1.0.v20100307
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
--launcher.defaultAction
openFile
-vmargs
-Xms40m
-Xmx384m

This is setting that's not having any effect after 6u21:

--launcher.XXMaxPermSize
256m

Remove it. In it's place, add -XX:MaxPermSize=256m on a new line after the -Xmx setting. Better yet, while you are in there, bump the memory limits to a higher value. Nothing ruins your train of thought better than your IDE crashing with an OutOfMemoryError. Here is a sample eclipse.ini that works on 6u21.

-startup
plugins/org.eclipse.equinox.launcher_1.1.0.v20100507.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.1.0.v20100503
-showsplash
org.eclipse.platform
--launcher.defaultAction
openFile
-vmargs
-Xms40m
-Xmx1024m
-XX:MaxPermSize=512m

IMPORTANT: I do work for Oracle, but this is not an official Oracle statement on this issue. Just some advice from one Eclipse developer to another.

Update: This problem is specific to Windows. On *nix variants, Eclipse launcher uses slower, but more robust logic for detecting JVM type. More information in Bug 320005 for those who are interested.

Update: Oracle has produced another build of 6u21 JVM that reverts the change that adversely affected Eclipse. If you have reverted back to an older JVM, you can safely move forward to 6u21. The build 1.6.0_21-b07 is safe to use. The version that Eclipse has trouble with is b06. You can check which version you have by running "java -version". More information in Sun Bug 6969236 for those who are interested.

Sapphire – Focus on Localization

2010-07-08T14:13:00.001-07:00

If you have missed the introduction to Sapphire, make sure to read it first… Introduction to Sapphire

Localization is like build systems, something that most developers prefer not to think about. Unfortunately, the developer must take explicit steps to manually externalize all user-visible strings for the software to be localizable. The localizable strings go into a separate file and the code references them by a key. The developer must come up with a key and then must manage the list of externalized strings so that it stays in sync with the code. Some tools have been developed to make this a little easier, but two types of problems remain very common:

Strings that should be externalized are not. It’s too easy for the developer to put the string directly into code and then forget to externalize it later.
The string resource files get out of sync with code. The case where the resource file is missing a string is easy enough to catch at runtime. The case where resource files contain orphaned strings not referenced in code is much harder to detect.

Since Sapphire is a UI framework, localization is very important. Since Sapphire is focused on ease of use and developer productivity, relying on current methods of localization is not satisfactory.

Localizable strings largely occur in two places in Sapphire. You see them in the model annotations (such as the @Label annotation) and you see them throughout the UI definition files. Sapphire’s approach is to allow the developer to leave the strings in their original language at point of use. The string resource files that will be translated are created at build time. The build system takes the original string and applies a function to it to generate a key for the string resources file. The same function is applied at runtime to derive the key to lookup the translated string.

The critical concept is that the developer does not take any explicit steps to enable localization. It just happens under the covers.

The nature of the function that is used to derive the string resources file key is not particularly important as long as the resulting key is not overly long and is reasonably free from collisions. The current implementation takes the original string, chops it off at 20 characters and replaces some characters that are illegal in a property file key with an underscore. Decent approach for the first cut, but we will likely replace it with an md5 hash in the first version of Sapphire to ship at Eclipse Foundation.

On top of the automatic externalization, Sapphire is architected to minimize the number of strings that must be externalized in the first place. In particular, when the developer specifies a property label, the string is expected to be all in lower case (except where acronyms or proper nouns are used). Sapphire is able to transform the capitalization of the label to make it suitable for different contexts. Three modes of capitalization are supported:

NO_CAPS: Basically the original string as specified by developer. This is most frequently used for embedding inside validation messages.
FIRST_WORD_ONLY: This is your typical label in the UI. The colon is added by the UI renderer where appropriate.
TITLE_STYLE: This is typically used in column headers, section headers, dialog titles, etc.

The current capitalization algorithm works well for English and reasonably well for other languages, but it will need to be made pluggable in the future.

Extension system when you cannot depend on OSGi?

2010-06-30T14:32:00.001-07:00

I've been developing with OSGi for so long that sometimes I forget that not everyone in the Java world can take advantage of all the benefits offerred by it. Recently I have been contemplating the approaches to framework extensibility when you cannot depend on OSGi. Note that I am not looking for other solutions to modularity. I am looking for an extension contribution system that is not specific to OSGi. We'd like to support Sapphire in all Java UI contexts and extensibility for implementing new UI parts, renderers, etc. is key.

Before I start re-inventing the wheel... Have others faced similar requirements? If so, what was the approach that you chose?

Sapphire - Focus on Browsing

2010-06-29T12:15:00.001-07:00

If you have missed the introduction to Sapphire, make sure to read it first... Introduction to Sapphire

One of the most enduring UI patterns is a browse button next to the text box for selecting among possible values. Very frequently the scenario is to browse for files or folders, but the pattern is more generic than that and has been used to browse for arbitrary items especially when the set of possible values can be large.

In Sapphire, developers are not creating and wiring up individual UI widgets. This makes it possible to implement the browse button pattern at a higher level of abstraction. If a browse handler is active for a property, a browse button will be automatically created. The framework will even register a keyboard shortcut (Ctrl+L, 'L' is for locate) which can be used to open the browse dialog while focus is on the text field.

Sapphire uses image-based buttons for compactness and to create a more modern look-n-feel. In the following screen capture you can see how the browse buttons appear to the user. Note a tiny browse image in the table cell editor. That's a browse button too.

File System Paths

Sapphire provides a set of annotations that make it easier to deal with file system paths. The developer uses these annotations to specify the semantics of the property and Sapphire automatically adds validation and browsing support.

Consider the case where a property must hold an absolute path to a file that must exist and must have "jar" or "zip" extension. Such a property could be declared as follows:

@Type( base = IPath.class )
@AbsolutePath
@ValidFileSystemResourceType( FileSystemResourceType.FILE )
@ValidFileExtensions( { "jar", "zip" } )
@MustExist
    
ValueProperty PROP_ABSOLUTE_FILE_PATH = new ValueProperty( TYPE, "AbsoluteFilePath" );
    
Value<IPath> getAbsoluteFilePath();
void setAbsoluteFilePath( String value );
void setAbsoluteFilePath( IPath value );

Based on the above specification, the framework will attach validation that will make sure that the entered path is absolute, that it references a file, that the referenced file exists and that it has the appropriate extension. That happens in the model layer. The UI framework will see these annotations and supply a browse button wired to open the operating system's native file browse dialog pre-filtered to only show jar and zip files.

Similar support is available for absolute folder paths. Just remove @ValidFileExtensions and change @ValidFileSystemResourceType.

Or maybe you are writing an extension to Eclipse IDE and your property needs to hold a workspace path instead of an absolute path... Just replace @AbsolutePath with @EclipseWorkspacePath in the above example. The validation will change to use Eclipse resources API and the native browse dialog will be replaced with the standard Eclipse workspace resources dialog.

Or maybe you need to deal with relative paths, but you have custom requirements for how these relative paths are to be resolved. Sapphire still got you covered. Just replace @AbsolutePath with @BasePathsProvider annotations and implement a class that returns all possible roots...

@Type( base = IPath.class )
@BasePathsProvider( CustomBasePathsProvider.class )
@ValidFileSystemResourceType( FileSystemResourceType.FILE )
@ValidFileExtensions( "dll" )
@MustExist
    
ValueProperty PROP_RELATIVE_FILE_PATH = new ValueProperty( TYPE, "RelativeFilePath" );
    
Value<IPath> getRelativeFilePath();
void setRelativeFilePath( String value );
void setRelativeFilePath( IPath value );

public final class CustomBasePathsProvider extends BasePathsProviderImpl
{
    @Override
    public List<IPath> getBasePaths( IModelElement element )
    {
        final List<IPath> roots = new ArrayList<IPath>();
        
        roots.add( new Path( "c:/Windows" ) );
        roots.add( new Path( "c:/Program Files" ) );

        return roots;
    }
}

You will still get all the validation that you would get with an absolute path, including validation for existence which will try to locate your path using the roots returned by your base paths provider. On the UI side you will get a custom browse dialog box that lets you browse for resources in all the roots simultaneously. This can be very powerful in many contexts where the system that UI is being built for searches for the specified file in a set of defined locations.

String Values

Another common scenario is the case where the value must come from a list possible values not necessarily tied to something specific like file system resources. For instance, consider the case where a property must reference an entity name from the set of entities defined elsewhere.

Sapphire provides a set of three annotations to simplify these scenarios. The annotations are @PossibleValuesProvider, @PossibleValues and @PossibleValuesFromModel. Of the three annotations, the first one is the most generic one. It lets the developer implement a class that computes the set of possible values at runtime...

@PossibleValuesProvider( impl = CityNameValuesProvider.class )
    
ValueProperty PROP_CITY = new ValueProperty( TYPE, "City" );
    
Value<String> getCity();
void setCity( String value );

public class CityNameValuesProvider extends PossibleValuesProviderImpl
{
    @Override
    protected abstract void fillPossibleValues( SortedSet values )
    {
        // Your logic goes here.
    }
}

If you find that in your scenario the set of possible values is static you can use the @PossibleValues annotation instead. This annotation lets you specify the set of possible values right in the annotation instead of implementing a custom values provider.

Or maybe your scenario calls for a property to draw its possible values from another property in the model. The @PossibleValuesFromModel annotation has you covered. It lets you specify a path through the model where possible values should be harvested.

@PossibleValuesFromModel( path = "/Contacts/Name", caseSensitive = false ) 
    
ValueProperty PROP_ASSISTANT = new ValueProperty( TYPE, "Assistant" );
    
Value<String> getAssistant();
void setAssistant( String value );

Regardless of which of the three annotations you use, you will get validation that will check that the specified value is in the set of possible values. Additional attributes are available on all three of these annotations that let you customize the validation. For instance, you can change the problem severity to warning or even disable validation completely. You can even specify whether the comparison should be case sensitive. On the UI front, you will get browse button wired to the standard list item selection dialog.

Java Types

Sapphire even integrates with JDT to support properties that reference classes or interfaces visible to a given Java project. The developer uses the supplied JavaTypeName class as the type for a value property and then tunes the semantics using @JavaTypeConstraints and @MustExist annotations. Sapphire takes care of the rest. You get validation for type existence, kind of type (interface, class, etc.) and even whether type derives from another type. On the UI side, you get a browse button wired to JDT's type selection dialog.

In the following example, the property is specified to take a name of a non-abstract class that must extend AbstractList class while also implementing Cloneable interface.

@Type( base = JavaTypeName.class )
@JavaTypeConstraints( kind = JavaTypeKind.CLASS, type = { "java.util.AbstractList", "java.lang.Cloneable" } )
@MustExist
    
ValueProperty PROP_CUSTOM_LIST_CLASS = new ValueProperty( TYPE, "CustomListClass" );
    
Value<JavaTypeName> getCustomListClass();
void setCustomListClass( String value );
void setCustomListClass( JavaTypeName value );

Completely Custom

Sapphire browse handling support is extensible to support cases that do not fit one of the above molds. To do this, you create a custom class that extends BrowseHandler. You can then register your browse handler globally (to activate under a condition that you specify) or locally for a specific property editor in the UI definition. The second case is more common.

Here is an example:

<property-editor>
  <property>Photo</property>
  <browse-handler>
    <class>PhotosCatalogBrowseHandler</class>
  </browse-handler>
</property-handler>

Multi-Way

One variant of the browse button pattern has baffled UI writers for years. In some cases, the semantics of the property require the use of more than one browse dialog. For instance, consider the case where the property can take an absolute path to an archive file or a folder. No established convention exists for how to handle this case and developers have tried a number of different options. Here are a few examples from Eclipse itself.

Sapphire adopts the convention of using a drop-down menu from the browse button when multiple browse handlers are active concurrently. Here is what that looks like:

Currently, there are no model annotations that can fully describe the complex semantics of such scenarios. The developer must register the browse handlers in the UI definition. Validation should be done in a custom validator class attached via @Validator annotation.

Here is the UI definition from the above screen capture. All the system-provided browse handlers that activate when certain annotations are used are also available for direct reference from the UI definitions as can be seen in this example.

<property-editor>
  <property>MultiOptionPath</property>
  <browse-handler>
    <class>AbsoluteFilePathValueBrowseHandler</class>
    <param>
      <name>extensions</name>
      <value>jar,zip</value>
    </param>
  </browse-handler>
  <browse-handler>
    <class>AbsoluteFolderPathValueBrowseHandler</class>
  </browse-handler>
  <browse-handler>
    <class>EclipseWorkspacePathValueBrowseHandler</class>
    <param>
      <name>extensions</name>
      <value>jar,zip</value>
    </param>
    <param>
      <name>leading-slash</name>
      <value>true</value>
    </param>
  </browse-handler>
</property-editor>

Sapphire

2010-06-25T22:45:00.001-07:00

Little has changed in the way Java desktop UI is written since the original Java release. Technologies have changed (AWT, Swing, SWT, etc.), but fundamentals remain the same. The developer must choose which widgets to use, how to lay those widgets out, how to store the data being edited and how to synchronize the model with the UI. Even the best developers fall into traps of having UI components talk directly to other UI components rather than through the model. Inordinate amount of time is spent debugging layout and data-binding issues.

Sapphire aims to raise UI writing to a higher level of abstraction. The core premise is that the basic building block of UI should not be a widget (text box, label, button, etc.), but rather a property editor. Unlike a widget, a property editor analyzes metadata associated with a given property, renders the appropriate widgets to edit that property and wires up data binding. Data is synchronized, validation is passed from the model to the UI, content assistance is made available, etc.

This fundamentally changes the way developers interact with a UI framework. Instead of writing UI by telling the system how to do something, the developer tells the system what they intend to accomplish. When using Sapphire, the developer says "I want to edit LastName property of the person object". When using widget toolkits like SWT, the developer says "create label, create text box, lay them out like so, configure their settings, setup data binding and so on". By the time the developer is done, it is hard to see the original goal in the code that's produced. This results in UI that is inconsistent, brittle and difficult to maintain.

First, The Model

Sapphire includes a simple modeling framework that is tuned to the needs of the Sapphire UI framework and is designed to be easy to learn. It is also optimized for iterative development. A Sapphire model is defined by writing Java interfaces and using annotations to attach metadata. An annotation processor that is part of Sapphire SDK then generates the implementation classes. Sapphire leverages Eclipse Java compiler to provide quick and transparent code generation that runs in the background while you work on the model. The generated classes are treated as build artifacts and are not source controlled. In fact, you will rarely have any reason to look at them. All model authoring and consumption happens through the interfaces.

In this article we will walk through a Sapphire sample called EzBug. The sample is based around a scenario of building a bug reporting system. Let's start by looking at IBugReport.

@GenerateXmlBinding

public interface IBugReport extends IModelElementForXml, IRemovable
{
    ModelElementType TYPE = new ModelElementType( IBugReport.class );
    
    // *** CustomerId ***
    
    @XmlBinding( path = "customer" )
    @Label( standard = "customer ID" )

    ValueProperty PROP_CUSTOMER_ID = new ValueProperty( TYPE, "CustomerId" );

    Value<String> getCustomerId();
    void setCustomerId( String value );

    // *** Title ***
    
    @XmlBinding( path = "title" )
    @Label( standard = "title" )
    @NonNullValue

    ValueProperty PROP_TITLE = new ValueProperty( TYPE, "Title" );

    Value<String> getTitle();
    void setTitle( String value );
    
    // *** Details ***
    
    @XmlBinding( path = "details" )
    @Label( standard = "details" )
    @LongString
    @NonNullValue

    ValueProperty PROP_DETAILS = new ValueProperty( TYPE, "Details" );

    Value<String> getDetails();
    void setDetails( String value );
    
    // *** ProductVersion ***

    @Type( base = ProductVersion.class )
    @XmlBinding( path = "version" )
    @Label( standard = "version" )
    @DefaultValue( "2.5" )

    ValueProperty PROP_PRODUCT_VERSION = new ValueProperty( TYPE, "ProductVersion" );

    Value<ProductVersion> getProductVersion();
    void setProductVersion( String value );
    void setProductVersion( ProductVersion value );
    
    // *** ProductStage ***

    @Type( base = ProductStage.class )
    @XmlBinding( path = "stage" )
    @Label( standard = "stage" )
    @DefaultValue( "final" )

    ValueProperty PROP_PRODUCT_STAGE = new ValueProperty( TYPE, "ProductStage" );

    Value<ProductStage> getProductStage();
    void setProductStage( String value );
    void setProductStage( ProductStage value );
    
    // *** Hardware ***

    @Type( base = IHardwareItem.class )
    @ListPropertyXmlBinding( mappings = { @ListPropertyXmlBindingMapping( element = "hardware-item", type = IHardwareItem.class ) } )
    @Label( standard = "hardware" )
    
    ListProperty PROP_HARDWARE = new ListProperty( TYPE, "Hardware" );
    
    ModelElementList<IHardwareItem> getHardware();
}

As you can see in the above code listing, a model element definition in Sapphire is composed of a series of blocks. These blocks define properties of the model element. Each property block has a PROP_* field that declares the property, the metadata in the form of annotations and the accessor methods. All metadata about the model element is stored in the interface. There are no external files. When this interface is compiled, Java persists these annotation in the .class file and Sapphire is able to read them at runtime.

Sapphire has three types of properties: value, element and list. Value properties hold simple data, such as strings, integers, enums, etc. Any object that is immutable and can be serialized to a string can be stored in a value property. An element property holds a reference to another model element. You can specify whether this nested model element should always exist or if it should be possible to create and delete it. A list property holds zero or more model elements. A list can be homogeneous (only holds one type of elements) or heterogeneous (holds elements of various specified types).

Using a combination of list and element properties, it is possible to create an arbitrary model hierarchy. In the above listing, there is one list property. It is homogeneous and references IHardwareItem element type. Let's look at that type next.

@GenerateXmlBinding

public interface IHardwareItem extends IModelElementForXml, IRemovable
{
    ModelElementType TYPE = new ModelElementType( IHardwareItem.class );
    
    // *** Type ***
    
    @Type( base = HardwareType.class )
    @XmlBinding( path = "type" )
    @Label( standard = "type" )
    @NonNullValue

    ValueProperty PROP_TYPE = new ValueProperty( TYPE, "Type" );

    Value<HardwareType> getType();
    void setType( String value );
    void setType( HardwareType value );
    
    // *** Make ***
    
    @XmlBinding( path = "make" )
    @Label( standard = "make" )
    @NonNullValue

    ValueProperty PROP_MAKE = new ValueProperty( TYPE, "Make" );

    Value<String> getMake();
    void setMake( String value );
    
    // *** ItemModel ***
    
    @XmlBinding( path = "model" )
    @Label( standard = "model" )

    ValueProperty PROP_ITEM_MODEL = new ValueProperty( TYPE, "ItemModel" );

    Value<String> getItemModel();
    void setItemModel( String value );

    // *** Description ***
    
    @XmlBinding( path = "description" )
    @Label( standard = "description" )
    @LongString

    ValueProperty PROP_DESCRIPTION = new ValueProperty( TYPE, "Description" );

    Value<String> getDescription();
    void setDescription( String value );
}

The IHardwareItem listing should look very similar to IBugReport and that's the point. A Sapphire model is just a collection of Java interfaces that are annotated in a certain way and reference each other.

A bug report is contained in IFileBugReportOp, which serves as the top level type in the model.

@GenerateXmlBindingModelImpl
@RootXmlBinding( elementName = "report" )

public interface IFileBugReportOp extends IModelForXml, IExecutableModelElement
{
    ModelElementType TYPE = new ModelElementType( IFileBugReportOp.class );
    
    // *** BugReport ***
    
    @Type( base = IBugReport.class )
    @Label( standard = "bug report" )
    @XmlBinding( path = "bug" )
    
    ElementProperty PROP_BUG_REPORT = new ElementProperty( TYPE, "BugReport" );
    
    IBugReport getBugReport();
    IBugReport getBugReport( boolean createIfNecessary );
}

Let's now look at the last bit of code that goes with this model, which is the enums.

@Label( standard = "type", full = "hardware type" )

public enum HardwareType
{
    @Label( standard = "CPU" )

    CPU,
    
    @Label( standard = "main board" )
    @EnumSerialization( primary = "Main Board" )
    
    MAIN_BOARD,

    @Label( standard = "RAM" )
    
    RAM,
    
    @Label( standard = "video controller" )
    @EnumSerialization( primary = "Video Controller" )
    
    VIDEO_CONTROLLER,

    @Label( standard = "storage" )
    @EnumSerialization( primary = "Storage" )
    
    STORAGE,
    
    @Label( standard = "other" )
    @EnumSerialization( primary = "Other" )
    
    OTHER
}


@Label( standard = "product stage" )

public enum ProductStage
{
    @Label( standard = "alpha" )
    
    ALPHA,

    @Label( standard = "beta" )
    
    BETA,

    @Label( standard = "final" )
    
    FINAL
}


@Label( standard = "product version" )

public enum ProductVersion
{
    @Label( standard = "1.0" )
    @EnumSerialization( primary = "1.0" )
    
    V_1_0,
    
    @Label( standard = "1.5" )
    @EnumSerialization( primary = "1.5" )

    V_1_5,
    
    @Label( standard = "1.6" )
    @EnumSerialization( primary = "1.6" )
    
    V_1_6,
    
    @Label( standard = "2.0" )
    @EnumSerialization( primary = "2.0" )
    
    V_2_0,
    
    @Label( standard = "2.3" )
    @EnumSerialization( primary = "2.3" )
    
    V_2_3,
    
    @Label( standard = "2.4" )
    @EnumSerialization( primary = "2.4" )
    
    V_2_4,
    
    @Label( standard = "2.5" )
    @EnumSerialization( primary = "2.5" )
    
    V_2_5
}

You can use any enum as a type for a Sapphire value property. Here, once again, you see Sapphire pattern of using Java annotations to attach metadata to model particles. In this case the annotations are specifying how Sapphire should present enum items to the user and how these items should be serialized to string form.

Then, The UI

The bulk of the work in writing UI using Sapphire is modeling the data that you want to present to the user. Once the model is done, defining the UI is simply a matter of arranging the properties on the screen. This is done via an XML file.

<definition>

  <import>
    <bundle>org.eclipse.sapphire.samples</bundle>
    <package>org.eclipse.sapphire.samples.ezbug</package>
  </import>
  
  <composite>
    <id>bug.report</id>
    <content>
      <property-editor>CustomerId</property-editor>
      <property-editor>Title</property-editor>
      <property-editor>
        <property>Details</property>
        <hint>
          <name>expand.vertically</name>
          <value>true</value>
        </hint>
      </property-editor>
      <property-editor>ProductVersion</property-editor>
      <property-editor>ProductStage</property-editor>
      <property-editor>
        <property>Hardware</property>
        <child-property>
          <name>Type</name>
        </child-property>
        <child-property>
          <name>Make</name>
        </child-property>
        <child-property>
          <name>ItemModel</name>
        </child-property>
      </property-editor>
      <composite>
        <indent>true</indent>
        <content>
          <separator>
            <label>Details</label>
          </separator>
          <switching-panel>
            <list-selection-controller>
              <property>Hardware</property>
            </list-selection-controller>
            <panel>
              <key>IHardwareItem</key>
              <content>
                <property-editor>
                  <property>Description</property>
                  <hint>
                    <name>show.label.above</name>
                    <value>true</value>
                  </hint>
                  <hint>
                    <name>height</name>
                    <value>5</value>
                  </hint>
                </property-editor>
              </content>
            </panel>
            <default-panel>
              <content>
                <label>Select a hardware item above to view or edit additional parameters.</label>
              </content>
            </default-panel>
          </switching-panel>
        </content>
      </composite>
    </content>
    <hint>
      <name>expand.vertically</name>
      <value>true</value>
    </hint>
    <hint>
      <name>width</name>
      <value>600</value>
    </hint>
    <hint>
      <name>height</name>
      <value>500</value>
    </hint>
  </composite>

  <dialog>
    <id>bug.report.dialog</id>
    <label>Create Bug Report (Sapphire Sample)</label>
    <initial-focus>Title</initial-focus>
    <content>
      <composite-ref>
        <id>bug.report</id>
      </composite-ref>
    </content>
    <hint>
      <name>expand.vertically</name>
      <value>true</value>
    </hint>
  </dialog>
  
</definition>

A Sapphire UI definition is a hierarchy of parts. At the lowest level we have the property editor and a few other basic parts like separators. These are aggregated together into various kinds of composities until the entire part hierarchy is defined. Some hinting here and there to guide the UI renderer and the UI definition is complete. Note the top-level composite and dialog elements. These are parts that you can re-use to build more complex UI definitions or reference externally from Java code.

Next we will write a little bit of Java code to open the dialog that we defined.

final IFileBugReportOp op = new FileBugReportOp( new ModelStoreForXml( new ByteArrayModelStore() ) );
final IBugReport report = op.getBugReport( true );

final SapphireDialog dialog 
    = new SapphireDialog( shell, report, "org.eclipse.sapphire.samples/sdef/EzBug.sdef!bug.report.dialog" );
        
if( dialog.open() == Dialog.OK )
{
    // Do something. User input is found in the bug report model.
}

Pretty simple, right? We create the model and then use the provided SapphireDialog class to instantiate the UI by referencing the model instance and the UI definition. The pseudo-URI that's used to reference the UI definition is simply bundle id, followed by the path within that bundle to the file holding the UI definition, followed by the id of the definition to use.

Let's run it and see what we get...

There you have it. Professional rich UI backed by your model with none of the fuss of configuring widgets, trying to get layouts to do what you need them to do or debugging data binding issues.

One Step Further

A dialog is nice, but really a wizard would be better suited for filing a bug report. Can Sapphire do that? Sure. Let's first go back to the model. A wizard is a UI pattern for configuring and then executing an operation. Our model is not really an operation yet. We can create and populate a bug report, but then we don't know what to do with it.

Any Sapphire model element can be turned into an operation by adding an execute method. We will do that now with IFileBugReportOp. In particular, IFileBugReportOp will be changed to also extend IExecutableModelElement and will acquire the following method definition:

// *** Method: execute ***
    
@DelegateImplementation( FileBugReportOpMethods.class )
    
IStatus execute( IProgressMonitor monitor );

Note how the execute method is specified. We don't want to modify the generated code to implement it, so we use delegation instead. The @DelegateImplementation annotation can be used to delegate any method on a model element to an implementation located in another class. The Sapphire annotation processor will do the necessary hookup.

public class FileBugReportOpMethods
{
    public static final IStatus execute( IFileBugReportOp context, IProgressMonitor monitor )
    {
        // Do something here.
        
        return Status.OK_STATUS;
    }
}

The delegate method implementation must match the method being delegated with two changes: (a) it must be static, and (b) it must take the model element as the first parameter.

Now that we have completed the bug reporting operation, we can return to the UI definition file and add the following:

<wizard>
  <id>wizard</id>
  <label>Create Bug Report (Sapphire Sample)</label>
  <page>
    <id>main.page</id>
    <label>Create Bug Report</label>
    <description>Create and submit a bug report.</description>
    <initial-focus>Title</initial-focus>
    <content>
      <with>
        <property>BugReport</property>
        <content>
          <composite-ref>
            <id>bug.report</id>
          </composite-ref>
        </content>
      </with>
    </content>
    <hint>
      <name>expand.vertically</name>
      <value>true</value>
    </hint>
  </page>
</wizard>

The above defines a one page wizard by re-using the composite definition created earlier. Now back to Java to use the wizard...

final IFileBugReportOp op = new FileBugReportOp( new ModelStoreForXml( new ByteArrayModelStore() ) );
op.getBugReport( true );  // Force creation of the bug report.

final SapphireWizard<IFileBugReportOp> wizard 
    = new SapphireWizard<IFileBugReportOp>( op, "org.eclipse.sapphire.samples/sdef/EzBug.sdef!wizard" );
        
final WizardDialog dialog = new WizardDialog( shell, wizard );
        
dialog.open();

SapphireWizard will invoke the operation's execute method when the wizard is finished. That means we don't have to act based on the result of the open call. The execute method will have completed by the time the open method returns to the caller.

The above code pattern works well if you are launching the wizard from a custom action, but if you need to contribute a wizard to an extension point, you can extend SapphireWizard to give your wizard a zero-argument constructor that creates the operation and references the correct UI definition.

Let's run it...

One More Step

Now that we have a system for submitting bug reports, it would be nice to have a way to maintain a collection of these reports. Even better if we can re-use some of our existing code to do this. Back to the model.

The first step is to create IBugDatabase type which will hold a collection of bug reports. By now you should have a pretty good idea of what that will look like.

@GenerateXmlBindingModelImpl
@RootXmlBinding( elementName = "bug-database" )

public interface IBugDatabase extends IModelForXml
{
    ModelElementType TYPE = new ModelElementType( IBugDatabase.class );

    // *** BugReports ***
    
    @Type( base = IBugReport.class )
    @Label( standard = "bug report" )
    @ListPropertyXmlBinding( mappings = { @ListPropertyXmlBindingMapping( element = "bug", type = IBugReport.class ) } )
    
    ListProperty PROP_BUG_REPORTS = new ListProperty( TYPE, "BugReports" );
    
    ModelElementList<IBugReport> getBugReports();
}

That was easy. Now let's go back to the UI definition file.

Sapphire simplifies creation of multi-page editors. It also has very good integration with WTP XML editor that makes it easy to create the very typical two-page editor with a form-based page and a linked source page showing the underlying XML. The linkage is fully bi-directional.

To create an editor, we start by defining the structure of the pages that will be rendered by Sapphire. Sapphire currently only supports one editor page layout, but it is a very flexible layout that works for a lot scenarios. You get a tree outline of content on the left and a series of sections on the right that change depending on the selection in the outline.

<editor-page>
  <id>editor.page</id>
  <page-header-text>Bug Database (Sapphire Sample)</page-header-text>
  <initial-selection>Bug Reports</initial-selection>
  <root-node>
    <node>
      <label>Bug Reports</label>
      <section>
        <description>Use this editor to manage your bug database.</description>
        <content>
          <action-link>
            <action-id>node:add</action-id>
            <label>Add a bug report</label>
          </action-link>
        </content>
      </section>
      <node-list>
        <property>BugReports</property>
        <node-template>
          <dynamic-label>
            <property>Title</property>
            <null-value-label>&lt;bug&gt;</null-value-label>
          </dynamic-label>
          <section>
            <label>Bug Report</label>
            <content>
              <composite-ref>
                <id>bug.report</id>
              </composite-ref>
            </content>
          </section>
        </node-template>
      </node-list>
    </node>
  </root-node>
</editor-page>

You can see that the definition centers around the outline. The definition traverses the model as the outline is defined with sections attached to various nodes acquiring the context model element from their node. The outline can nest arbitrarily deep and you can even define recursive structures by externalizing node definitions, assigning ids to them and then referencing those definitions similarly to how this sample references an existing composite definition.

The next step is to create the actual editor. Sapphire includes several editor classes for you to choose from. In this article we will use the editor class that's specialized for the case where you are editing an XML file and you want to have an editor page rendered by Sapphire along with an XML source page.

public final class BugDatabaseEditor extends SapphireEditorForXml
{
    public BugDatabaseEditor()
    {
        super( "org.eclipse.sapphire.samples" );
        setEditorDefinitionPath( "org.eclipse.sapphire.samples/sdef/EzBug.sdef/editor.page" );
    }

    @Override
    protected IModel createModel( final ModelStore modelStore )
    {
        return new BugDatabase( (ModelStoreForXml) modelStore );
    }
}

Finally, we need to register the editor. There are a variety of options for how to do this, but covering all of these options is outside the scope of this article. For simplicity we will register the editor as the default choice for files named "bugs.xml".

<extension point="org.eclipse.ui.editors">
  <editor
    class="org.eclipse.sapphire.samples.ezbug.ui.BugDatabaseEditor"
    default="true"
    filenames="bugs.xml"
    id="org.eclipse.sapphire.samples.ezbug.ui.BugDatabaseEditor"
    name="Bug Database Editor (Sapphire Sample)"/>
</extension>

That's it. We are done creating the editor. After launching Eclipse and creating a bug.xml file, you should see an editor that looks like this:

Sapphire really shines in complex cases like this where form UI is sitting on top a source file that users might edit by hand. In the above screen capture, what happened is that the user manually entered "BETA2" for the product stage in the source view. There is a problem marker next to the property editor and the yellow assistance popup is accessible by clicking on that marker. The problem message is displayed along with additional information about the property and available actions. The "Show in source" action, for instance, will immediately jump to the editor's source page and highlight the text region associated with this property. This is very valuable when you must deal with large files. These facilities and many others are available out of the box with Sapphire with no extra effort from the developer.

Conclusion

Now that you've been introduced to what Sapphire can do, compare it to how you are currently writing UI code. All of the code presented in this article can be written by a developer with just a few weeks of Sapphire experience in an hour or two. How long would it take you to create something comparable using your current method of choice?

I hope that this article has piqued your interest in Sapphire. Oracle is committed to bringing this technology to the open source community. We have proposed a project at the Eclipse Foundation. If you are interested, you should post a message on the project's forum. Introduce yourself and describe your interest. We are actively seeking both consumers of this technologies as well as potential partners to come join the effort and help us take this technology in the directions that we have not yet anticipated.

Tool for exporting formatted code to HTML?

2010-06-25T13:40:00.001-07:00

Quick poll… When writing blogs or articles, what do you use to nicely format code snippets as HTML? I am particularly curious if anyone found an Eclipse plugin that simply exports the style that’s visible in the Eclipse editor rather than trying to implement parsing and styling on its own.

JDT, Manifest Classpath, Classpath Containers and Helios

2010-05-27T14:58:00.001-07:00

In the interest of public service, thought I’d communicate a behavior change in Eclipse Java Developer Tools (JDT) coming in Helios (aka Eclipse 3.6). In Galileo (aka Eclipse 3.5), JDT started resolving manifest classpath in libraries added to project’s build path. This worked whether the library was added to project’s build path directly or via a classpath container, such as the user library facility provided by JDT or one implemented by a third party. In Helios, this behavior was changed to exclude classpath containers from manifest classpath resolution.

This change in behavior has potential to affect users who have started relying on this facility in their projects. A workspace with projects that built fine in Galileo may not build in Helios. The cause may not be obvious as the only thing that the user will notice is build errors complaining of missing types. The user will need to figure out where those types were coming from originally and take steps to make sure those libraries are referenced directly. The exact way to do that is dependent on the implementation of the classpath container in question. For instance, if the container is based on JDT user library feature, then the definition of the user library will need to be adjusted in preferences. Alternatively, users can set a system property in their eclipse.ini file to revert to Galileo behavior. Adding the following line to the end of the file should to the trick:

-DresolveReferencedLibrariesForContainers=true

This change can also affect third parties shipping plugins on top of JDT that implement classpath containers. If the classpath container was implemented to rely on manifest classpath resolution, it will need to be updated to work properly on Helios. Fortunately, JDT provides an API to make this process less painful…

JavaCore.getReferencedClasspathEntries( [IClasspathEntry], [IJavaProject] )

The above API call will do manifest classpath resolution on the library referenced by the provided classpath entry. Pass in null for the second parameter. The result is an array of classpath entries that can be added to the original set in classpath container initialization. Several things to watch out for…

Make sure not add the same library twice. This is fairly easy to do, especially if your container implementation gives user some control over the contents. The last time I ran into this, JDT threw an exception on container initialization.
Check returned entries for existence before adding them to your container. The getReferencedClasspathEntries method does not check for existence, but if your container adds a reference to a non-existing file, JDT will put an error in the problems view and nothing will build. Could be an ugly surprise for your users as a code fix in the container implementation will be required to resolve this.
The getReferencedClasspathEntries method is new for Helios, which means that your container implementation will no longer be compatible with Galileo. If you need to support Galileo and Helios from the same code base, you will need to implement your own manifest classpath resolution.

References

Bug 305037 - missing story for attributes of referenced JARs in classpath containers
Bug 313965 - Breaking change in classpath container API
Bug 313890 - Migration guide to 3.6 for containers with MANIFEST-referred entries

Olivier Thomann has asked me to include the following clarifying statement:

“Galileo behavior was wrong as a container should control exactly what is inside the container. So Helios fixed this issue.”

I have no disagreement with that statement. My purpose in writing this blog is purely to document a difference in behavior from Galileo to Helios that can appear to many as a regression. I do think this change could have been handled better, but that’s besides the point at this stage in Helios release and not the reason that I wrote this post.

Eclipse is a Product and that’s a Good Thing (tm)

2009-04-03T08:06:00.001-07:00

I know that Bjorn is just trying to stimulate the discussion and challenge the status quo with his recent blog posts. That’s a good thing. I do find myself disagreeing completely with his latest proposal to stop distribution of binaries from eclipse.org and instead shift the responsibility to various member companies. Basically, we would go from the FireFox model to the Linux model.

Here is a quote from Bjorn’s blog post responding to some of the negative comments about his proposal:

Changing Things Will Kill Eclipse. I just don't see this. For example, The Linux Foundation doesn't distribute a single binary and yet Linux is so popular that it is scaring Microsoft. Wayne also pointed this out.

The important question to ask here is could Linux have been much more successful if there was a single canonical distribution provided by the Linux Foundation. Yes, Linux is getting more popular, but not nearly as fast as people would have liked and its adoption curve against competition is not nearly as good as the adoption curve for other major open source projects that follow the product model. Why is that? The dozens of different Linux distros fragment the market, create confusion for new users (have to make a choice between distros that are potentially radically different when you don’t yet have a clue), create barriers to skill transition (just because you’ve learned how to use Linux on your machine doesn’t mean that you will be able to use Linux on friend’s machine), and make it significantly more expensive for vendors to deliver new software for the platform (what works on one distro may not work on another). Now compare that to FireFox. It is much younger project than Linux, but has already managed to make significantly more progress against competition than Linux. This is not an accident. You don’t have to take my word for it, a number of people have written about these problems with Linux and how they stand in the way of its growth. Why would we want to emulate the Linux model?

Platform alone is not a good strategy. No matter how good the platform is, companies and individuals will only use the platform if it enables them to reach a significant user base. It takes a product to do that. Not dozens of different products that confuse the users and make it more difficult to build on the platform, but a single trusted canonical product. Eclipse as a Product helps ensure success of Eclipse as a Platform.

Ultimately, what is the problem that we would be trying to solve by stopping distribution of binaries at eclipse.org? Bjorn makes the argument that Eclipse community delivers such a poor quality product and that users are having such a hard time receiving adequate support on the forums that we need to do something drastic to address the problem. How do we evaluate this argument? You cannot look at forum posts alone. The voices of a few disgruntled individuals drown out the opinions of thousands of satisfied users. After all, people only go to forums when they have problems. I would look at Eclipse adoption curves instead as a true measure of user satisfaction. A product that has significant quality problems would not keep growing. The growth would stall and we should see adoption numbers going down. We are not seeing that with Eclipse. The evidence just does not backup Bjorn’s argument.

I do happen to agree that there is more that we could do to help users get better support through paid channels, but we do not need to resort to drastic measures like what Bjorn is proposing. The harm from going forward with this proposal would be far greater than potential benefits.

Count me out from p2 fan club

2009-03-01T16:22:00.001-08:00

I don’t make habit of ranting about technology, but p2 has been driving me up the wall. The old update manager may not have been perfect, but at least it didn’t have the bad habit of preventing installation cases that should work from working.

So we are putting finishing touches on a new version of Oracle Enterprise Pack for Eclipse (OEPE) and it’s time to test various installation scenarios. Eclipse Ganymede SR2 was also just released last week, so we are verifying compatibility with it. One of the basic installation scenarios that we are testing starts out with an all-in-one kit that includes Eclipse Ganymede GA with the previous version of OEPE. The second step in the scenario is to update all of the Eclipse components in that installation. The new version of OEPE requires at least SR1. I let Eclipse search for updates and install everything that it finds. That works. Presumably at this point, the installation should be equivalent to a fresh Eclipse Ganymede SR2 install. The final step is to install the new version of OEPE from a local update site. P2 thinks for a while and then says there are problems that will prevent the installation from working and refuses to go forward.

WTF? I know perfectly well that the plugins we are installing are compatible with Ganymede SR2. They’ve been built using SR2 as the target platform and they work just fine when simply added to the Eclipse installation. Now what? Taking a look at the problems reported by p2, I find about a hundred messages that look like the following.

Cannot find a solution where both "bundle org.eclipse.wst.validation [1.2.0,1.3.0)" and "bundle org.eclipse.wst.validation [1.1.0,1.2.0)" are satisfied.
Unsatisfied dependency: [org.eclipse.jst.ws.axis.consumption.core 1.0.204.v200708151945] requiredCapability: osgi.bundle/org.eclipse.core.resources/[3.2.0,3.4.0)
Unsatisfied dependency: [org.eclipse.jst.ws.axis.consumption.ui 1.0.204.v200801222138] requiredCapability: osgi.bundle/org.eclipse.core.resources/[3.2.0,3.4.0)
Unsatisfied dependency: [org.eclipse.wst.ws 1.0.204.v200711140435] requiredCapability: osgi.bundle/org.eclipse.core.resources/[3.2.0,3.4.0)
Unsatisfied dependency: [org.eclipse.wst.command.env.ui 1.0.203.v200709052219] requiredCapability: osgi.bundle/org.eclipse.core.resources/[3.2.0,3.4.0)

These messages don’t make a whole lot of sense. None of them reference plugins that I am trying to install and there is no hint in the messages regarding what actually caused the problem. I looked at one of them in detail to make sure I wasn’t missing something obvious. The second message says that a dependency of org.eclipse.jst.ws.axis.consumption.core plugin cannot be found. That makes sense since it’s a very old version of the plugin that’s not compatible with Ganymede. The question is why p2 trying to resolve that plugin? I look at my installation and I see versions 1.0.304.v200805140230 and 1.0.306.v200810082309. That makes sense. Those versions correspond to what shipped with Ganymede GA and Ganymede SR2. I do not find version 1.0.204.v200708151945 that p2 is complaining about anywhere.

At this point, I gave up trying to make sense of the problem messages and proceeded to blindly try various changes to the way the OEPE update site is constructed to see if I would get a different result. Two alternatives I tried made this scenario work: (a) removing all version constraints from plugin dependencies and (b) reverting to the old-style update site with a site.xml file and no p2 metadata. We still need to do some more testing, but we probably will go with (b) and give up on p2-enabling our update site.

I had reservations about p2 since the poor way in which it was rolled out roughly a year ago, but after a year of fighting with it and this recent experience, I can honestly say (without an ounce of exaggeration) that p2 is the worst regression ever introduced into the Eclipse Platform. I understand the problems that p2 is supposed to solve, but there is just no excuse for destroying the most basic of core scenarios in the process. If it wasn’t ready for Ganymede, it should have stayed as an incubator for a while longer.

Field-level key bindings

2009-02-05T21:49:00.001-08:00

Sometimes you need to create key bindings in Eclipse which are scoped to just a single control. I had one such case today. I have a table cell editor that’s based on the TextCellEditor, but adds a small graphical browse button. It works great as long as you are using a mouse, but I needed to make the browsing function keyboard accessible for people with disabilities.

Eclipse has a nice command framework that lets you define commands in abstract sense, place them in contexts, define key bindings and finally associate handlers to do the actual work. Finding an example that puts all of these concepts to work together in a particular way can be challenging, so I thought I would share my solution to the above problem and explain some of this API along the way.

The first step is to define the command. A command is an operation that a user can perform, but we don’t actually specify how to perform that operation when defining the command. That comes later when we add a handler. Every command must belong to a category. Here we define a category as well. You will typically want to create a category for each broad functional area to make it easier for users to find and manage your commands in the preferences.

<extension point="org.eclipse.ui.commands">
  <category
    id="my.category"
    name="My Category"/>
  <command
    id="my.browse.command"
    categoryId="my.category"
    name="Browse"/>
</extension>

The next step is to define the context. The context controls what commands are available via key bindings based on where in the workbench the user is working. Typically views and editors define contexts, but there is nothing stopping you from defining one that is more focused. In this example, we will create a context for fields with browsing capability.

<extension point="org.eclipse.ui.contexts">
  <context
    id="my.browseable.field.context"
    parentId="org.eclipse.ui.contexts.window"
    name="In Browseable Field"/>
</extension>

The final declarative step is to define the key binding. The following assigns Ctrl+L to the browse command in the browseable field context.

<extension point="org.eclipse.ui.bindings">
  <key
    sequence="M1+L"
    contextId="my.browseable.field.context"
    commandId="my.browse.command"
    schemeId="org.eclipse.ui.defaultAcceleratorConfiguration"/>
</extension>

And now for the final bit of magic… The following function brings it all together by enabling the browseable field context and associating a handler with the browse command when the specified text field gains focus. When the focus is lost, the context and the handler are deactivated.

public static void addBrowseKeyBinding( final Text textField,
                                        final Runnable browseOperation )
{
    final IHandler browseCommandHandler = new AbstractHandler() 
    {
        public Object execute( final ExecutionEvent event )
        {
            browseOperation.run();
            return null;
        }
    };
        
    final IWorkbench workbench = PlatformUI.getWorkbench();
    
    final IHandlerService handlerService 
        = (IHandlerService) workbench.getService( IHandlerService.class );

    final IContextService contextService 
        = (IContextService) workbench.getService( IContextService.class );
        
    final IHandlerActivation[] handlerActivationRef = new IHandlerActivation[ 1 ];
    final IContextActivation[] contextActivationRef = new IContextActivation[ 1 ];
        
    textField.addFocusListener
    (
        new FocusListener()
        {
            public void focusGained( final FocusEvent event )
            {
                final IHandlerActivation handlerActivation
                    = handlerService.activateHandler( "my.browse.command", browseCommandHandler );
                    
                handlerActivationRef[ 0 ] = handlerActivation;
                    
                final IContextActivation contextActivation
                    = contextService.activateContext( "my.browseable.field.context" );
                    
                contextActivationRef[ 0 ] = contextActivation;
            }

            public void focusLost( final FocusEvent event )
            {
                handlerService.deactivateHandler( handlerActivationRef[ 0 ] );
                contextService.deactivateContext( contextActivationRef[ 0 ] );
            }
        }
    );
}

Better way to manage dependency version ranges

2009-02-01T18:29:00.001-08:00

OSGi provides an extremely powerful and precise mechanism for controlling acceptable version ranges when specifying dependency on bundles or packages. In theory (as described by policies of various projects at Eclipse), the developer would take into account his plugin’s API and behavior needs, cross-reference that with version information about the bundle in question and carefully craft the version range in dependency declaration to accurately reflect his plugin’s actual needs while leaving the version range as open as possible to allow users maximum flexibility when composing an installation. Further, in theory, the developer should be continuously aware of dependency version ranges specified in his product’s various plugins and how they correlate to functionality exposed by those plugin. As development progresses, the developer is supposed to be able to spot when he started depending on functionality that’s not available in the specified min version and reset the min version accordingly.

That’s the theory. In practice I haven’t met a single developer with sufficient time on their hands or sufficient mental capacity to keep all of the necessary information in his head at all times in order to properly apply this policy. What I’ve seen happen most often is that the min range gets set based on whatever the plugin version happens to be at the time the dependency is first added. PDE helpfully inserts this information in your manifest by default. The max version then gets set by applying a team policy (typically by bumping up either the major or the minor version). This happens when dependency is first introduced. As the code continues to evolve, the min version is typically not touched again. The max version is incremented when the build gets broken by the dependency bumping up their versions past a certain point. The cycle repeats.

After many years of observing this situation, I am convinced that having developers manage version ranges creates a lot of overhead and does not yield satisfactory results no matter how hard people try. To me, dependency version ranges are most useful when you have shipped your product in binary form. When taken collectively across a component (collection of bundles), they represent a statement of what your team is willing to support as a working configuration. Ideally, this information should be consistent across plugins and as accurate as possible.

Any time you talk about setting version ranges, you are considering three versions:

The version that you developed and did most of your testing with. I call this the “target version”. Typically, this is what you would list as recommended configuration in your documentation.
The minimum version that you are willing to support. The level of testing you can afford to allocate to this version is bound to be less than what you would allocate for the target version, so there is a certain amount of risk that an undetected issue is going to slip through. The further back you go from the target version when setting the minimum version, the greater your risk.
The maximum version that you are willing to support. Since this version will typically not exists at the time of your ship date, setting this version involves an educated guess based on understanding of what policies your dependencies use when incrementing their versions and the degree to which you are relying on undocumented (internal) code and behaviors. The spread between the target version and the maximum version is where you highest risk lies. On one hand you’d like to assure long viability of your release in the field. On the other hand, the further out you go, the greater the risk that your product will not work and make a liar out of you in the eyes of your users.

Because getting the above version decisions right and consistent across a component is extremely important, it is not a good idea for individual developers to be making these decisions on a plugin-by-plugin basis. In an Open Source environment, this should be a component-wide decision made collectively by the committers. In a commercial environment, this decision is often made higher up in the organization based on availability of resources and target user base considerations.

When the overall decision is made, it is typically expressed in broad terms. For instance… “this version will ship on Ganymede SR1, but should work with all versions of Ganymede starting with GA”. It is then up to developers to translate that requirement into version ranges in the manifest.

That’s a ton of tedious manual work with lots of room for mistakes. In other words, a perfect candidate for automation. A few years ago, I wrote a set of two custom Ant tasks to automate this process. The first task reads an Eclipse installation and produces an inventory file that lists id and version of every bundle found. The second tasks takes as input an inventory file representing the minimum platform, an inventory file representing the target platform and a policy for setting the maximum versions. For every dependency, the task looks up the version from the minimum platform inventory. That becomes the left-hand-side of the version range. It then looks up the bundle version in the target platform inventory and applies the policy function to it. Here are some examples of policy functions: “x.y.z ->x+1.0.0”, “x.y.z ->x.y+1.o” or the extremely conservative “x.y.z ->x.y.z+1”. You can set different policies for different plugins or components based on what you know of their versioning conventions. The version returned by the policy function becomes the right-hand-side of the version range.

We have been using these two tasks to automate and improve the quality of our version ranges for several releases of Eclipse tooling products at BEA and now at Oracle. Developers don’t set the versions on the dependencies specified in the bundle manifests stored in the source repository. At the end of every build, a process runs that splices version ranges into the manifests just prior to packaging the bundles for distribution. The target inventory is always generated on the fly based on whatever the product is building against. The minimum platform inventory is generated once when the minimum platform decision is made. The inventory is then stored in the source repository.

This has been an extremely useful process improvement for us. Not only do we have more confidence in the version ranges encoded in our product distributions, but it takes significantly less work for developers to manage all of this. The developers never have to think about dependency versions during normal course of development and integrating new versions of dependencies takes less work (since version ranges in manifest don’t have to be fixed manually to get the build to work).

Ant Snippets : expand-to-single-dir

2009-01-31T16:12:00.001-08:00

I try to feign ignorance about anything Ant-related, but it hasn't been working very well for me. It seems that no matter which way I turn, I am elbows deep in some Ant-based project. I guess I just like automating the tedious aspects of software engineering and I hate shell scripts even more than I dislike Ant. So I decided to do something very evil. I figure if I start spreading some of the knowledge around, other people will pick up some of these automation tasks and I can take a break from Ant for a while.

First, the most powerful tool in your Ant arsenal is the Ant-Contrib package from SourceForge. Pure Ant is declarative in nature and lacks basic code flow constructs such as loops and if statements that most engineers live by. This is intentional. The core Ant premise is that you should describe what you want to accomplish rather than spelling out how to accomplish it. That works for some people, but I am not one of those people. I take my Ant with a good dose of Ant-Contrib.

Now that we got preliminaries out of the way, I will share a little snippet of Ant that I wrote a while ago to help wrangle various zip-based distributions into usable form. One of the more common chores that you run into is to take a bunch of zip files in a specified directory and expand them all into a single directory (overwriting files as necessary). In the context of Eclipse this scenario comes up often when setting up target platforms from integration builds of various relevant projects or when packaging your Eclipse-based product for distribution (aka the all-in-one kit). It is nice to be able to have a utility in your arsenal that can do this easily and without hard coding the names of all the zips that need to be extracted.

<target name="expand-to-single-dir">
  <check-required-property name="src"/>
  <property name="dest" value="${src}"/>
  <property name="includes" value="*.zip"/>
  <property name="excludes" value=""/>
  <property name="strip.path.prefix" value=""/>
  <expand-to-single-dir 
    src="${src}" dest="${dest}" includes="${includes}" 
    excludes="${excludes}" strip-path-prefix="${strip.path.prefix}"/>
</target>
  
<macrodef name="expand-to-single-dir">
  <attribute name="src"/>
  <attribute name="dest"/>
  <attribute name="includes" default="*.zip"/>
  <attribute name="excludes" default=""/>
  <attribute name="strip-path-prefix" default=""/>
  <sequential>
    <mkdir dir="@{dest}"/>
    <for param="component.archive">
      <path>
        <fileset dir="@{src}" includes="@{includes}" excludes="@{excludes}"/>
      </path>
      <sequential>
        <unzip src="@{component.archive}" dest="@{dest}" overwrite="true">
          <mapper type="regexp" from="^@{strip-path-prefix}(.*)$$" to="\1"/>
        </unzip>
      </sequential>
    </for>
  </sequential>
</macrodef>
  
<macrodef name="check-required-property">
  <attribute name="name"/>
  <sequential>
    <if>
      <not><isset property="@{name}"/></not>
      <then>
        <fail message="Property '@{name}' must be specified."/>
      </then>
    </if>
  </sequential>
</macrodef>

The above snippet defines expand-to-single-dir macro that you can easily use when writing your Ant targets and it also defines a target with the same name. The target is useful as a stand-alone tool that can be invoked directly from the command line. Since I am an Eclipse developer these days, the second part of this snippet adds a convenience target that calls the above utility in a way that also strips the typically-unwanted leading “eclipse” directory that is present in all Eclipse distributions.

<target name="expand-eclipse-zips">
  <check-required-property name="src"/>
  <property name="dest" value="${src}"/>
  <expand-to-single-dir 
    src="${src}" dest="${dest}" includes="*.zip" strip-path-prefix="eclipse/"/>
</target>

Are code generators dumbing down our models?

2008-10-29T11:04:00.001-07:00

I suspect that I am about to bring the Wrath of Ed down on me, but here it goes...

There are quite a few Java code generators that can take an arbitrary XML Schema and spit out tons of code that a developer doesn't have to write. There is JAXB, Apache XMLBeans and of course EMF. I am sure there are others. While code generators save us a lot of time, the push-button approach can lead to dumbing down of our models.

I would argue that there are relatively few core modeling patterns, but the flexibility of XML makes it easy to express these patterns in a variety of ways. The generated code then unintentionally surfaces (rather than hiding) these XML serialization details in the model layer. This forces the clients of the model to deal with inconsistent and often difficult to use API.

Consider the basic example of a boolean property. I have seen at least three different ways of representing that in XML:

<some-flag>true</some-flag>
<some-flag-enabled/>  <!-- absence means false --> 
<some flag value="true"/>  <!-- the attribute is required -->

The above three cases would generate different model code even though from the modeling perspective, they represent the same construct.

A more complex pattern is the selector-details construct where selector is a type enumeration and details provide settings specific to the type. I stopped counting how many different ways I've seen that pattern represented. Here are two of the most common examples:

Example 1: An explicit type element controls which property elements are applicable.

<type>...</type>  <!-- valid values are X and Y -->
<property-1>...</property-2>  <!-- associated with type X -->
<property-2>...</property-2>  <!-- associated with type Y -->
<property-3>...</property-3>  <!-- associated with type X and type Y -->

Example 2: In this case, the elements alternative-x and alternative-y are mutually exclusive. The element names are functioning as type selectors.

<alternative-x>
  <property-1>...</property-1>
  <property-3>...</property-3>
</alternative-x>
<alternative-y>
  <property-2>...</property-2>
  <property-3>...</property-3>
</alternative-y>

I would argue that the the above cases are semantically identical and therefore should have the same representation in the Java model. Of course, that doesn't happen. All of the existing code generators that I am aware of will produce drastically different code for these two alternatives.

So why should we care? I would argue that in many cases, while we are saving time by generating model code, the cost savings are at the expense of complicating the model consumer code. Recently, I took over a project at Oracle that was building a form-based editors for several rather complicated WebLogic Server deployment descriptors. The schemas of these descriptors evolved over many server releases and many people had a hand at augmenting them. The result is a complete lack of consistency. You could say that perhaps the schemas should have been more carefully evolved, but I would argue that they represent a rather realistic example of what real world complex schemas look like. In any case, the first attempt at building these editors was to generate an EMF model based on the XSDs and to build UI that would bind to EMF. That worked ok for a while, but eventually the UI code started to get too complicated. Many of the UI binding code had to be hand-written. It ultimately made sense to throw away the generated model code and to hand-code the model. That allowed us to arbitrarily control how model surfaces XML constructs and made it possible to reduce the amount of custom UI code that was necessary by literally several orders of magnitude.

I am certainly not trying to say that generated model code is a bad idea, but the ease with which it is possible to toss an XSD into a code generator and get a bunch of model code in return plays part in encouraging developers to pay less attention than is really necessary to the model layer.

Common Servers View for Eclipse

2008-10-23T16:13:00.001-07:00

There is a cool collaboration happening right now between WTP and DTP to build a shared Servers view that will replace the separate WTP's Servers view and DTP's Data Source Explorer view. The new view is built using the Common Navigator framework and will make it easy for other Eclipse Projects to contribute content. One of the important goals is to reduce clutter on user's workbench by collapsing many individual views into one. If you are interested in this effort, you should check out Bug 252239. There has also been some relevant discussion on Bug 245013 and Bug 247934.

So, I am looking at you... CVS Tooling, Subversive, DSDP Target Management, SOA Tools, etc. You know who you are. Come join the party.

Eclipse Project Declaration : Faceted Project Framework

2008-10-23T11:54:00.001-07:00

I am blogging today to raise awareness of a project declaration that might have gone unnoticed in the inboxes of Eclipse committers and other members. The goal of the Faceted Project Framework is to provide a re-usable system that facilitates treating Eclipse projects as composed of units of functionality (called facets) that can be easily added or removed by users. The initial code contribution will come from a mature and a rather successful component in the Eclipse Web Tools Platform (WTP), but the ultimate goal for creating this independent project is to encourage broader adoption in contexts beyond that of WTP. I expect this project will evolve substantially as others bring their use cases to the table.

Anyone who has ever wondered if there was a better solution that a multitude of "Enable function X" menu items or has ever thought that users should be able to add and remove natures without hacking the .project file should get involved. I am looking for both potential contributors and potential consumers. If you have use cases or just random thoughts on this subject, I encourage you to jump in and get involved at the newly-created newsgroup.

Project Proposal: http://www.eclipse.org/proposals/fproj/

Newsgroup: http://www.eclipse.org/newsportal/thread.php?group=eclipse.fproj

Creating API, Lessons Learned

2008-10-21T14:13:00.001-07:00

The subject of how to properly create and declare API is frequently debated at various communities within the Eclipse ecosystem. One of the thorniest issues is the disagreement over how to treat the so-called "provisional API", basically the API that either has not yet received sufficient feedback or has known issues that cannot be addressed prior to the release. There is a lively debate going on right now on this very subject on the mailing list of the Eclipse E4 project (the effort to build the next generation Eclipse platform - sometimes referred to as Eclipse 4.0), so I thought I should jump in and share our experience in this area at the Eclipse Web Tools Platform (WTP) project in hopes that others don't repeat the mistakes that were made.

It's important to note that opinions expressed here are mine alone. Other involved parties may not agree. Names and other identifying information is withheld to protect the guilty.

History

The start of WTP project was pretty rough. Large code contributions had to be rationalized in the context of a platform that is supposed to be extensible for many external adopters. One of the challenges was the belief by many of the committers from the company that made the code contribution that the APIs are good as is because they existed like that for a long time inside that company's commercial products and are therefore proven. Aligned against that was the growing feedback from new adopters who were saying that the APIs were insufficient and in some cases just plain wrong. Creating good APIs that are flexible enough to address variety of adopter usecases takes a very long time, but unfortunately time was running out. Major companies involved in WTP were pressuring the project to make a release so that they can build commercial products with it. After much debate, a compromise was reached. WTP was going to make a release, but we were not going to declare any API as stable. Everything will be labeled as provisional.

Sounds good in theory, right? What went wrong is that the concept of provisional API was not concretely defined as part of the initial agreement. Everyone (from committers to adopters) ended up with their own ideas about the meaning of the concept. The first release happened and WTP team went to work on the next release trying to improve the APIs based on the growing feedback. That's when the fireworks really started. Certain adopters were not particularly happy that WTP was continuously breaking them despite the fact that they were leveraging code clearly placed in internal packages or otherwise marked as provisional. Granted, adopters didn't have much choice if they wanted to build products on top of WTP, but that's what you get when a project is starting out. None of that seemed to matter and eventually WTP PMC bowed under the pressure by instituting a very restrictive code change policy. An "adopter usage scan tool" was created that could be used by WTP adopters to scan their code base for references to WTP code and send these reports back to WTP where they would be collected and used as a reference for determine whether a change is allowed or not. This new policy effectively negated the original promise that was made with regard to provisional API. The new contract covered everything including code previously designated as provisional and purely internal code. Instead of committers promoting API, anything that an adopter touched (as represented by these reports) effectively became API.

Work on improving API essentially ground to a halt. It just became too expensive to fix many of the larger problems. Technically, a committer could seek PMC approval to break code referenced in adopter scans, but exceptions were rarely granted. The argument that was frequently made is that by making a proposed change, many lines of code in adopter products would be effected. It's "cheaper" for committers to not make the change in question or at least make it in a way that's completely backwards compatible. I will leave it as an exercise for the reader to see the fallacy of that argument.

The end result is that WTP was left with large amounts of "in progress" API code in random internal packages that was effectively frozen because it became too expensive for committers to continue to work on this API within the imposed constraints. In many cases, providing the requisite backwards compatibility would have effectively doubled the amount of work. Some improvements that were easy to make in additive fashion continued to be made over the next few releases, but real progress essentially stopped.

Finally, last year a group of committers was convened to try to improve the situation by proposing a new API policy for WTP. The end result formally defined provisional API and started the process of phasing out the flawed adopter usage scans policy. As someone who was involved in drafting the new API policy, I can tell you that I still see many flaws in it, but it is an effort to take a step in the right direction. Only time will tell for sure.

Thoughts on API Creation

The following is a collection of my somewhat random thoughts on API creation and the related processes.

Ability to declare provisional API is an essential step in API creation. You cannot be sure that the API is right until you received sufficient and diverse feedback. It is impossible to attain that level of feedback with one release cycle. Most external adopters will not start looking at a release until it's close to being finished. They will not start building products on it until even later. The best you will get early on is "yeah, that looks about right", which is not good enough.
Placing provisional API in an internal package (such as internal.provisonal convention sometimes used by Eclipse Platform ) creates unnecessary churn for adopters and committers. Consider the case where provisional API turns out to be 90% correct. The advantage of the internal.provisional approach is that you don't have to separately define expectations for provisional code (it gets treated as internal by virtue of the package name), but I would argue that it's worth taking the time to define a separate contract for provisional API since allowing provisional API in non-internal packages results in less work for both adopters and committers.
It's important to have a good system for determining whether API is ready to be declared as fully supported (not provisional any more). Leaving the decision completely in the hands of committers or even project leads can lead to problems since people are inherently biased towards their own code. Some things to check when deciding if API is ready to be declared are level of documentation, unit test coverage, presence of outstanding API issues in bugzilla and level (as well as diversity) of adopter feedback. I prefer a system where a committer nominates the API for declaration and there is a process where other committers and adopters can raise objections.
It's important to carefully balance the needs of committers working on the API and adopters consuming the API. It's a mistake to only look at the problem from the perspective of resource expenditure. For any successful platform, there will always be far fewer resources working on the platform than consuming the platform. Trying to add too much protection for platform adopters can inhibit innovation in the platform and ultimately hurt those same adopters.

Eclipse Nexus Project Proposal

2008-09-30T10:53:00.001-07:00

It's an unfortunate fact that many Eclipse projects operate in their own little worlds without knowledge of or collaboration with other projects. This leads to code duplication and visible seams in the finished Eclipse product. Part of the problem is social. It's hard to keep track of all the projects out there and even harder to reach out to discuss collaboration, but a big part of it is also due to the lack of infrastructure that facilitates code sharing efforts. Consider the situation where two sibling projects (no dependency on each other) want to collaborate on some shared code. There is really no effective way for this collaboration to take place. Where would you put the shared code?

In order to try to address this problem, I have been working a proposal for Eclipse Nexus Project that would take on facilitating such collaboration. Right now, I am discussing the draft proposal with the Eclipse Technology Project PMC which would serve as a host for Nexus as it gets off the ground.

Anyone interested in learning more or in joining the effort can read the draft proposal, add themselves to the wiki, contact me directly, etc.

Eclipse Nexus Project Proposal Wiki

Facets FAQ : Supporting modular runtimes

2008-09-18T18:01:00.001-07:00

This is the first entry in a series of posts where I will answer some frequently asked questions about the Faceted Project Framework in Eclipse.

Question: Some application servers such as WebLogic and JBoss are modular in nature. Various components of the server can be selectively present or absent. Further, even if the component is present, a particular configuration of the server might turn that component on or off. So say I have a portal server component and a corresponding facet for enabling tooling related to that portal component. I want the portal facet to only be available for selection if the targeted runtime includes the portal component. How do I set that up?

Answer: Faceted Project Framework models runtimes as made up of one or more runtime components. When you create a facet, you get to declare which runtime components it is supported on. In addition to what's specified explicitly, the facet will have implicit constraints on runtimes based on the dependencies that it declares on other facets.

Let's take the portal example described in the question. A Java application server will typically be modeled as composed of at least two runtime components. One will represent the JRE that the server is running on. The other will represent the base application server with all of its core capabilities. In the portal example, we will want to add a third runtime component to the mix to represent the portal module. Once we do that, we can easily map the portal facet to the portal component and facet will only be shown to the user if the runtime component is present in the runtime.

The following little snippet declares a portal runtime component and maps portal facet (assumed to be already declared) to it.

<extension point="org.eclipse.wst.common.project.facet.core.runtimes">
  <runtime-component-type id="sample-portal-component"/>
  <runtime-component-version type="sample-portal-component" version="1.0"/>
  <supported>
    <runtime-component id="sample-portal-component" version="1.0"/>
    <facet id="sample-portal-facet" version="1.0"/>
  </supported>
</extension>

So how do I add runtime components to my runtime? In WTP there is a bridge that translates runtimes defined using WTP Server Tools API to API that's understood by Faceted Project Framework. The default behavior of the bridge is to create two-component runtimes as described in the previous paragraph, but there is an extension point that lets you add a component provider that will be called when bridge is converting the runtime. Here is how you add declare a component provider:

<extension point="org.eclipse.jst.server.core.internalRuntimeComponentProviders">
  <runtimeComponentProvider
    id="[extension-id]"
    class="[provider-class-name]"
    runtimeTypeIds="[server-tools-runtime-id]"/>
</extension>

Once invoked, the component provider can examine various aspects of the runtime (such as state on disk at the location pointed to by the runtime or settings in the workspace). It can then construct and return the appropriate runtime components that will be merged with components created by the bridge to create a fully-specified runtime definition. Here is a sketch of how such component provider might look like:

import java.io.File;
import java.util.ArrayList;
import java.util.List;

import org.eclipse.wst.common.project.facet.core.runtime.IRuntimeComponent;
import org.eclipse.wst.common.project.facet.core.runtime.IRuntimeComponentType;
import org.eclipse.wst.common.project.facet.core.runtime.IRuntimeComponentVersion;
import org.eclipse.wst.common.project.facet.core.runtime.RuntimeManager;
import org.eclipse.wst.server.core.IRuntime;
import org.eclipse.wst.server.core.internal.facets.RuntimeFacetComponentProviderDelegate;

public final class SampleRuntimeComponentProvider extends RuntimeFacetComponentProviderDelegate
{
    private static final IRuntimeComponentType PORTAL_TYPE 
        = RuntimeManager.getRuntimeComponentType( "sample.portal.component" );
    
    private static final IRuntimeComponentVersion PORTAL_VERSION_1 
        = PORTAL_TYPE.getVersion( "1.0" );
    
    public List<IRuntimeComponent> getRuntimeComponents( final IRuntime runtime )
    {
        final File location = runtime.getLocation().toFile();
        final List<IRuntimeComponent> components = new ArrayList<IRuntimeComponent>();
        
        if( isPortalPresent( location ) )
        {
            final IRuntimeComponent portalComponent
                = RuntimeManager.createRuntimeComponent( PORTAL_VERSION_1, null );
            
            components.add( portalComponent );
        }
    }
    
    private static boolean isPortalPresent( final File location )
    {
        return false;  // TODO: Implement the check for portal.
    }
}

Calling all UI experts

2008-09-18T16:43:00.001-07:00

So I was working on an Eclipse form-based editor the other day when I came across a rather interesting UI puzzle. In my model, I have an enumeration field. Depending on what the user selects, certain other detail fields become relevant and need to be shown. Previously, I have solved this problem by putting the master combo field first followed by a details frame that contains all the detail fields and is updated when combo selection is made. That worked relatively well when that master-details block was in a section by itself, but as soon as it got surrounded by other fields, it started to become difficult to tell at a glance that the combo and the frame belonged together and were separate from other fields in the section.

See for yourself...

Besides dancing around the problem by adding a little white space above the master combo or putting the entire master-details block into a section by itself, one other approach occurred to me. Here, the master and detail fields are next to each other and enclosed together in a frame.

Both approaches have their pluses and minuses. The second approach does make it more clear that master and details are tied together, but we loose the ability to identify what is master and what is details. My question for the UI experts out there is how do you typically render such master-details blocks? Do you use one of these approaches that I described? Something else entirely?

In San Francisco area next week

2008-09-18T16:29:00.001-07:00

I will be in the San Francisco area visiting Oracle HQ next week. Send me an e-mail if you are in the area and want to get together for drinks after work and talk about Eclipse, WTP, etc.

Are Eclipse committer elections a little too open?

2008-09-10T09:02:00.000-07:00

Since I became a committer on Eclipse WTP project a few years ago, I have witnessed and participated in many committer elections. One aspect of the way elections are conducted struck me as somewhat problematic. Clearly having transparent processes is important to an open source community, but I wonder if there is such thing as too much of a good thing. In all the committer elections that I observed, I have never seen a single negative vote. That somewhat defeats the point of having an election in the first place. As you can imagine, I have a theory for why negative votes don't happen and I am curious if other people agree with my observations... Consider that a nominated contributor likely knows a few existing committers on the project in other ways than just interactions over past contributions. Perhaps the nominee works for the same employer. These committers might have a vested interest in getting the nominee elected. Then suppose, you have another committer on the project who has a real objection to the nominee getting elected. What options does this committer have? He can vote his true opinion and likely face retribution from other committers on the project (thus making it more difficult for him to work on the project). He can bite his tongue and abstain. Or he might actually feel compelled to vote +1. Since voting record is visible, he might feel that even abstaining would jeopardize his working relationship with other committers on the project. I wonder if a system where only EMO knows who voted how and public record hides the names (comments would still be shown) would create an environment for more effective committer elections?

Designing API for fragile content

2008-09-05T09:16:00.000-07:00

Just as with any other profession, programming involves quite a bit of monotonous and repetitive work. Interesting problems do come up, of course, but not so frequently that encountering one always brings a smile to my face. One of my deep interests in the programming profession is API design, so it would be fair to say that when I recently encountered a tricky API design puzzle I got pretty excited. So I was tasked with building a forms-based editor in Eclipse for an XML file with a certain schema. I started out by extending the XML source editor that's part of WTP. That gave the source view tab for my editor and I could access XML DOM that the source editor exposed. Any changes I made to the DOM would propagate to the source buffer. That's a pretty good start, but I did not want my forms UI working directly with DOM. I don't know if DOM API has any fans, but I am certainly not one of them. I didn't want my UI code getting cluttered with it. Ok, easy enough. Just take DOM and wrap it in API custom-created for the schema. Many of the elements in this particular document schema are tightly-typed. There are integers, class names, file paths, etc. My first cut at the API used these types in the getters and setters...

Integer getMinDuration();
void setMinDuration( Integer minDuration );

That works well enough when content is well-formed, but this is an XML file that's edited directly by users. Handling of malformed content is very important. Let's say that the min-duration element is found, but it's content cannot be parsed as an integer. The only option that the above API left me was to return null. That might be acceptable in some cases, but it's produces a rather poor user experience in the context of an editor. The text field that would be bound to this property would be blank, forcing the user to either type in a new value or revert to the source view in order to fix the existing value. What I wanted to do is show the malformed value in the text field together with a problem decoration so that the user can see and fix it easily. Ok, so let's augment the API a bit...

Integer getMinDuration();
String getMinDurationUnparsed();
void setMinDuration( Integer minDuration );
void setMinDuration( String minDuration );

That's better, but min duration has a default value and only positive integers are valid. A bit more API augmentation was in order...

Integer getMinDuration();
String getMinDurationUnparsed();
Integer getMinDurationDefault();
void setMinDuration( Integer minDuration );
void setMinDuration( String minDuration );
IStatus validateMinDuration();

Now I had enough information in the API to build the UI that I needed, but the API was starting to smell a bit. That's six methods for one element in the schema that has dozens of elements. There has to be a better way to structure this API. After some head-scratching, I decided to try returning a surrogate object from the getter method instead of the actual value. The surrogate would handle parsing, default values and validation...

IntegerValue getMinDuration();
void setMinDuration( Integer minDuration );
void setMinDuration( String minDuration );

class IntegerValue
{
    String getString();
    String getString( boolean useDefault );
    Integer getParsedValue();
    Integer getParsedValue( boolean useDefault );
    IStatus validate();
}

The getMinDuration() method would always return a non-null surrogate object. The caller then decides what aspect of value they are interested in querying. The IntegerValue class supplies default validation logic for handling unparsable content, but additional validation can be added. For instance, in this case only integers greater than zero are valid. Since range is a pretty common constraint, I made the IntegerValue constructor take the min and max values (in addition to the raw string value of the property and the default value). More complicated validation scenarios can be handled by subclassing the IntegerValue class. Note that only the getter deals with surrogate object. I wanted to keep the surrogate objects immutable so that they can be handled in a manner similar to basic value types without worrying about synchronization. When setting a value, you either have a raw value (either it can't be parsed or the code in question doesn't want to deal with parsing it) or you have a tightly-typed value. An overloaded setter method takes care of both of these scenarios. As you can imagine, it was simple at this point to extend this pattern to other types. I created a base class for all value types, which made it possible for some code to handle variety of types without knowing what they actually are. A good example of this is text field data binding code. Since any value can be retrieved and set as a string, any value can be bound to a text field.

abstract class Value<T>
{
    String getString();
    String getString( boolean useDefault );
    T getParsedValue();
    T getParsedValue( boolean useDefault );
    IStatus validate();
}

class IntegerValue extends Value<Integer>
{
    ...
}

I actually ended up using the same pattern even for properties that were strings by creating a StringValue class. Even though there is no parsing involved, the benefit of having consistent access to default value handling and validation made it worth it. So what do you think?