    001    // Copyright 2006, 2007, 2009 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.ioc.def;
    016
    017    import org.apache.tapestry5.ioc.ModuleBuilderSource;
    018    import org.apache.tapestry5.ioc.ServiceDecorator;
    019    import org.apache.tapestry5.ioc.ServiceResources;
    020
    021    /**
    022     * Definition of a service decorator, which (by default) is derived from a service decorator method.
    023     * <p/>
    024     * A note on decorator scheduling. The scheduling is based on the desired order of <em>behavior</em>. Thus, if logging
    025     * should occur before security checks, and security checks should occur before transaction management, then the desired
    026     * decorator order is Logging, Security, Transactions. This might be specified as having Security occur after Logging,
    027     * and Transactions occur after Security. It might also be specified by having Logging ordered "before:*", and
    028     * Transactions ordered "after:*" with no specified scheduling for Security.
    029     * <p/>
    030     * Once this order is established, decorators are <em>applied</em> in reverse order. Each decorator's job is to create
    031     * an <em>interceptor</em> for the service, that delegates to the next implementation. This implies that the decorators
    032     * are executed last to first. In the above example, the core service implementation would be passed to the Transaction
    033     * decorator, resulting in the Transaction interceptor. The Transaction interceptor would be passed to the Security
    034     * decorator, resulting in the Security interceptor. The Security interceptor would be passed to the Logging decorator,
    035     * resulting in the Logging interceptor. Thus at runtime, the Logging interceptor will execute first, then delegate to
    036     * the Security interceptor, which would delegate to the Transaction interceptor, which would finally delegate to the
    037     * core service implementation.
    038     * <p/>
    039     * Service decorators are part of the initial version of Tapestry IoC.  Starting in release 5.1, their use has been
    040     * deprecated, in favor of {@link org.apache.tapestry5.ioc.AdvisorDef}, which is based on {@link
    041     * org.apache.tapestry5.ioc.services.AspectInterceptorBuilder}.
    042     * <p/>
    043     * Note: service decorators are applied <em>around</em> the interceptor generated via any {@link
    044     * org.apache.tapestry5.ioc.AdvisorDef}s (for compatibility with Tapestry 5.0). In general, you should use service
    045     * decoration or service advice, not both.
    046     */
    047    public interface DecoratorDef
    048    {
    049        /**
    050         * Returns the id of the decorator, which is derived from the decorator method name.
    051         */
    052        String getDecoratorId();
    053
    054        /**
    055         * Returns zero or more ordering constraint strings, used to order the decorated relative to the other decorators.
    056         */
    057
    058        String[] getConstraints();
    059
    060        /**
    061         * Creates an object that can perform the decoration (in the default case, by invoking the decorator method on the
    062         * module class or instance.
    063         *
    064         * @param moduleSource access to the the module  instance associated with the module containing the decorator (not
    065         *                     necessarily the module containing the service being decorated)
    066         * @param resources    the resources visible <em>to the decorator</em> (which may be in a different module than the
    067         *                     service being decorated). Other resource properties (serviceId, serviceInterface, log, etc.)
    068         *                     are for the service being decorated.
    069         */
    070        ServiceDecorator createDecorator(ModuleBuilderSource moduleSource,
    071                                         ServiceResources resources);
    072
    073        /**
    074         * Used to determine which services may be decorated by this decorator. When decorating a service, first the
    075         * decorators that target the service are identified, then ordering occurs, then the {@link ServiceDecorator}s are
    076         * invoked.
    077         *
    078         * @param serviceDef
    079         * @return true if the decorator applies to the service
    080         */
    081        boolean matches(ServiceDef serviceDef);
    082    }