This chapter contains the following topics:
Note:
This chapter is applicable only if you use guaranteed events delivery. Guaranteed event delivery is available when you use JD Edwards EnterpriseOne Tools 8.94 with JD Edwards EnterpriseOne Applications 8.11, or if you use JD Edwards EnterpriseOne Tools 8.95 and later Tools releases with JD Edwards EnterpriseOne Applications 8.10 and later Applications releases.Refer to the Classic Events chapters if you use JD Edwards EnterpriseOne Tools 8.94 with JD Edwards EnterpriseOne Applications 8.10 or earlier releases of the JD Edwards EnterpriseOne Applications.
The Java connector provides a set of APIs that you can use to receive events when you establish a subscriber in JD Edwards EnterpriseOne with a JAVACONN transport type. When using the events portion of the Java connector, you connect directly to the JD Edwards EnterpriseOne Transaction server to receive events that have been placed in the subscriber queue.
Note:
When you use the events portion of the Java connector, you do not call any business functions on the JD Edwards EnterpriseOne server. This implies that the events portion of the Java connector is not specific to the Java connector or dynamic Java connector. Therefore, the term Java connector is used throughout this chapter even though the APIs and the sample code reside in subpackages underneath the com.jdedwards.system.connector.dynamic package. All classes for the Java connector and the dynamic Java connector (not including the sample applications) reside in the Connector.jar file. Putting the Connector.jar file on the CLASSPATH is sufficient for working with either Java connector and the events operations.Whether you are developing a Java connector events application or using the sample Java connector events client, these prerequisites must exist on the machine running the events application or client sample:
A Java Development Kit (JDK) that corresponds to the version of the JDK under which the JD Edwards EnterpriseOne Transaction server is running.
For example, when connecting to a JD Edwards EnterpriseOne Transaction server hosted on WebSphere, you must run the Java connector events client or application using the same IBM JDK. Generally, the IBM JDK is located in <WebSphere installation directory>/java).
An installation of IBM WebSphere MQ, if the JD Edwards EnterpriseOne Transaction Server is hosted on WebSphere.
This software comes installed as part of the installation of many different WebSphere-related software, including the WebSphere Application Client.
A completed set of configured files for the environment:
jdeinterop.ini
jdbj.ini
jdelog.properties
A JAVA_HOME environment variable that points to this JDK.
A PATH environment variable that includes the entry, %JAVA_HOME%\bin, which assumes that JAVA_HOME has already been defined.
Additional prerequisites are required to compile and run the application or client.
These jar files must be in the CLASSPATH:
ApplicationAPIs_JAR.jar
ApplicationLogic_JAR.jar
Base_JAR.jar
BizLogicContainer_JAR.jar
BizLogicContainerClient_JAR.jar
BusinessLogicServices_JAR.jar
castor.jar
commons-httpclient-3.0.jar
commons-logging.jar
Connector.jar
EventProcessor_JAR.jar
Generator.jar
j2ee1_3.jar
JdbjBase_JAR.jar
JdbjInterfaces_JAR.jar
JdeNet_JAR.jar
jmxremote.jar
jmxremote_optional.jar
jmxri.jar
log4j.jar
ManagementAgent_JAR.jar
Metadata.jar
MetadataInterface.jar
PMApi_JAR.jar
Spec_JAR.jar
System_JAR.jar
SystemInterfaces_JAR.jar
xerces.jar
xmlparserv2.jar
Note:
With the exception of the EventProcessor_JAR.jar file, the files can be found at <Windows client installation directory>\system\classes on the generation machine that is used for the JD Edwards EnterpriseOne environment to which you are connecting.The EventProcessor_JAR.jar file must be copied from the Transaction server's installation directory, which is typically located in <Transaction Server installation>\EventProcessor\app\EventProcessor.ear.
The files that you place on the CLASSPATH must be the exact same files that are on the Transaction server installation directory.
The JDBC driver files that correspond to the database to which you are connecting.
The directory location for these files:
jdeinterop.ini
jdbj.ini
jdelog.properties
The files must all be in the same directory. It is important to note that you put the directory in the CLASSPATH without the file names, so there is just one entry for these three files. Also, this entry must end in a slash (/), indicating that it is a directory entry and not a file name.
If you connect to a Transaction server hosted on WebSphere, you also need these files:
com.ibm.mqjms.jar
com.ibm.mq.jar
bootstrap.jar
com.ibm.ws.runtime_6.1.0.jar
com.ibm.ws.admin.client_6.1.0.jar
ibmorb.jar
ibmext.jar
ibmcfw.jar
The files are typically located in the <WebSphere installation directory>/lib folder. Additionally, you must put the <WebSphere installation directory>)/properties directory entry in the CLASSPATH, without an ending slash (/).
If you connect to a Transaction server hosted on Oracle Application Server, you also need these files:
oc4j.jar
oc4jclient.jar
jms.jar
javax77.jar
This section provides an overview of Java connector events application development and discusses:
Introspection operations
Asynchronous event sessions
Synchronous event sessions
This list identifies the steps that you use when you write a Java class that serves as a Java connector subscriber. The steps are further explained in the code samples in this section.
Instantiate a connector object.
Login through the connector to the JD Edwards EnterpriseOne system.
Instantiate an EventService object (not required for introspection operations).
Perform introspection operations (optional).
Create a session and receive events (optional).
Logoff from JD Edwards EnterpriseOne.
Shut the connector down.
You can create two types of Event Sessions, asynchronous and synchronous, to receive events through the Java connector.
The Java Connector Events API enables you to perform several introspection requests as provided in the Event IntrospectionApp.java code sample.
This sample code shows example introspection requests:
import java.util.LinkedList; import com.jdedwards.system.connector.dynamic.Connector; import com.jdedwards.system.connector.dynamic.newevents.EventService;
Sample Java Connector Events Introspection application.
public class EventIntrospectionApp {
public static void main(String[] args) {
try {
// Instantiate a Connector object
Connector con = Connector.getInstance();
// Login through the Connector
int sessionID = con.login("username", "password",
"environment", "role");
Get the list of all events in JD Edwards EnterpriseOne. This list is returned as a LinkedList of Strings.
LinkedList list = EventService.getEventList(sessionID);
Get the template for a particular event type. This is returned as an XML template in a single String object.
String template = EventService.getEventTemplate(sessionID, "category",
"type", "environment");
Get the list of all subscriptions for the user associated with the given sessionID. This is returned as a LinkedList of com.jdedwards.pt.e1.common.events.connectorsvc.Subscription objects. This Subscription class is located in the Common_JAR.jar file.
LinkedList subs = EventService.getSubscriptions(sessionID);
// Logoff the user from JD Edwards EnterpriseOne
con.logoff(sessionID);
// Shut the Connector down
con.shutDown();
} catch (Exception e) {
e.printStackTrace();
System.exit(-1);
}
System.exit(0);
}
}
With an asynchronous event session, you must create a listener class to receive events and process them according to the requirements for the event data. Once you create the listener class, you register an instance of that class with the asynchronous event session that you request. The details of these steps are listed in the MyListener.java and EventAsyncApp.java sample programs.
Additionally, the MyListener.java sample code shows that since the Asynchronous Event Session is created in CLIENT_ACKNOWLEDGE mode (illustrated in EventAsyncApp.java), the EventObject must be acknowledged to let the Transaction server know that you received the event.
This sample code for the listener class not only shows the single onEvent(EventObject) method that the listener must implement, but it also shows what data you can get from the EventObject.
import javax.jms.IllegalStateException; import com.jdedwards.base.datatypes.JDECalendar; import com.jdedwards.system.connector.dynamic.SystemException; import com.jdedwards.system.connector.dynamic.newevents.EventListener; import com.jdedwards.system.connector.dynamic.newevents.EventObject;
Sample implementation of a Java Connector Asynchronous Event SessionListener.
public class MyListener implements EventListener {
Permits the listener to receive an event when it has been delivered from the Transaction Server.
@param event the event
public void onEvent(EventObject event) {
Do some processing here with the event that is sent by the Transaction Server. The onEvent(EventObject) method is called once for every event that is delivered.
*The event category: "RTE", "XAPI", or "ZFILE".
String category = event.getCategory();
The event type, such as "RTSOOUT".
String type = event.getType();
The JD Edwards EnterpriseOne environment in which the event was generated.
String environment = event.getEnvironment();
The global sequence number of the event.
long sequenceNumber = event.getSequenceNumber();
The date and time stamp of the event.
JDECalendar date = event.getDateTime();
The XML content of the event as a single String object.*/
String xmlPayload = event.getXMLPayload();
If you created an EventSession with CLIENT_ACKNOWLEDGE mode, you must acknowledge each message you receive. Otherwise the event will be redelivered according to the Transaction Server JMS Provider's logic.
try {
event.acknowledge();
} catch (IllegalStateException e) {
This Exception will be thrown if the session associated with this event has already been closed.
} catch (SystemException e) {
This Exception will be thrown if the original event could not be acknowledged (duplicate event delivery is likely in this scenario).
}
}
}
The asynchronous-specific calls in this asynchronous event application (AsyncEventApp.java) are illustrated in this code sample. Between the eventSession.start and the eventSession.stop method calls, you would normally solicit user input or wait for some type of intervention to let the class know that event delivery needs to stop.
import com.jdedwards.system.connector.dynamic.Connector; import com.jdedwards.system.connector.dynamic.newevents.AsyncEventSession; import com.jdedwards.system.connector.dynamic.newevents.EventService; import com.jdedwards.system.connector.dynamic.newevents.EventSession;
Sample Java Connector Asynchronous Event application
public class EventAsyncApp {
public static void main(String[] args) {
try {
Instantiate a Connector object.
Connector con = Connector.getInstance();
Login through the Connector to JD Edwards EnterpriseOne.
int sessionID = con.login("username", "password",
"environment", "role");
Instantiate an EventService object
EventService service = EventService.getInstance();
Create a synchronous event session in CLIENT_ACKNOWLEDGE mode.
AsyncEventSession eventSession = service.getAsyncEventSession
(sessionID, EventSession.CLIENT_ACKNOWLEDGE);
Register a listener object which you have created
eventSession.registerListener(new MyListener());
Start the delivery of events to the listener.
eventSession.start();
Stop the delivery of events to the listener. Note that you can continuously alternate between calls to start() and stop() as long as you do not call the close() method.
eventSession.stop();
Close the event session. No other operations on the event session are possible at this point.
eventSession.close();
Logoff the user from JD Edwards EnterpriseOne.
con.logoff(sessionID);
Shut the Connector down.
con.shutDown();
} catch (Exception e) {
e.printStackTrace();
System.exit(-1);
}
System.exit(0);
}
}
With synchronous event sessions, you receive only one event at a time. No listener class is involved with this type of session.
The three ways to receive an event, along with an explanation of functionality, are illustrated in this EventSyncApp.java class sample code. This sample code uses the AUTO_ACKNOWLEDGE acknowledgement mode:
import com.jdedwards.system.connector.dynamic.Connector; import com.jdedwards.system.connector.dynamic.newevents.EventObject; import com.jdedwards.system.connector.dynamic.newevents.EventService; import com.jdedwards.system.connector.dynamic.newevents.EventSession; import com.jdedwards.system.connector.dynamic.newevents.SyncEventSession;
Sample Java Connector Synchronous Events application.
public class EventSyncApp {
public static void main(String[] args) {
try {
Instantiate a Connector object.
Connector con = Connector.getInstance();
Login from the Connector to JD Edwards EnterpriseOne.
int sessionID = con.login("username", "password",
"environment", "role");
Instantiate an EventService object.
EventService service = EventService.getInstance();
Create a synchronous event session in AUTO_ACKNOWLEDGE mode.
SyncEventSession eventSession =
service.getSyncEventSession(sessionID,
EventSession.AUTO_ACKNOWLEDGE);
Start the delivery of events.
eventSession.start();
The receive() method will not return control to the caller until an event is delivered.
EventObject event1 = eventSession.receive();
Do some processing of the event data here. Refer to the sample class (MyListener.java) for a list of the methods that can be called on the EventObject class.
The receive(long timeout) method will return control to the caller if the timeout value (in milliseconds) elapses without an event being delivered. Of course, if an event is delivered before the timeout value elapses, the EventObject will be returned to the caller.
EventObject event2 = eventSession.receive(5000);
Do some processing of the event data here. Refer to the sample 'MyListener.java' class for a list of the methods that can be called on the EventObject class.
The receiveNoWait() method either immediately returns an EventObject to the caller if an event is waiting to be delivered or returns null if no event is waiting.
EventObject event3 = eventSession.receiveNoWait();
Do some processing of the event data here. Refer to the sample 'MyListener.java' class for a list of the methods that can be called on the EventObjectclass.
Stop the delivery of events. Note that you can continuously alternate between calls to start() and stop() as long as you do not call the close() method.
eventSession.stop();
Close the event session. No other operations on the event session are possible at this point.
eventSession.close();
Logoff the user from JD Edwards EnterpriseOne
con.logoff(sessionID);
Shut the Connector down.
con.shutDown();
} catch (Exception e) {
e.printStackTrace();
System.exit(-1);
}
System.exit(0);
}
}
This section provides an overview of connector events client tool and discusses:
Using the Connector Events Client tool.
Configuring the sample connector events client.
Running the sample connector events client.
Resolving Connector Events Client tool issues.
The connector events client is a Java-based graphical tool that enables you to log in to JD Edwards EnterpriseOne and receive events that you have subscribed to from the JD Edwards EnterpriseOne Transaction server. This tool enables all possible event operations, including all of the introspection requests as well as the creation of both asynchronous and synchronous event sessions.
In addition to meeting the requirements listed in the Prerequisites for Understanding Java Connector Events section, you must also verify:
The Transaction server is running.
The user ID that you use to log in to the tool is a user ID that is an active subscriber with at least one active subscription.
A Java Runtime Environment (JRE) version 1.4 or later is installed on the machine.
You can download a valid JRE from Sun Developer Network web site.
See Also:
Sun Developer Network (SDN), http://java.sun.com/j2se/downloads/index.html.
You sign in to the connector events client tool through the login window. Once you have successfully signed in, you can perform any of the introspection operations without creating an event session. All error messages are displayed in the bottom pane. If you receive an error message that is not explained sufficiently, you can look in the debug log file of the tool to obtain more information.
The buttons that enable you to create a new event session prohibit you from entering an invalid sequence or combination (such as starting event delivery without opening a session). Once you start receiving events, the event sequence numbers for received events appear in the Event List window. If you select an event sequence number, the event details for that event appear in the Event Data window. Additionally, the XML content for all received events is automatically created as an XML file in the tool's log directory, regardless of whether you select the sequence number for the event.
To use the tool, you must build, configure, and then run the tool. The tool is shipped to you as source code so that you can inspect the usage of the connector events APIs. You can find the entire source code in a single jar file: connector_samples_src.jar. This file should be located in the <Windows client generation machine installation directory>/system/classes/samples folder.
This section provides steps for configuring the sample connector events client.
Use these steps to configure the sample connector events client:
Create a C:\ConnectorEventsClient directory.
If a directory with this name already exists, rename the existing directory before you create a new directory.
Unzip the Connector Events Client.zip file to the newly created directory on the C drive.
Make sure to unzip the file with the full path information for each file in the Zip file.
Configure the files in the C:\ConnectorEventsClient\config directory.
Make sure that the configured files have the .templ file extension removed from them. The proper file names for this directory are:
jdbj.ini
jdeinterop.ini
jdelog.properties
Configure the jdbj.ini and jdelog.properties files according to your environment. See your JD Edwards EnterpriseOne systems administrator if you do not know the appropriate values for these files. You should name your jdbj.ini file with the same file name that is configured on your Transaction server.
Configure your jdeinterop.ini file with these values:
| Section | Setting | Value |
|---|---|---|
| [EVENTS] | eventServiceURL | http://machine_name:port/e1events/EventClientService
The machine name is the name of your WebSphere Transaction Server and the port is the port for your WebSphere Transaction Server. |
| [SECURITY] | SecurityServer | Name of your JD Edwards EnterpriseOne Security Server. |
| [JDENET] | serviceNameConnect | The port you are connecting to on your JD Edwards EnterpriseOne Security Server. |
Add the appropriate JDBC driver files to the C:\ConnectorEventsClient\lib directory.
See your JD Edwards EnterpriseOne systems administrator to determine which driver file to use.
Edit the C:\ConnectorEventsClient\setDynConNewEventDriver.bat file, change it to point to the location of your installed JRE.
Use these steps to run the sample Connector Events Client:
Navigate to the C:\ConnectorEventsClient directory.
Double-click the runDynConNewEventDriver.bat file.
On the Java Connector EnterpriseOne signon window, enter your JD Edwards EnterpriseOne credentials, and then select the OK button.
Click Open Session and then click Start to receive events for which you have subscribed.
The event numbers for any events that are waiting for you should appear in the Event List window. If you select an event number, the event data for the selected event appears in the Event Data window. The XML content for each event is also placed in your C:\ConnectorEventsClient\logs directory.
This table discusses potential problems that you might encounter when using the Java Connector Events Client tool, along with possible solutions.
| Problem | Possible Solution |
|---|---|
| I can't get past the sign-on screen. | Try entering all of your credentials (username, password, environment, and role) in all capital letters. |
| My C:\ConnectorEventsClient\logs directory is full, and I would like to delete some of the .log and .xml files. | You may delete any files that this directory at any time. However, if your Connector Events Client application is running, some of the files might be locked. |
| Why are there orbtrc...txt files in my C:\ConnectorEventsClient directory? | These files are created by WebSphere runtime code. You may delete these files at any time. However, if your Connector Events Client application is running, some of these files might be locked. |
| An error message that I don't understand appears in the Error Messages window. | Look in your C:\ConnectorEventsClient\logs directory for the jasdebug_date.log file that corresponds to the appropriate date. Often a more explanatory error message can be found in this file. |
| I clicked the ReceiveAndWait button, and now the interface is frozen. | This happens when you click the ReceiveAndWait button and there is no event waiting for you on the Transaction Server. ReceiveAndWait means that you are willing to wait indefinitely for an event to be generated and delivered to you. The interface freezes in this instance until an event is delivered. If you are not willing to wait, click the ReceiveNoWait button. |