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}