com.jniwrapper
Class Pointer

java.lang.Object
  |
  +--com.jniwrapper.Parameter
        |
        +--com.jniwrapper.Pointer
Direct Known Subclasses:
ArithmeticalPointer, Pointer.Const, Pointer.OutOnly, ResizingPointer

public class Pointer
extends Parameter

This class represents a pointer to object in terms of C language.

Pointer type is defined by its referenced object. E.g. an int pointer (int *) is a Pointer to Int.

 Int value = new Int();
 Pointer pValue = new Pointer(value); // this is int*
 


Nested Class Summary
static class Pointer.Const
          Represents a pointer to constant object.
static class Pointer.OutOnly
          Represents a pointer to object with undefined initial value.
static class Pointer.Void
          Represents a void *.
 
Field Summary
static int POINTER_LENGTH
           
 
Constructor Summary
Pointer(Parameter ref)
          Constructs a new pointer to the given object.
Pointer(Parameter ref, boolean isNull)
          Constructs a new pointer to the given object.
 
Method Summary
protected  void acceptIOPerformer(IOPerformer performer, DataBuffer source, int initialOffset)
          Realization of a Visitor pattern for parameter IO.
protected  void checkMemHandleLength()
          Checks that memory block referred to by this pointer is big enough to hold the referenced object and allocates a new one if required.
 java.lang.Object clone()
           
 int getLength()
          Returns a length of the parameter in memory.
protected  long getPointerHandle()
          Returns the value of pointer as used by the native side.
 Parameter getReferencedObject()
          Returns the referenced object of this pointer.
 boolean isNull()
          Tests if this pointer is null.
 void pop(DataBuffer stackBuffer, int offset)
          Default implementation, which does nothing as most primitive types do nothing on pop.
 void read(byte[] arr, int offset)
          Reads the parameter value from a byte array.
 void read(DataBuffer stackBuffer, int offset)
          Reads this parameter from a specified data source.
protected  void readPointer(DataBuffer stackBuffer, int offset)
          Reads this pointer handle part (not the referenced object) from the given data buffer.
protected  void readReferencedObject()
          Reads the referenced object only.
 void setNull(boolean isNull)
          Sets pointer null value.
 void setReferencedObject(Parameter ref)
          Changes the pointer referenced object.
 void setReferencedObject(Parameter ref, boolean isNull)
          Changes the pointer referenced object.
 java.lang.String toString()
           
 void write(byte[] arr, int offset)
          Writes the parameter value to a byte array.
 void write(DataBuffer stackBuffer, int offset)
          Writes this parameter to a specified data source.
protected  void writePointer(DataBuffer stackBuffer, int offset)
          Writes this pointer handle part (not the referenced object) to a given data buffer.
protected  void writeReferencedObject()
          Writes the referenced object only.
 
Methods inherited from class com.jniwrapper.Parameter
asReturnValue, equals, getAlignedLength, getBuffer, getOffset, indent, push, setBuffer, toByteArray
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

POINTER_LENGTH

public static final int POINTER_LENGTH
Constructor Detail

Pointer

public Pointer(Parameter ref)
Constructs a new pointer to the given object. Constructed pointer is a non-null pointer parameter that points to the given object.

Parameters:
ref - referenced object.

Pointer

public Pointer(Parameter ref,
               boolean isNull)
Constructs a new pointer to the given object. Constructed pointer may be null in which case referenced object value is not used or updated until pointer value is changed to non-null by native function.

Parameters:
ref - referenced object
isNull - if true the constructed pointer is null.
Method Detail

getReferencedObject

public final Parameter getReferencedObject()
Returns the referenced object of this pointer.


setReferencedObject

public void setReferencedObject(Parameter ref)
Changes the pointer referenced object.


setReferencedObject

public void setReferencedObject(Parameter ref,
                                boolean isNull)
Changes the pointer referenced object.

Parameters:
ref - new referenced object.
isNull - if true this pointer becomes null.

isNull

public final boolean isNull()
Tests if this pointer is null.


setNull

public final void setNull(boolean isNull)
Sets pointer null value. Setting this to true makes the pointer to be null, setting to false makes it to reference its referenced object.


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

write

public void write(byte[] arr,
                  int offset)
Description copied from class: Parameter
Writes the parameter value to a byte array.

Overrides:
write in class Parameter

read

public void read(byte[] arr,
                 int offset)
Description copied from class: Parameter
Reads the parameter value from a byte array.

Overrides:
read in class Parameter

clone

public java.lang.Object clone()
Specified by:
clone in class Parameter

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getPointerHandle

protected long getPointerHandle()
Returns the value of pointer as used by the native side.


write

public void write(DataBuffer stackBuffer,
                  int offset)
           throws MemoryAccessViolationException
Description copied from class: Parameter
Writes this parameter to a specified data source.

Specified by:
write in class Parameter
MemoryAccessViolationException

writePointer

protected void writePointer(DataBuffer stackBuffer,
                            int offset)
                     throws MemoryAccessViolationException
Writes this pointer handle part (not the referenced object) to a given data buffer. This method checks if enough memory is allocated to store the referenced object and reallocates it if necessary.

MemoryAccessViolationException

read

public void read(DataBuffer stackBuffer,
                 int offset)
          throws MemoryAccessViolationException
Description copied from class: Parameter
Reads this parameter from a specified data source.

Specified by:
read in class Parameter
MemoryAccessViolationException

readPointer

protected void readPointer(DataBuffer stackBuffer,
                           int offset)
                    throws MemoryAccessViolationException
Reads this pointer handle part (not the referenced object) from the given data buffer. This method checks if the read handle is the same as the previously written one and also adjusts null status accordingly. If pointer handle was changed by the native code, the new memory is considered external and is not freed by JNI Wrapper.

MemoryAccessViolationException

pop

public void pop(DataBuffer stackBuffer,
                int offset)
         throws MemoryAccessViolationException
Description copied from class: Parameter
Default implementation, which does nothing as most primitive types do nothing on pop. Reads a parameter from a function stack.

Overrides:
pop in class Parameter
MemoryAccessViolationException

checkMemHandleLength

protected final void checkMemHandleLength()
Checks that memory block referred to by this pointer is big enough to hold the referenced object and allocates a new one if required. If this pointer is set to be null, no action is taken.


acceptIOPerformer

protected void acceptIOPerformer(IOPerformer performer,
                                 DataBuffer source,
                                 int initialOffset)
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
source - data buffer for I/O operation
initialOffset - I/O operation offset of this parameter in the buffer

writeReferencedObject

protected final void writeReferencedObject()
Writes the referenced object only. No checking is performed for memory block size or even location validity.


readReferencedObject

protected void readReferencedObject()
Reads the referenced object only. No checking is performed for memory block size or even location validity.