Writing Your First Java PAPI Program

Programming a Java PAPI Client

Import the Required Libraries

You need to import PAPI classes to be able to use them in your code. The following code imports the PAPI classes needed for this example.

import fuego.papi.CommunicationException;
import fuego.papi.InstanceInfo;
import fuego.papi.ProcessService;
import fuego.papi.ProcessServiceSession;
import fuego.papi.OperationException;
            

Create a Process Service

In order to create a ProcessService you need a java.util.Properties object containing its configuration. You can create this property object and build it within your Java code, or you can load it from a properties file. This example adds the properties within the code for practical reasons.

The two mandatory properties you need to specify are the directory id and the path to the directory.xml file.

Properties configuration = new Properties();
properties.setProperty(ProcessService.DIRECTORY_ID, "default");
properties.setProperty(ProcessService.DIRECTORY_PROPERTIES_FILE, "directory.xml");

            

To create a ProcessService object you need to invoke the factory method ProcessService.create() from the class ProcessService passing it the Property object as an argument.

If there is a problem locating the Directory Service, this method throws a CommunicationException , so you need to call it inside a try-catch block.

                
try {
    ProcessService processService = ProcessService.create(configuration);
    //...
} catch (CommunicationException e) {
    System.out.println("Could not connect to Directory Service");
    e.printStackTrace();
}
            

Create a Process Service Session

If there is a problem authenticating the specified participant, this method throws an OperationException , so you need to invoke it inside a try-catch block.

try {
    //...
    ProcessServiceSession session = processService.createSession("user", "password", "host");
    //...
} catch (OperationException e) {
    System.out.println("Could not perform the requested operation");
    e.printStackTrace();
}
            

Perform Operations with PAPI

The following code retrieves a list of available processes by invoking the method processesGetIds() over a ProcessServiceSession object.

It then iterates over them using those ids to obtain the process instances for each process by invoking the method processGetInstances() over the session object.If there is a problem performing any of the requested operations, this method throws an OperationException , so you need to invoke it inside a try-catch block.

Finally it iterates over those instances invoking the method getId() and prints its result.

try {
    //...
    System.out.println("Show Instances by process:");
    for (String processId : session.processesGetIds()) {
        System.out.println("\n Process: " + processId);
        for (InstanceInfo instance : session.processGetInstances(processId)) {
            System.out.println(" -> " + instance.getId());
        }
    }
} catch (OperationException e) {
    System.out.println("Could not perform the requested operation");
    e.printStackTrace();
}

            

Close the Process Service Session

To close the session, invoke the method close() over the ProcessServiceSession object.

session.close();
            

Closing a session releases all the resources this session is using. After calling the method close(), the session can no longer be used. If you try to invoke a method on a closed session, its execution fails and a SessionClosedException is thrown.

Close the Process Service

To close the ProcessService object, invoke the method close() over the ProcessService object.

processService.close();
            

This releases all the resources used by PAPI, clears the caches, deletes the temporary files, and closes the connections to the Process Engine and the Directory Service.

Complete Code Example

The following class contains all the steps described in this section.

                    
package papidoc.examples;

import fuego.papi.CommunicationException;
import fuego.papi.InstanceInfo;
import fuego.papi.ProcessService;
import fuego.papi.ProcessServiceSession;
import fuego.papi.OperationException;
import java.util.Properties;

public class PapiExample {

    public static void main(String[] args) {

            /////////////////// API Initialization ///////////////////
            Properties configuration = new Properties();
            configuration.setProperty(ProcessService.DIRECTORY_ID, "default");
            configuration.setProperty(ProcessService.DIRECTORY_PROPERTIES_FILE, "directory.xml");
            configuration.setProperty(ProcessService.WORKING_FOLDER, "/tmp");

        try {
            ProcessService processService = ProcessService.create(configuration);

            /////////////////// Establish a session ///////////////////
            ProcessServiceSession session = processService.createSession("test", "test", "host");

            /////////////////// Operate with PAPI ///////////////////
            for (String processId : session.processesGetIds()) {
                System.out.println("\n Process: " + processId);
                for (InstanceInfo instance : session.processGetInstances(processId)) {
                    System.out.println(" -> " + instance.getId());
                }
            }

            /////////////////// Close the session ///////////////////
            session.close();

            /////////////////// Release API Resources ///////////////////
            processService.close();
        } catch (CommunicationException e) {
            System.out.println("Could not connect to Directory Service");
            e.printStackTrace();
        } catch (OperationException e) {
            System.out.println("Could not perform the requested operation");
            e.printStackTrace();
        }
    }
}
            
                

The following sequence diagram shows the interaction between the classes used in the example.

Figure 1. PAPI Client Example Sequence Diagram