To properly write Java code that is to be made available as services in PLAN, a number of rules must be followed.
One of these classfiles should contain a method install with the following signature:
public static void install(SymbolTable svcs_symtab, Class thisClass)This method will install bindings into the given SymbolTable for the functions to be exported into the PLAN evaluation environment. The methods that are installed may be obtained using Java functions which take thisClass as an argument (see the example in the previous section).
All methods that are installed in the symbol table should have the signature
public static Value myMethod( List<Value> vlist, ActivePacket p) throws ExecException, PLANExceptionwhere myMethod is the name of the method you wish to make available.
Each exported method is responsible for its own verification (arity, argument type-checking). If verification fails, some form of ExecException should be thrown. If some other problem occurs with the execution of the function, then a PLANException should be thrown, which will be visible to the executing PLAN program. For example, if the PLAN exception BadHost is to be raised, then the Java method would execute the code
throw new PLANException("BadHost");All PLAN exceptions that are thrown by services must also be installed in the symbol table by the install method or else PLAN programs will not be able to handle them.
The class that contains the install method must be a public class. The access privelages of the other classes depend on whether the classes are to be installed statically or dynamically.
To install services statically requires two steps:
package PLAN.foo;The makefiles of the source distribution should be altered to include this new package.
To install services dynamically involves using a PLAN program to transfer your files to the appropriate node and install them. This is done by using PLANStart's getBlobFromFile service to read the files from disk into a PLAN packet to be injected. This packet travels to the node to receive the new code and then invokes installServices (see the PLAN programmer's guide for more).
To install a new version of the same service dynamically, you need to recompile your service code using different class names. This is because Java will only allow you to have one version of a class running at a time (and the JVM currently does not garbage collect classes). For example, if your service was loaded under the classname foo, you could change the name to bar, recompile, and the reload the new classfile. The old classfile and bindings will still be present in the running router, but they will be hidden by the new version. Eventually stale classes will occupy too many system resources, and so the router will have to be shut down and restarted. This problem is Java- and not PLAN-specific, so it may be fixed in future versions of PLAN.