@Value

Indicates that the class has value semantics.

By "value semantics" all we actually mean that the class is aggregated (or embedded) and so therefore (conceptually) is not shared between instances of classes. However, values very often have other semantics, and so this annotation allows these to also be specified:

  • it may be parseable

  • it may be encodeable

  • it may be immutable, and by default is presumed that it is

  • it may follow the equal-by-content contract (as per EqualByContent ), and by default is presumed that it does.

    Note also that though a value is conceptually not shared, if it is also immutable then it is in fact safe to share objects (as in the flyweight pattern). In addition, the EqualByContent semantic means that we needn’t care whether value types are being shared or not.

API

Value.java
@interface Value {
  String logicalTypeName() default "";     (1)
  String semanticsProviderName() default "";     (2)
  Class<?> semanticsProviderClass() default Value.class;     (3)
}
1 logicalTypeName

The logical name of this value’s type, that uniquely and fully qualifies it. The logical name is analogous to - but independent of - the actual fully qualified class name. eg. sales.Customer for a class 'org.mycompany.dom.Customer'

2 semanticsProviderName

The fully qualified name of a class that implements the ValueSemanticsProvider interface.

3 semanticsProviderClass

As per #semanticsProviderName() , but specifying a class literal rather than a fully qualified class name.

Members

logicalTypeName

The logical name of this value’s type, that uniquely and fully qualifies it. The logical name is analogous to - but independent of - the actual fully qualified class name. eg. sales.Customer for a class 'org.mycompany.dom.Customer'

If not specified, the fully qualified class name is used instead.

semanticsProviderName

The fully qualified name of a class that implements the ValueSemanticsProvider interface.

This is optional because some implementations may pick up encodeability via a configuration file, or via the equivalent #semanticsProviderClass() .

It is possible for value classes to act as their own semantics providers, and may in particular implement the EncoderDecoder interface. The framework requires that the nominated class provides a public no-arg constructor on the class, and will instantiates an instance of the class to interact with it. In the case of encoding, the framework uses the result of discards the instantiated object. What that means in particular is that a self-encoding class shouldn’t encode its own state, it should encode the state of the object passed to it.

Implementation note: the default value provided here is simply an empty string because null is not a valid default.

semanticsProviderClass

As per #semanticsProviderName() , but specifying a class literal rather than a fully qualified class name.

Implementation note: the default value provided here is simply the Value 's own class, because null is not a valid default.