Abstract
The architecture of the DataCutter written by Mike Beynon is done entirely in C++.  Users of his architecture must compile their filters, which are essentially remote objects, with his API.  The filters are made in such a way that they will be spawned by an application daemon.  However, the filters can theoretically be done in any language as long as it is possible to deal with TCP streams.  The problem of using different languages is that for each language there would have to be created an infrastructure to deal with the incoming/outgoing streams, according to the original specification.  Not only is this a difficult task to accomplish but also it would require changes each time the C++ spec is changed.  
Currently the need for another language suitable for filter creation besides C++ is JAVA.  To avoid the problem of creating two identical architectures in different languages it was decided to use as much of the C++ code as possible and enable JAVA to use it.  JNI allows having function declarations in JAVA but have the actual implementation done in C++.  In most cases where JNI is used, the JAVA program loads a C++ DLL and that contains the implementations of the native functions.  A more advanced method was chosen where a C++ program would load the JVM and then register native functions with the JVM so that JAVA code doesn’t have to use load any C++ libraries.  This method simplifies things as minor changes can be done to the application daemon to incorporate the new architecture instead of creating a special DLL for JAVA to use.

Overview of Integration
In order to make the JAVA filters compatible with the existing C++ DataCutter architecture a couple of modifications are required to the existing C++ code.  All other required steps do not require any further changes since they rely on the existing API.  A special version of the App Daemon must be built that has the required JNI functions compiled and linked into it.  Also this special version will use the DC_CToJava_Filter_t class to launch JAVA filters and some small changes must be added to make sure that singleton classes and the JVM get cleaned up on exist.  The new version of the App Daemon creates a new DC_CToJava_Filter_t using the provided class factory when a request for a JAVA filter creation comes in.  The call to the constructor of DC_CToJava_Filter_t will cause dynamic registration of the JNI methods with the JVM and NativeReg utility class.  The NativeReg class is created as a singleton the first time somebody calls its class factory and subsequent calls to the factory will return a pointer to the already active class.  
After the creation of the filter the “init” call is issued to the filter and a initarg_t structure is passed to it.  When the call is made the pointer between the JAVA filter and the structure is saved in the DC_JNIMap map.  DC_JNIMap is similar in nature to the NativReg because only a single instance of it can be created during execution so thus it can be used as a global mapping table.  Then a call is made to the “start_work” method of the filter.  Any JNI calls by the JAVA filter can access the mapping table to fetch any information that was passed from C++ side to JAVA and use it to perform needed operations.  
The JNI functions work as wrappers and data converters to simply invoke the C++ functions of the DataCutter API.  For the most part App Daemon doesn’t call JAVA methods.  The majority of the calls are passed down into C++ because that’s where the core functionality is implemented.  The JAVA filter can use the provided API without any knowledge that the functions are implemented as natives, thus abstracting the user from the details of the JNI/JVM programming.
	Upon the termination of the App Daemon the singleton classes must be deleted as they will clean up any resources allocated on the heap and will initiate the JVM shutdown.

Required Classes
	The implemented architecture extensively relies on the three main classes: NativeReg, DC_JNIMap, and DC_CToJava_Filter_t.  NativeReg class can be thought of as a utility class required for managing the JVM and simplifying interactions with JAVA from C++.  DC_JNIMap is used as global storage table to store links between JAVA classes and C++ pointers.  And DC_CToJava_Filter_t acts as a wrapper by inheriting DC_Filter_Base_t so that the rest of C++ API could treat the JAVA filter as a regular C++ filter.

Class NativeReg

NativeReg provides functionality that simplifies integration of a JAVA virtual machine into C++ code.  A class factory is used to make sure that this is the only instance of the class as it will contain a JVM.  The class also facilitates registration of native methods with JNI so that they can be called from the JAVA side.  Besides allowing easier registration of the native methods this class provides methods to invoke JAVA methods without knowing the ins and outs of JNI.

Private members of the class

    struct FArgs
    {
        char        type;       // type of the argument
        bool        barr;       // array or just a single argument
        std::string class_path; // path of the class in case type is            
  // 'O' for object
    };
FArgs structure is used to specify a type of an argument a function is expecting

    struct FParams
    {
        jclass              clazz;      // class id
	  std::string         fname;      // name of the function
	  std::string         fsignature; // function signature in JAVA
	  void               *fptr;       // function pointer
        std::vector<FArgs>  arg_vec;    // expected argument types
    };

FParams structure describes all the needed information about a function that is native and can be registered with JNI.  Each time a function is registered a new FParams structure is filled out and appended to a list of registered functions. 

Public Methods
~NativeReg();  
Destructor for the class that unloads the JVM and does other clean up.

jclass  RegisterMethod(char *class_name, 
     char *method_name, 
     char *signature, 
     void *fptr);
This function registers a native function with the JNI and appends the function info to the internal list of registered functions.  
class_name – specifies what JAVA class declares the natively implemented function
method_name – JAVA name of the function to be registered
signature – ASCI signature of the function based on the JNI format
fptr – C++ function pointer of the implemented native function
Returns a jclass value that identifies a class that declares this function.

int GetNativeCount();
Returns the number of registered methods.

jvalue InvokeRegMethod(jobject &obj, 
     jclass   jc, 
     char    *method_name, 
     ...);
Invokes a registered JNI function through the JVM.  The function will take arguments and go through a list of registered methods to see if such function was indeed registered.  If a match is found, then the arguments that were passed through a variable argument list are converted into JAVA types based on the function signature.   Then a function is invoked and its return value is returned through jvalue that InvokeRegMethod returns.
obj – represents the instance of the JAVA object that declares the function
jc – type of the JAVA object
method_name – Name of the method to be invoked
… - Variable argument list that will be used as arguments by the function being invoked

jvalue  InvokeMethod(jobject &obj, 
         jclass   jc,
         char    *method_name, 
   char    *method_sig,
   ...);
Works like the above function.  The only difference is that the function does not have to be registered.  Because of that the user must provide the functions signature according to the JNI convention and the function name.  The invoked function can be any JAVA method.  
obj – represents the instance of the JAVA object that declares the function
jc – type of the JAVA object
method_name – Name of the method to be invoked
method_sig – As the function is not registered it is unknown what  signature it has.  The passed in signature string of the JNI format specifies how the passed in arguments must be converted into JAVA types.
… - Variable argument list that will be used as arguments by the function being invoked

int     CreateDefObject(jclass  clazz, 
jobject &obj);
Creates a default JAVA object.  Based on the class id the function will instantiate a JAVA object that has a default constructor and then will give a reference to it.
clazz – JAVA class id
obj – references to the instantiated object.

    	int     CreateJavaClass(JNIEnv     *env, 
const char *className, 
const char *constructorSig, 
jvalue      params[], 
jobject    &result);

Creates an instance of a JAVA class.  The function will use the JNIEnv that is stored in the NativeReg class if the provided is identical; otherwise, it will use the new value.  The other arguments specify what class should be instantiated and what constructor to call.   A reference to the new instance is returned.
env – What JVM environment to use
className – Name of the JAVA class that will produce a jclass id
constructorSig – JNI formatted string to specify the constructor signature
params – parameters for the constructor
result – reference to the newly instantiated object

      jint    GetHashCode(JNIEnv *env, 
  jobject obj);
Returns a hash code value of the JAVA class type to which the reference belongs.  
env – pointer to a JVM environment.  If the pointer is different from what is inside the NativeReg class is used the new value is adopted.

obj – a reference to the JAVA object whose hash value is needed
	
JNIEnv *GetEnv();
Returns a JVM environment pointer that is contained in the NativeReg class.  

Class DC_JNIMap

This class exists as a singleton to provide a map of JAVA object references to C++ pointers.  JNI native functions can use this map to find C++ classes to which they are associated to in order to use functionality enclosed in that class.   Typically a native function that is called during the initialization stages of a JAVA object creates a C++ class that it is trying to reflect and saves the pointer so that the C++ object can be accessed later on.  

static DC_JNIMap* GetJNIMap(); 
 Creates a new singleton instance of the DC_JNIMap class and returns a pointer to it.  If the object has already been instantiated then a pointer to it is returned.  

   	jlong find(JNIEnv *env, 
     jobject javaObject);
Finds out if a reference to a JAVA object is mapped to a C++ pointer.  If such association exists then the pointer is returned; otherwise, zero is a return value.
env – pointer to a JNI environment.  This pointer will be passed to the 
NativeReg::GetHashCode function
javaObject – reference to a JAVA object whose association in the map needs to be looked 
  up.

void addPair(JNIEnv *env, 
jobject  javaObject, 
jlong    cObject);
	Add an association into the map of a C++ pointer and a JAVA object reference.
env – pointer to a JNI environment.  This pointer will be passed to the 
NativeReg::GetHashCode function 
	javaObject – reference to a JAVA object to create a map pair.
	cObject – C++ pointer cast to a jlong to make the map pair.

   	bool remove(JNIEnv *env, 
jobject javaObject);
If a map entry is found that corresponds to a hashed value of javaObject then the map entry is removed.
env - pointer to a JNI environment.  This pointer will be passed to the 
NativeReg::GetHashCode function
javaObject – JAVA object reference whose hash value is looked up and then searched in the 
map.  If the search is successful the map entry is purged.

   	inline int getSize(); 
	Returns the number of pairs that are in the map.

inline void clear();
Clears all entries in the map.

Class DC_CToJava_Filter_t 

This class is used by the application demon to start a JAVA filter.  The class factory is used to create a user filter by loading the JAVA class.  Essentially this class is just a wrapper that creates a JAVA filter in the JVM and then uses JNI to communicate with the filter from C++ code.  Also links are made in the static map between C++ structures like initarg_t and arg_t and their JAVA versions for later access.  Calls by the JAVA filter into the JNI functions will use the links in the map to gain the needed information.

static DC_Filter_Base_t *filter_factory(
const char    *sbFilterName);
Constructs a user JAVA filter.  The class name of the filter must be in one of the directories that can be found by the JVM in order to load the class.  

virtual int init(initarg_t &arg);
Attaches the arg to the map of the class and then calls the “start_work” function of the JAVA filter.

virtual DC_RTN_t process(arg_t &arg);
Attaches the arg to the map of the class and then calls the “process” function of the JAVA filter.

   	virtual int finalize(void);
	Calls the “finish_work” function of the JAVA filter.