Leverage Properties

Polygene™ does not follow the JavaBeans standard for property support. Instead, a much more explicit concept is in place. The advantages are enormous, and the only real downside is that people are already destroyed, thinking in so called POJO terms.

If you want to reproduce what’s explained in this tutorial, remember to depend on the Core API artifact:

Table 8. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.core	org.apache.polygene.core.api	3.0.0

At runtime you will need the Core Runtime artifact too. See the Depend on Polygene™ tutorial for details.

So in Polygene, instead of writing;

public interface Book
{
    String getTitle();
    String getAuthor();
}

public interface MutableBook extends Book
{
    void setTitle( String title );
    void setAuthor( String author );
}

where we need the MutableBook to be able to initialize it (known as Type 2 Dependency Injection) on creation. From our point of view, this has many flaws. If we refactor the "Title" property, our IDE need to understand the getters and setters concept. The good news now is that they all do, but how about meta information about the property itself. For instance, how to define a system where a UI can get an Icon for "Author" in a generic way? All kinds of system has been added, such as one can create a BookBean for some metadata, and then MBeans for management. Where will it end?

We think we have a much better solution, and are bold enough to abandon the getters/setters and POJOs. The above looks like this;

public interface Book
{
    @Immutable
    Property<String> title();

    @Immutable
    Property<String> author();
}

There is more to this than meets the eye.

@Immutable annotation signals that this can’t change.
Property still have a set() method, which can be used during the initialization only.
Metadata about each Property can be declared as MetaInfo.

@Structure
Module module;
  [...snip...]

    TransientBuilder<Book> builder = module.newTransientBuilder( Book.class );
    Book prototype = builder.prototype();
    prototype.title().set( "The Death of POJOs" );
    prototype.author().set( "Niclas Hedhman" );
    Book book = builder.newInstance();
    String title = book.title().get();     // Retrieves the title.
    book.title().set( "Long Live POJOs" ); // throws an IllegalStateException

Persistence

The Property concept also allows a much better defined persistence model. In Polygene, only Property and Association instances are persisted, and that makes the semantics around the persistence system very clear.

Properties reference values only, and these values must be Serializable, which means that Properties can not contain Entities, since Entities are not Serializable. Associations are the opposite, as they must only reference Entities and nothing else.

MetaInfo

Properties can also have typed, custom meta information associated with them. Meta information is declared once per Property per Module. A Property is identified by its method name and the interface it is declared in.

Let’s say we want to create a generic Swing client that can show and navigate the domain model, without knowing the actual domain model. Such Swing client will utilize a SwingInfo property info if it is available.

public interface SwingInfo
{
    Icon icon( Rectangle size );

    String displayName( Locale locale );
}

Our generic Swing UI will be mainly reflective in nature, but when it gets hold of a Property, it can simply do;

    @Structure
    private PolygeneAPI api;
      [...snip...]

    private void addProperty( JPanel panel, Property<?> property )
    {
        SwingInfo info = api.propertyDescriptorFor( property ).metaInfo( SwingInfo.class );
        Icon icon = info.icon( SIZE_32_32 );
        panel.add(  new JLabel(info.displayName( this.locale ), icon, JLabel.CENTER) );
    }
      [...snip...]

}