001    // Copyright 2006, 2007 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.tapestry5;
016    
017    import org.apache.tapestry5.ioc.AnnotationProvider;
018    
019    /**
020     * A binding is a connection between a component and its container (another component), that allows the embedded
021     * component to gain access to <em>resources</em> defined by the container. Resources can represent any kind of value
022     * that can be obtained from the parent component, but is often a JavaBean property that can be read and updated.
023     * Different implementations of Binding as used to access different kinds of resources of the container.
024     * <p/>
025     * A binding ultimately must provide access to the underlying annotations. In most cases, there are no annotations, but
026     * bindings that ultimate invoke methods or read and update fields must provide access to those annotations.
027     */
028    public interface Binding extends AnnotationProvider
029    {
030        /**
031         * Reads the current value of the property (or other resource). When reading properties of objects that are
032         * primitive types, this will return an instance of the wrapper type. In some cases, a binding is read only and this
033         * method will throw a runtime exception.
034         */
035        Object get();
036    
037        /**
038         * Updates the current value. Most types of bindings are read-only, and this method will throw a runtime exception.
039         * It is the caller's responsibility to ensure that the value passed in is of the appropriate type.
040         *
041         * @param value
042         */
043        void set(Object value);
044    
045        /**
046         * Returns true if the value of the binding does not ever change. Components will often cache such values
047         * aggressively.
048         */
049        boolean isInvariant();
050    
051        /**
052         * Returns the type of the binding, either the type of resource exposed by the binding, or the type of the property
053         * bound.
054         */
055        Class getBindingType();
056    }