Writing Service Code

To properly write Java code that is to be made available as services in PLAN, a number of rules must be followed.

• Mutual Exclusion
  There are no primitives in PLAN to allow for mutual exclusion. Therefore, services must implement their own to guarantee that PLAN programs do not cause inconsistent state. In the current version of PLAN, this is not a problem, because the active router is single-threaded; that is, only one PLAN program may ever be running at any time, so there is no way that two programs may concurrently interact with shared state. This will undoubtedly change, so you should be aware of it when writing your services.

• Form of Services
  A new service for PLAN should have the following form. It will consist of N classfiles which make up the code for the new service. The Java source that constitute these services must be compiled with access to the PLAN implementation. This is done by properly setting up your CLASSPATH (see the tutorial document for more).

  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, PLANException
  

  where 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.

• Dynamic vs. Static Loading

  To install services statically requires two steps:

  • First create a separate package for your service. All source files should be in this package, and it should be placed in the PLAN directory. In other words, the service foo will have its source in the directory PLAN/foo and each source file will have in it the declaration in it

    package PLAN.foo;
    

    The makefiles of the source distribution should be altered to include this new package.

  • Secondly, the class ARMain must be altered to invoke the install method in the appropriate class of the service. This invocation should occur in the ARMain function installServices.

  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.