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