001 package org.nakedobjects.applib.adapters;
002
003 import org.nakedobjects.applib.annotation.TypicalLength;
004
005
006 /**
007 * Provides a mechanism for parsing and rendering string representations of objects.
008 *
009 * <p>
010 * Specifically, this interface embodies three related capabilties:
011 * <ul>
012 * <li> to parse a string representation and convert to an object.
013 * <li> to provide a string representation of the object, for use as its title.
014 * <li> to indicate the typical length of such a string representation.
015 * </ul>
016 *
017 * <p>
018 * For custom-written (as opposed to third-party) value types, the ability for the {@link Parser} to provide a
019 * title responsibilities overlap with other conventions for domain objects. Specifically, normally we write a
020 * <tt>title()</tt> method to return a title. In such cases a typical implementation of {@link Parser} would
021 * just delegate to the value type itself to obtain the title (ie invoking the <tt>title()</tt> method
022 * directly rather than having the framework do this).
023 *
024 * <p>
025 * Similarly, the ability to return a typical length also overlaps with the {@link TypicalLength} annotation;
026 * which is why {@link TypicalLength} cannot be applied to types, only to properties and parameters.
027 *
028 * <p>
029 * For third-party value types, eg {@link http://timeandmoney.sourceforge.net/ Time-and-Money} there is no
030 * ability to write <tt>title()</tt> methods or annotated with {@link TypicalLength}; so this is the main
031 * reason that this interface has to deal with titles and lengths.
032 *
033 * <p>
034 * This interface is used in two complementary ways:
035 * <ul>
036 * <li> As one option, it allows objects to take control of their own parsing, by implementing directly.
037 * However, the instance is used as a factory for itself. The framework will instantiate an instance, invoke
038 * the appropriate method method, and use the returned object. The instantiated instance itself will be
039 * discarded.</li>
040 * <li> Alternatively, an implementor of this interface can be nominated in the
041 * {@link org.nakedobjects.applib.annotation.Parseable} annotation, allowing a class that needs to be
042 * parseable to indicate how it can be parsed. </li>
043 *
044 * <p>
045 * Whatever the class that implements this interface, it must also expose either a
046 * <tt>public</tt> no-arg constructor, or (for implementations that also are <tt>Facet</tt>s)
047 * a <tt>public</tt> constructor that accepts a single <tt>FacetHolder</tt>. This constructor allows the
048 * framework to instantiate the object reflectively.
049 *
050 * @see DefaultsProvider
051 * @see EncoderDecoder
052 * @see ValueSemanticsProvider
053 */
054 public interface Parser<T> {
055
056 /**
057 * Parses a string to an instance of the object.
058 *
059 * <p>
060 * Note that here the implementing class is acting as a factory for itself.
061 *
062 * @param context -
063 * the context in which the text is being parsed. For example +3 might mean add 3 to the
064 * current number.
065 */
066 T parseTextEntry(T context, String entry);
067
068 /**
069 * The typical length of objects that can be parsed.
070 */
071 int typicalLength();
072
073 /**
074 * The title of the object.
075 */
076 String displayTitleOf(T object);
077
078 /**
079 * The title of the object using a mask.
080 */
081 String displayTitleOf(T object, String usingMask);
082
083 /**
084 * A title for the object that is valid but which may be easier to edit than the title provided by a
085 * {@link org.nakedobjects.metamodel.facets.object.ident.TitleFacet}.
086 *
087 * <p>
088 * The idea here is that the viewer can display a parseable title for an existing object when, for
089 * example, the user initially clicks in the field. So, a date might be rendered via a {@link TitleFacet}
090 * as <tt>May 2, 2007</tt>, but its editable form might be <tt>20070502</tt>.
091 */
092 String parseableTitleOf(T existing);
093
094 }
095
096 // Copyright (c) Naked Objects Group Ltd.