    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.beanmodel.services;
    014
    015import org.apache.tapestry5.beanmodel.BeanModel;
    016import org.apache.tapestry5.commons.Messages;
    017
    018/**
    019 * Used by a component to create a default {@link org.apache.tapestry5.beanmodel.BeanModel} for a particular bean
    020 * class. Also provides support to the model by generating validation information for individual fields.
    021 *
    022 * BeanModels are the basis for the {@link org.apache.tapestry5.corelib.components.BeanEditor} and {@link
    023 * org.apache.tapestry5.corelib.components.Grid} comopnents.
    024 *
    025 * @see org.apache.tapestry5.beanmodel.services.PropertyConduitSource
    026 */
    027public interface BeanModelSource
    028{
    029    /**
    030     * Creates a new model used for editing the indicated bean class. The model will represent all read/write properties
    031     * of the bean. The order of properties is determined from the order of the getter methods in the code, and can be
    032     * overridden with the {@link org.apache.tapestry5.beaneditor.ReorderProperties} annotation. The labels for the
    033     * properties are derived from the property names, but if the component's message catalog has keys of the form
    034     * <code>propertyName-label</code>, then those will be used instead.
    035     *
    036     * Models are <em>mutable</em>, so they are not cached, a fresh instance is created each time.
    037     *
    038     * @param beanClass                class of object to be edited
    039     * @param filterReadOnlyProperties if true, then properties that are read-only will be skipped (leaving only
    040     *                                 read-write properties, appropriate for {@link org.apache.tapestry5.corelib.components.BeanEditForm},
    041     *                                 etc.). If false, then both read-only and read-write properties will be included
    042     *                                 (appropriate for {@link org.apache.tapestry5.corelib.components.Grid} or {@link
    043     *                                 org.apache.tapestry5.corelib.components.BeanDisplay}).
    044     * @param messages                 Used to find explicit overrides of
    045     * @return a model
    046     * @deprecated use {@link #createDisplayModel(Class, org.apache.tapestry5.commons.Messages)} or {@link
    047     *             #createEditModel(Class, org.apache.tapestry5.commons.Messages)}
    048     */
    049    <T> BeanModel<T> create(Class<T> beanClass, boolean filterReadOnlyProperties, Messages messages);
    050
    051    /**
    052     * Creates a model for display purposes; this may include properties which are read-only.
    053     *
    054     * @param beanClass class of object to be edited
    055     * @param messages
    056     * @return a model containing properties that can be presented to the user
    057     */
    058    <T> BeanModel<T> createDisplayModel(Class<T> beanClass, Messages messages);
    059
    060    /**
    061     * Creates a model for edit and update purposes, only properties that are fully read-write are included.
    062     *
    063     * @param beanClass class of object to be edited
    064     * @param messages
    065     * @return a model containing properties that can be presented to the user
    066     */
    067    <T> BeanModel<T> createEditModel(Class<T> beanClass, Messages messages);
    068}