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