    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    }