# Migration Guide for Sapphire 0.6

This documents covers changes that need to be made by Sapphire adopters as part of migrating to Sapphire 0.6 from a prior release. Only changes from the previous major release are covered.

Table of Contents

1. DefaultValueService
2. DerivedValueService
3. EnablementService
4. FactsAggregationService
5. FactsService
6. Filter
7. FormEditorPage
8. FormPart
9. FormPartDef
10. IModelElement
11. ISapphireCompositeDef
12. ISapphireDialogDef
13. ISapphireSectionDef
14. ISapphireSeparatorDef
15. ISapphireSpacerDef
16. ISapphireWizardDef
17. ISapphireWizardPageDef
18. MasterDetailsContentNode
19. MasterDetailsContentOutline
20. MasterDetailsEditorPage
21. ModelElementType
22. ModelProperty
23. PartDef
24. PropertyEditorDef
25. ReadOnlyListFactory
26. ReadOnlyMapFactory
27. ReadOnlySetFactory
28. SapphireControl
29. SapphireDiagramEditor
30. SapphireDialog
31. SapphireEditor
32. SapphireEditorForXml
33. SapphireModelCondition
34. SapphirePart
35. SapphirePartContainer
36. SapphirePropertyEnabledCondition
37. SapphireSection
38. SapphireSeparator
39. SapphireSpacer
40. SapphireUiDefFactory
41. SapphireWizard
42. Service
43. Status
44. ValidationChangedEvent
45. Conditional
46. Section Visibility
47. Node Visibility
48. Node Factory Visibility
49. Hide If Disabled Hint

## DefaultValueService

Before | After
--- | ---

    public class ExampleDefaultValueService extends DefaultValueService
    {
        @Override
        protected DefaultValueServiceData data()
        {
            ...
        }
    }

    public class ExampleDefaultValueService extends DefaultValueService
    {
        @Override
        public DefaultValueServiceData data()
        {
            ...
        }
    }

## DerivedValueService

Before | After
--- | ---

    public class ExampleDerivedValueService extends DerivedValueService
    {
        @Override
        protected DerivedValueServiceData data()
        {
            ...
        }
    }

    public class ExampleDerivedValueService extends DerivedValueService
    {
        @Override
        public DerivedValueServiceData data()
        {
            ...
        }
    }

## EnablementService

Before | After
--- | ---

    public class ExampleEnablementService extends EnablementService
    {
        @Override
        protected EnablementServiceData data()
        {
            ...
        }
    }

    public class ExampleEnablementService extends EnablementService
    {
        @Override
        public EnablementServiceData data()
        {
            ...
        }
    }

## FactsAggregationService

Before | After
--- | ---

    List<String> facts = element.service( property, FactsAggregationService.class ).facts()

    SortedSet<String> facts = element.service( property, FactsAggregationService.class ).facts()

## FactsService

Before | After
--- | ---

    public class ExampleFactsService extends FactsService
    {
        @Override
        protected void facts( List<String> facts )
        {
            ...
        }
    }

    public class ExampleFactsService extends FactsService
    {
        @Override
        protected void facts( SortedSet<String> facts )
        {
            ...
        }
    }

## Filter

Before | After
--- | ---

    org.eclipse.sapphire.modeling.util.Filter

    org.eclipse.sapphire.util.Filter

    public class ExampleFilter extends Filter<String>
    {
        @Override
        public boolean check( String element )
        {
            ...
        }
    }

    public class ExampleFilter extends Filter<String>
    {
        @Override
        public boolean allows( String element )
        {
            ...
        }
    }

## FormEditorPage

Before | After
--- | ---

    new FormEditorPage
    {
        this, element,
        new Path( "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef/ExamplePage" )
    }

    new FormEditorPage
    {
        this, element,
        DefinitionLoader
            .context( getClass().getClassLoader() )
            .sdef( "org.eclipse.sapphire.examples.Examples" )
            .page( "ExamplePage" )
    }

## FormPart

Before | After
--- | ---

    FormPart

    FormComponentPart

## FormPartDef

Before | After
--- | ---

    FormPartDef

    FormComponentDef

## IModelElement

Before | After
--- | ---

    ContactAddress address = element.read( Contact.PROP_ADDRESS );

    ContactAddress address = element.read( Contact.PROP_ADDRESS ).element();

    element.write( (ValueProperty) property, content )

    element.write( property, content )

    element.write( (TransientProperty) property, content )

    element.write( property, content )

## ISapphireCompositeDef

Before | After
--- | ---

    ISapphireCompositeDef

    CompositeDef

## ISapphireDialogDef

Before | After
--- | ---

    ISapphireDialogDef

    DialogDef

## ISapphireSectionDef

Before | After
--- | ---

    ISapphireSectionDef

    SectionDef

## ISapphireSeparatorDef

Before | After
--- | ---

    ISapphireSeparatorDef

    LineSeparatorDef

## ISapphireSpacerDef

Before | After
--- | ---

    ISapphireSpacerDef

    WhitespaceSeparatorDef

## ISapphireWizardDef

Before | After
--- | ---

    ISapphireWizardDef

    WizardDef

## ISapphireWizardPageDef

Before | After
--- | ---

    ISapphireWizardPageDef

    WizardPageDef

## MasterDetailsContentNode

Before | After
--- | ---

    node.isVisible()

    node.visible()

    node.hasChildNodes()

    node.nodes().visible().isEmpty()

    node.getChildNodes()

    node.nodes().visible()

    node.getChildNodeByLabel( text )

    node.findNode( text )

    node.findNodeByModelElement( element )

    node.findNode( element )

    MasterDetailsContentNode.HINT_HIDE_IF_DISABLED

The hide.if.disabled hint no longer exists. See migration notes for equivalent functionality.

## MasterDetailsContentOutline

Before | After
--- | ---

    outline.refresh()

No direct equivalent has been provided. The outline will update itself without explicit refresh calls. For further guidance, post a question on Sapphire Adopter Forum.

    outline.attach
    (
        new Listener()
        {
            @Override
            public void handle( Event event )
            {
                if( event instanceof MasterDetailsContentOutline.NodeUpdatedEvent )
                {
                    ...
                }
            }
        }
    )

    node.attach
    (
        new Listener()
        {
            @Override
            public void handle( Event event )
            {
                if( event instanceof SapphirePart.LabelChangedEvent ||
                    event instanceof SapphirePart.ImageChangedEvent )
                {
                    ...
                }
            }
        }
    )

Note that the equivalent events are on the nodes, not on the outline.

    outline.attach
    (
        new Listener()
        {
            @Override
            public void handle( Event event )
            {
                if( event instanceof MasterDetailsContentOutline.NodeStructureChangedEvent )
                {
                    ...
                }
            }
        }
    )

    node.attach
    (
        new Listener()
        {
            @Override
            public void handle( Event event )
            {
                if( event instanceof SapphirePart.VisibilityChangedEvent ||
                    event instanceof MasterDetailsContentNode.NodeListEvent )
                {
                    ...
                }
            }
        }
    )

Note that the equivalent events are on the nodes, not on the outline.

    outline.notifyOfNodeUpdate( node )

No direct equivalent has been provided. The outline will update itself without explicit notify calls. For further guidance, post a question on Sapphire Adopter Forum.

    outline.notifyOfNodeStructureChange( node )

No direct equivalent has been provided. The outline will update itself without explicit notify calls. For further guidance, post a question on Sapphire Adopter Forum.

## MasterDetailsEditorPage

Before | After
--- | ---

    new MasterDetailsEditorPage
    {
        this, element,
        new Path( "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef/ExamplePage" )
    }

    new MasterDetailsEditorPage
    {
        this, element,
        DefinitionLoader
            .context( getClass().getClassLoader() )
            .sdef( "org.eclipse.sapphire.examples.Examples" )
            .page( "ExamplePage" )
    }

## ModelElementType

Before | After
--- | ---

    type.attach( listener )

No direct equivalent has been provided, but attaching the listener via @Listener annotation may be a viable substitute in some cases. For further guidance, post a question on Sapphire Adopter Forum.

## ModelProperty

Before | After
--- | ---

    property.refine( type )

    type.property( property.getName() )

    property.refine( element )

    element.property( property.getName() )

    property.attach( listener )

No direct equivalent has been provided, but attaching the listener via @Listener annotation may be a viable substitute in some cases. For further guidance, post a question on Sapphire Adopter Forum.

## PartDef

Before | After
--- | ---

    PartDef.HINT_HIDE_IF_DISABLED

The hide.if.disabled hint no longer exists. See migration notes for equivalent functionality.

## PropertyEditorDef

Before | After
--- | ---

    PropertyEditorDef.HINT_HIDE_IF_DISABLED

The hide.if.disabled hint no longer exists. See migration notes for equivalent functionality.

## ReadOnlyListFactory

Before | After
--- | ---

    ReadOnlyListFactory

    ListFactory

    ReadOnlyListFactory.create()

    ListFactory.start()

    ReadOnlyListFactory.create( element )

    ListFactory.singleton( element )

    ReadOnlyListFactory.create( collection )

    ListFactory.unmodifiable( collection )

    ReadOnlyListFactory.create( array )

    ListFactory.unmodifiable( array )

    ReadOnlyListFactory.create().add( element ).export()

    ListFactory.start().add( element ).result()

## ReadOnlyMapFactory

Before | After
--- | ---

    ReadOnlyMapFactory

    MapFactory

    ReadOnlyMapFactory.create()

    MapFactory.start()

    ReadOnlyMapFactory.create( key, value )

    MapFactory.singleton( key, value )

    ReadOnlyMapFactory.create( map )

    MapFactory.unmodifiable( map )

    ReadOnlyMapFactory.create().add( element ).export()

    MapFactory.start().add( element ).result()

## ReadOnlySetFactory

Before | After
--- | ---

    ReadOnlySetFactory

    SetFactory

    ReadOnlySetFactory.create()

    SetFactory.start()

    ReadOnlySetFactory.create( element )

    SetFactory.singleton( element )

    ReadOnlySetFactory.create( collection )

    SetFactory.unmodifiable( collection )

    ReadOnlySetFactory.create( array )

    SetFactory.unmodifiable( array )

    ReadOnlySetFactory.create().add( element ).export()

    SetFactory.start().add( element ).result()

## SapphireControl

Before | After
--- | ---

    SapphireControl

    SapphireForm

    new SapphireControl
    {
        parent, element,
        "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef!ExampleComposite"
    }

    new SapphireForm
    {
        parent, element,
        DefinitionLoader
            .context( getClass().getClassLoader() )
            .sdef( "org.eclipse.sapphire.examples.Examples" )
            .form( "ExampleComposite" )
    }

    form.getModelElement()

    form.element()

    form.getPart()

    form.part()

## SapphireDiagramEditor

Before | After
--- | ---

    page.setDiagramHeaderText( text )

No direct equivalent has been provided, but page header text can now be specified as an expression. This accounts for the dynamic header text use cases. For further guidance, post a question on Sapphire Adopter Forum.

## SapphireDialog

Before | After
--- | ---

    new SapphireDialog
    {
        shell, element,
        "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef!ExampleDialog"
    }

    new SapphireDialog
    {
        shell, element,
        DefinitionLoader
            .context( getClass().getClassLoader() )
            .sdef( "org.eclipse.sapphire.examples.Examples" )
            .dialog( "ExampleDialog" )
    }

    dialog.getModelElement()

    dialog.element()

## SapphireEditor

Before | After
--- | ---

    public class ExampleEditor extends SapphireEditor
    {
        public ExampleEditor()
        {
            super( "org.sapphire.examples" );
        }
    }

    public class ExampleEditor extends SapphireEditor
    {
        public ExampleEditor()
        {
            super();
        }
    }

## SapphireEditorForXml

Before | After
--- | ---

    public class ExampleEditor extends SapphireEditorForXml
    {
        public ExampleEditor()
        {
            super( "org.sapphire.examples" );

            setRootModelElementType( ExampleElement.TYPE );
            setEditorDefinitionPath( "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef/EditorPage" );
        }
    }

    public class ExampleEditor extends SapphireEditorForXml
    {
        public ExampleEditor()
        {
            super
            (
                ExampleElement.TYPE,
                DefinitionLoader
                    .context( ExampleEditor.class.getClassLoader() )
                    .sdef( "org.eclipse.sapphire.examples.Examples" )
                    .page( "EditorPage" )
            );
        }
    }

## SapphireModelCondition

SapphireModelCondition class has been removed as part of the transition from SapphireCondition architecture to using Sapphire Expression Language. Depending on context, other sections of this migration guide may provide more details on expected migration. For further guidance, post a question on Sapphire Adopter Forum.

## SapphirePart

Before | After
--- | ---

    part.visible()

SapphirePart has a new public final visible() method that is linked with the "visible when" feature in sdef. A custom part implementation may be defining this method already, in which case the method will need to be renamed. For further guidance, post a question on Sapphire Adopter Forum.

    part.getValidationState()

    part.validation()

    part.computeValidationState()

    part.computeValidation()

    part.updateValidationState()

    part.refreshValidation()

    SapphirePart.ValidationChangedEvent

    PartValidationEvent

    SapphirePart.VisibilityChangedEvent

    PartVisibilityEvent

    SapphirePart.StructureChangedEvent

The StructureChangedEvent has been eliminated and its function subsumed by other events, such as PartVisibilityEvent and PartChildrenEvent.

## SapphirePartContainer

Before | After
--- | ---

    SapphirePartContainer

    FormPart

## SapphirePropertyEnabledCondition

SapphirePropertyEnabledCondition class has been removed as part of the transition from SapphireCondition architecture to using Sapphire Expression Language. Depending on context, other sections of this migration guide may provide more details on expected migration. For further guidance, post a question on Sapphire Adopter Forum.

## SapphireSection

Before | After
--- | ---

    SapphireSection

    SectionPart

    section.checkVisibleWhenCondition()

    section.visible()

    section.getVisibleWhenCondition()

No direct equivalent has been provided. It is possible to check section visibility using visible() method and to listen for visibility changes using VisibilityChangedEvent, but it is no longer possible to access the actual visibility condition. For further guidance, post a question on Sapphire Adopter Forum.

## SapphireSeparator

Before | After
--- | ---

    SapphireSeparator

    LineSeparatorPart

## SapphireSpacer

Before | After
--- | ---

    SapphireSpacer

    WhitespaceSeparatorPart

## SapphireUiDefFactory

Before | After
--- | ---

    ISapphireUiDef def = SapphireUiDefFactory.load
    (
        "org.eclipse.sapphire.examples",
        "org/eclipse/sapphire/examples/Examples.sdef"
    );

    DefinitionLoader.Reference<ISapphireUiDef> defref = DefinitionLoader
        .context( BundleBasedContext.adapt( "org.eclipse.sapphire.examples" ) )
        .sdef( "org.eclipse.sapphire.examples.Examples" )
        .root();

    try
    {
        ISapphireUiDef def = defref.resolve();
    }
    finally
    {
        // Do not dispose the definition reference until the definition is not
        // needed any longer.

        defref.dispose();
    }

    ISapphireUiDef def = SapphireUiDefFactory.load
    (
        sapphireUiDefinition,
        "org/eclipse/sapphire/examples/Examples.sdef"
    );

No direct equivalent has been provided. For further guidance, post a question on Sapphire Adopter Forum.

    ISapphireUiDef def = SapphireUiDefFactory.load
    (
        xmlResourceStore,
        writable
    );

No direct equivalent has been provided. For further guidance, post a question on Sapphire Adopter Forum.

    ISapphireCompositeDef def = SapphireUiDefFactory.getCompositeDef
    (
       "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef!ExampleComposite"
    );

    DefinitionLoader.Reference<FormComponentDef> defref = DefinitionLoader
        .context( BundleBasedContext.adapt( "org.eclipse.sapphire.examples" ) )
        .sdef( "org.eclipse.sapphire.examples.Examples" )
        .form( "ExampleComposite" );

    try
    {
        CompositeDef def = (CompositeDef) defref.resolve();
    }
    finally
    {
        // Do not dispose the definition reference until the definition is not
        // needed any longer.

        defref.dispose();
    }

    ISapphireCompositeDef def = SapphireUiDefFactory.getCompositeDef
    (
        "org.eclipse.sapphire.examples",
        "org/eclipse/sapphire/examples/Examples.sdef",
        "ExampleComposite"
    );

    DefinitionLoader.Reference<FormComponentDef> defref = DefinitionLoader
        .context( BundleBasedContext.adapt( "org.eclipse.sapphire.examples" ) )
        .sdef( "org.eclipse.sapphire.examples.Examples" )
        .form( "ExampleComposite" );

    try
    {
        CompositeDef def = (CompositeDef) defref.resolve();
    }
    finally
    {
        // Do not dispose the definition reference until the definition is not
        // needed any longer.

        defref.dispose();
    }

    ISapphireDialogDef def = SapphireUiDefFactory.getDialogDef
    (
       "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef!ExampleDialog"
    );

    DefinitionLoader.Reference<DialogDef> defref = DefinitionLoader
        .context( BundleBasedContext.adapt( "org.eclipse.sapphire.examples" ) )
        .sdef( "org.eclipse.sapphire.examples.Examples" )
        .dialog( "ExampleDialog" );

    try
    {
        DialogDef def = defref.resolve();
    }
    finally
    {
        // Do not dispose the definition reference until the definition is not
        // needed any longer.

        defref.dispose();
    }

    ISapphireDialogDef def = SapphireUiDefFactory.getDialogDef
    (
        "org.eclipse.sapphire.examples",
        "org/eclipse/sapphire/examples/Examples.sdef",
        "ExampleDialog"
    );

    DefinitionLoader.Reference<DialogDef> defref = DefinitionLoader
        .context( BundleBasedContext.adapt( "org.eclipse.sapphire.examples" ) )
        .sdef( "org.eclipse.sapphire.examples.Examples" )
        .dialog( "ExampleDialog" );

    try
    {
        DialogDef def = defref.resolve();
    }
    finally
    {
        // Do not dispose the definition reference until the definition is not
        // needed any longer.

        defref.dispose();
    }

    ISapphireWizardDef def = SapphireUiDefFactory.getWizardDef
    (
       "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef!ExampleWizard"
    );

    DefinitionLoader.Reference<WizardDef> defref = DefinitionLoader
        .context( BundleBasedContext.adapt( "org.eclipse.sapphire.examples" ) )
        .sdef( "org.eclipse.sapphire.examples.Examples" )
        .wizard( "ExampleWizard" );

    try
    {
        WizardDef def = defref.resolve();
    }
    finally
    {
        // Do not dispose the definition reference until the definition is not
        // needed any longer.

        defref.dispose();
    }

    ISapphireWizardDef def = SapphireUiDefFactory.getWizardDef
    (
        "org.eclipse.sapphire.examples",
        "org/eclipse/sapphire/examples/Examples.sdef",
        "ExampleWizard"
    );

    DefinitionLoader.Reference<WizardDef> defref = DefinitionLoader
        .context( BundleBasedContext.adapt( "org.eclipse.sapphire.examples" ) )
        .sdef( "org.eclipse.sapphire.examples.Examples" )
        .wizard( "ExampleWizard" );

    try
    {
        WizardDef def = defref.resolve();
    }
    finally
    {
        // Do not dispose the definition reference until the definition is not
        // needed any longer.

        defref.dispose();
    }

## SapphireWizard

Before | After
--- | ---

    new SapphireWizard
    {
        element,
        "org.eclipse.sapphire.examples/org/eclipse/sapphire/examples/Examples.sdef!ExampleWizard"
    }

    new SapphireWizard
    {
        element,
        DefinitionLoader
            .context( getClass().getClassLoader() )
            .sdef( "org.eclipse.sapphire.examples.Examples" )
            .wizard( "ExampleWizard" )
    }

    wizard.getModelElement()

    wizard.element()

## Service

Before | After
--- | ---

    broadcast( new Event() )

    broadcast( new ServiceEvent( this ) )

Events broadcast by a service must now extend ServiceEvent class. This facilitates differentiation of service events from other events and identifies the originating service.

## Status

Before | After
--- | ---

    List<Status> children = status.children()

    SortedSet<Status> children = status.children()

    Status.Severity.INFO

INFO is no longer available as validation severity. Use WARNING or OK instead.

    Status.createInfoStatus( message )

INFO is no longer available as validation severity. Use WARNING or OK instead.

## ValidationChangedEvent

Before | After
--- | ---

    SapphirePart.ValidationChangedEvent

    PartValidationEvent

## Conditional

The conditional construct in sdef has been converted to use Sapphire Expression Language instead of a class implementing SapphireCondition.

Before | After
--- | ---

    <if>
        <condition>
            <class>ExampleCondition</class>
            <parameter>...</parameter>
        </condition>
        <then>
            ...
        </then>
        <else>
            ...
        </else>
    </if>

    <if>
        <condition>${ corresponding logic as an expression }</condition>
        <then>
            ...
        </then>
        <else>
            ...
        </else>
    </if>

## Section Visibility

The method of specifying visibility of a section in sdef has been converted to use Sapphire Expression Language instead of a class implementing SapphireCondition.

Before | After
--- | ---

    <section>
        <visible-when>
            <class>ExampleCondition</class>
            <parameter>...</parameter>
        </visible-when>
        <content>
            ...
        </content>
    </section>

    <section>
        <visible-when>${ corresponding logic as an expression }</visible-when>
        <content>
            ...
        </content>
    </section>

## Node Visibility

The method of specifying visibility of a master-details content node in sdef has been converted to use Sapphire Expression Language instead of a class implementing SapphireCondition.

Before | After
--- | ---

    <node>
        <visible-when>
            <class>ExampleCondition</class>
            <parameter>...</parameter>
        </visible-when>
        <section>
            ...
        </section>
    </node>

    <node>
        <visible-when>${ corresponding logic as an expression }</visible-when>
        <section>
            ...
        </section>
    </node>

## Node Factory Visibility

The method of specifying visibility of a master-details content node factory in sdef has been converted to use Sapphire Expression Language instead of a class implementing SapphireCondition.

Before | After
--- | ---

    <node-factory>
        <property>...</property>
        <visible-when>
            <class>ExampleCondition</class>
            <parameter>...</parameter>
        </visible-when>
        <case>
            ...
        </case>
    </node-factory>

    <node-factory>
        <property>...</property>
        <visible-when>${ corresponding logic as an expression }</visible-when>
        <case>
            ...
        </case>
    </node-factory>

## Hide If Disabled Hint

The use cases covered by hide.if.disabled hint have been subsumed by the "visible when" feature.

Before | After
--- | ---

    <node>
        <hint>
            <name>hide.if.disabled</name>
            <value>true</value>
        </hint>
    </node>

    <node>
        <visible-when>${ Enabled( "ExampleProperty" ) }</visible-when>
    </node>

Copyright (c) 2016 Oracle
Content made available under the terms of Eclipse Public License.