001// Copyright 2004, 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;
016
017import org.apache.hivemind.Locatable;
018
019/**
020 * A binding is the mechanism used to provide values for parameters of specific {@link IComponent}
021 * instances. The component doesn't care where the required value comes from, it simply requires
022 * that a value be provided when needed.
023 * <p>
024 * Bindings are set inside the containing component's specification or template. Bindings may be
025 * invariant or dynamic (though that is irrelevant to the component). Components may also use a
026 * binding to write a value back through a property to some other object (typically, another
027 * component).
028 * 
029 * @author Howard Lewis Ship
030 */
031
032public interface IBinding extends Locatable
033{
034    /**
035     * Returns the value of this binding. This is the essential method.
036     */
037
038    public Object getObject();
039
040    /**
041     * Returns the value for the binding after performing some basic checks.
042     * <p>
043     * Note: In release 4.0, the parameterName parameter was removed.
044     * 
045     * @param type
046     *            if not null, the value must be assignable to the specific class
047     * @throws BindingException
048     *             if the value is not assignable to the specified type
049     * @since 0.2.9
050     */
051
052    public Object getObject(Class type);
053
054    /**
055     * Returns true if the value is invariant (not changing; the same value returned each time).
056     * Static and message bindings are always invariant, and
057     * {@link org.apache.tapestry.binding.ExpressionBinding}s may be marked invariant (as an
058     * optimization).
059     * 
060     * @since 2.0.3
061     */
062
063    public boolean isInvariant();
064
065    /**
066     * Updates the value of the binding, if possible.
067     * 
068     * @exception BindingException
069     *                If the binding is read only.
070     */
071
072    public void setObject(Object value);
073
074    /**
075     * Returns a description of how the binding is used; this description
076     * is localized and incorporated into some exception messages.
077     * 
078     * @since 4.0
079     */
080    
081    public String getDescription();
082}