001 // Copyright 2006, 2008, 2011 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
015 package org.apache.tapestry5;
016
017 import org.apache.tapestry5.services.FormSupport;
018
019 /**
020 * Translates between client-side and server-side values. Client-side values are always strings.
021 *
022 * @param <T>
023 * @see org.apache.tapestry5.services.TranslatorSource
024 * @see org.apache.tapestry5.FieldValidationSupport
025 * @see org.apache.tapestry5.FieldTranslator
026 */
027 public interface Translator<T>
028 {
029 /**
030 * Returns a unique name for the translator. This is used to identify the translator by name, but is also used when
031 * locating override messages for the translator.
032 *
033 * @return unique name for the translator
034 */
035 String getName();
036
037 /**
038 * Converts a server-side value to a client-side string. This allows for formatting of the value in a way
039 * appropriate to the end user. The output client value should be parsable by
040 * {@link #parseClient(Field, String, String)}.
041 *
042 * @param value
043 * the server side value (which will not be null)
044 * @return client-side value to present to the user
045 */
046 String toClient(T value);
047
048 /**
049 * Returns the type of the server-side value.
050 *
051 * @return a type
052 */
053 Class<T> getType();
054
055 /**
056 * Returns the message key, within the application's global message catalog, normally used by this validator. This
057 * is used to provide the formatted message to {@link #parseClient(Field, String, String)} or
058 * {@link #render(Field, String, MarkupWriter, org.apache.tapestry5.services.FormSupport)}.
059 *
060 * @return a message key
061 */
062 String getMessageKey();
063
064 /**
065 * Converts a submitted request value into an appropriate server side value.
066 *
067 * @param field
068 * for which a value is being parsed
069 * @param clientValue
070 * to convert to a server value; this will not be null, but may be blank
071 * @param message
072 * formatted validation message, either from validation messages, or from an override
073 * @return equivalent server-side value (possibly null)
074 * @throws ValidationException
075 * if the value can not be parsed
076 */
077 T parseClient(Field field, String clientValue, String message) throws ValidationException;
078
079 /**
080 * Hook used by components to allow the validator to contribute additional attributes or (more often) client-side
081 * JavaScript (via the
082 * {@link org.apache.tapestry5.services.FormSupport#addValidation(Field, String, String, Object)}).
083 *
084 * @param field
085 * the field which is currently being rendered
086 * @param message
087 * formatted validation message, either from validation messages, or from an override
088 * @param writer
089 * markup writer, allowing additional attributes to be written into the active element
090 * @param formSupport
091 * used to add JavaScript
092 */
093 void render(Field field, String message, MarkupWriter writer, FormSupport formSupport);
094 }