    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.services;
    014
    015import org.apache.tapestry5.Block;
    016import org.apache.tapestry5.ioc.annotations.UsesConfiguration;
    017
    018/**
    019 * A source of {@link Block}s used to display the properties of a bean (used by the {@link
    020 * org.apache.tapestry5.corelib.components.Grid} component), or to edit the properties of a bean (used by the {@link
    021 * org.apache.tapestry5.corelib.components.BeanEditForm} component). Contributions to this service (a configuration of
    022 * {@link BeanBlockContribution}s) define what properties may be editted.
    023 *
    024 * Blocks are accessed in terms of a <strong>data type</strong> a string that identifies the type of data to be editted,
    025 * such as "string", "date", "boolean", etc.
    026 *
    027 * Tapestry contributes a number of default data types and corresponding edit and display blocks. The {@link
    028 * org.apache.tapestry5.services.BeanBlockOverrideSource} service allows these to be overridden.
    029 *
    030 * @see org.apache.tapestry5.commons.services.DataTypeAnalyzer
    031 * @see org.apache.tapestry5.modules.TapestryModule#provideDefaultBeanBlocks(org.apache.tapestry5.commons.Configuration)
    032 */
    033@UsesConfiguration(BeanBlockContribution.class)
    034public interface BeanBlockSource
    035{
    036    /**
    037     * Returns a block which can be used to render an editor for the given data type, in the form of a field label and
    038     * input field.
    039     *
    040     * @param datatype logical name for the type of data to be displayed
    041     * @return the Block
    042     * @throws RuntimeException if no appropriate block is available
    043     */
    044    Block getEditBlock(String datatype);
    045
    046    /**
    047     * Returns a block which can be used to render output for the given data type.
    048     *
    049     * @param datatype logical name for the type of data to be displayed
    050     * @return the Block
    051     * @throws RuntimeException if no appropriate block is available
    052     */
    053    Block getDisplayBlock(String datatype);
    054
    055    /**
    056     * Checks to see if there is a display block for the indicated data type.
    057     *
    058     * @param datatype to check for
    059     * @return true if a block is available
    060     */
    061    boolean hasDisplayBlock(String datatype);
    062}