This document describes the proper way to develop .NET applications using Oaa2JavaNet.dll and the dotnetproxy API.

There are 3 classes which are used for configuring the dotnetproxy connection. They are:

• jnb.com.sri.sedc.javanetbridge.JavaNetBridgeInteropClass: This is the base class for Oaa2JavaInterop (see below). This class is not meant to be created directly, but contains two important static methods which allow the programmer to set the host and port of the dotnetproxy. Note that the host and port must be set at the start of the application before any proxy objects are used. The connection to the proxy will be initiated the first time any of the proxy APIs are accessed, so these settings must be applied first. Currently there is no way to change the proxy agent location, and if a connection is broken to the proxy agent the application must be restarted. The following is example code for changing the host and port:

      JavaNetBridgeInteropClass.setConnectAddress(System.Net.IPAddress.Parse("128.18.233.111"));
      JavaNetBridgeInteropClass.setConnectPort(4080);

• com.sri.sedc.javanetbridge.Oaa2JavaInterop: This is the main interop class, or the "guts" of the dotnetproxy code. This class does not need to be accessed except for the following two reasons:
  1. To cause the application to connect with the dotnetproxy, simply invoke the method Oaa2JavaInterop.getSingleton().
  2. To retrieve the JavaNetBridgeBean interface (see below), execute the following code:

         JavaNetBridgeBean bean = Oaa2JavaInterop.getSingleton().getJavaNetBridgeBean();

  Note that this class is packaged in the "com" namespace as opposed to the "jnb" namespace. This is because the class is not generated and is not part of the core jnb apis. As such, it is packaged outside the "jnb" package.
• jnb.com.sri.sedc.javanetbridge.JavaNetBridgeBean: Generated java interface which allows access to the java bridge bean. Here, "java bridge bean" does not mean "JavaBean" in the java sense, but instead refers to the controller on the Java side which proxies calls back and forth. This bridge bean is a placeholder for setting options and accessing the internal workings of the dotnetproxy. For example, it can be used to obtain the object database and inspect what objects exist, their reference counts, etc. From a basic developer perspective, this bridge bean only has one method which needs considering, and that is the method which turns tracing on and off. For example:

      JavaNetBridgeBean bean = Oaa2JavaInterop.getSingleton().getJavaNetBridgeBean();
      bean.setTraceMethods(false);
  

  If setTraceMethods is called with a "true" value, then the dotnetproxy will print information every time a java method is invoked. This can be very verbose, and is intended only for debugging purposes.

The remaining API is almost equivalent to the OAA2 Java API with the following differences:

• Methods and constructors which have a return value or parameters that is an array of objects are not generated. These methods are not supported. However, an array of String objects is supported.
• Exceptions are not mapped to .NET. If a Java exception occurs, a System.Exception will be thrown by the dotnetproxy assembly containing a description of the error and the java stack trace.
• The dotnetproxy classes are packaged starting with "jnb". For example, the java package "com.sri.oaa2.icl" presents itself as "jnb.com.sri.oaa2.icl" in the dotnetproxy API.
• Every java class which is mapped has the static const "JAVA_CLASS_NAME" defined (this does not include interfaces). Furthermore, two constructors and two static methods which start with "new" are defined internaly to the dotnetproxy. Normally these constructors and methods are not intended to be used. However, under special circustances they may be required. The static methods provide the same functionality of the constructors. The constructors are used to cast an arbitrary object to an object of that particular type. The first constructor accepts a "JavaObject" type, which is a mapping to the base java object (see below). The second accepts an id and a flag inidicating whether or not to add a reference for the object. Using these methods can be dangerous, and errors will occur if the input object ot object id is not the expected class. Use these generated constructors and static methods with caution, or do not use them at all.

  It is important to avoid using these constructors on accident. For example, it may appear that you can supply any object to the constructor, when in Java code that it not the case. Understand that this constructor is only intended for casting, and check the constructor syntax before using it.

• For interfaces only, callback implementation stubs are provided. See the next section on how to do callbacks with the dotnetproxy API.

In addition to the OAA classes, basic java.lang and java.util classes are also generated. They include:

• jnb.java.lang.*: This package contains java language classes as well as reflection classes. The base class, "JavaObject" maps to the base java class. Note that when the "ToString" method of any proxy object is called, the Java "toString" method will be invoked. Also note that the proxy attempts to avoid nameclashing with existing dotnet objects. For example, "JavaObject", "JavaLong", "JavaString", etc.
• jnb.java.util.*: Contains a subset of the java.util package. Some of these interfaces and classes are used in OAA.

As mentioned, callback stubs are provided for interfaces. Suppose a Java method has a arameter which is an interface, and you want to implement that interface in .NET? By conventional means, it is necessary to implement that interface in .NET. However, this is not trivial because every Java interface that is generated also requires java object methods to be implemented, as well as underlying proxying code. For this reason, callback stubs are generated automatically for each interface. To implement an interface in .NET, inherit the .NET class from the callback stub and implement the methods for the interface.

Callback interface classes are packaged and named the same as their corresponding implementation, except that "_CallbackImpl" is added on the end. For example, the interface jnb.com.sri.oaa2.lib.OAAEventListener has the callback stub class jnb.com.sri.oaa2.lib.OAAEventListener_CallbackImpl. A class can inherit from this class and overide the methods for the interface. For example:

    public class MyAgent : OAAEventListener_CallbackImpl
    {
        public override bool doOAAEvent(IclTerm goalTerm, IclList parameters, IclList answers)
        {
            Console.WriteLine("doOAAEvent called, goal = " + goalTerm);
            String goal = goalTerm.toIdentifyingString();
            if (goal.Equals("mysolvable"))
            {
                // ...
                return true;
            }
            return false;
        }
    }

Full source is provided for the dotnetproxy code. The source is located in the OAA repository under "src/oaalib/dotnet/Source/csharp". In this directory is a zip file named "generated_source.zip". To examine the source from the Oaa2JavaNet.dll solution, unzip the contents of this file into the directory "src/oaalib/dotnet/Source/csharp/generated" (note: this directory does not exist by default and will probably need to be created). Once this is done, the solution file "src/oaalib/dotnet/Project/Oaa2JavaNet/Oaa2JavaNet.sln" can be opened to examine the source.

In the OAA distribution, "src/samples_dotnet" contains sample applications which use the dotnetproxy agent library. The most simple of these is the AddAgent, which adds two integers together. See these examples for example csharp code. Also note that the example program "TestAgent" is a port of the Java TestAgent to csharp. This agent is used for unit testing and performance testing.