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 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

Method Summary

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