001// Copyright 2004, 2005 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 015package org.apache.tapestry.valid; 016 017import org.apache.tapestry.IMarkupWriter; 018import org.apache.tapestry.IRequestCycle; 019import org.apache.tapestry.form.IFormComponent; 020 021/** 022 * An object that works with an {@link IFormComponent} to format output (convert object values to 023 * strings values) and to process input (convert strings to object values and validate them). 024 * <p> 025 * Note that this interface represents validation as supported in Tapestry 2.x to 3.0. It has been 026 * outdated (and will eventually be deprecated) by new support in Tapestry 4.0, centered around the 027 * {@link org.apache.tapestry.form.translator.Translator} and 028 * {@link org.apache.tapestry.form.validator.Validator} interfaces. 029 * 030 * @author Howard Lewis Ship 031 * @since 1.0.8 032 */ 033 034public interface IValidator 035{ 036 /** 037 * All validators must implement a required property. If true, the client must supply a non-null 038 * value. 039 */ 040 041 public boolean isRequired(); 042 043 /** 044 * Invoked during rendering to convert an object value (which may be null) to a String. It is 045 * acceptible to return null. The string will be the VALUE attribute of the HTML text field. 046 */ 047 048 public String toString(IFormComponent field, Object value); 049 050 /** 051 * Converts input, submitted by the client, into an object value. May return null if the input 052 * is null (and the required flag is false). 053 * <p> 054 * The input string will already have been trimmed. It may be null. 055 * 056 * @throws ValidatorException 057 * if the string cannot be converted into an object, or the object is not valid (due 058 * to other constraints). 059 */ 060 061 public Object toObject(IFormComponent field, String input) throws ValidatorException; 062 063 /** 064 * Invoked by the field after it finishes rendering its tag (but before the tag is closed) to 065 * allow the validator to provide a contribution to the rendering process. Validators typically 066 * generated client-side JavaScript to peform validation. 067 * 068 * @since 2.2 069 */ 070 071 public void renderValidatorContribution(IFormComponent field, IMarkupWriter writer, 072 IRequestCycle cycle); 073 074}