    001// Copyright 2007, 2008, 2023 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.ioc;
    016
    017import org.apache.tapestry5.ioc.annotations.Scope;
    018import org.apache.tapestry5.ioc.def.ServiceDef;
    019
    020/**
    021 * Allows a module to bind service interfaces to service implementation classes in support of autobuilding services. A
    022 * ServiceBinder is passed to to a method with the following signature: <code>public static void bind(ServiceBinder
    023 * binder)</code>. This is an adaptation of ideas from <a href="http://code.google.com/p/google-guice/">Guice</a>.
    024 */
    025public interface ServiceBinder
    026{
    027    /**
    028     * Binds the service interface to a conventionally named service implementation class or defines a service in terms of an implementation class, without a service interface.
    029     * <p>
    030     * The conventional name for the service implementation class is the same as the name of the service interface with "Impl" appended.
    031     * For example, {@code bind(Service.class)} will implicitly attempt to bind to {@code ServiceImpl.class}.
    032     * Use {@link #bind(Class, Class)} if the name of the service implementation class does not follow the convention.
    033     * <p>
    034     * In case the service is defined through the implementation class, the service
    035     * will not be proxiable (proxying requires a service interface) and {@link ServiceDef#getServiceInterface()} will
    036     * return the implementation class. In this situation, the service will not be proxied; it will be instantiated
    037     * fully on first reference (ignoring its scope, if any) and will not be decorated.
    038     *
    039     * @param <T>
    040     * @param interfaceClassOrImplementationClass service interface class to bind implicitly or implementation class
    041     * to instantiate as the service
    042     * @return binding options, used to specify additional details about the service
    043     * @see #bind(Class, Class)
    044     */
    045    <T> ServiceBindingOptions bind(Class<T> interfaceClassOrImplementationClass);
    046
    047    /**
    048     * Alternative implementation that supports a callback to build the service, rather than instantiating a particular
    049     * class.
    050     *
    051     * @param serviceInterface interface implemented by the service
    052     * @param builder          constructs the core service implementation
    053     * @return binding options, used to specify additional details about the service
    054     */
    055    <T> ServiceBindingOptions bind(Class<T> serviceInterface, ServiceBuilder<T> builder);
    056
    057    /**
    058     * Binds the service interface to a service implementation class. The default service name is the unqualified name
    059     * of the service interface. The default service scope is "singleton", unless the service implementation class
    060     * includes the {@link Scope} annotation.
    061     * <p>
    062     * The service implementation class may be omitted (in other words, {@link #bind(Class)} used instead) if the name
    063     * of the service implementation class is the same as the name of the service interface with "Impl" appended.
    064     *
    065     * @param <T>
    066     * @param serviceInterface      service interface (used when locating services, and when building proxies)
    067     * @param serviceImplementation implementation class that implements the service interface
    068     * @return binding options, used to specify additional details about the service
    069     * @see #bind(Class)
    070     */
    071    <T> ServiceBindingOptions bind(Class<T> serviceInterface,
    072                                   Class<? extends T> serviceImplementation);
    073}