====== Integrating External Commands Into a MIF Pipeline ======

An "external command" is an operating system command called by MIF when a request is received to execute it.  To integrate an external command into a MIF pipeline, an ''ExternalCommandModule'' is created to wrap the call to the command.

This document demonstrates:

  - How to create an ''ExternalCommmandModule'' by following a sample provided with MIF.
  - How to run the external command sample code

Prerequisites:

  * [[Install MIF]]
  * Review and understand the [[hello world example]]

Sample code:

  * The sample code described here can be found in the most recent MIF distribution in the directory:

  $MIF_HOME/samples/gov/pnnl/mif/api/samples/guide/external

===== Creating an ExternalCommandModule =====

==== ExternalCommandDriver ====

This sample driver class shows how to create an ''ExternalCommandModule''.  Here are the pertinent excerpts...

First, create a MIF pipeline and a JMS connector:

  MifPipeline pipeline = new MifPipeline();
  pipeline.addMifJmsConnector("jmsConnector1", "localhost:1099");

Next, create inbound and outbound endpoints for the module:

  // Inbound endpoint - used to receive the external command and its parameters 
  MifEndpoint inEndp = pipeline.addMifEndpoint("inEndp", EndpointType.JMS, "topic/testTopic");
      
  // Outbound endpoint - used to send the return value of the external command
  MifEndpoint outEndp = pipeline.addMifEndpoint("outEndp", EndpointType.JMS, "topic/HalTopic");

Now create an ''ExternalCommandModule'' and add it to the MIF pipeline, specifying a unique name for the module, the inbound and outbound endpoints.

  pipeline.addExternalCommandModule("MyExternalCommand", inEndp, outEndp);

Note that no processor implementation is specified.  The command is supplied by a data object which is sent to the inbound endpoint of the module.  The processor code which calls the actual command is provided behind the scenes by MIF.

==== ExternalCommandPublisher ====

This sample class is a typical JMS publisher.  It creates an ''ExternalCommand'' object and then publishes it to the topic specified by the inbound endpoint of the external command module listed above.  Here, we want to execute the command ''ls -la''.

First, create the ''ExternalCommand'' Object, specifying the ''ls'' command:

  ExternalCommand cmd = new ExternalCommand("ls");

Then, we add the arguments to ls:

  cmd.setArgs(new String[]{"-l", "-a"});

We could also set the working directory, whether to run the command in the background, and an array specifying the environment variables to use for the command run.  The environment is specified with an array of key value pairs, for example:

  cmd.setEnvironment(new String[]{"VAR1","value1","VAR2","value2"});




===== Summary =====

As you can see, it's pretty easy to integrate a command line program into a MIF pipeline.  You will need to implement other MIF constructs to check on the status of the command or to move the output data to a desired location.