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 Summary

Fields

Modifier and Type	Field and Description
protected EquivalentConverter<TField>	converter
protected boolean	customConvertHandling
protected List<Field>	data
protected Map<Field,Integer>	defaultFields
protected Class	fieldType
protected Map<Class,StructureModifier>	subtypeCache
protected Object	target
protected Class	targetType
protected boolean	useStructureCompiler

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StructureModifier() Consumers of this method should call "initialize".
	StructureModifier(Class targetType) Creates a structure modifier.
	StructureModifier(Class targetType, boolean useStructureCompiler) Creates a structure modifier.
	StructureModifier(Class targetType, Class superclassExclude, boolean requireDefault) Creates a structure modifier.
	StructureModifier(Class targetType, Class superclassExclude, boolean requireDefault, boolean useStructureCompiler) Creates a structure modifier.

Method Summary

Modifier and Type	Method and Description
Field	getField(int fieldIndex) Retrieve a field by index.
List<Field>	getFields() Retrieves a list of the fields matching the constraints of this structure modifier.
Class	getFieldType() Retrieves the common type of each field.
protected Class<?>	getFieldType(int index) Retrieve the type of a specified field.
Object	getTarget() Retrieves the object we're currently modifying.
Class	getTargetType() Retrieves the type of the object we're modifying.
List<TField>	getValues() Retrieve every value stored in the fields of the current type.
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.
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.
protected void	initialize(StructureModifier<TField> other) Initialize using the same field types.
boolean	isPublic(int fieldIndex) Determine if a given field is public or not.
boolean	isReadOnly(int fieldIndex) Determine whether or not a field is read-only (final).
StructureModifier<TField>	modify(int fieldIndex, com.google.common.base.Function<TField,TField> select) Correctly modifies the value of a field.
TField	read(int fieldIndex) Reads the value of a field given its index.
TField	readSafely(int fieldIndex) Reads the value of a field only if it exists.
protected void	setConverter(EquivalentConverter<TField> converter) Set the current object converter.
protected static void	setFinalState(Field field, boolean isReadOnly) Alter the final status of a field.
void	setReadOnly(int fieldIndex, boolean value) Set whether or not a field should be treated as read only.
int	size() Retrieve the number of readable types.
String	toString()
protected <T> StructureModifier<T>	withFieldType(Class fieldType, List<Field> filtered, Map<Field,Integer> defaults) Create a new structure modifier for the new field type.
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.
StructureModifier<TField>	withTarget(Object target) Retrieves a structure modifier of the same type for a different object target.
<T> StructureModifier<T>	withType(Class fieldType) Retrieves a structure modifier that only reads and writes fields of a given type.
<T> StructureModifier<T>	withType(Class fieldType, EquivalentConverter<T> converter) Retrieves a structure modifier that only reads and writes fields of a given type.
StructureModifier<TField>	write(int fieldIndex, TField value) Writes the value of a field given its index.
StructureModifier<TField>	writeDefaults() Sets all non-primitive fields to a more fitting default value.
StructureModifier<TField>	writeSafely(int fieldIndex, TField value) Writes the value of a given field IF and ONLY if it exists.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

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 Detail

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 Detail

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.

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.

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