Sapphire Developer Guide > Services

InitialValueService

InitialValueService produces a value to assign to a property when the containing model element is created.

The concept of an initial value is different from a default value. The initial value is explicitly assigned to the property during containing model element's creation. This includes writing to the backing resource (such as an XML document). In comparison, the default value is used when null is read for a property from the backing resource. As such, the default value is only visible to model consumers (such as the user interface), while the initial value is persisted.

Whether you use an initial value or a default value is frequently dictated by the requirements of the backing resource. As an example, let's consider an XML document that stores phone numbers. In this XML document, the phone number element has a type child element which contains a value like home, mobile, work, etc. Let's further say that semantically, we wish to use mobile phone number type unless specified differently. Now, if the XML schema dictates that the phone number type element is required, we would need to specify "mobile" as the initial value. If the phone number type element is optional, it would be better to specify "mobile" as the default value.

In many situations, the initial value is static and should be configured using @InitialValue annotation.

Example

@Required
@PossibleValues( values = { "home", "mobile", "work", "other" }, invalidValueSeverity = Status.Severity.OK )
@InitialValue( text = "mobile" )

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

Value<String> getType();
void setType( String type );

When the initial value varies due to runtime conditions, a custom implementation of InitialValueService can be provided.

Example

public class PhoneTypeInitialValueService extends InitialValueService
{
    @Override
    protected void initInitialValueService()
    {
        // Register listeners to invoke refresh() method when the initial value
        // may have changed.
    }

    @Override
    protected String compute()
    {
        // Compute and return the initial value.
    }

    @Override
    public void dispose()
    {
        super.dispose();

        // Remove any listeners that were added during initialization.
    }
}
@Required
@PossibleValues( values = { "home", "mobile", "work", "other" }, invalidValueSeverity = Status.Severity.OK )
@Service( impl = PhoneTypeInitialValueService.class )

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

Value<String> getType();
void setType( String type );