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