ISS

This is the main class we will work with. This class provides methods to execute (delegate) processes and gather executing processes information.

All the queue managing, synchronous/asynchronous logic, dynamic threshold, max and min synchronous processes thresholds are inside the ISS object, but none of this is relevant to the client code.

delegate: Request a process execution

The delegate method is "thee" ISS method. This method delivers a process to ISS for it's managed execution. This is the trigger for ISS to "do his thing"!

Lets see it's usage:

public ServiceRequest delegate(IProcess process);
public ServiceRequest delegate(IProcess aProcess, String id);

So as you can see it is all very simple. We create a process object, witch as we've seen before, is any object of any class that implements the IProcess interface and pass it to the ISS delegate method. The result is the already know to us ServiceRequest, where we can get info about the state of the process or the results themselves.

There are two methods. One receives only the process and another receives an extra String parameter, the ID. What's this for?

Every delegated process to ISS get's tagged with a generated process ID. This will enable ISS to refer to this process from know on by this ID. We can ask ISS for information about any process by passing this process ID to it. IT's the key for the process search. Some times we may want to provide this ID ourselves. And thus skip the generation of a new unique ID by ISS and give it our ID that it will attach to the process as if it had created it himself.

Why would we need to give our own ID?

There are times when we want to ensure that a process bound to a given task/user/session is not executed more than once at the same time.

ISS ensures that there cannot be two process running or waiting on queue with the same ID. If we create IDs with a given rule that ensures the unicity we need, then we can be rest assure that ISS will use it and thus not allow a second process to be delegated to ISS. If requested to, ISS will return the ServiceRequest object with the status of the first process and ignore the second process. Let's clarify this a bit more with an example...

For instance: Let's say we want to execute a process for a given user. There is a filled that identifies the user, the userID. Let's say that if ISS receives a second request for the same user (regardless of the session it comes from) ISS should return the first request and not create a new one.

(...)

// Create two different dummy process
IProcess processA = new SomeProcess();
IProcess processB = new SomeProcess();

// Get the current user ID from a dummy user instance
String userID = SomeUserObject.getUserID;

(...)

ServiceRequest resultProcessA = ISS.delegate(processA, userID);
ServiceRequest resultProcessB = ISS.delegate(processB, userID);

(...)

The previous example would place in both resultProcessA and resultProcessB the generated ServiceRequest for... processA! processB would not be executed nor accepted by ISS, and thus, be lost. This could be preciselly what we wanted or a very serious mistake!

And so, this is what we can get by controlling the IDs ourselves. If it is what we desire to. ISS is all about simplicity and flexibility.

Note: A very important thing to keep in mind is that once the process is delegated, only it's ID can allow us to ask ISS for information on it again. If we don't save the ServiceRequest to an attribute, we lose the process. It will get executed normally, but we loose the ability to interact with ISS regarding this process.

Getting information of a delegated method

We have stated before that we could get information of a given process by passing ISS a given ID. What can we receive and how can we do it?

Let's jump right into a quick sample code:

 1              ISS iss = ISSManager.getISS("TestISS");
 2              IProcess processA = new AProcess();
 3
 4              ServiceRequest request = iss.delegate(processA);
 5              
 6              while (request.getState() != ProcessState.FINISHED && request.getState() != ProcessState.ERROR) {
 7                      long estimatedTime = iss.getEstimatedTimeOfExecution(request.getRequestID());
 8                      
 9                      System.out.println("Process A will take " + estimatedTime + " ms...");
10                      
11                      // Wait the predicted duration as given by ISS for the process to end
12                      Thread.sleep(estimatedTime);
13                      
14                      // Update the request
15                      request = iss.fetchResults(request.getRequestID());
16              }
17              
18              System.out.println("Process A has finished execution with the result: " + request.getResults() + " ms...");
19              
20              if (iss.existsRequest(request.getRequestID()))
21                      System.out.println("ISS is faulty! The request is still present after final retrieval!");

This example was created just to show the available methods for process/request information retrieval. It is not supposed to mimic a real iss execution.

Basically this sample does the following:

  • Line 1: gets a ISS instance from the ISSManager.
  • Line 2: Created a dummy process.
  • Line 4: Delegates it's execution to ISS and saves the request returned.
  • Lines 6 to 16: While the process has not ended it's execution:
    • Line 7: Gets an estimated time for execution
    • Line 12: Waits the estimated time that ISS predicted
    • Line 15: Updates the request with the current state
  • Line 20: Murphy's law catch! If the process still exists in the ISS manager, then ISS is not functioning properly! ;-)

So, this little and inconsequent sample has just showed how to call all relevant ISS methods.

The JavaDocs are pretty well documented so when in doubt do read it.