Submitting events by using the Java gateway API

The SolutionGateway API helps you submit events to an Insight Server in production.

About this task

Use the SolutionGateway API and related APIs (GatewayClient, EventFactory, GridConnection, GridConfiguration) to establish a connection to an object grid, create a gateway instance so that events can be routed to the event queue, create events, and submit these events for processing.

By default, the gateway submits events at the same rate they are received. The maximum event submission delay is equal to the maximum transaction delay of the inbound connectivity system (JMS and IIB, for example). If too many events are submitted over a certain period, or if event processing is slower than event submission, the Insight Server can be overrun. If the server is overrun, the gateway slows down event submission. The default maximum submission delay is 1,100 milliseconds. When this limit is reached, events are no longer submitted and an EventCapacityExceededException error is written in the server log. You can modify the maximum delay value to prevent the error by using the setMaxSubmitDelay method.

Note: Do not submit an event object more than once.

Procedure

Add the Decision Server Insights runtime JAR files as external libraries to the build path.
1. Select your Java™ project and click Project > Properties on the workbench menu.
2. In the Project Properties dialog, select the Java Build Path page in the navigator.
3. On the Java Build Path page, click the Libraries tab.
4. Click Add Library.
5. In the JAR Selection dialog, select IBM ODM Library and click Next.
6. Select the Insight Solution Gateway, Insight Solution Liberty Server, and Insight Solution TestDriver libraries and click OK.
7. In Window > Preferences, expand Java and select Compiler to verify that the JDK compliance level of your project is set to 1.8. If it is not, change it to 1.8.

Import the gateway client class.

import com.ibm.ia.gateway.client.GatewayClient;

Initialize a gateway client:
```
GatewayClient.init();
```
Establish a connection to the grid by calling a GridConnection and a GridConfiguration.
For example:
```
GridConfiguration gridConfig = new GridConfiguration("localhost:2809");
GridConnection connection = GridConnectionFactory.createGridConnection(gridConfig);
```
Where localhost:2809 is the connection endpoint of the grid server. A GridConfiguration constructor also exists to take AuthenticationConfiguration.
Note: When you create a grid configuration to the catalog servers in a production environment, you must pass in a list of IP addresses. For example, the following line of code passes three addresses to three different hosts.
```
GridConfiguration gridConfig = new GridConfiguration("localhost:2809,host01:2810,host02:2811");
```
Using the GridConnection API, you can establish connections between a single object grid and multiple solutions.
Create a gateway instance. You must supply the solution name to create a gateway and establish the connection.
For example:
```
SolutionGateway gateway = connection.getSolutionGateway("AcmeAirlines"); 
```
Where AcmeAirlines is the solution name. Use the gateway class to retrieve information about a solution. The following example returns the current version value for the gateway solution:
```
SolutionVersion solVersion = gateway.getSolutionVersion();
```
Each solution gateway instance represents a single, specific solution that is connected to the object grid.

Submit an event to the runtime environment by using a specific event instance.

For example:

CustomerEvent event = gateway.getEventFactory().createEvent(CustomerEvent.class);     
   event.setDescription("Customer event");
   Relationship customer = gateway.getEventFactory().createRelationship(Customer.class, "Alan");
   event.setCustomer(customer);
   Relationship flight = gateway.getEventFactory().createRelationship(Flight.class, "Flight123");
   event.setFlight(flight);                
   try{
      RoutingStatus status = gateway.submit(event);
      System.out.println("Event submitted successfully, status is " + status);
   } 
   catch (GatewayException e) {
      System.out.println("Failed to submit event" + e.getMessage());
   } 
   catch (RoutingException re ){
      System.out.println("Failed to route event" + re.getMessage());
   }

In this example, the EventFactory API is called to create an instance of the CustomerEvent event type.

Note: A RoutingException normally occurs when something is wrong with the submitted event. For example, one of the fields is null or the wrong type, or the bound entity is null.

Events must have a time stamp. If the event time stamp is missing, provide the defaultTime value as a parameter in the submit call:
```
gateway.submit(event, defaultTime);
```
Specify the defaultTime setting as LocalDateTime or ZonedDateTime, or a string representation of the local time or zoned time. The value of defaultTime is converted by using the ZoneId for the solution and then used as the event time stamp. If the event does not include a time stamp and a defaultTime value is not provided, the event submission time is used as the event time stamp. The event time stamp in this case uses the solution ZoneId.
Optional: To override the default maximum event submission delay setting, use the SolutionGateway.setMaxSubmitDelay(int delay) API. Alternately, you can add the system property com.ibm.ia.gateway.MaxSubmitDelay and specify the delay value in milliseconds.
For more information about what to do if you receive a GatewayException, see Object grid transaction exceptions.