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
015package org.apache.tapestry.describe;
016
017import 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 */
026public 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}