Injection de Dépendances

Sponge utilise l’injection de dépendances pour fournir des instances de l’API aux plugins. L’injection de dépendances permet aux plugins de désigner quelques types de l’API qui seront injectés après la construction.

Liste Temporaire des Types Injectés

ConfigDir (annotation sur Path ou File): Utilisé pour injecter le répertoire de configuration du plugin: ./config/ ou ./config/<Plugin#id>/ selon la valeur de ConfigDir#sharedRoot()
DefaultConfig (annotation sur Path, ConfigurationLoader ou File): Utilisé pour injecter le fichier de configuration spécifique du plugin: <Plugin#id>.conf.
AssetId (annotation sur Asset): Utilité pour injecter un Asset depuis le dossier d’asset du plugin
AsynchronousExecutor (annotation sur SpongeExecutorService): Utilisé pour injecter l’AsynchronousExecutor spécifique du plugin
SynchronousExecutor (annotation sur SpongeExecutorService): Utilisé pour injecter le SynchronousExecutor spécifique du plugin
ChannelId (annotation sur ChannelBinding.IndexedMessageChannel ou ChannelBinding.RawDataChannel): Utilisé pour injecter un ChannelBinding avec l’id du canal donné
Asset: Doit être annoté avec @AssetId.
SpongeExecutorService: Doit être annoté avec soit @AsynchronousExecutor ou @SynchronousExecutor. Dépendant de l’annotation donnée, il contiendra une référence vers l’exécuteur Asynchrone ou Synchrone du plugin.
ConfigurationLoader<CommentedConfigurationNode>: Doit être une annotation avec @DefaultConfig. Utilisé pour injecter un ConfigurationLoader pré-généré pour le File ou la même annotation.
EventManager: Gère l’enregistrement des manipulateurs d’événements (event handlers) et de l’envoi des événements.
File: Doit être une annotation avec soit @DefaultConfig soit @ConfigDir. Dépendant de l’annotation de ce que contiendra une référence de fichier vers le fichier de configuration par défaut des plugins ou du dossier utilisé pour stocker les fichiers de configuration. Toutefois, Path (voir ci-dessus) doit être privilégié.
Game: L’objet Game est l’accesseur principal de SpongeAPI.
GameRegistry: Fournit un moyen facile pour récupérer certains types depuis un objet Game.
GuiceObjectMapperFactory: Un outil fournit par Configurate qui permet un mapping plus simple des objets des nodes de configuration. Voir Sérialisation d’objets pour l’usage.
Injector: com.google.inject.Injector est disponible depuis Guice, c’est un injecteur utilisé pour injecter les dépendances de votre plugin. Vous pouvez l’utiliser pour créer un child injector avec votre propre module pour vos propres class avec soit avec les dépendances de Sponge listées sur cette page, ou configurer vos propres class
Logger: Utilisé pour identifier le plugin depuis lequel les messages de log sont envoyés.
Path: Doit être une annotation avec soit @DefaultConfig soit @ConfigDir. Dépendant de l’annotation de ce que contiendra une référence de chemin d’accès vers le fichier configuration par défaut des plugins ou du dossier utilisé pour stocker les fichiers de configuration.
PluginContainer: Un wrapper de classe Plugin, utilisé pour récupérer les informations de l’annotation plus facilement.
PluginManager: Gère les plugins qui sont chargés par l’implémentation. Peut récupérer le PluginContainer d’un autre plugin.

Exemples d’injections

Il y a quelques références difficiles à obtenir (voire impossible) sans injection. Même si elles ne sont pas forcément vitales à tous les plugins, elles sont assez souvent utilisées.

Note

N’oubliez pas que c’est presque toujours le meilleur moyen d’injecter vos objets dans la classe principale, tant que votre plugin est instancié avec le Guide de l’injecteur quand le plugin est chargé.

Logger

Astuce

Voir Journalisation (Logging) et Débogage pour un guide complet sur le Logger.

Game

La classe Game est l’ouverture à plusieurs fonctions internes de SpongeAPI depuis l”EventManager jusqu’au Server et même les Sync/Async Scheduler.

Alors qu’il est tout à fait possible de récupérer l’objet Game avec Sponge.getGame(), il est généralement obtenu via une injection.

Exemple - Field

import com.google.inject.Inject;
import org.spongepowered.api.Game;

@Inject
private Game game;

Exemple - Méthode

private Game game;

@Inject
private void setGame(Game game) {
    this.game = game;
}

Exemple - Constructeur

Pour les besoins de ce tutoriel, « Apple » est le nom de la classe.

private Game game;

@Inject
public Apple(Game game) {
    this.game = game;
}

Dossier de configuration

La manière recommandée pour obtenir votre fichier de configuration est d’utiliser Guice, au moyen de l’annotation ConfigDir.

Astuce

Si vous assignez à sharedRoot la valeur true, votre ConfigDir sera le même répertoire qui - potentiellement - contient la configuration d’autres plugins. Dans la plupart des cas où récupérer le ConfigDir est nécessaire, la valeur devrait être mise à false.

Exemple - Field

import org.spongepowered.api.config.ConfigDir;

import java.nio.file.Path;

@Inject
@ConfigDir(sharedRoot = false)
private Path configDir;

Exemple - Méthode

private Path configDir;

@Inject
private void setConfigDir(@ConfigDir(sharedRoot = false) Path configDir) {
    this.configDir = configDir;
}

Exemple - Constructeur

Pour les besoins de ce tutoriel, « Orange » est le nom de la classe.

private Path configDir;

@Inject
public Orange(@ConfigDir(sharedRoot = false) Path configDir) {
    this.configDir = configDir;
}

DefaultConfig

La façon dont @DefaultConfig fonctionne est très proche de celle de @ConfigDir. La plus grande différence étant que @DefaultConfig fait référence à un fichier spécifique, tandis que @ConfigDir fait référence à un répertoire.

Astuce

Voir Configuration des plugins pour un guide complet sur @DefaultConfig.