Injeção de dependência

O Sponge usa injeção de dependência para fornecer instâncias da API para os plugins. A injeção de dependência permite os plugins definirem alguns tipos da API para serem injetados após a construção.

Lista temporária dos tipos injetados

ConfigDir (anotação em um Path ou File): Usado para injetar o diretório de configuração do plugin: ./config/ OU ./config/<Plugin#id>/ dependendo da opção ConfigDir#sharedRoot()
DefaultConfig (anotação em um Path, ConfigurationLoader ou File): Usado para injetar o arquivo de configuração especifico para o plugin: <Plugin#id>.conf
AssetId (annotation on Asset): Used to inject a Asset from the asset folder of the plugin
AsynchronousExecutor (annotation on SpongeExecutorService): Used to inject the plugin’s specific AsynchronousExecutor
SynchronousExecutor (annotation on SpongeExecutorService): Used to inject the plugin’s specific SynchronousExecutor
ChannelId (annotation on ChannelBinding.IndexedMessageChannel or ChannelBinding.RawDataChannel): Used to inject a ChannelBinding with the given channel id
Asset: Must be annotated with @AssetId.
SpongeExecutorService: Must be annotated with either @AsynchronousExecutor or @SynchronousExecutor. Depending on the annotation given this will contain a reference to the plugin’s specific Asynchronous or Synchronous Executor.
ConfigurationLoader<CommentedConfigurationNode>: Precisa ser anotado com @DefaultConfig. Usado para injetar um ConfigurationLoader pré-elaborado para o File da mesma anotação.
EventManager: Gerencia o registro dos gerenciadores de evento e a chamada de eventos.
File (Arquivo): Precisa ser anotado com @DefaultConfig ou @ConfigDir. Dependendo da anotação informada isto irá conter a referencia para o arquivo de configuração padrão dos plugins ou o diretório usado para armazenar os arquivos de configuração. Porém, Path (veja abaixo) pode ser usado.
Game: The Game object is the core accessor of SpongeAPI.
GameRegistry: Fornece uma forma fácil de obter os tipos a partir do Game.
GuiceObjectMapperFactory: Uma ferramenta fornecida pelo Configurate para mapear facilmente os objetos para as “configuration nodes” (entradas de valores da configuração). Veja Serializing Objects para ter uma base de seu uso.
Injector (Injetor): com.google.inject.Injector é fornecido pelo Guice, este é o injetor usado para injetar as dependências do seu plugin. Você pode usar isto para criar um injetor filho com seus módulos para injetar suas classes com as dependências fornecidas pelo Sponge listadas nesta pagina, ou definir suas próprias classes
Logger (Agente de registros): Usado para identificar qual o plugin está enviando mensagens de registro.
Path: Precisa ser anotado com @DefaultConfig ou @ConfigDir. Dependendo da anotação informada isto irá conter a referencia para o arquivo de configuração padrão dos plugins ou o diretório usado para armazenar os arquivos de configuração.
PluginContainer: Um wrapper de uma classe de Plugin, usado para obter informações da anotação com fácil uso.
PluginManager: Gerencia os plugins carregados pela implementação. Pode obter o PluginContainer de outros plugins.

Exemplos de injeção

Estas são algumas referencias que são difíceis de obter - ou, em alguns casos, impossíveis - sem injeção. Elas não são absolutamente vitais para todos plugins, elas são usadas frequentemente.

Nota

Lembre-se esta é quase sempre a melhor forma de injetar objetos dentro da classe principal, já que são instanciadas com o injetor Guice quando o plugin é carregado.

Logger (Agente de registros)

Dica

Veja Logging and Debugging para um guia completo, especialmente para o Logger.

Game (Jogo)

The Game object is the opening for many of the internal functions of SpongeAPI, from the EventManager to the Server and even the Sync/Async Scheduler.

Embora seja perfeitamente possível recuperar o objeto Game através de Sponge.getGame(), ele é comumente obtido através de uma injeção.

Exemplo - Variável

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

@Inject
private Game game;

Exemplo - Método

private Game game;

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

Exemplo - Construtor

Para propósito deste tutorial, “Apple” é o nome da classe.

private Game game;

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

Diretório de configuração

A forma recomendada de obter seu arquivo de configuração é por meio do Guice, juntamente com a anotação :javadoc:`ConfigFile`.

Dica

Se você definir o parâmetro sharedRoot para true será o mesmo diretório que - potencialmente - guarda as configurações de outros plugins. Em muitos casos quando obter o ConfigDir for necessário, isto deve ser false.

Exemplo - Variável

import org.spongepowered.api.config.ConfigDir;

import java.nio.file.Path;

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

Exemplo - Método

private Path configDir;

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

Exemplo - Construtor

Para propósito deste tutorial, “Orange” é o nome da classe.

private Path configDir;

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

DefaultConfig (Configuração padrão)

O @DefaultConfig funciona de forma semelhante ao @ConfigDir. A grande diferença é obviamente que @DefaultConfig se refere a um arquivo especifico, enquanto @ConfigDir se refere a um diretório.

Dica

Veja Configuring Plugins para um guia completo, especialmente para @DefaultConfig.