IProcess: The Process interface for tasks to execute

The IProcess is the interface that all processes that we wish to delegate their execution to ISS must implement.

Has you can see in the JavaDoc documentation it is a very simple interface. It simply declares a single method, execute.

public ProcessResults execute();

This method will be invoked by the ISS when it decides to launch the processes into execution. It takes no parameters, since they're not necessary.

The execute method must return an object of the class ProcessResults with a compiled result of the executed process.

ProcessResults: The return object

All process execute some task. Nearly all of them have some feedback to give their caller. This can be a simple success of failure info (like a boolean flag), but more often than not a more detailed feedback is needed.

ISS provides a generic and flexible class to this need. The ProcessResults.

Let's for instance say that we needed to create a bunch of files on disk. These files would be created by a complex algorithm that would operate on external inputs that would determine what would be written to the files and even what would be the file names that would be created.

In this situation we would probably wish to receive the following return feedback:

• Was the file was created successfully?
• What was the name of the created file?
• How many bytes has been written to the file?
• Since were asking... a handler to the file. A File object for this file.

Lets see a quick code sample of how we could do this with the ProcessResults class:

(...)

// The file handler
File outputFile;

// The bytes written counter
Long bytesWritten = 0L;

(...)

// After the execution, let's assume that outputFile has been
// instanciated and contains the just created file!

ProcessResults results = new ProcessResults();
results.setOnError(false);
results.setResult("FileName", outputFile.getName());
results.setResult("TotalBytes", bytesWritten);
results.setResult("FileObject", outputFile);

(...)

We can see that it's very simple to use the ProcessResults for any kind of return data we want to return. The ProcessResults is basically an object that contains an error flag, and a MapString, Object that can contain any list of objects identified by a key string.

If these objects are simple or complex, if they contain for instance other Collections as the value, well, that's up to you.

In this example we return:

• No errors, by setting the error Flag to false.
• The name of the file, as a String object associated with the key "FileName"
• The number of bytes written to the file, by an Integer object associated with the key "TotalBytes"
• The file itself, or a handler to it, as a File object associated with the key "FileObject"

How could we get these values from the ProcessResults object? For instance...

File theWrittenFile = (File)results.getResult("FileObject");

ServiceRequest: The object for any process we delegate execution to the ISS

When we delegate execution of a process, by means of the delegate method (more on this later on) we expect some response in return. We could say we should receive the results of the execution of our process. A ProcessResults object like the one we have seen just now.

But we don't! Why? Because since ISS manages the execution of our process, it can decide that it cannot execute it immediately and so schedule it for later execution.

What then would be returned to the caller? A null result?

ISS addresses this by always returning a ServiceRequest object.

The ServiceRequest class encapsulates a set of information about the request we just issued to the ISS:

• The process that will be executed: The process object we delegated execution to ISS.
• The process state (as a ProcessState attribute): It will state if the process has been executed, it it is queued, if it is executing or if it has failed.
• The time when the request was made: The time of delegation to ISS, not the time if started executing.
• The time when the request finished it's execution: The time of execution end. Only filled if the process has terminated it's execution (successfully or not).
• The request id: The ID that was either generated by ISS for this request, or, when provided, the one we passed on to ISS to identify it. (more on this later on)
• The process execution results: The results as a ProcessResults object, but only when the process has finished execution. Until then it's null.

As you can see ServiceRequest contains much more information than just the results. It has relevant information even if there are still no results to be obtained.

We will see later on this section how we can monitor ISS constantly by asking for an updated ServiceRequest object for our process.

ISSManager

The ISSManager is were all starts.

The ISS instances must be instanciated, managed and given to the callers when asked. They have common needs, like logging. All this is the task of the ISSManager.

ISSManager is a static class that is used to get/create ISSs. We can have one ISS instance for managing all of our processes, or we can have several ISSs instances each dedicated to specific kind of processes, tunned is a specific way. This is up to the client application. ISSManager just provides what it is asked for.

synchronized static public ISS getISS(String id);
synchronized static public ISS getISS(String id, Properties configuration);