001 package org.nakedobjects.applib.annotation;
002
003 import java.lang.annotation.ElementType;
004 import java.lang.annotation.Inherited;
005 import java.lang.annotation.Retention;
006 import java.lang.annotation.RetentionPolicy;
007 import java.lang.annotation.Target;
008
009 import org.nakedobjects.applib.adapters.EncoderDecoder;
010 import org.nakedobjects.applib.adapters.ValueSemanticsProvider;
011
012
013 /**
014 * Indicates that the class has value semantics.
015 *
016 * <p>
017 * By "value semantics" all we actually mean that the class is {@link Aggregated} and so therefore
018 * (conceptually) is not shared between instances of classes. However, values very often have other semantics,
019 * and so this annotation allows these to also be specified:
020 * <li> it may be parseable (as per {@link Parseable})</li>
021 * <li> it may be encodeable (as per {@link Encodable})</li>
022 * <li> it may be immutable (as per {@link Immutable}), and by default is presumed that it is</li>
023 * <li> it may follow the equal-by-content contract (as per {@link EqualByContent}), and by default is
024 * presumed that it does.</i>
025 * </ul>
026 *
027 * <p>
028 * Note also that though a value is conceptually not shared, if it is also {@link Immutable immutable} then it
029 * is in fact safe to share objects (as in the flyweight pattern). In addition, the {@link EqualByContent}
030 * semantic means that we needn't care whether value types are being shared or not.
031 *
032 * @see Aggregated
033 * @see Parseable
034 * @see Encodable
035 * @see Immutable
036 * @see EqualByContent
037 */
038 @Inherited
039 @Target( { ElementType.TYPE })
040 @Retention(RetentionPolicy.RUNTIME)
041 public @interface Value {
042
043 /**
044 * The fully qualified name of a class that implements the {@link ValueSemanticsProvider} interface.
045 *
046 * <p>
047 * This is optional because some implementations may pick up encodeability via a configuration file, or
048 * via the equivalent {@link #semanticsProviderClass()}.
049 *
050 * <p>
051 * It is possible for value classes to act as their own semantics providers, and may in particular
052 * implement the {@link EncoderDecoder} interface. The framework requires that the nominated class
053 * provides a <tt>public</tt> no-arg constructor on the class, and will instantiates an instance of the
054 * class to interact with it. In the case of encoding, the framework uses the result of discards the
055 * instantiated object. What that means in particular is that a self-encoding class shouldn't encode its
056 * own state, it should encode the state of the object passed to it.
057 *
058 * <p>
059 * Implementation note: the default value provided here is simply an empty string because <tt>null</tt>
060 * is not a valid default.
061 */
062 String semanticsProviderName() default "";
063
064 /**
065 * As per {@link #semanticsProviderName()}, but specifying a class literal rather than a fully qualified
066 * class name.
067 *
068 * <p>
069 * Implementation note: the default value provided here is simply the {@link Value}'s own class, because
070 * <tt>null</tt> is not a valid default.
071 */
072 Class<?> semanticsProviderClass() default Value.class;
073
074 }