001// Copyright 2007-2013 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
015package 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 * <p/>
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 {@linkplain org.apache.tapestry5.ioc.services.TypeCoercer
033 * custom type coercion} has been 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 * @see org.apache.tapestry5.annotations.RequestParameter
064 * @see org.apache.tapestry5.annotations.ActivationRequestParameter
065 */
066public interface ValueEncoder<V>
067{
068    /**
069     * Converts a value into a client-side representation. The value should be parseable by {@link #toValue(String)}. In
070     * some cases, what is returned is an identifier used to locate the true object, rather than a string representation
071     * of the value itself.
072     *
073     * @param value to be encoded
074     * @return a string representation of the value, or the value's identity
075     */
076    String toClient(V value);
077
078    /**
079     * Converts a client-side representation, provided by {@link #toClient(Object)}, back into a server-side value.
080     *
081     * @param clientValue string representation of the value's identity
082     * @return the corresponding entity, or null if not found
083     */
084    V toValue(String clientValue);
085}