org.spongepowered.api.event.lifecycle.ProvideServiceEvent Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of spongeapi Show documentation
A plugin API for Minecraft: Java Edition
There is a newer version: 13.0.0
/*
 * This file is part of SpongeAPI, licensed under the MIT License (MIT).
 *
 * Copyright (c) SpongePowered 
 * Copyright (c) contributors
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package org.spongepowered.api.event.lifecycle;

import org.spongepowered.api.Engine;
import org.spongepowered.api.event.GenericEvent;

import java.util.function.Supplier;

/**
 * An event that allows plugins to suggest their own implementation for a given
 * service.
 *
 * Service providers should not construct the service object
 * prior to selection. Instead, they should wait for if, and only if, their
 * service factory as supplied in {@link #suggest(Supplier)} has been called.
 * Further, each plugin may only supply one service provider
 * for each service.
 *
 * It is not guaranteed that this event will fire for the indicated service
 * for a plugin that registers this listener. This may happen if the server
 * is configured to select a particular service, or that another plugin has
 * already been offered the chance to provide the implementation and has done
 * so.
 *
 * @param  The service to provide.
 */
public interface ProvideServiceEvent extends GenericEvent, LifecycleEvent {

    /**
     * Provides a suggestion for the given service. This may only be
     * called once by any given plugin for a given service and event.
     *
     * @param serviceFactory A {@link Supplier} that can construct the service
     *      if this service is selected
     */
    void suggest(Supplier serviceFactory);

    interface GameScoped extends ProvideServiceEvent {
    }

    /**
     * Supplies a service that is scoped to the given {@link Engine}.
     *
     * Engine scoped services have a lifetime of the attached Engine. If the
     * engine is restarted, plugins will be asked to provide a new service.
     *
     * It is up to the provider to determine which engine a service is to be
     * supplied for. Services that are engine scoped may not support all
     * engines. Plugins can check to see what {@link Engine} the service will
     * be provided for via the {@link #engine()} method, and can choose to
     * forgo providing a service based on this information.
     *
     * @param  The service to provide.
     */
    interface EngineScoped extends ProvideServiceEvent {

        /**
         * Gets the {@link Engine} that is associated with this event.
         *
         * @return The engine.
         */
        Engine engine();
    }
}