Using Presto Connect for Java

You use PC4J to connect Java applications or portlets for portals to the Presto Mashup Server and invoke mashables or mashups. This API is a Java wrapper for the JUMP protocol.

See PC4J API documentation for details on Presto Connect classes.

PC4J works in local mode and remote mode. In local mode, both the client application and the Mashup Server run in the same JVM. In remote mode, the client runs in a separate JVM from the Mashup Server.

To begin working with PC4J, you must Add PC4J to Your Application. You can then Create Connections and Invoke Artifacts with PC4J.

Add PC4J to Your Application

The PC4J library contains everything you need for remote connections. For local connections, you must also add some additional classes from the Mashup Server.

Steps:

Copy the following files and folders from the PC4J distribution, shown below, to the library folder or other location for third-party JARs used in your application:
- presto-install/apis/java/prestoconnect.jar
- presto-install/apis/java/prestoconnect_for_java/lib
Add the PC4J library and all dependent JARs from this distribution to your classpath.
For local connections, add the Mashup Server classes for all of the following paths to your classpath:
- web-apps-home/presto/WEB-INF/classes
- web-apps-home/presto/WEB-INF/lib
If not already included, add the servlet-api.jar file from your local environment to your classpath.

Create Connections and Invoke Artifacts with PC4J

Once you have added the PC4J library to your application, you can begin using it to connect your Java application to the Presto Mashup Server and invoke mashables and mashups.

Steps:

Classes that create connections to Presto, create requests or handle responses should import these PC4J packages.

... 
import com.jackbe.presto.connect.Connection; 
import com.jackbe.presto.connect.ConnectionFactory; 
import com.jackbe.presto.connect.LocalConnection; 
//import com.jackbe.presto.connect.RemoteConnection; 
//import com.jackbe.presto.connect.SecureRemoteConnection; 
import com.jackbe.presto.connect.JUMPRequest; 
import com.jackbe.presto.connect.JUMPResponse; 
import com.jackbe.presto.connect.common.PrestoConstants; 
...

Generally, you import LocalConnection, RemoteConnection or SecureRemoteConnection. See PC4J API documentation for details.

Use ConnectionFactory to create a connection.

... 
  //create local connection 
  Connection connection = null; 
  connection = ConnectionFactory.create(); 
...

Connections may be local, to the Mashup Server running in the same JVM as your application, or remote. For remote connections, pass the URL to the Mashup Server as a string. For example:

... 
  String prestoURL = "http://234.10.32.210:8080/presto/edge/api" 
  //create remote connection 
  Connection connection = null; 
  connection = ConnectionFactory.create(prestoURL); 
...

Presto URLs for JUMP requests are in the form app-server:port/presto/edge/api.

Log a user in to begin a session. For examle:

... 
  //log in and get session 
  String dummy = connection.login(username, password); 
...

In previous releases, logging a user in returned an authentication token that had to be sent in all subsequent requests. In version 3.0 and later, Presto uses a standard HTTP session and adds a session cookie. Authentication tokens are no longer applicable.

Create a JUMP request object.

JUMPRequest request = new JUMPRequest();

Set the required JUMP headers:

sid = mashable or mashup ID.
oid = operation ID
version = version of the JUMP protocol for this request. Set this to 1.1.
svcVersion = set this to 0.1. Mashable versions are not yet implemented.

to find the mashable or mashup ID and operation ID, open the Technical Spec tab in the mashable’s or mashup’s artifact page in Presto Hub. See Using Mashable/Mashup Technical Specs for more information.

For example:

... 
  request.setVersion(PrestoConstants.JUMP_PROTOCOL_1_1); 
  request.setSid("Some_Service"); 
  request.setOid("getData"); 
  request.setSvcVersion("0.1"); 
...

If needed, set optional JUMP headers.
```
... 
  request.setHeaderParameter(  // optional header 
    PrestoConstants.JUMP_REQUEST_HEADER_RESULT_FORMAT, 
    PrestoConstants.JUMP_RESULT_FORMAT_XML); 
...
```
This example shows one common, optional header that requests the response in an XML format rather than JSON. See the ServiceRequest class in 2.7 Javadocs for a full list of optional JUMP headers.
Create the parameters for the request payload and add them to the request.

Named parameters are passed as a Map. Unnamed parameters are passed as a List. See Service Parameters in JUMP for more information.

You can provide parameter values as literals or from variables. You can also use Presto attributes to have the parameter values resolved by the Mashup Server at runtime. See Mapping Presto Attributes to Artifact Input Parameters for more information.
```
... 
  Map params = new HashMap(); 
  params.put("Service", "AWSECommerceService"); 
  params.put("Version", "2006-06-28"); 
  params.put("AWSAccessKeyId", "1SF8BTKBTXN6XP68BY02"); 
  params.put("Operation", "ListSearch"); 
  params.put("ListType", "WishList"); 
  params.put("Email", "someone@myCompany.com"); 
  request.setParameterMap(params); 
...
```

Send the request.

... 
  JUMPResponse response = connection.invoke(request); 
...

Handle the response.

There are several options to cast responses to the Java objects needed by your application:
- JUMPResponse objects can translate the response from JUMP into a string in the JSON format. There are several JSON libraries that can translate JSON to Java Objects, including org.json or json-lib. Or see the json.org site for a list of additional libraries.
- JUMPResponse can also return XML if the request includes the resultFormat optional header with XML as the value.