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<Class<Color>, ValueEncoderFactory<Color>> 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}