Package com.comphenix.protocol.reflect

Class StructureModifier<T>

java.lang.Object
com.comphenix.protocol.reflect.StructureModifier<T>
Type Parameters:
T - Type of the fields to retrieve.
public class StructureModifier<T> extends Object
Provides list-oriented access to the fields of a Minecraft packet.

Implemented by using reflection. Use a CompiledStructureModifier, if speed is essential.

  • Field Details

  • Constructor Details

    • StructureModifier

      public StructureModifier(Class<?> targetType)
      Creates a structure modifier.
      Parameters:
      targetType - - the structure to modify.

    • StructureModifier

      public StructureModifier(Class<?> targetType, Class<?> superclassExclude, boolean requireDefault)
      Creates a structure modifier.
      Parameters:
      targetType - - the structure to modify.
      superclassExclude - - a superclass to exclude.
      requireDefault - - whether we will be using writeDefaults()

    • StructureModifier

      protected StructureModifier()
      Consumers of this method should call "initialize".

  • Method Details

    • initialize

      protected void initialize(StructureModifier<T> other)
      Initialize using the same field types.
      Parameters:
      other - - information to set.

    • initialize

      protected void initialize(Class<?> targetType, Class<?> fieldType, List<FieldAccessor> data, Map<FieldAccessor,Integer> defaultFields, EquivalentConverter<T> converter, Map<Class<?>,StructureModifier<?>> subTypeCache)
      Initialize every field of this class.
      Parameters:
      targetType - - type of the object we're reading and writing from.
      fieldType - - the common type of the fields we're modifying.
      data - - list of fields to modify.
      defaultFields - - list of fields that will be automatically initialized.
      converter - - converts between the common field type and the actual type the consumer expects.
      subTypeCache - - a structure modifier cache.

    • read

      public T read(int fieldIndex) throws FieldAccessException
      Reads the value of a field given its index.

      Note: This method is prone to exceptions (there are currently 5 total throw statements). It is recommended that you use readSafely(int), which returns null if the field doesn't exist, instead of throwing an exception.

      Parameters:
      fieldIndex - - index of the field.
      Returns:
      Value of the field.
      Throws:
      FieldAccessException - if the given field index is out of bounds.
      IllegalStateException - if this modifier has no target set.

    • readSafely

      public T readSafely(int fieldIndex) throws FieldAccessException
      Reads the value of a field only if it exists. If the field does not exist, null is returned.

      As its name implies, this method is a much safer alternative to read(int). In addition to throwing less exceptions and thereby causing less console spam, this method makes providing backwards compatiblity signficiantly easier, as shown below: 

      
 BlockPosition position = packet.getBlockPositionModifier().readSafely(0);
 if (position != null) {
     // Handle 1.8+
 } else {
     // Handle 1.7-
 }
      Parameters:
      fieldIndex - - index of the field.
      Returns:
      Value of the field, or NULL if it doesn't exist.
      Throws:
      IllegalStateException - if this modifier has no target set.
      FieldAccessException

    • optionRead

      public Optional<T> optionRead(int fieldIndex)
      Reads the value of a field only if it exists. If the field does not exist, an empty Optional is returned.

      This method has the same functionality as readSafely(int), but enforces null checks by way of an Optional. It will eventually become the preferred method of reading fields.

      Parameters:
      fieldIndex - index of the field
      Returns:
      An optional that may contain the value of the field
      See Also:

    • write

      public StructureModifier<T> write(int fieldIndex, T value) throws FieldAccessException
      Writes the value of a field given its index.
      Parameters:
      fieldIndex - - index of the field.
      value - - new value of the field.
      Returns:
      This structure modifier - for chaining.
      Throws:
      FieldAccessException - The field doesn't exist, or it cannot be accessed under the current security contraints.

    • writeSafely

      public StructureModifier<T> writeSafely(int fieldIndex, T value) throws FieldAccessException
      Writes the value of a given field IF and ONLY if it exists.
      Parameters:
      fieldIndex - - index of the potential field.
      value - - new value of the field.
      Returns:
      This structure modifer - for chaining.
      Throws:
      FieldAccessException - The field cannot be accessed under the current security contraints.

    • modify

      public StructureModifier<T> modify(int fieldIndex, UnaryOperator<T> select) throws FieldAccessException
      Correctly modifies the value of a field.
      Parameters:
      fieldIndex - - index of the field to modify.
      select - - the function that modifies the field value.
      Returns:
      This structure modifier - for chaining.
      Throws:
      FieldAccessException - The field cannot be accessed under the current security contraints.

    • findFieldAccessor

      protected FieldAccessor findFieldAccessor(int fieldIndex)

    • writeDefaults

      public StructureModifier<T> writeDefaults() throws FieldAccessException
      Sets all non-primitive fields to a more fitting default value. See DefaultInstances.getDefault(Class).
      Returns:
      The current structure modifier - for chaining.
      Throws:
      FieldAccessException - If we're unable to write to the fields due to a security limitation.

    • getFieldType

      public Class<?> getFieldType()
      Retrieves the common type of each field.
      Returns:
      Common type of each field.

    • getTargetType

      public Class<?> getTargetType()
      Retrieves the type of the object we're modifying.
      Returns:
      Type of the object.

    • getTarget

      public Object getTarget()
      Retrieves the object we're currently modifying.
      Returns:
      Object we're modifying.

    • size

      public int size()
      Retrieve the number of readable types.
      Returns:
      Readable types.

    • getFields

      public List<FieldAccessor> getFields()
      Retrieves a list of the fields matching the constraints of this structure modifier.
      Returns:
      List of fields.

    • getField

      public Field getField(int fieldIndex)
      Retrieve a field by index.
      Parameters:
      fieldIndex - - index of the field to retrieve.
      Returns:
      The field represented with the given index.
      Throws:
      IllegalArgumentException - If no field with the given index can be found.

    • getValues

      public List<T> getValues() throws FieldAccessException
      Retrieve every value stored in the fields of the current type.
      Returns:
      Every field value.
      Throws:
      FieldAccessException - Unable to access one or all of the fields

    • withType

      public <R> StructureModifier<R> withType(Class<?> fieldType)
      Retrieves a structure modifier that only reads and writes fields of a given type.
      Type Parameters:
      R - Type
      Parameters:
      fieldType - - the type, or supertype, of every field to modify.
      Returns:
      A structure modifier for fields of this type.

    • withType

      public <R> StructureModifier<R> withType(Class<?> fieldType, EquivalentConverter<R> converter)
      Retrieves a structure modifier that only reads and writes fields of a given type.
      Type Parameters:
      R - Type
      Parameters:
      fieldType - - the type, or supertype, of every field to modify.
      converter - - converts objects into the given type.
      Returns:
      A structure modifier for fields of this type.

    • withParamType

      public <R> StructureModifier<R> withParamType(Class<?> fieldType, EquivalentConverter<R> converter, Class<?>... paramTypes)
      Retrieves a structure modifier that only reads and writes fields of a given type.
      Type Parameters:
      R - Type
      Parameters:
      fieldType - - the type, or supertype, of every field to modify.
      converter - - converts objects into the given type.
      paramTypes - - field type parameters
      Returns:
      A structure modifier for fields of this type.

    • withFieldType

      protected <V> StructureModifier<V> withFieldType(Class<?> fieldType, List<FieldAccessor> filtered, Map<FieldAccessor,Integer> defaults)
      Create a new structure modifier for the new field type.
      Type Parameters:
      V - Type
      Parameters:
      fieldType - - common type of each field.
      filtered - - list of fields after filtering the original modifier.
      defaults - - list of default values after filtering the original.
      Returns:
      A new structure modifier.

    • withFieldType

      protected <V> StructureModifier<V> withFieldType(Class<?> fieldType, List<FieldAccessor> filtered, Map<FieldAccessor,Integer> defaults, EquivalentConverter<V> converter)
      Create a new structure modifier for the new field type.
      Type Parameters:
      V - Type
      Parameters:
      fieldType - - common type of each field.
      filtered - - list of fields after filtering the original modifier.
      defaults - - list of default values after filtering the original.
      converter - - the new converter, or NULL.
      Returns:
      A new structure modifier.

    • withTarget

      public StructureModifier<T> withTarget(Object target)
      Retrieves a structure modifier of the same type for a different object target.
      Parameters:
      target - - different target of the same type.
      Returns:
      Structure modifier with the new target.

    • setConverter

      protected void setConverter(EquivalentConverter<T> converter)
      Set the current object converter. Should only be called during construction.
      Parameters:
      converter - - current object converter.

    • toString

      public String toString()
      Overrides:
      toString in class Object