Package com.comphenix.protocol.reflect

Class StructureModifier<TField>

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

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

Author:
Kristian

  • Field Details

    • targetType

      protected Class targetType

    • target

      protected Object target

    • converter

      protected EquivalentConverter<TField> converter

    • fieldType

      protected Class fieldType

    • data

      protected List<Field> data

    • defaultFields

      protected Map<Field,​Integer> defaultFields

    • subtypeCache

      protected Map<Class,​StructureModifier> subtypeCache

    • customConvertHandling

      protected boolean customConvertHandling

    • useStructureCompiler

      protected boolean useStructureCompiler

  • Constructor Details

    • StructureModifier

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

    • StructureModifier

      public StructureModifier​(Class targetType, boolean useStructureCompiler)
      Creates a structure modifier.
      Parameters:
      targetType - - the structure to modify.
      useStructureCompiler - - whether or not to use a structure compiler.

    • 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 or not we will be using writeDefaults().

    • StructureModifier

      public StructureModifier​(Class targetType, Class superclassExclude, boolean requireDefault, boolean useStructureCompiler)
      Creates a structure modifier.
      Parameters:
      targetType - - the structure to modify.
      superclassExclude - - a superclass to exclude.
      requireDefault - - whether or not we will be using writeDefaults().
      useStructureCompiler - - whether or not to automatically compile this structure modifier.

    • StructureModifier

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

  • Method Details

    • initialize

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

    • initialize

      protected void initialize​(Class targetType, Class fieldType, List<Field> data, Map<Field,​Integer> defaultFields, EquivalentConverter<TField> 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.

    • initialize

      protected void initialize​(Class targetType, Class fieldType, List<Field> data, Map<Field,​Integer> defaultFields, EquivalentConverter<TField> converter, Map<Class,​StructureModifier> subTypeCache, boolean useStructureCompiler)
      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.
      useStructureCompiler - - whether or not to automatically compile this structure modifier.

    • read

      public TField 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 field doesn't exist, or it cannot be accessed under the current security contraints.

    • readSafely

      public TField 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:
      FieldAccessException - if the field cannot be accessed under the current security constraints.

    • optionRead

      public Optional<TField> 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:
      readSafely(int)

    • isReadOnly

      public boolean isReadOnly​(int fieldIndex)
      Determine whether or not a field is read-only (final).
      Parameters:
      fieldIndex - - index of the field.
      Returns:
      TRUE if the field by the given index is read-only, FALSE otherwise.

    • isPublic

      public boolean isPublic​(int fieldIndex)
      Determine if a given field is public or not.
      Parameters:
      fieldIndex - - field index.
      Returns:
      TRUE if the field is public, FALSE otherwise.

    • setReadOnly

      public void setReadOnly​(int fieldIndex, boolean value) throws FieldAccessException
      Set whether or not a field should be treated as read only.

      Note that changing the read-only state to TRUE will only work if the current field was recently read-only or the current structure modifier hasn't been compiled yet.

      Parameters:
      fieldIndex - - index of the field.
      value - - TRUE if this field should be read only, FALSE otherwise.
      Throws:
      FieldAccessException - If we cannot modify the read-only status.

    • setFinalState

      protected static void setFinalState​(Field field, boolean isReadOnly) throws IllegalAccessException
      Alter the final status of a field.
      Parameters:
      field - - the field to change.
      isReadOnly - - TRUE if the field should be read only, FALSE otherwise.
      Throws:
      IllegalAccessException - If an error occured.

    • write

      public StructureModifier<TField> write​(int fieldIndex, TField 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.

    • getFieldType

      protected Class<?> getFieldType​(int index)
      Retrieve the type of a specified field.
      Parameters:
      index - - the index.
      Returns:
      The type of the given field.

    • writeSafely

      public StructureModifier<TField> writeSafely​(int fieldIndex, TField 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<TField> modify​(int fieldIndex, com.google.common.base.Function<TField,​TField> 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.

    • withType

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

    • writeDefaults

      public StructureModifier<TField> 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.

    • withType

      public <T> StructureModifier<T> withType​(Class fieldType, EquivalentConverter<T> converter)
      Retrieves a structure modifier that only reads and writes fields of a given type.
      Type Parameters:
      T - 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 <T> StructureModifier<T> withParamType​(Class fieldType, EquivalentConverter<T> converter, Class... paramTypes)
      Retrieves a structure modifier that only reads and writes fields of a given type.
      Type Parameters:
      T - 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.

    • 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.

    • withFieldType

      protected <T> StructureModifier<T> withFieldType​(Class fieldType, List<Field> filtered, Map<Field,​Integer> defaults)
      Create a new structure modifier for the new field type.
      Type Parameters:
      T - 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 <T> StructureModifier<T> withFieldType​(Class fieldType, List<Field> filtered, Map<Field,​Integer> defaults, EquivalentConverter<T> converter)
      Create a new structure modifier for the new field type.
      Type Parameters:
      T - 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<TField> 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<TField> converter)
      Set the current object converter. Should only be called during construction.
      Parameters:
      converter - - current object converter.

    • getFields

      public List<Field> 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<TField> 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

    • toString

      public String toString()
      Overrides:
      toString in class Object