"Fossies" - the Fresh Open Source Software Archive

Member "apidocs/src-html/org/apache/tapestry5/ioc/OrderedConfiguration.html" (9 Sep 2020, 9352 Bytes) of package /linux/www/apache-tapestry-5.6.1-apidocs.zip:


Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the project site itself.

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.ioc;
014
015/**
016 * Object passed into a service contributor method that allows the method provide contributed values to the service's
017 * configuration.
018 *
019 * A service can <em>collect</em> contributions in three different ways:
020 * <ul>
021 * <li>As an un-ordered collection of values</li>
022 * <li>As an ordered list of values (where each value has a unique id, pre-requisites and post-requisites)</li>
023 * <li>As a map of keys and values
024 * </ul>
025 *
026 * The service defines the <em>type</em> of contribution, in terms of a base class or service interface. Contributions
027 * must be compatible with the type, or be {@linkplain org.apache.tapestry5.ioc.services.TypeCoercer coercable} to the type.
028 *
029 * @see org.apache.tapestry5.ioc.annotations.Contribute
030 * @see org.apache.tapestry5.ioc.annotations.UsesConfiguration
031 */
032public interface OrderedConfiguration<T>
033{
034    /**
035     * Adds an ordered object to a service's contribution. Each object has an id (which must be unique). Optionally,
036     * pre-requisites (a list of ids that must precede this object) and post-requisites (ids that must follow) can be
037     * provided.
038     *
039     * If no constraints are supplied, then an implicit constraint is supplied: after the previously
040     * contributed id <em>within the same contribution method</em>.
041     *
042     * @param id          a unique id for the object; the id will be fully qualified with the contributing module's id
043     * @param constraints used to order the object relative to other contributed objects
044     * @param object      to add to the service's configuration
045     */
046    void add(String id, T object, String... constraints);
047
048    /**
049     * Overrides a normally contributed object. Each override must match a single normally contributed object.
050     *
051     * @param id          identifies object to override
052     * @param object      overriding object (may be null)
053     * @param constraints constraints for the overridden object, replacing constraints for the original object (even if
054     *                    omitted, in which case the override object will have no ordering constraints)
055     * @since 5.1.0.0
056     */
057    void override(String id, T object, String... constraints);
058
059    /**
060     * Adds an ordered object by instantiating (with dependencies) the indicated class. When the configuration type is
061     * an interface and the class to be contributed is a local file,
062     * then a reloadable proxy for the class will be created and contributed.
063     *
064     * @param id          of contribution (used for ordering)
065     * @param clazz       class to instantiate
066     * @param constraints used to order the object relative to other contributed objects
067     * @since 5.1.0.0
068     */
069    void addInstance(String id, Class<? extends T> clazz, String... constraints);
070
071    /**
072     * Instantiates an object and adds it as an override. When the configuration type is an interface and the class to
073     * be contributed is a local file, then a reloadable proxy for the class will be created and contributed.
074     *
075     * @param id          of object to override
076     * @param clazz       to instantiate
077     * @param constraints constraints for the overridden object, replacing constraints for the original object (even if
078     *                    omitted, in which case the override object will have no ordering constraints)
079     * @since 5.1.0.0
080     */
081    void overrideInstance(String id, Class<? extends T> clazz, String... constraints);
082}