NativeInterface

```
public interface NativeInterface
```
This class provides some utilities to implement simulated natives.
- It allows to refresh/flush the content of arrays passed as arguments through HIL protocol. Synchronization is done manually to limit byte transfer (speed optimization). An immutable array can be synchronized (refresh/flush) at any time. An array passed as argument is local to the invoke context (new instance). It cannot be refreshed but it may be flushed when the method that has created this argument returns.
- It provides interaction to get back resources content
- It also gives a framework to interact with the shutdown process of the whole simulation thanks to StopListener and the stop() method

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addStopListener(StopListener stopListener)` Register a stop listener. The stop listeners will be notified when the simulation stops.
`void`	`flushContent(java.lang.Object array)` Flush fully an array. Equivalent to call `flushContent(Object, int, int)` with the full array range.
`void`	`flushContent(java.lang.Object array, int offset, int length)` Flush the content of an array. Only range `[offset, offset + length - 1]` is flushed.
`void`	`flushImmortalContent(java.lang.Object array)` Flush fully an immortal array. Equivalent to call `flushImmortalContent(Object, int, int)` with the full array range.
`void`	`flushImmortalContent(java.lang.Object array, int offset, int length)` Flush content of an immortal array. Only range `[offset, offset + length - 1]` is flushed.
`NativeResource`	`getNativeResource(int resourceId)` Returns the registered `NativeResource` for the given resource ID.
`int`	`getNativeResourceCloseFunctionId()` Returns an integer that can be passed by the application to the method `SNI.closeOnGC()` as the `closeFunction` argument.
`byte[]`	`getResourceContent(java.lang.String resourceName)` Get full content of a resource.
`boolean`	`isImmortal(java.lang.Object obj)` Tells whether an object is an immortal array or not.
`void`	`notifySuspendEnd()` Notifies the simulator that the current native is no more suspended.
`void`	`notifySuspendStart()` Notifies the simulator that the current native is suspended so it can schedule a thread with a lower priority.
`void`	`refreshContent(java.lang.Object array)` Refresh full content of array if it is immortal. Does nothing if the given object is not an immortal array. Equivalent to call `refreshImmortalContent(Object)` assuming that the array is immortal.
`void`	`refreshContent(java.lang.Object array, int offset, int length)` Refresh content of array if it is immortal. Does nothing if the given object is not an immortal array.
`void`	`refreshImmortalContent(java.lang.Object array)` Refresh fully an immortal array. Equivalent to call `refreshImmortalContent(Object, int, int)` with the full array range.
`void`	`refreshImmortalContent(java.lang.Object array, int offset, int length)` Refresh content of an immortal array. Only range `[offset, offset + length - 1]` is refreshed.
`NativeResource`	`registerNativeResource(java.io.Closeable resource)` Registers a native resource that will be closed automatically when the simulator will stop or when the native resource will be unregistered (see `unregisterNativeResource(int)`).
`void`	`stop()` Allows to request the simulation stop.
`void`	`toCString(java.lang.String javaString, byte[] cString)` Transforms a Java String into a C String. The platform default encoding is used to transform Java characters into C characters. The created C String is a NULL terminated String (ends with '\0').
`java.lang.String`	`toJavaString(byte[] cString)` Transforms a C String into a Java String, using platform default encoding.
`NativeResource`	`unregisterNativeResource(int resourceId)` Unregisters the given resource.

- Method Detail
  - isImmortal
```
boolean isImmortal(java.lang.Object obj)
```
    Tells whether an object is an immortal array or not.
    
    Parameters:
    
    obj - the object to test.
    
    Returns:
    
    true if the given object is an immortal array, false otherwise.
  - refreshContent
```
void refreshContent(java.lang.Object array)
```
    Refresh full content of array if it is immortal.
    Does nothing if the given object is not an immortal array.
    Equivalent to call refreshImmortalContent(Object) assuming that the array is immortal.
    
    See Also:
    
    isImmortal(Object)
  - refreshContent
```
void refreshContent(java.lang.Object array,
                    int offset,
                    int length)
```
    Refresh content of array if it is immortal.
    Does nothing if the given object is not an immortal array. Equivalent to call refreshImmortalContent(Object, int, int) assuming that the array is immortal.
    
    See Also:
    
    refreshImmortalContent(Object, int, int), isImmortal(Object)
  - refreshImmortalContent
```
void refreshImmortalContent(java.lang.Object array)
```
    Refresh fully an immortal array.
    Equivalent to call refreshImmortalContent(Object, int, int) with the full array range.
  - refreshImmortalContent
```
void refreshImmortalContent(java.lang.Object array,
                            int offset,
                            int length)
```
    Refresh content of an immortal array.
    Only range [offset, offset + length - 1] is refreshed.
    
    Parameters:
    
    array - the immortal array to refresh.
    
    offset - the start index of the range.
    
    length - the length of the range.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given array is not an array or is not immortal.
    
    java.lang.ArrayIndexOutOfBoundsException - if the given range is invalid.
    
    BrokenConnection - if the array cannot be refreshed.
  - flushContent
```
void flushContent(java.lang.Object array)
```
    Flush fully an array.
    Equivalent to call flushContent(Object, int, int) with the full array range.
  - flushContent
```
void flushContent(java.lang.Object array,
                  int offset,
                  int length)
```
    Flush the content of an array.
    Only range [offset, offset + length - 1] is flushed. If array is immortal, this method calls flushImmortalContent(Object, int, int). Otherwise, if array has been passed as argument of an invoke method, the content of the array is marked to be flushed when method returns. This method may be called many times to extend the range to flush (union of intervals).
    
    Parameters:
    
    array - the immortal array to flush.
    
    offset - the start index of the range.
    
    length - the length of the range.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given array is not an array or is not immortal.
    
    java.lang.ArrayIndexOutOfBoundsException - if the given range is invalid.
    
    BrokenConnection - if the array cannot be flushed.
  - flushImmortalContent
```
void flushImmortalContent(java.lang.Object array)
```
    Flush fully an immortal array.
    Equivalent to call flushImmortalContent(Object, int, int) with the full array range.
  - flushImmortalContent
```
void flushImmortalContent(java.lang.Object array,
                          int offset,
                          int length)
```
    Flush content of an immortal array.
    Only range [offset, offset + length - 1] is flushed.
    
    Parameters:
    
    array - the immortal array to flush.
    
    offset - the start index of the range.
    
    length - the length of the range.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given array is not an array or is not immortal.
    
    java.lang.ArrayIndexOutOfBoundsException - if the given range is invalid.
    
    BrokenConnection - if the array cannot be flushed.
  - getResourceContent
```
byte[] getResourceContent(java.lang.String resourceName)
```
    Get full content of a resource.
    
    Parameters:
    
    resourceName - as described in Class.getResourceAsStream(String).
    
    Returns:
    
    the content of the resource (byte array) or null if not found.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given resource name is not absolute.
    
    BrokenConnection - if the resource could not be retrieved.
  - addStopListener
```
void addStopListener(StopListener stopListener)
```
    Register a stop listener.
    The stop listeners will be notified when the simulation stops.
    
    Parameters:
    
    stopListener - the listener to register.
  - stop
```
void stop()
```
    Allows to request the simulation stop.
  - toCString
```
void toCString(java.lang.String javaString,
               byte[] cString)
```
    Transforms a Java String into a C String.
    The platform default encoding is used to transform Java characters into C characters.
    The created C String is a NULL terminated String (ends with '\0'). The cString array length must be at least javaString.length()+1.
    The content of the given cString array is automatically flushed with the method flushContent(Object, int, int). Only javaString.length() bytes are flushed.
    
    Parameters:
    
    javaString - the Java String
    
    cString - byte array which contains the C String.
    
    Throws:
    
    java.lang.IllegalArgumentException - if javaString or cString is null
    
    java.lang.ArrayIndexOutOfBoundsException - if cString is too small to contain the string
  - toJavaString
```
java.lang.String toJavaString(byte[] cString)
```
    Transforms a C String into a Java String, using platform default encoding. The C String must be NULL terminated.
    The content of the given cString is automatically refreshed with the method refreshContent(Object).
    
    Parameters:
    
    cString - byte array which contains the C String
    
    Returns:
    
    a new Java String.
    
    Throws:
    
    java.lang.IllegalArgumentException - if cString is null or its length is 1
    
    java.lang.IllegalArgumentException - if cString is not NULL terminated.
  - registerNativeResource
```
NativeResource registerNativeResource(java.io.Closeable resource)
```
    Registers a native resource that will be closed automatically when the simulator will stop or when the native resource will be unregistered (see unregisterNativeResource(int)). When the native resource is closed, the close() method is called on the given Closeable.
    The native resource can also be closed if the application calls the SNI method NativeResource.closeOnGC() and if the object linked to the native resource is reclaimed by the application garbage collector.
    
    Parameters:
    
    resource - the resource to register.
    
    Returns:
    
    the NativeResource for the resource.
  - unregisterNativeResource
```
NativeResource unregisterNativeResource(int resourceId)
                                 throws java.lang.IllegalArgumentException
```
    Unregisters the given resource. This method doesn't call the close method on the NativeResource. The given resourceId must be a value returned by NativeResource.getResourceId().
    
    Parameters:
    
    resourceId - ID of the resource.
    
    Returns:
    
    the NativeResource that has been unregistered.
    
    Throws:
    
    java.lang.IllegalArgumentException - if no native resource is registered with the given ID.
  - getNativeResource
```
NativeResource getNativeResource(int resourceId)
                          throws java.lang.IllegalArgumentException
```
    Returns the registered NativeResource for the given resource ID. The given resource ID must be a value returned by NativeResource.getResourceId().
    
    Parameters:
    
    resourceId - ID of the resource.
    
    Returns:
    
    the native resource.
    
    Throws:
    
    java.lang.IllegalArgumentException - if no native resource is registered with the given ID.
  - getNativeResourceCloseFunctionId
```
int getNativeResourceCloseFunctionId()
```
    Returns an integer that can be passed by the application to the method SNI.closeOnGC() as the closeFunction argument.
  - notifySuspendStart
```
void notifySuspendStart()
```
    Notifies the simulator that the current native is suspended so it can schedule a thread with a lower priority.
    This method must be called before a wait or a sleep to simulate that a native has been suspended in SNI.
  - notifySuspendEnd
```
void notifySuspendEnd()
```
    Notifies the simulator that the current native is no more suspended. Lower priority threads in the simulator will not be scheduled anymore.
    This method must be called after a wait or a sleep to simulate that a native has been resumed in SNI.

Interface NativeInterface

Method Summary

Method Detail

isImmortal

refreshContent

refreshContent

refreshImmortalContent

refreshImmortalContent

flushContent

flushContent

flushImmortalContent

flushImmortalContent

getResourceContent

addStopListener

stop

toCString

toJavaString

registerNativeResource

unregisterNativeResource

getNativeResource

getNativeResourceCloseFunctionId

notifySuspendStart

notifySuspendEnd