Custom Method Invocation

You can use the methods provided here to perform Custom Method Invocation.

You sometimes need to implement your own functionality and be able to access it from the Server API, both locally and remotely. This was supported by the Server API in IBM® Security Directory Integrator 6.0, but it needed to be simplified so that you can drop a JAR file of your own in the IBM Security Directory Integrator classpath and then access it from the Remote Server API without having to deal with RMI.

Two methods are now available in the following interfaces:

com.ibm.di.api.remote.Session
com.ibm.di.api.local.Session

The two methods are:

public Object invokeCustom(String aCustomClassName, String aMethodName, Object[] aParams)
	throws DIException;

and

public Object invokeCustom(String aCustomClassName, String aMethodName,
	Object[] aParamsValue, String[] aParamsClass)
	throws DIException;

Both methods invoke a custom method described by its class name, method name and method parameters.

These methods can invoke only static methods of the custom class. This is not a limitation, because the static method of the custom class can instantiate an object of the custom class and then call instance methods of the custom class.

The main difference between the two methods is that the invokeCustom(String, String, Object[], String[]) method requires the type of the parameters to be explicitly set (in the paramsClass String array) when invoking the method. This helps when you want to invoke a custom method from a custom class, but also want to invoke this method with a null parameter value. Since the parameter's value is null its type can not be determined and so the required method to be called cannot be determined.

If the you need to invoke a custom method with a null value you must use the invokeCustom(String, String, Object[], String[]) method, where the required method is determined by the elements of the String array which represents the types and the exact order of the method parameters. If the user uses invokeCustom(String, String, Object[]) and in the object array put a value which is null than an Exception will be thrown.

Primitive types handling

These methods do not support the invocation of a method with primitive types of parameter(s). All primitive types in Java™ have a wrapper class which could be used instead of the primitive type.

Custom methods with no parameters

If your need to invoke a method which has no parameters you must set the paramsValue object array to null (and the paramsClass String array if the other method is used).

Errors

Several exceptions may occur when using these methods. Both local and remote sessions support these two methods, but the Server API JMX does not.

Turning custom invocation on/off

The ability to use invokeCustom() methods can be turned on or off (the default is off). This can be done by setting a property in the global.properties file named api.custom.method.invoke.on to true or false. If the value of this property is set to true then users can use these methods.

Specifying the classes allowed for custom invocation

There is a restriction on the classes which can be invoked by these Server API methods. In the global.properties file there is another property named api.custom.method.invoke.allowed.classes which specifies the list of classes which these methods can invoke. If these methods are used and a class which is not in the list of allowed classes is invoked then an exception is thrown. The value of this property is the list of fully qualified class names separated by comma, semicolon, or space.

Examples

Here are some sample values for these properties:

api.custom.method.invoke.on=true 
api.custom.method.invoke.allowed.classes=com.ibm.MyClass,com.ibm.MyOtherClass

The first line of this example specifies that custom invocation is turned on and thus the two invokeCustom() methods are allowed to be used. The second line specifies which classes can be invoked. In this case only com.ibm.MyClass and com.ibm.MyOtherClass classes are allowed to be invoked. If one of the two invokeCustom() methods is used to invoke a different class then an exception is thrown.

Defaults

The default value of the api.custom.method.invoke.on property is false. This means that users are not allowed to use the two invokeCustom() methods and that an exception would be thrown if any one of these methods is invoked. The default value of the api.custom.method.invoke.allowed.classes is empty, in other words, no classes can be invoked. This means that even if custom invocation is turned on no classes can be invoked by the two invokeCustom() methods.

A Full Example

Suppose the following class is packaged in a jar file, which is then placed in the 'jars' folder of IBM Security Directory Integrator:

public class MyClass {
	public static Integer multiply(Integer a, Integer b) {
		return new Integer(a.intValue() * b.intValue());
	}  
}

Suppose the global.properties IBM Security Directory Integrator configuration file contains the following lines:

api.custom.method.invoke.on=true
api.custom.method.invoke.allowed.classes=MyClass

Then in a client application the 'multiply' method of 'MyClass' can be invoked in a Server API session like this:

Integer result = (Integer) session.invokeCustom(
                          "MyClass", 
	                        "multiply", 
											new Object[] {new Integer(3), new Integer (5)});