com.jniwrapper
Class Union

java.lang.Object
  com.jniwrapper.Parameter
      com.jniwrapper.Union

All Implemented Interfaces:

AlignmentAwareParameter, CompositeParameter

public class Union
extends Parameter
implements CompositeParameter, AlignmentAwareParameter

Represents a C union type. Function parameters of this type are initialized with several parameters representing the union members. The length of the union is equal to that of its longest member. A union represents only one of its members at a time. Users of this class should define which member the union represents by calling one of the setActiveMember methods.

Field Summary

Fields inherited from class com.jniwrapper.Parameter

LICENSE_TYPE, V

Constructor Summary

protected	Union() Preconstructs a union.
	Union(Parameter[] members) Constructs a union with a given set of members.
protected	Union(Union that)

Method Summary

protected void	acceptIOPerformer(IOPerformer performer, DataBuffer buffer, int initialOffset, boolean isReadOperation, boolean invokedByCallback) Implementation of a Visitor pattern for parameter IO.
java.lang.Object	clone() This method is not supported and throws exception to designate that.
Parameter	getActiveMember()
int	getAlignmentRequirement()
protected boolean	getCheckMembers()
java.lang.String	getDebugInfo() Return debug info for JNIWrapper parameter.
int	getFirstMemberSize() Should return first member size.
int	getLength() Returns the length of the parameter in memory.
Parameter[]	getMembers()
protected void	init(Parameter[] members) Sets union members.
void	pop(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Default implementation that does nothing because most primitive types do nothing on pop.
void	push(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Writes a parameter to a function stacks.
void	read(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Reads this parameter from a specified data source.
protected void	readPerformed()
void	setActiveMember(int index) Selects a new active member of the union by its index in the array passed on the initialization.
void	setActiveMember(int index, boolean read) Selects a new active member of the union by its index in the array passed on the initialization.
void	setActiveMember(Parameter active) Defines the member of this union that is currently used.
void	setActiveMember(Parameter active, boolean read) Defines the member of this union that is currently used.
protected void	setCheckMembers(boolean value)
protected void	setDataBuffer(DataBuffer newStorage, int newOffset, boolean shouldRead) Sets the data buffer this parameter should use to store data and an offset in bytes within that buffer.
void	write(DataBuffer stackBuffer, int offset, boolean invokedByCallback) Writes this parameter to a specified data source.

Methods inherited from class com.jniwrapper.Parameter

asReturnValue, dataBufferAssigned, equals, getAlignedLength, getDataBuffer, getDataBufferOffset, hashCode, indent, read, read, toByteArray, write

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Union

protected Union()

Preconstructs a union. Unions constructed with this constructor should be initialized using the init() method.

Union

protected Union(Union that)

Union

public Union(Parameter[] members)

Constructs a union with a given set of members. A constructed union initially has no active member - it has to be set using the setActiveMember() method.

Parameters:

members - union members - the order does not matter.

Method Detail

init

protected void init(Parameter[] members)

Sets union members. The order of the parameters in the passed array is of no importance.

Parameters:

members - union members

getMembers

public Parameter[] getMembers()

setDataBuffer

protected void setDataBuffer(DataBuffer newStorage,
                             int newOffset,
                             boolean shouldRead)

Description copied from class: Parameter

Sets the data buffer this parameter should use to store data and an offset in bytes within that buffer.

Overrides:

setDataBuffer in class Parameter

getActiveMember

public Parameter getActiveMember()

Returns:

- The active member of the union.

setActiveMember

public void setActiveMember(Parameter active)

Defines the member of this union that is currently used. This method should be called before a value is assigned to that member.

Parameters:

active - a new active member

setActiveMember

public void setActiveMember(Parameter active,
                            boolean read)

Defines the member of this union that is currently used. This method should be called before a value is assigned to that member. If the read parameter is true, this member is read from the last value of this union. This is for the case when an active member can be determined only after the function call is completed.

If the union contains pointers, it is recommended to set an active member to null before making such calls.

Because of performance considerations, the method does not check that the passed Parameter instance actually belongs to the union.

Parameters:

active - a new active member

read - if true, this member is read from the last value of this union.

setActiveMember

public void setActiveMember(int index)

Selects a new active member of the union by its index in the array passed on the initialization.

Parameters:

index - the index of the new active member.

See Also:

init(Parameter[])

setActiveMember

public void setActiveMember(int index,
                            boolean read)

Selects a new active member of the union by its index in the array passed on the initialization.

Parameters:

index - the index of a new active member.

read - if true, a new active member is read from the last value of the union.

See Also:

init(Parameter[])

clone

public java.lang.Object clone()

This method is not supported and throws exception to designate that.

Specified by:

clone in class Parameter

Throws:

java.lang.UnsupportedOperationException - always

getLength

public int getLength()

Description copied from class: Parameter

Returns the length of the parameter in memory. This method is similar to C sizeof() operator.

Specified by:

getLength in class Parameter

Returns:

The length of the union which equals to that of its longest member.

read

public void read(DataBuffer stackBuffer,
                 int offset,
                 boolean invokedByCallback)
          throws MemoryAccessViolationException

Description copied from class: Parameter

Reads this parameter from a specified data source.

Specified by:

read in class Parameter

Throws:

MemoryAccessViolationException

readPerformed

protected void readPerformed()

getCheckMembers

protected boolean getCheckMembers()

setCheckMembers

protected void setCheckMembers(boolean value)

write

public void write(DataBuffer stackBuffer,
                  int offset,
                  boolean invokedByCallback)
           throws MemoryAccessViolationException

Description copied from class: Parameter

Writes this parameter to a specified data source.

Specified by:

write in class Parameter

Throws:

MemoryAccessViolationException

push

public void push(DataBuffer stackBuffer,
                 int offset,
                 boolean invokedByCallback)
          throws MemoryAccessViolationException

Description copied from class: Parameter

Writes a parameter to a function stacks.

Overrides:

push in class Parameter

Throws:

MemoryAccessViolationException

pop

public void pop(DataBuffer stackBuffer,
                int offset,
                boolean invokedByCallback)
         throws MemoryAccessViolationException

Description copied from class: Parameter

Default implementation that does nothing because most primitive types do nothing on pop. Reads a parameter from a function stack.

Overrides:

pop in class Parameter

Throws:

MemoryAccessViolationException

acceptIOPerformer

protected void acceptIOPerformer(IOPerformer performer,
                                 DataBuffer buffer,
                                 int initialOffset,
                                 boolean isReadOperation,
                                 boolean invokedByCallback)

Description copied from class: Parameter

Implementation of a Visitor pattern for parameter IO. A performer is responsible for reading and writing the parameter. Users implementing a complex parameter from scratch (i.e. not by extending a pre-existing class such as Structure or Pointer) may wish to override this method to make a performer visit object internal parts.

Overrides:

acceptIOPerformer in class Parameter

Parameters:

performer - a visitor responsible for I/Oing the parameter.

buffer - data buffer for I/O operation.

initialOffset - I/O operation offset of this parameter in the buffer.

getAlignmentRequirement

public int getAlignmentRequirement()

Overrides:

getAlignmentRequirement in class Parameter

Returns:

required alignment within a structure or an array

getDebugInfo

public java.lang.String getDebugInfo()

Description copied from class: Parameter

Return debug info for JNIWrapper parameter.

Specified by:

getDebugInfo in class Parameter

Returns:

debug info

getFirstMemberSize

public int getFirstMemberSize()

Description copied from interface: AlignmentAwareParameter

Should return first member size. If first member is structure, should return it's first parameter (in recursive manner). Unions should return their full size.

Specified by:

getFirstMemberSize in interface AlignmentAwareParameter

Returns:

first structure member size