001    package org.nakedobjects.applib.adapters;
002    
003    import java.math.BigDecimal;
004    
005    import org.nakedobjects.applib.annotation.Aggregated;
006    import org.nakedobjects.applib.annotation.Defaulted;
007    import org.nakedobjects.applib.annotation.Encodable;
008    import org.nakedobjects.applib.annotation.EqualByContent;
009    import org.nakedobjects.applib.annotation.Immutable;
010    import org.nakedobjects.applib.annotation.Parseable;
011    import org.nakedobjects.applib.annotation.Value;
012    
013    
014    /**
015     * Provides a mechanism for providing a set of value semantics.
016     * 
017     * <p>
018     * As explained in the Javadoc of the {@link Value} annotation, value semantics only actually implies that the
019     * type is {@link Aggregated aggregated}. However, values are very often also {@link Parseable},
020     * {@link Encodable}, {@link Immutable} and implement {@link EqualByContent} semantics. In addition, there
021     * may be a {@link Defaulted default value}.
022     * 
023     * <p>
024     * This interface is used by {@link Value} to allow these semantics to be provided through a single point.
025     * Alternatively, {@link Value} supports this information being provided via the configuration files.
026     * 
027     * <p>
028     * Whatever the class that implements this interface, it must also expose either a
029     * <tt>public</tt> no-arg constructor, or (for implementations that also are <tt>Facet</tt>s) 
030     * a <tt>public</tt> constructor that accepts a single <tt>FacetHolder</tt>.  This constructor allows the 
031     * framework to instantiate the object reflectively.
032     * 
033     * @see Parser
034     * @see EncoderDecoder
035     * @see DefaultsProvider
036     */
037    public interface ValueSemanticsProvider<T> {
038    
039        /**
040         * The {@link Parser}, if any.
041         * 
042         * <p>
043         * If not <tt>null</tt>, implies that the value is {@link Parseable}.
044         */
045        Parser<T> getParser();
046    
047        /**
048         * The {@link EncoderDecoder}, if any.
049         * 
050         * <p>
051         * If not <tt>null</tt>, implies that the value is {@link Encodable}.
052         */
053        EncoderDecoder<T> getEncoderDecoder();
054    
055        /**
056         * The {@link DefaultsProvider}, if any.
057         * 
058         * <p>
059         * If not <tt>null</tt>, implies that the value has (or may have) a default.
060         */
061        DefaultsProvider<T> getDefaultsProvider();
062    
063        /**
064         * Whether the value is {@link Immutable}.
065         */
066        boolean isImmutable();
067    
068        /**
069         * Whether the value has {@link EqualByContent equal by content} semantics.
070         * 
071         * <p>
072         * If so, then it must implement <tt>equals(Object)</tt> and <tt>hashCode()</tt> consistently.
073         * Examples in the Java language that do this are {@link String} and {@link BigDecimal}, for example.
074         */
075        boolean isEqualByContent();
076    
077    }
078    
079    // Copyright (c) Naked Objects Group Ltd.