001// Copyright 2007, 2008 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.tapestry5.services;
016
017import org.apache.tapestry5.Field;
018import org.apache.tapestry5.FieldTranslator;
019import org.apache.tapestry5.FieldValidator;
020import org.apache.tapestry5.commons.AnnotationProvider;
021import org.apache.tapestry5.commons.Messages;
022
023/**
024 * Defines a context for editing a property of a bean via {@link org.apache.tapestry5.corelib.components.BeanEditor}.
025 * This value is made available to blocks via the {@link org.apache.tapestry5.annotations.Environmental} annotation.
026 *
027 * @see org.apache.tapestry5.services.BeanBlockSource
028 */
029public interface PropertyEditContext extends AnnotationProvider
030{
031    /**
032     * Returns the current value of the property being edited (the context encapsulates the object containing the
033     * property).
034     */
035    Object getPropertyValue();
036
037    /**
038     * Updates the value of the property being edited (the context encapsulates the object containing the property).
039     *
040     * @param value new value for the property
041     */
042    void setPropertyValue(Object value);
043
044    /**
045     * Returns the user-presentable label, for use with the {@link org.apache.tapestry5.corelib.components.Label}
046     * component, or to be integrated into any validation error messages.
047     */
048    String getLabel();
049
050    /**
051     * Returns the translator appropriate for the field (this is based on the property type).
052     *
053     * @param field
054     * @see org.apache.tapestry5.services.TranslatorSource
055     */
056    FieldTranslator getTranslator(Field field);
057
058    /**
059     * Returns the FieldValidator for the field.
060     *
061     * @see org.apache.tapestry5.beaneditor.Validate
062     * @see org.apache.tapestry5.services.FieldValidatorDefaultSource
063     */
064    FieldValidator getValidator(Field field);
065
066    /**
067     * Returns a string that identifies the property, usually the property name. This is used as the basis for the
068     * client-side client id.
069     */
070    String getPropertyId();
071
072    /**
073     * Returns the type of the property being edited.
074     */
075    Class getPropertyType();
076
077    /**
078     * Returns the message catalog for the container of the {@link org.apache.tapestry5.corelib.components.BeanEditForm},
079     * which is the correct place to look for strings used for labels, etc.
080     */
081    Messages getContainerMessages();
082}