    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
    015    package org.apache.tapestry5.services;
    016
    017    import org.apache.tapestry5.beaneditor.BeanModel;
    018    import 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     */
    029    public 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    }