com.jniwrapper
Class Union

java.lang.Object
  |
  +--com.jniwrapper.Parameter
        |
        +--com.jniwrapper.Union

public class Union
extends Parameter

Represents a C union type. Function parameters of this type are initialized with several parameters representing union members. A 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.


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)
          Realization of a Visitor pattern for parameter IO.
 java.lang.Object clone()
          This method is not supported and throws exception to designate that.
 int getAlignmentRequirement()
           
 int getLength()
          Returns a length of the parameter in memory.
 Parameter[] getMembers()
           
protected  void init(Parameter[] members)
          Sets union members.
 void read(DataBuffer stackBuffer, int offset, boolean invokedByCallback)
          Reads this parameter from a specified data source.
 void setActiveMember(int index)
          Selects the new active member of the union by its index in the array passed on the initialization.
 void setActiveMember(int index, boolean read)
          Selects the 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 setDataBuffer(DataBuffer newStorage, int newOffset)
          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, equals, getAlignedLength, getDataBuffer, getDataBufferOffset, indent, pop, push, read, toByteArray, write
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Union

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


Union

protected Union(Union that)

Union

public Union(Parameter[] members)
Constructs a union with a given set of members. Constructed union initially has no active member - it has to be set using setActiveMember() method.

Parameters:
members - union members - 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)
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

setActiveMember

public void setActiveMember(Parameter active)
Defines the member of this union that is currently used. This method should be called before value is assigned to that 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 parameter read is true this member is read from the last value of this union. This is for the case when the active member can be determined only after the function call is completed.

If the union contains pointers it is recommended to set 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 - new active member
read - if true this member is read from the last value of this union.

setActiveMember

public void setActiveMember(int index)
Selects the 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 the new active member of the union by its index in the array passed on the initialization.

Parameters:
index - index the index of the new active member.
read - if true the 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 a length of the parameter in memory. This method is analogous 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
MemoryAccessViolationException

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
MemoryAccessViolationException

acceptIOPerformer

protected void acceptIOPerformer(IOPerformer performer,
                                 DataBuffer buffer,
                                 int initialOffset,
                                 boolean isReadOperation,
                                 boolean invokedByCallback)
Description copied from class: Parameter
Realization of a Visitor pattern for parameter IO. A performer is responsible for I/Oing 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 - 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 of type instance withing a structure or an array