ManipuladoresDeDatos Personalizados

Advertencia

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

La parte principal de los datos personalizados es DataManipulator. Para implementarlo, primero debes decidir si quieres crear una API separada para tus datos personalizados. Generalmente hablando es mejor separar la API de la implementación (como lo hace la API de Sponge), pero si no va a ser vista por otros desabolladores entonces puedes simplemente poner ambas en la misma clase.

You’ll want to define an API method for each «unit» your data, such as a String, int, ItemStack or a custom type like Home. These units will be wrapped in a Value, which will allow it to be accessed with Keys. There are various extensions of Value depending on which object will be represented, such as MapValue which provides the standard map operations, or MutableBoundedValue which can set limits on the upper and lower bound of the value (like integers). The bounds of the values are verified using a Comparator.

Ahora, elige de cual de los tipos de AbstractData extenderás. Aunque podrias implementar desde cero, estos tipos de abstracto quitan mucho del trabajo que necesita hacerse implementando los métodos requeridos. Una lista completa puede ser encontrada en org.spongepowered.api.data.manipulator.mutable.common. Ve también Tipos Únicos or Tipos Compuestos a continuación para detalles de implementación de cada tipo.

Debes crear dos clases diferentes - una que es alterable e implementa DataManipulator y tu tipo de abstracto, y una versión inalterable que implementa ImmutableDataManipulator y tu tipo de abstracto inmutable.

Nota

Todos los datos deben tener versiones mutables e inmutables, debes implementar ambas.

Para todos los tipos, necesitaras definir los metodos DataManipulator#asImmutable()/ asMutable() - esto es tan simple como copiar los objetos existentes a constructores para las versiones alternativas.

Valores

Tu(s) getter(s) de valor deben devolver un valor. En el ejemplo a continuación, obtenemos el ValueFactory. Esto nos ahorra un montón de tipeo al usar los objetos Value ya implementados de Sponge. Dependiendo de que valor estes creando hay diferentes metodos que llamar tales como createMapValue, createBoundedComparableValue, etc.

Ejemplo de Código: Implementando un Getter de Valor

import org.spongepowered.api.Sponge;
import org.spongepowered.api.data.value.ValueFactory;
import org.spongepowered.api.data.value.mutable.Value;

import org.spongepowered.cookbook.myhomes.data.home.Home;
import org.spongepowered.cookbook.myhomes.data.Keys;

@Override
protected Value<Home> defaultHome() {
    return Sponge.getRegistry().getValueFactory()
            .createValue(Keys.DEFAULT_HOME, getValue(), null);
}

Nota que un ImmutableDataManipulator devolvería en su lugar un ImmutableValue, al llamar asImmutable() en el Value devuelto. Recomendamos que cachees esto (al igual que con una campo de clase) en la versión inmutable.

Cada Value también necesita un Key para identificarlo, visto en el siguiente ejemplo como Keys.DEFAULT_HOME. Similar a los valores, usas uno de los métodos makeXKey() en KeyFactory para crear un Key para tu valor.

Necesitar pasar un TypeToken representando el tipo puro de tu valor, y un TypeToken representando el Value. También necesitas proporcionar una ruta DataQuery - esto es mas comúnmente usado para serializar el Value. Al igual que con cualquier tipo de catalogo debes también proporcionar un ID y nombre únicos. Reúne todo esto y tendrás un Key que pudes usar en tus Values.

Ejemplo de Código: Creando una Clave

import org.spongepowered.api.data.DataQuery;
import org.spongepowered.api.data.key.Key;
import org.spongepowered.api.data.key.KeyFactory;
import org.spongepowered.api.data.value.mutable.Value;
import org.spongepowered.api.data.value.mutable.Value;

import com.google.common.reflect.TypeToken;

import org.spongepowered.cookbook.myhomes.data.home.Home;

public static final Key<Value<Home>> DEFAULT_HOME = KeyFactory.makeSingleKey(
        TypeToken.of(Home.class),
        new TypeToken<Value<Home>>() {},
        DataQuery.of("DefaultHome"), "myhomes:default_home", "Default Home");

Nota

Los TypeTokens son usados por la implementación para conservar el tipo genérico de tus valores. Sponge proporciona una larga lista de símbolos pre-construidos para la API en TypeTokens.

Si necesitas crear el tuyo propio, puedes hacerlo de dos maneras:

• Para tipos no genéricos, utiliza TypeToken.of(MyType.class)

• Para tipos genéricos, crea una clase anónima con TypeToken<MyGenericType<String>>() {}

Serialización

Para hacer sus datos serializable <../serialization>`a :javadoc:`DataHolders o archivos de configuración, Ud debería también implementar DataSerializable#toContainer().Nosotros recomendamos llamar a``super.toContainer()``ya que este incluirá la versión de DataSerializable#getContentVersion(). Usted debería incrementar la versión cada vez que se hace un cambio al formato de los datos serializados, y usar :ref:`content-updaters`para permitir la compatibilidad con las versiones anteriores.

Nota

Esto no es requerido para tipos únicos simples, ya que ya implementan toContainer()

Ejemplo de Código: Implementando toContainer

import org.spongepowered.api.data.DataContainer;

import org.spongepowered.cookbook.myhomes.data.Keys;

@Override
public DataContainer toContainer() {
    DataContainer container = super.toContainer();
    // This is the simplest, but use whatever structure you want!
    container.set(Keys.DEFAULT_HOME.getQuery(), this.defaultHome);
    container.set(Keys.HOMES, this.homes);

    return container;
}

Registro

Registrando tu DataManipulator permite que sea accesible por Sponge y por otras extensiones en una forma generica. El juego/extensión puede crear copias de tus datos y serializar/deserializar tus datos sin referenciar ninguna de tus clases directamente.

Para registrar un DataManipulator Sponge tiene la guía DataRegistration#builder(). Esto construirá un DataRegistration y lo registrará automáticamente.

Nota

Debido a la naturaleza de los datos, debs registrar tu``DataManipulator`` durante la inicialización - generalmente escuchando a :javadoc: “GameInitializationEvent” tal como en el ejemplo siguiente. Si intentas registrar un DataManipulator una vez completada la inicialización se producirá una excepción.

import org.spongepowered.api.event.game.state.GameInitializationEvent;
import org.spongepowered.api.data.DataRegistration;

import org.example.MyCustomData;
import org.example.ImmutableCustomData;
import org.example.CustomDataBuilder;

@Listener
public void onInit(GameInitializationEvent event) {
  DataRegistration.builder()
      .dataClass(MyCustomData.class)
      .immutableClass(ImmutableCustomData.class)
      .builder(new CustomDataBuilder())
      .manipulatorId("my-custom")
      .dataName("My Custom")
      .build();
}

Advertencia

Data that was serialized prior to 6.0.0, or data where you have changed the ID, will not be recognized unless registered with DataManager#registerLegacyManipulatorIds(String, DataRegistration). If registering a pre-6.0.0 DataManipulator the ID is taken from Class.getName(), such as com.example.MyCustomData.

Tipos Únicos

Single types require little implementation because much of the work has already been done in the AbstractSingleData type you extend from.

Los tipos de abstractos «simples» son los mas fáciles de implementas, pero se limitan solo a los siguientes tipos:

• Boolean

• Comparable

• Integer

• List

• Map

• CatalogType

• Enum

Para todos los otros tipos debes implementar un tipo único personalizado extendiendo AbstractSingleData. Esto te permite definir tus propios datos con cualquier tipo que quieras, mientras sigue haciendo la mayor parte del trabajo por ti.

Truco

Las implementaciones abstractas guardan el objeto para ti en el constructor. Puedes acceder a él en su ejecución llamando a los métodos getValue() and getValueGetter().

Tipos Únicos Simples

Casi todo el trabajo es hecho por ti con tipos abstractos simples. Todo lo que necesitas hacer es:

• Extiende el tipo abstracto relevante

• pasa la Key para tus datos, el objeto en si mismo, y el objeto por defecto (si el objeto es nulo) en el constructor

AbstractBoundedComparableData (y el equivalente inmutable) adicionalmente requiere valores mínimos y máximos que serán comprobados, al igual que un Comparator.

Nota

Los tipos simples List y Mapped deben implementar en su lugar ListData / MappedData``(o el equivalente inmutable). Esto añade métodos adicionales para permitir el comportamiento similar a Mapa/Lista directamente en el ``DataManipulator.

The following 3 methods must be defined on mutable manipulators:

fill(DataHolder, MergeFunction) deberia remplazar los datos en tu objeto con ese del DataHolder dado, usando el resultado de MergeFunction#merge().

import org.spongepowered.api.data.DataHolder;
import org.spongepowered.api.data.merge.MergeFunction;

import org.spongepowered.cookbook.myhomes.data.friends.FriendsData;

import java.util.Optional;

@Override
public Optional<FriendsData> fill(DataHolder dataHolder, MergeFunction overlap) {
    FriendsData merged = overlap.merge(this, dataHolder.get(FriendsData.class).orElse(null));
    setValue(merged.friends().get());

    return Optional.of(this);
}

from(DataContainer) debería sobrescribir su valor con el del contenedor y devolverse a si mismo, de otra forma devolver Optional.empty()

import org.spongepowered.api.data.DataContainer;
import org.spongepowered.api.data.DataQuery;

import org.spongepowered.cookbook.myhomes.data.Keys;
import org.spongepowered.cookbook.myhomes.data.friends.FriendsData;
import org.spongepowered.cookbook.myhomes.data.friends.ImmutableFriendsData;

import com.google.common.collect.Maps;

import java.util.Optional;
import java.util.UUID;

@Override
public Optional<FriendsData> from(DataContainer container) {
    if(container.contains(Keys.FRIENDS)) {
        List<UUID> friends = container.getObjectList(Keys.FRIENDS.getQuery(), UUID.class).get();
        return Optional.of(setValue(friends));
    }

    return Optional.empty();
}

copy() deberia, como el nombre sugiere, devolver una copia de si mismo con los mismos datos.

import org.spongepowered.cookbook.myhomes.data.friends.FriendsData;

@Override
public FriendsData copy() {
    return new FriendsDataImpl(getValue());
}

Tipos Unicos Personalizados

In addition to the methods from the simple single types, you need to override the following methods:

getValueGetter() deberia pasar el Value representando tus datos (ver arriba).

toContainer() deberia devolver un DataContainer representando tus datos (see above).

Tipos Compuestos

Mientras que los tipos únicos admiten sólo un valor, los tipos «compuesto» soportan cuantos valores quieras. Esto es útil cuando se agrupan varios objetos, tales como :javadoc: “FurnaceData”. El lado negativo, sin embargo, es que son más complejos de implementar.

Para comenzar, cree todos los getters “Valor” que tendrá la información. Para cada valor, cree un método para acceder y configurar el objeto en crudo, el cual será usado luego. Para los datos que sean invariables, solamente se necesitarán los getters.

Registrando Valores

Next, you’ll want to register these so that the Keys-based system can reference them. To do this, implement either AbstractData#registerGettersAndSetters() or AbstractImmutableData#registerGetters() depending on whether the data is mutable or not.

Para cada valor debes llamar:

• registerKeyValue(Key, Supplier) referenciando el getter de ``Value` para la clave dada

• registerFieldGetter(Key, Supplier) haciendo referencia al método getter para el objeto sin procesar definido anteriormente

• registerFieldSetter(Key, Consumer) haciendo referencia al método setter anterior si está implementando la versión mutable

Nosotros recomendamos usar las funciones Java 8´s :: syntax for easy Supplier y Consumer.

Ejemplo de Código: Implementando Getters y Setters

import org.spongepowered.cookbook.myhomes.data.Keys

// registerGetters() for immutable implementation
@Override
protected void registerGettersAndSetters() {
    registerKeyValue(Keys.DEFAULT_HOME, this::defaultHome);
    registerKeyValue(Keys.HOMES, this::homes);

    registerFieldGetter(Keys.DEFAULT_HOME, this::getDefaultHome);
    registerFieldGetter(Keys.HOMES, this::getHomes);

    // Only on mutable implementation
    registerFieldSetter(Keys.DEFAULT_HOME, this::setDefaultHome);
    registerFieldSetter(Keys.HOMES, this::setHomes);
}

fill(DataHolder, MergeFunction) y from(DataContainer) son similares a las implementaciones para datos individuales, pero cargando todos tu valores.