Sapphire Developer Guide > Services

FactsService

When a property is described to a user in documentation one does it with a series of short statements that define its semantics, such as "must be specified" or "maximum value is 100". When a property is described to Sapphire one does it with a series of annotations, such as @Required or @NumericRange. This duplicate specification is a maintenance problem.

A FactsService provides a means to dynamically derive statements about property's semantics based on property's metadata. The derived facts can then be presented to the user as part of documentation, property editor information popup and in other relevant places.

A single facts service can produce multiple facts and multiple facts services can be active concurrently for a given property. See FactsAggregationService for an easier way to consume all facts.

Sapphire includes a number of FactsService implementations.

ID Description
Sapphire.FactsService.AbsolutePath Creates fact statements about property's absolute path requirement by using semantical information specified by @AbsolutePath annotation.
Sapphire.FactsService.CountConstraint Creates fact statements about list property's count constraint by using semantical information specified by @CountConstraint annotation.
Sapphire.FactsService.DefaultValue Creates fact statements about property's default value by using semantical information specified by DefaultValueService and @DefaultValue annotation.
Sapphire.FactsService.Deprecated Creates fact statements about property's deprecated state by using semantical information specified by @Deprecated annotation.
Sapphire.FactsService.FileExtensions Creates fact statements about valid file extensions for property's value by using semantical information specified by @FileExtensions annotation.
Sapphire.FactsService.InitialValue Creates fact statements about property's initial value by using semantical information specified by InitialValueService and @InitialValue annotation.
Sapphire.FactsService.JavaTypeConstraint Creates fact statements about Java type property's constraints by using semantical information specified by @JavaTypeConstraints annotation.
Sapphire.FactsService.MustExist Creates fact statements about existence requirement on the entity referenced by property's value by using semantical information specified by @MustExist annotation.
Sapphire.FactsService.NumericRange Creates fact statements about numeric value property's range by using semantical information specified by @NumericRange annotation.
Sapphire.FactsService.PreferDefaultValue Creates fact statements about property's recommended value by using semantical information specified by @PreferDefaultValue annotation.
Sapphire.FactsService.ProjectRelativePath Creates fact statements about property's relative to the project path requirement by using semantical information specified by @ProjectRelativePath annotation.
Sapphire.FactsService.ReadOnly Creates fact statements about property's read-only state by using semantical information specified by @ReadOnly annotation.
Sapphire.FactsService.Required FactsService implementation that contributes fact statements based on semantics specified by RequiredConstraintService.
Sapphire.FactsService.Serialization Creates fact statements about property's serialization by using semantical information specified by the @Serialization annotation.
Sapphire.FactsService.Static Creates fact statements about property by using static content specified in @Fact and @Facts annotations.
Sapphire.FactsService.Unique Creates fact statements about value property's uniqueness constraint by using semantical information specified by @Unique annotation.
Sapphire.FactsService.ValidFileSystemResourceType Creates fact statements about valid file system resource type (file or folder) for property's value by using semantical information specified by @ValidFileSystemResourceType annotation.
Sapphire.FactsService.VersionCompatibility Creates fact statements about property's version compatibility by using semantic information specified by @Since and @VersionCompatibility annotations.
Sapphire.FactsService.WorkspaceRelativePath Creates fact statements about property's relative to the workspace path requirement by using semantical information specified by @WorkspaceRelativePath annotation.

Example

This screen capture shows user experience with some of the provided FactsService implementation. See if you can match facts in the screen capture to service implementations above.

Adopters can provide custom FactService implementations either globally using Sapphire extension system or at the property level using @Service annotation.

Example

A simple global FactsService implementation that is triggered by a hypothetical @Since property annotation.

public class SinceVersionFactsService extends FactsService
{
    @Override
    protected void facts( List facts )
    {
        Since since = property().getAnnotation( Since.class );
        facts.add( "Since version " + since.version() + "." );
    }

    public static class Factory extends ServiceFactory
    {
        @Override
        public boolean applicable( ServiceContext context,
                                   Class<? extends Service> service )
        {
            return context.find( ModelProperty.class ).hasAnnotation( Since.class );
        }

        @Override
        public Service create( ServiceContext context,
                               Class<? extends Service> service )
        {
            return new SinceVersionFactsService();
        }
    }
}

The service implementation is registered in META-INF/sapphire-extension.xml file.

<extension xmlns="http://www.eclipse.org/sapphire/xmlns/extension">
    <service>
        <id>Example.SinceVersionFactsService</id>
        <type>org.eclipse.sapphire.services.FactsService</type>
        <context>Sapphire.Property.Instance</context>
        <factory>example.SinceVersionFactsService$Factory</factory>
    </service>
</extension>

Facts can also be statically specified for a given property by using @Fact annotation. Use @Facts annotation to specify multiple facts. The facts contained in these annotations are surfaced by an included FactsService implementation (id:Sapphire.FactsService.Static).

Example

// *** ExampleOne ***

@Fact( statement = "Important fact.")

ValueProperty PROP_EXAMPLE_ONE = new ValueProperty( TYPE, "ExampleOne" );

Value<String> getExampleOne();
void setExampleOne( String value );

// *** ExampleMultiple ***

@Facts( { @Fact( statement = "First important fact." ), @Fact( statement = "Second important fact." ) } )

ValueProperty PROP_EXAMPLE_MULTIPLE = new ValueProperty( TYPE, "ExampleMultiple" );

Value<String> getExampleMultiple();
void setExampleMultiple( String value );