org.apache.tapestry5

## Interface ValueEncoder<V>

- All Known Implementing Classes:
    EnumValueEncoder, HibernateEntityValueEncoder, JpaValueEncoder, StringValueEncoder

      public interface ValueEncoder<V>

  A ValueEncoder is used to convert server side objects to unique client-side strings (typically IDs) and back. This mechanism is widely used in Tapestry to allow you to work more seamlessly with objects rather than manually managing the encoding and decoding process throughout your application. Tapestry uses a ValueEncoder when generating an `EventContext` as part of a URL, and when components (such as `Select`) need to generate unique client-side strings to be rendered within form elements. Tapestry can automatically generate ValueEncoders for enums as well as Collections of any object types for which a coercion can be found from a formatted String, such as primitives, primitive wrappers, Dates, Calendars, "name=value" strings, and any types for which a custom type coercion has been contributed. Custom ValueEncoder implementations will need to be supplied for entity type objects. In such cases the `toClient(Object)` method typically returns an object's database primary key, and the `toValue(String)` re-acquires the corresponding entity object, perhaps by doing a database lookup by that ID. Some optional modules, such as Tapestry's own Hibernate and JPA modules, can automatically create a ValueEncoder for each of your entity types and then configure Tapestry to use them whenever a ValueEncoder is needed for those types. If you don't use one of those modules, you can still configure Tapestry to automatically use your custom ValueEncoder implementations by having your ValueEncoder implement the `ValueEncoderFactory` interface and then contributing a ValueEncoderSource that adds your encoder, like this, in your application's module class:

       public static void contributeValueEncoderSource(
               MappedConfiguration<Class<Color>, ValueEncoderFactory<Color>> configuration)
       {
           configuration.addInstance(Color.class, ColorEncoder.class);
       }

  See Also:
    `SelectModel`, `ValueEncoderSource`, `ValueEncoderFactory`, `PageActivationContext`, `RequestParameter`, `ActivationRequestParameter`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `toClient(V value)` Converts a value into a client-side representation.
    `V` | `toValue(String clientValue)` Converts a client-side representation, provided by `toClient(Object)`, back into a server-side value.

- - ### Method Detail

    - #### toClient

          String toClient(V value)

      Converts a value into a client-side representation. The value should be parseable by `toValue(String)`. In some cases, what is returned is an identifier used to locate the true object, rather than a string representation of the value itself.
      Parameters:
        `value` - to be encoded
      Returns:
        a string representation of the value, or the value's identity

    - #### toValue

          V toValue(String clientValue)

      Converts a client-side representation, provided by `toClient(Object)`, back into a server-side value.
      Parameters:
        `clientValue` - string representation of the value's identity
      Returns:
        the corresponding entity, or null if not found

${project.version} - Copyright © 2003-2015 The Apache Software Foundation.