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