# 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.