# 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.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.Length.List | An implementation of FactsService that creates fact statements about a list property's item count constraints by using the semantical information specified by the @Length annotation or the deprecated @CountConstraint annotation.
Sapphire.FactsService.Length.Value | An implementation of FactsService that creates fact statements about a value property's text length constraints by using the semantical information specified by the @Length 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 );

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