Usage

Topics covered in this chapter:

Calling Java

Add uses 'mosjvm' to the top of your model then you can call any static Java method by passing its full class and method name to one fo the jvmcall<type> functions, where <type> represents the return type of the function, for example:

model myModel
  uses 'mosjvm'

  writeln('Integer return value=', jvmcallint('com.fico.MyClassName.myIntMethod'))
  writeln('String return value=', jvmcallstr('com.fico.MyClassName.myStringMethod'))
  writeln('Real return value with two parameters=',
          jvmcallreal('com.fico.MyClassName.myRealMethod', 5.7, true))
  writeln('Any object return value=', jvmcallobj('com.fico.MyClassName.myObjMethod'))
end-model

You can call jvmcallvoid if your Java method doesn't return anything. Any number of method arguments may be specified, from the following types:

• boolean (translates to Java type: boolean)
• integer (translates to Java type: int)
• real (translates to Java type: double)
• string (translates to Java type: java.lang.String)
• text (translates to Java type: java.lang.String)
• jvmobject
• array of boolean (translates to Java type: boolean[])
• array of integer (translates to Java type: int[])
• array of real (translates to Java type: double[])
• array of string (translates to Java type: java.lang.String[])
• array of text (translates to Java type: java.lang.String[])
• array of jvmobject (translates to Java type: java.lang.Object[])

Where an argument is an array, it must be indexed by a Mosel range starting from 0, e.g.:

model myModelAr
  uses 'mosjvm'
  declarations
    MyArray: array(range) of string
  end-declarations

  MyArray(0) := "zero"
  MyArray(1) := "one"
  MyArray(2) := "two"

  jvmcallvoid("com.fico.MyClassName.myMethodTakingArrayOfString", MyArray)
end-model

You can call instance methods on a Java object by passing the object reference as the first parameter and method name as second, e.g.:

model myModel
  uses 'mosjvm'

  ! Call static method to get object
  sysprops := jvmcallobj('java.lang.System.getProperties')
  ! Call non-static method on that object
  writeln('java.version property value = ',jvmcallstr(sysprops, 'getProperty', 'java.version'))
end-model

Starting Java

The first time a jvmcall<type> function is called from a model in a Mosel process, mosjvm will load and initialize a Java virtual machine. This Java virtual machine will then be used by all subsequent jvmcall<type> functions called by models in this process—if your Java functions modify any static fields, those modified values will be read by subsequent calls, possibly from different models. If you are using mosjvm from multiple submodels within the same Mosel instance, your Java code will need to be threadsafe.

By default, mosjvm will look for the Java Runtime Environment in the following locations:

• The folder specified by the MOSJVM_JAVA_HOME environment variable, if set
• The folder specified by the JAVA_HOME environment variable, if set
• Relative to the location of a java executable found in a folder on the PATH environment variable
• In some common install locations

To force mosjvm to use a specific installation of Java, set the environment variable MOSJVM_JAVA_HOME before starting Mosel.

Classpath

By default, mosjvm will look for your Java classes using a classpath determined as follows:

• The classpath specified by the jvmclasspath parameter, if set
• Otherwise, the classpath specified by the MOSJVM_CLASSPATH environment variable, if set
• Otherwise, the classpath specified by the CLASSPATH environment variable, if set
• Otherwise, the current working directory of the Mosel process

Exception handling

When an error occurs within a Java method, the Java Virtual Machine will throw an exception. From Mosel, you can check whether your last call to Java threw an exception by calling the jvmstatus function; a return value of false indicates an exception. When jvmstatus is false, the jvmgetexceptionclass function will return the class name of the exception (e.g. java.io.FileNotFoundException) and the jvmgetexceptionmsg function will return the exception's message. For example:

model myModelExc
  uses 'mosjvm'

  jvmcallvoid('com.fico.MyClassName.parseMyInputFile', 'inputfile.dat')
  if jvmstatus=false then
    setioerr('Encountered Java error of type: '+jvmgetexceptionclass+", message: "+jvmgetexceptionmsg)
  end-if
end-model

If you set the parameter jvmdebug to 'true', the stack trace of any exceptions thrown by your calls to Java will be written to the Mosel model's error stream.

If you set the parameter jvmabortonexception to 'true', the Mosel model will immediately terminate with a runtime error if any Java method throws an exception.

Method Signatures

When you invoke any of the jvmcall functions, mosjvm will first look for a method with the types exactly matching those passed in. For example, if you pass two integers, mosjvm will look for a function signature that takes two int values. If passed an argument of type jvmobject, mosjvm will look for a method accepting values of the type of the object reference stored in the jvmobject.

If no match is found, mosjvm will search the class for any method with the correct name that could accept the parameters passed. If multiple matching methods are found, the one chosen is arbitrary, for example if the arguments are a jvmobject containing a java.lang.Integer and your class defines these methods:

public static void myMethod(Object o);
public static void myMethod(Number o);

then it is not possible to predict which method mosjvm will call.