001    // Copyright 2007, 2008, 2011 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry5;
016    
017    /**
018     * A ValueEncoder is used to convert server side objects to unique client-side
019     * strings (typically IDs) and back. This mechanism is widely used in Tapestry
020     * to allow you to work more seamlessly with objects rather than manually
021     * managing the encoding and decoding process throughout your application.
022     * 
023     * Tapestry uses a ValueEncoder when generating an
024     * {@link org.apache.tapestry5.EventContext} as part of a URL, and when
025     * components (such as {@link org.apache.tapestry5.corelib.components.Select})
026     * need to generate unique client-side strings to be rendered within form
027     * elements.
028     * <p/>
029     * Tapestry can automatically generate ValueEncoders for enums as well as
030     * Collections of any object types for which a coercion can be found from a
031     * formatted String, such as primitives, primitive wrappers, Dates, Calendars,
032     * "name=value" strings, and any types for which a custom coercion has been
033     * contributed.  
034     * <p/>
035     * Custom ValueEncoder implementations will need to be supplied for entity type
036     * objects. In such cases the {@link #toClient(Object)} method typically returns
037     * an object's database primary key, and the {@link #toValue(String)}
038     * re-acquires the corresponding entity object, perhaps by doing a database
039     * lookup by that ID.
040     * <p/>
041     * Some optional modules, such as Tapestry's own Hibernate and JPA modules, can
042     * automatically create a ValueEncoder for each of your entity types and then
043     * configure Tapestry to use them whenever a ValueEncoder is needed for those
044     * types. If you don't use one of those modules, you can still configure
045     * Tapestry to automatically use your custom ValueEncoder implementations by
046     * having your ValueEncoder implement the
047     * {@link org.apache.tapestry5.services.ValueEncoderFactory} interface and then
048     * contributing a ValueEncoderSource that adds your encoder, like this, in your
049     * application's module class:
050     * 
051    * <pre>
052     * public static void contributeValueEncoderSource(
053     *              MappedConfiguration&lt;Class&lt;Color&gt;, ValueEncoderFactory&lt;Color&gt;&gt; configuration)
054     * {
055     *      configuration.addInstance(Color.class, ColorEncoder.class);
056     * }
057     * </pre>
058     * 
059     * @see SelectModel
060     * @see org.apache.tapestry5.services.ValueEncoderSource
061     * @see org.apache.tapestry5.services.ValueEncoderFactory
062     * @see org.apache.tapestry5.annotations.PageActivationContext
063     */
064    public interface ValueEncoder<V>
065    {
066        /**
067         * Converts a value into a client-side representation. The value should be parseable by {@link #toValue(String)}. In
068         * some cases, what is returned is an identifier used to locate the true object, rather than a string representation
069         * of the value itself.
070         *
071         * @param value to be encoded
072         * @return a string representation of the value, or the value's identity
073         */
074        String toClient(V value);
075    
076        /**
077         * Converts a client-side representation, provided by {@link #toClient(Object)}, back into a server-side value.
078         *
079         * @param clientValue string representation of the value's identity
080         * @return the corresponding entity, or null if not found
081         */
082        V toValue(String clientValue);
083    }