001// Copyright 2006-2013 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.tapestry5;
016
017import 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 are 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 */
028public 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}