Sapphire Developer Guide > Releases > 0.6

Migration Guide for 0.6

This documents covers code changes that need to be made by Sapphire adopters as part of migrating to 0.6 release. Only changes from the previous 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>