    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005//     http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5;
    014
    015import org.apache.tapestry5.commons.AnnotationProvider;
    016
    017/**
    018 * A binding is a connection between a component and its container (another component), that allows the embedded
    019 * component to gain access to <em>resources</em> defined by the container. Resources can represent any kind of value
    020 * that can be obtained from the parent component, but is often a JavaBean property that can be read and updated.
    021 * Different implementations of Binding are used to access different kinds of resources of the container.
    022 *
    023 * A binding ultimately must provide access to the underlying annotations. In most cases, there are no annotations, but
    024 * bindings that ultimate invoke methods or read and update fields must provide access to those annotations.
    025 */
    026public interface Binding extends AnnotationProvider
    027{
    028    /**
    029     * Reads the current value of the property (or other resource). When reading properties of objects that are
    030     * primitive types, this will return an instance of the wrapper type. In some cases, a binding is read only and this
    031     * method will throw a runtime exception.
    032     */
    033    Object get();
    034
    035    /**
    036     * Updates the current value. Most types of bindings are read-only, and this method will throw a runtime exception.
    037     * It is the caller's responsibility to ensure that the value passed in is of the appropriate type.
    038     *
    039     * @param value
    040     */
    041    void set(Object value);
    042
    043    /**
    044     * Returns true if the value of the binding does not ever change. Components will often cache such values
    045     * aggressively.
    046     */
    047    boolean isInvariant();
    048
    049    /**
    050     * Returns the type of the binding, either the type of resource exposed by the binding, or the type of the property
    051     * bound.
    052     */
    053    Class getBindingType();
    054}