Sapphire Developer Guide > Services

ElementReferenceService

ElementReferenceService provides a common implementation base for ReferenceService implementations that resolve to an Element.

In many situations, the reference semantics can be specified using the @ElementReference annotation rather than through a custom ElementReferenceService implementation.

@Reference( target = Table.class )
@ElementReference( list = "/Tables", key = "Name" )

ValueProperty PROP_TABLE = new ValueProperty( TYPE, "Table" );

ReferenceValue<String,Table> getTable();
void setTable( String value );

When more control is necessary, a custom implementation of ElementReferenceService can be provided. This is necessary, for example, when the referenced elements are located in a different model or when the list and key are variable.

@Reference( target = Table.class )
@Service( impl = ExampleElementReferenceService.class )

ValueProperty PROP_TABLE = new ValueProperty( TYPE, "Table" );

ReferenceValue<String,Table> getTable();
void setTable( String value );
public class ExampleElementReferenceService extends ElementReferenceService
{
    @Override
    protected void initReferenceService()
    {
        // Attach a listener if list or key are variable.
        // Call broadcast( new ListEvent() ) if the list changes.
        // Call broadcast( new KeyEvent() ) if the key changes.
        
        super.initReferenceService();
    }
    
    @Override
    protected ElementList<?> list()
    {
        ...
    }

    @Override
    protected String key()
    {
        ...
    }

    @Override
    public void dispose()
    {
        // Detach any listeners that were added during init.
        
        super.dispose();
    }
}

A PossibleValuesService implementation is automatically provided when @ElementReference annotation is used or ElementReferenceService is implemented.