    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;
    014
    015import org.apache.tapestry5.commons.AnnotationProvider;
    016
    017/**
    018 * Part of a {@link org.apache.tapestry5.beanmodel.BeanModel} that defines the attributes of a single property of a
    019 * bean.
    020 *
    021 *
    022 * A PropertyModel is also an {@link AnnotationProvider}, as long as the {@link org.apache.tapestry5.beanmodel.PropertyConduit} is
    023 * non-null.  When there is no property conduit, then {@link org.apache.tapestry5.commons.AnnotationProvider#getAnnotation(Class)}
    024 * will return null.
    025 */
    026public interface PropertyModel extends AnnotationProvider
    027{
    028    /**
    029     * Returns the name of the property (which may, in fact, be a property expression).
    030     */
    031    String getPropertyName();
    032
    033    /**
    034     * Returns the id used to access other resources (this is based on the property name, but with any excess
    035     * punctuation stripped out).
    036     */
    037    String getId();
    038
    039    /**
    040     * Returns a user-presentable label for the property.
    041     */
    042    String getLabel();
    043
    044    /**
    045     * Returns the type of the property.
    046     */
    047    Class getPropertyType();
    048
    049    /**
    050     * Returns a logical name for the type of UI needed to view or edit the property. This is initially determined from
    051     * the property type.
    052     */
    053    String getDataType();
    054
    055    /**
    056     * Changes the data type for the property.
    057     *
    058     * @param dataType
    059     * @return the property model, for further changes
    060     */
    061    PropertyModel dataType(String dataType);
    062
    063    /**
    064     * Returns an object used to read or update the property. For virtual properties (properties that do not actually
    065     * exist on the bean), the conduit may be null.
    066     */
    067    PropertyConduit getConduit();
    068
    069    /**
    070     * Changes the label for the property to the provided value.
    071     *
    072     * @param label new label for property
    073     * @return the property model, for further changes
    074     */
    075    PropertyModel label(String label);
    076
    077    /**
    078     * Returns the containing model, often used for "fluent" construction of the model.
    079     */
    080    BeanModel model();
    081
    082    /**
    083     * Returns true if the property can be used for sorting. By default, this is true only if the property type
    084     * implements Comparable.
    085     */
    086    boolean isSortable();
    087
    088    /**
    089     * Updates sortable and returns the model for further changes.
    090     *
    091     * @return the property model, for further changes
    092     */
    093    PropertyModel sortable(boolean sortable);
    094}