com.smardec.j2native
Class Callback

java.lang.Object
  |
  +--com.smardec.j2native.Argument
        |
        +--com.smardec.j2native.Callback
All Implemented Interfaces:
java.lang.Cloneable

public abstract class Callback
extends Argument

Callback is a superclass for all classes representing callback functions. A class nested from Callback must override the callback() method.


Example of usage:

 final public class TestCallback extends Callback{
   public Int a = new Int();
   public Int b = new Int();
   public Int retVal = new Int();
   public TestCallback(){
     initialize(retVal, new Argument[] {a, b});
   }
 

public void callback(){ System.out.println("a = " + a.intValue()); retVal.setValue(b.intValue() >> 2); } }

void myMethod(){ Function.call("userLib", "userFunc", null, new TestCallback()); }

Expected native code usage is:

  typedef int TestCallback(int a, int b);
 

void userFunc(TestCallback *func){ int val = func(1, 2); }


Field Summary
 
Fields inherited from class com.smardec.j2native.Argument
JAVA_SIDE, NATIVE_SIDE
 
Constructor Summary
protected Callback()
          Constructs a Callback instance.
protected Callback(Argument returnArgument, Argument[] arguments)
          Constructs a Callback instance.
 
Method Summary
abstract  void callback()
          This method is called when callback function is called.
 java.lang.Object clone()
          This method throws UnsupportedOperationException because we cannot provide default behaviour as creating simple Callback object, when creation of child is unavaliable.
 void dispose()
          Releases resources associated with this callback.
 void fromBytesValue(byte[] bytes, int offset)
          Restores itself from provided array of bytes.
protected  Argument[] getArguments()
          Returns callback function's arguments.
 byte getCallingConvention()
          Returns calling convention for callback function.
 int getLength()
          Returns length in bytes.
 int getResultFlags()
          Callback function return value mechanizm.
protected  Argument getReturnArgument()
          Returns callback function's return value.
protected  void initialize(Argument returnArgument, Argument[] arguments)
          Initializes callback arguments.
protected  boolean isFixedLength()
          Identify if Argument is a fixed length variable.
protected  void read(long handle, int offset)
          do nothing
protected  void readFromStack(byte[] stack, int offset)
          Read itself from stack.
protected  void setCallingConvention(byte callingConvention)
          Sets calling convention for callback function
 void setReturnFlags(int resultFlags)
          In most cases this method will be never used, because return value Argument wrapper fully describes behaviour of the native function.
 byte[] toBytesValue()
          Encodes itself and returns it's representation as array of bytes.
protected  void toBytesValue(byte[] bytes, int offset)
          Encodes itself to the provided array of bytes.
protected  void update(byte side)
          This method is used to synchronize Java side and native part.
protected  void write(long handle, int offset)
          Writes itself to the memory.
protected  void writeToStack(byte[] stack, int offset)
          Writes itself to stack.
 
Methods inherited from class com.smardec.j2native.Argument
finalize, free, getAlignedLength, readFromRAM, restoreFromRAM, storeToRAM, writeToRAM
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Callback

protected Callback()
Constructs a Callback instance. If a subclass uses this method to construct a callback, it must then invoke the initialize()<> method to initialize callback arguments/return.


Callback

protected Callback(Argument returnArgument,
                   Argument[] arguments)
Constructs a Callback instance.

Parameters:
returnArgument - callback function return value
arguments - callback function arguments
Method Detail

getCallingConvention

public byte getCallingConvention()
Returns calling convention for callback function.

Returns:
calling convention

setCallingConvention

protected void setCallingConvention(byte callingConvention)
Sets calling convention for callback function

Parameters:
callingConvention - calling convention

initialize

protected void initialize(Argument returnArgument,
                          Argument[] arguments)
Initializes callback arguments.

Parameters:
returnArgument - callback function return value
arguments - callback function arguments

getArguments

protected Argument[] getArguments()
Returns callback function's arguments.

Returns:
callback function's arguments.

getReturnArgument

protected Argument getReturnArgument()
Returns callback function's return value.

Returns:
callback function's return value.

dispose

public void dispose()
Releases resources associated with this callback. This has to be done explicitly when the callback is no longer in use. Callback objects will not be garbige collected until this method is called.


callback

public abstract void callback()
This method is called when callback function is called. Parameters of the function are stored in variables specified during callback initialization. Overriden method must store return value to the return value variable specified during initialization.


getLength

public int getLength()
Description copied from class: Argument
Returns length in bytes.

Specified by:
getLength in class Argument
Returns:
an int

writeToStack

protected void writeToStack(byte[] stack,
                            int offset)
Description copied from class: Argument
Writes itself to stack.

Specified by:
writeToStack in class Argument
Parameters:
stack - it's byte array, where Argument will be written
offset - offset in stack

readFromStack

protected void readFromStack(byte[] stack,
                             int offset)
Description copied from class: Argument
Read itself from stack.

Specified by:
readFromStack in class Argument
Parameters:
stack - it's byte array, from which Argument will be restored
offset - offset in stack

getResultFlags

public int getResultFlags()
Callback function return value mechanizm. By default Callback uses com.smardec.j2native.Function#ARGUMENT_DEFINED_RESULTING_MECHANIZM flag. That means that if callback has defined return value, it's result flags will be used. If different flags value will be set, this value will override return argument flags.

Overrides:
getResultFlags in class Argument
Returns:
return value flag.

setReturnFlags

public void setReturnFlags(int resultFlags)
In most cases this method will be never used, because return value Argument wrapper fully describes behaviour of the native function. But sometimes native libraries are compiled with some keys, that change function default behaviour. So you need this method to set appropriate flag to define correct interaction with the such function.

Parameters:
resultFlags -

toBytesValue

public byte[] toBytesValue()
Description copied from class: Argument
Encodes itself and returns it's representation as array of bytes.

Specified by:
toBytesValue in class Argument
Returns:
byte[] representation of Argument

toBytesValue

protected void toBytesValue(byte[] bytes,
                            int offset)
Description copied from class: Argument
Encodes itself to the provided array of bytes.

Specified by:
toBytesValue in class Argument
Parameters:
bytes - array of bytes to which Argument will be written
offset - offset in array

fromBytesValue

public void fromBytesValue(byte[] bytes,
                           int offset)
Description copied from class: Argument
Restores itself from provided array of bytes.

Specified by:
fromBytesValue in class Argument
Parameters:
bytes - array of bytes from which Argument will be restored
offset - offset in array

clone

public java.lang.Object clone()
This method throws UnsupportedOperationException because we cannot provide default behaviour as creating simple Callback object, when creation of child is unavaliable. So, any child class disired to be cloneable should override clone() method. Good luck.

Specified by:
clone in class Argument
Returns:
a clone of this instance.
Throws:
java.lang.UnsupportedOperationException

write

protected void write(long handle,
                     int offset)
              throws MemoryException
Description copied from class: Argument
Writes itself to the memory. Exact memory address specified by params.

Specified by:
write in class Argument
Parameters:
handle - identifies location in memory where Argument will be written
offset - memory address offset
Throws:
MemoryException - if memory manipulations or memory access failed

read

protected void read(long handle,
                    int offset)
do nothing

Specified by:
read in class Argument
Parameters:
handle - identifies location in memory from which Argument will be read
offset - memory address offset

isFixedLength

protected boolean isFixedLength()
Description copied from class: Argument
Identify if Argument is a fixed length variable.

Specified by:
isFixedLength in class Argument
Returns:
true if it is so, and false otherwise

update

protected void update(byte side)
Description copied from class: Argument
This method is used to synchronize Java side and native part.

Overrides:
update in class Argument
Parameters:
side - identifies part that should be updated


Copyright © 2004-2006 Smardec. All Rights Reserved.