001    package org.nakedobjects.applib.adapters;
002    
003    /**
004     * Provides a mechanism for encoding/decoding objects.
005     * 
006     * <p>
007     * This interface is used in two complementary ways:
008     * <ul>
009     * <li> As one option, it allows objects to take control of their own encoding/decoding, by implementing
010     * directly. However, the instance is used as a factory for itself. The framework will instantiate an
011     * instance, invoke the appropriate method method, and use the returned object. The instantiated instance
012     * itself will be discarded.</li>
013     * <li> Alternatively, an implementor of this interface can be nominated in the
014     * {@link org.nakedobjects.applib.annotation.Encodable} annotation, allowing a class that needs to be
015     * encodeable to indicate how it can be encoded/decoded. </li>
016     * 
017     * <p>
018     * Whatever the class that implements this interface, it must also expose either a
019     * <tt>public</tt> no-arg constructor, or (for implementations that also are <tt>Facet</tt>s) 
020     * a <tt>public</tt> constructor that accepts a single <tt>FacetHolder</tt>.  This constructor allows the 
021     * framework to instantiate the object reflectively.
022     * 
023     * @see Parser
024     * @see DefaultsProvider
025     * @see ValueSemanticsProvider
026     */
027    public interface EncoderDecoder<T> {
028    
029        /**
030         * Returns the provided object as an encoded string.
031         * 
032         * <p>
033         * Even if the class is self-encodeable, note that this method is always called on a new instance of the
034         * object created via the no-arg constructor. That is, the object shouldn't encode itself, it should
035         * encode the object provided to it.
036         */
037        String toEncodedString(T toEncode);
038    
039        /**
040         * Converts an encoded string to an instance of the object.
041         * 
042         * <p>
043         * Note that here the implementing class is acting as a factory for itself.
044         * 
045         * @see #toEncodedString(% toEncode)
046         */
047        T fromEncodedString(String encodedString);
048    
049    }
050    
051    // Copyright (c) Naked Objects Group Ltd.