Transaction Listener lab
|
Time Estimates for Completion
|
|
Create a custom transaction listener.
In this lesson you will implement a custom transaction listener for the Creo Elements/Direct Manager Server.
|
Description:
|
15 minutes
|
|
Lab exercise:
|
2-3 hours
|
Description
The Transaction Listener Processor is a client of the database, just like Creo Elements/Direct Model Manager. It is built from the same Java code as Creo Elements/Direct Model Manager. This lab assumes that you are familiar with extending the Creo Elements/Direct Model Manager business logic or user interface as described in the Java API document. To create a transaction listener you must write the Java class to implement the listener and then register your listener in the Service Controller XML configuration file.
When Creo Elements/Direct Model Manager or another client completes a transaction, an event notification is stored in the database until all transaction listeners have successfully processed the event.
Event Handling
Clients store event notifications in the database's MM_QUEUE table in the form of documents and attached files.
The Transaction Listener Processor polls the event queue to check for new events. The Transaction Listener Processor retrieves the events in the order applied and calls the registered Transaction Listeners with the event information. The Transaction Listener Processor removes the event from the event notification queue after all of the registered Transaction Listeners have successfully processed the event.
By default the Transaction Listener Processor calls the transactionApplied method for each of the transaction listeners at the same time. If your transaction listener is not thread safe, set <ConcurrentProcessingMode> to false in the Service Controller XML file to have the Transaction Listener Processor call only one transaction listener at a time.
The transaction listener's Java class
Your transaction listener will be a TransactionListener Java class, which implements the transactionApplied() method. The transactionApplied method is called by the Transaction Listener Processor when it finds an Event Notification in the event notification queue. The transactionApplied method is passed a TransactionEvent.
The TransactionEvent contains information about the overall transaction. From the TransactionEvent you can find
• the name of the user who applied the transaction (getUserName())
• the date of the transaction (getDate())
• a list of AuditRecordSets for each item in the transaction (getAuditRecordSets()). Most transactions involve multiple items.
With the AuditRecordSet, you can find
• the object ID (getObjID())
• the list of AuditEventRecords for the object (getAuditEventRecords()). There will be one AuditEventRecord for each change to that element. For example, the version and state might both change, resulting in two AuditEventRecords.
The AuditRecordSet class contains some additional methods, but these are likely to be removed in future releases.
The general algorithm for processing the transaction is to loop through the AuditRecordSets and AuditEventRecords with a couple for loops:
for (int i = 0; i < e.getAuditRecordSets().size(); ++i) {
AuditRecordSet ars = (AuditRecordSet) e.getAuditRecordSets().get(i);
for (int j = 0; j < ars.getAuditEventRecords().size(); ++j) {
//do something
}
}
Transaction listener development practices
The transaction listeners must follow some rules to coexist within the Transaction Listener Processor. Specifically, you should develop thread safe code without memory leaks, and throw an Exception, rather than block, if your transaction listener does not have access to a critical resource for processing the event.
Development environment implications
The transaction listener is developed and deployed as part of the Transaction Listener Processor. This has several implications for the development environment:
• Since only one Transaction Listener Processor can process transactions from a database, you will need a test database.
• You will need to stop any other Transaction Listener Processors attached to the test database while you are debugging and testing your transaction listener.
• You will need to run Creo Elements/Direct Model Manager against your test database to generate the events that are sent to your transaction handler.
Registering the transaction listener
Transaction listeners are registered with the <TransactionListener> tag in the Transaction Listener Processor section of the ServiceControllerConfig.xml. Use the <ConfigurationFile> element to specify the customization file for the service.
Debugging the transaction listener
The Transaction Listener Processor can be run from the NetBeans IDE during development of the transaction listener. You can attach the debugger to the Transaction Listener Processor to debug your transaction listener.
1. Stop the Java Services using the Creo Elements/Direct Model Manager – Java Services Manager dialog box. For more information, see the Start, Stop, or Restart the Java Services topic of this guide. You may also choose to use the Windows Services panel. Only one instance of the Transaction Listener Processor can process events at a time.
2. Add your local Windows user name as an administrator to the Model Manager users.
3. Open the class com.osm.services.transaction.TransactionListenerProcessor and run in through NetBean's > .
4. Step through your transactionApplied method in the debugger while generating notification events with Creo Elements/Direct Model Manager.
Lab Exercise
Coordination with other systems might be needed when parts are created, modified, or released. For example, when a new part is created, it might need to be registered with another system. This is a good application for a transaction listener.
In this lab you can create a transaction listener that will look for transactions on parts (Masterdata) and write the changes to a file. Writing the information to a file will show you how to loop through the transaction records and that the transaction listener is working. For a real implementation you can replace the file-writing code with code to interact with another system.
This lab assumes that you have completed the
Basic customization and deployment lab and the
XML customization lab from the
Creo Elements/Direct Model Manager customization section.
The major steps in this lab are:
You will add code to the transaction listener in several steps. Refer to the completed class to see the final class.
Register the transaction listener in the XML file
Start by registering the transaction listener in the XML file.
1. In NetBeans, double-click the acme.xml file you created in the XML Customization Lab to bring it up in the editor pane.
2. Copy the ServiceControllerConfig.xml of the Manager Service installation to your project directory.
3. Add the following element to the Transaction Listener Processor section, being very careful of capitalization.
<TransactionListener java_class ="com.acme.event.AcmeTransactionListener"</TransactionListener>
Create the basic Java code
Begin by creating the basic transaction listener.
1. Create the Java class AcmeTransactionListener. Notice the try...catch. Unexpected events will throw an error, which will let the Transaction Listener Processor know that the Transaction Listener did not successfully process the event.
package com.acme.event;
import java.io.*;
import java.util.*;
import java.lang.*;
import com.osm.datamgmt.biz.*;
import com.osm.biz.*;
import com.osm.exception.*;
import com.osm.webservices.event.*;
import com.osm.webservices.service.*;
public class AcmeTransactionListener implements TransactionListener {
public void transactionApplied(TransactionEvent e)
throws WMException {
List recordSets = e.getAuditRecordSets();
File partsFile = new File("C:\\temp\\partsfile.txt");
try {
PrintWriter out = new PrintWriter(new FileOutputStream (partsFile));
out.println("Opened file: " + recordSets.size() + " recordSets");
out.flush();
}
catch (Exception ex) {
throw new WMException(ex);
}
}
}
Test the transaction listener
You can run the code from NetBeans, without having to install it.
1. Run the Transaction Listener Processor from NetBeans.
2. Start Windows Explorer and browse to C:\temp so you can see the file created by the transaction listener.
3. Start Creo Elements/Direct Modeling and Creo Elements/Direct Model Manager.
4. In the Creo Elements/Direct Model Manager Workspace create a new part with > > . Enter a name for the part and click OK.
5. Wait a few seconds, then refresh your Windows Explorer window with F5.
6. Open partsfile.txt with Notepad. You should see the Opened file: message. This means that the transaction listener is being called for Creo Elements/Direct Model Manager transactions.
Deploy the transaction listener
At this point, the transaction listener works from the NetBeans development environment. Now it's time to deploy it to a production server. When deployed, the Transaction Listener Processor process runs as a child of the Service Controller.
1. Stop the Java Services using the Creo Elements/Direct Model Manager – Java Services Manager dialog box. For more information, see the Start, Stop, or Restart the Java Services topic of this guide. You may also choose to use the Windows Services panel. Only one instance of the Transaction Listener Processor can process events at a time.
2. Copy the new custom.jar to the deployment location, usually C:\Program Files\PTC\Creo Elements\Direct Manager Server 20.6\jar\custom.
3. Register the listener in the Transaction Listener Processor section of the ServiceControllerConfig.xml.
4. Restart the Service Controller:
a. From the Windows Start menu, click > .
b. Double-click Services. The Services window opens.
c. Select Creo Elements Direct Manage Services, and then click Restart.
5. Start Creo Elements/Direct Model Manager Standalone and verify that it is using a compatible XML configuration file
◦ From the Windows Start menu, choose > > . If asked to Select Configuration, choose acme and click OK.
◦ In the Creo Elements/Direct Model Manager Workspace, look in Creo Elements/Direct Model Manager's > to see which XML configuration file is being used. (It's usually the last line.)
◦ Open the XML configuration file with Notepad. Modify the hostname and port to your local computer and port 8085 if necessary.
◦ If you changed the hostname or port, restart Creo Elements/Direct Model Manager to pick up the new configuration file.
6. In the Creo Elements/Direct Model Manager Workspace, create a new part with > > .
7. Check the partsfile.txt file to see that your transaction listener has been deployed.