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.binding;
016
017 import org.apache.hivemind.Location;
018 import org.apache.tapestry.IBinding;
019 import org.apache.tapestry.IComponent;
020 import org.apache.tapestry.spec.IParameterSpecification;
021
022 /**
023 * Used to convert a binding string (from a template or a specification) into an instance of
024 * {@link IBinding}.
025 *
026 * @since 4.0
027 */
028 public interface BindingSource
029 {
030 /**
031 * Creates a new binding. The locator is used to identify the <em>type</em> of binding to
032 * create as well as configure the binding instance. The locator is either a literal value
033 * (resulting in a {@link org.apache.tapestry.binding.LiteralBinding literal binding}) or
034 * consists of prefix and a path, i.e., <code>ognl:myProperty</code>.
035 * <p>
036 * When a prefix exists and is identified, it is used to select the correct
037 * {@link BindingFactory}, and the remainder of the path (i.e., <code>myProperty</code>)
038 * is passed to the factory. An unrecognized prefix is treated as a literal value
039 * (it is often "javascript:" or "http:", etc.).
040 *
041 * @param component
042 * The component for which the binding is created; the component is used
043 * as a kind of context for certain types of bindings (for example, the root object when
044 * evaluating OGNL expressions).
045 * @param description
046 {@link IBinding#getDescription() description} for the new binding
047 * @param reference
048 * The binding reference used to create the binding, possibly including a prefix to define the type.
049 * If the reference does not include a prefix, then the defaultBindingType is used as the prefix
050 * @param defaultBindingType
051 * Binding type to use when no prefix is provided in the reference
052 * or doesn't match a known binding factory.
053 * @param location
054 * Location used to report errors in the binding.
055 *
056 * @return A binding instance.
057 */
058 IBinding createBinding(IComponent component, String description, String reference,
059 String defaultBindingType, Location location);
060
061 /**
062 * Just like {@link #createBinding(org.apache.tapestry.IComponent, String, String, String, org.apache.hivemind.Location)} - except
063 * this version takes an additional parameter of type {@link IParameterSpecification} for those bindings that have a matching
064 * parameter.
065 *
066 * @param component
067 * The component for which the binding is created; the component is used
068 * as a kind of context for certain types of bindings (for example, the root object when
069 * evaluating OGNL expressions).
070 * @param parameter
071 * Optional argument of the parameter this binding is being bound for - may be null.
072 * @param description
073 {@link IBinding#getDescription() description} for the new binding
074 * @param reference
075 * The binding reference used to create the binding, possibly including a prefix to define the type.
076 * If the reference does not include a prefix, then the defaultBindingType is used as the prefix
077 * @param defaultBindingType
078 * Binding type to use when no prefix is provided in the reference
079 * or doesn't match a known binding factory.
080 * @param location
081 * Location used to report errors in the binding.
082 *
083 * @return A binding instance.
084 */
085 IBinding createBinding(IComponent component, IParameterSpecification parameter, String description, String reference,
086 String defaultBindingType, Location location);
087 }