001    // Copyright 2005 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.tapestry.describe;
016    
017    import java.util.Collection;
018    
019    /**
020     * An object that is provided with a description of another object. The receiver
021     * will format this information.
022     * 
023     * @author Howard M. Lewis Ship
024     * @since 4.0
025     */
026    public interface DescriptionReceiver
027    {
028    
029        /**
030         * Invoke to describe another object instead of the current object.
031         */
032    
033        void describeAlternate(Object alternate);
034    
035        /**
036         * Provides a title for the object; usually the object's class name.
037         * 
038         * @throws IllegalStateException
039         *             if called more than once (for the same object)
040         */
041        void title(String title);
042    
043        /**
044         * Starts a new sub-section within the description. A description may have
045         * any number of sections (but sections do not nest). A second title is only
046         * emitted when the firstproperty within the section is emitted.
047         * 
048         * @throws IllegalStateException
049         *             if called before invoking {@link #title(String)}.
050         */
051        void section(String section);
052    
053        /**
054         * Emits a key/value pair, describing a property of the object. The value
055         * will itself be described. This method is overridden for scalar property
056         * types.
057         * 
058         * @throws IllegalStateException
059         *             if called before invoking {@link #title(String)}
060         */
061        void property(String key, Object value);
062    
063        void property(String key, boolean value);
064    
065        void property(String key, byte value);
066    
067        void property(String key, short value);
068    
069        void property(String key, int value);
070    
071        void property(String key, long value);
072    
073        void property(String key, float value);
074    
075        void property(String key, double value);
076    
077        void property(String key, char value);
078    
079        /**
080         * Emits a list of values for the key. Each value will be described. Emits
081         * nothing if the array is null.
082         */
083        void array(String key, Object[] values);
084    
085        /**
086         * As with {@link #array(String, Object[])}, but the values are in a
087         * collection (which may be null, to emit nothing).
088         */
089    
090        void collection(String key, Collection values);
091    }