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    
015    package org.apache.tapestry;
016    
017    import 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    
032    public interface IBinding extends Locatable
033    {
034        /**
035         * Returns the value of this binding. This is the essential method.
036         */
037    
038        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        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        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        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        String getDescription();
082    }