EnyWare™ Developer Training Software Release 4.00 [March 2011 ]

1. EnyWare™ Developer Training Software Release 4.00 [March 2011]

3. Introduction EnyWare Core Event Model Service Architecture Communication Layers Consoles Error Handling

5. Introduction

6. Traditional Integration Risk Management Spreadsheets Transaction Management Accounting

7. Hub & Spoke Architecture Risk Management EnyWare Spreadsheets Transaction Management Accounting

8. Identity Management Application 1 Application 2 Company ID – 123 Name – ABC Corp Company ID – 456 Name – ABC Corp

9. EnyWare Core

10. System Flow Input Application Monitor (IAM) EnyWare Bus Input Objex Monitor (IOM) Application 1 Diagnostic Manager Event Server Objex Server Lite DB Output Objex Monitor Output Application Monitor (OAM) Application 2 Feedback Manager Service Manager Identity Manager

11. Application Monitors (IAM \ OAM) EnyWare Bus Input Application Monitor (IAM) Translate to Central Model Uniqueness Within Type Application 1 Output Application Monitor (OAM) Transform from Central Model Manage Identity Translation

12. Input Objex Monitor (IOM) Input Application Monitor (IAM) EnyWare Bus Input Objex Monitor (IOM) startService beginSession(); retrieveApplicationDefinitions(); retrieveApplicationEventConfigurations(); retrieveEventDefinitions(); EnforceEventOwnershipRules=true\false InputEnyWareEventHandler mapenywareidentity=true\false EventRelationshipFactory.getEventRelationships(anEnyWareEvent); Event Type, Field Name, Originating Application, ID -> GUID DB

13. Event Server EnyWare Bus Responsible for routing events to applications which have registered interest in them. eventservermaplocationtype=file|database eventservermaplocation=aFile DiagnosticTopic=aTopicName Applications can register interest in individual events & can determine whom they wish to receive them from. See Administration Console. Event Server DB

14. Objex Workspace Application 1 Objex Objex Lite Application 2 EnyEvents EnyEvents

15. Objex Server Lite EnyWare Bus • Responsible for saving the most current state of all EnyWareEvents that have passed through the system. • Creates the ability for Event Expansion discussed later. • Added simple Event Validation in EnyWare 4.0 • Boolean Field • Date Field • Event Field • Numeric Field • String Field Objex Server Lite DB

16. Output Objex Monitor (OOM) EnyWare Bus • Responsible for translation of ObjexEvents back to EnyWareEvents & translation of central identity to application identity. • Event Expansion performed here. • Reference Elements can be “expanded” to the most current state of the EnyWareEvent on the holder. mapenywareidentity=true\false eventsrequiringmapping=aList maintaincompanyid=true\false DB Output Objex Monitor Output Application Monitor (OAM)

17. Feedback Manager EnyWare Bus Input Objex Monitor (IOM) Responsible for consuming Error and Success events for later representation in the Feedback Console. Keeps a Trace History of events in the system. Sends change notifications to the Feedback Consoles. Event Server Objex Server Lite DB Output Objex Monitor Output Application Monitor (OAM) Feedback Manager FeedbackChangeNotificationTopicName=aTopicName Identity Manager

18. Identity Monitor Responsible for altering an Applications Identity for an Event. OAMs can inform EnyWare of a change to the identity of an Event & they will keep track of the request until complete. Requires sub-classing from EventMonitor for the feature. EnyWare Bus EnyWareApplicationIdentityMapLocationType= file|database EnyWareApplicationIdentityMapLocation=aFileName DB Output Application Monitor (OAM) Application 2 Identity Manager

19. Service Manager Input Application Monitor (IAM) EnyWare Bus Input Objex Monitor (IOM) Diagnostic Manager Responsible for the monitoring of Basic Services and allowing for the control of Controllable Services. HeartbeatDelay=1 useinternalthreads=true\false HeartbeatTopicName=aTopicName Event Server Objex Server Lite DB Output Objex Monitor Output Application Monitor (OAM) Feedback Manager AttemptToRestartServices=true\false ServiceChangeNotificationTopicName=aTopicName servicemanagertopic=aTopicName ServiceMapLocationType=file|database Service Manager Identity Manager

20. Diagnostic Manager Created to run timings on the EnyWare Core on a specific schedule. DiagnosticEventPollDelay=30 DiagnosticSchedule=…. When to start? Will start diagnostics at first time in schedule. DiagnosticEventPublishTopic=aTopicName DiagnosticEventSubscribeTopic=aTopicName Table: Event_Diagnostics EnyWare Bus Diagnostic Manager DB

21. Event Model

22. Event Parser JMS Messaging handleNewTextMessage() Event Monitor Event Parser parseEvent() SAXBuilder eventNameMap File or Database processEvent() Base Event populateFromXMLDocument() iterate the elements extractAndSetValuesFromElement()

23. Event Parsing – Extract & Set Base Event extractAndSetValuesFromElement(Element element) if (element.getName().equalsIgnoreCase(ELEMENT_NAME_1)) { setElement1(element.getText()); } else if (element.getName().equalsIgnoreCase(ELEMENT_NAME_2)) { setElement2(element.getText()); } else () { super.extractAndSetValuesFromElement(element) }

24. Event Parsing – parse*FromXML(String) Base Event EnyWare Event parseBigIntegerFromXML(String) parseBoolFromXML(String) parseBooleanFromXML(String) parseDateFromXML(String) parseDoubleFromXML(String) parseIntFromXML(String) parseIntegerFromXML(String) parseLongFromXML(String) extractMapFromElement(Element) extractPropertiesFromElement(Element) extractStringsFromCollectionElement(Element) extractEnyWareEventFromElement(Element) extractEnyWareEventsFromElement(Element)

25. Event Parsing – EnyWare Events extractEnyWareEventFromElement(Element) extractEnyWareEventsFromElement(Element) EnyWare Event Reference Element OR

26. Event Parsing – Basic Hierarchy Base Event Audited Event EnyWare Event String eventVersion Map extensionFields Date eventCreationTimestamp String sequenceGroupID String sequenceNumber String sequenceTotal String creationUser String creationTimestamp String eventAction String originatingApplication String actingPartyName String id List(String) history List(ExtensionEvent) extensions EnyWareEvent systemUser

27. Event Parsing – Coding Class private Type instVar; private static final String INST_VAR_ELEMENT_NAME = “InstVar”; extractAndSetValuesFromElement(Element) describeValuesAsXMLInto(Element) Standard parse*FromXML(String) formatForXML(Type) EnyWareEvent private EnyWareEvent instVar; public setInstVar(Type); public setInstVarID(String); public setInstVarID(String, String); public Type getInstVar(); private setInstVar(EnyWareEvent);

28. Events Time Bounded Event Quantity Activity Event Charge Element Quantity Element String quantityType Double amount String unitOfMeasure Date startTimestamp Date endTimestamp String commodity String unitOfMeasure String upstreamValve String downstreamValve String frequency Map quantities String packageID EnyWareEvent serviceProvider String chargeElementGroupId EnyWareEvent code String description String effectIndicator String tier String currency String frequency String chargeCounterPartyType FlatCharge FlatQuantityCharge PercentageCharge VolumetricCharge

29. Exercises 1. New Event 2. Change an existing Event 3. Migration Scripts for Event Additions Example Migration – From EnyWare DB Migration – 3_13 to 3_14.sql INSERT INTO ENYWARE_EVENT_DEF ( UUID, NAME, CLASS_NAME, DISPLAY_NAME, DEFINITION, PUBLIC_EVENT, LEAF_EVENT, SYSTEM_OWNERS ) VALUES ( '010000000089', 'TransferEvent', 'com.tradewellsystems.event.enyware.TransferEvent' , 'Transfer', 'TransferEventType.xsd', '1', '1' , NULL);

30. Service Architecture

31. Basic Service • Most basic services are provided to sub-classes: • Processing & Running Flags • Durable Name -> System Identity • Service Manager support • Logging (log, debug, trace) • 1 stdout • 2 normal – log • 3 debug • 4 trace • Error Manager -> Basic error logging • exceptionOccurred • Shutdown Time • Via shutdown schedule • Basic email services • Establish startup\shutdown sequence. • Create -> initialize • start -> startService • shutdown -> shutdownService Properties: startupdelay=0 loglevel=2 filelogging=true\false redirectstdout=true\false logpropertiesonstartup=true\false AutomaticShutdownSchedule=… servicemanagertopic=aTopicName

32. Controllable Service • Adds the ability to be controlled by the Service Manager. • Controllable Features • startProcessing • stopProcessing • shutdown • shutdownService • startupService • loadService • reset • startLogging • stopLogging • startReporting • stopReporting • Requests • processing ? -> boolean • reporting ? -> boolean • logging ? -> boolean • running ? -> boolean • configuration ? -> PropertyCatalogEvent EnyWare Bus Service Manager JVM Service Controller Controllable Service

33. Event Monitors • Abstract super class responsible for handling events in the EnyWare system. This class was created to simplify the addition of components to the system. Many services are provided by this class to it’s subclasses. • Creation of subscribers and publishers • Receive an event on a defined topic • Parse the event into a BaseEvent • Start the processing cycle • Publish the results if configured to do so • Keep a list of errors • Publish any errors or success information at the end of processing • Assumption of replay ability of all messages received • publishtopic=aTopicName • subscribetopic=aTopicName • eventmonitordurablesubscription=true\false • IdentityChangeEnabled=true\false • IdentityChangeRequestTopic=aTopicName • EnyWareApplicationIdentity=aString (mandatory for Identity Change Requests)

34. EnyWare Core Event Monitors EnyWareCoreEventMonitor Created to speed up the EnyWare Core. In previous versions, the Feedback Manager saved Trace information based on received Success Events. A Core Event Monitor knows how to save it’s own Trace information. Database transactions were added to aid in this. Also cleans up Feedback Errors itself. Change notifications to the Feedback Consoles are directly published from here as well. FeedbackChangeNotificationTopicName=aTopicName Input Objex Monitor (IOM) Event Server Objex Server Lite DB Output Objex Monitor

35. ExampleEventMonitor • Combines inbound and outbound enablers into 1 class. It is not necessary to do this, but it is possible. • The example produces and consumes PricePublicationEvents. For the purposes of the example, a special folder has been created for the reading and writing of the Events. UUIDs for the application will match the filename. • To accomplish the combination 2 inner classes where created: • PricePublicationPublisher to look for new events and publish them when it finds them. • ExamplePricePublicationEventHander to be the singular handler of events received. • ExampleDataDirectory=aDirectoryName

36. Property Catalog • Represent to storage of key\value pairs of global information to the VM. • Mostly configuration information. • They can have Parent Catalogs that they are adding values to or overriding values in. • This is a wrapper on a Properties object. • Basic Method Interface: • getBooleanProperty • getIntProperty • getEncryptedProperty • getListProperty • getProperty • getStringProperty • getMandatoryProperty(String) • isPropertyDeclared(String) • isPropertyDefined(String) • decrypt(String) • encrypt(String)

37. Communication Layers

38. EnyWare Communication Layer JMS All communications in EnyWare are based on the JMS spec. Communications do not deviate from the JMS spec at all. Whatever it provides is the extent of what is used. EnyWare currently only uses Topics. Think of JMS messaging, Topics and the way EnyWare utilizes them like tuning into a TV channel. No direct connections, but 1 media being broadcast out for anyone to listen. AbstractServerConnection Any messaging system capable of a JMS connection can have a connection to EnyWare. A subclass is created and the method createConnection() needs to be overridden. Publisher A JMS object for sending data out to a messaging system on a specific Topic or Queue name. Subscriber A JMS object for receiving data from a messaging system. Durable Messaging. EnyWareMessageListener An interface for Subscribers to adhere to in the EnyWare world.

39. Server Connection Server Connections exist because the different JMS providers create their connections in different ways. It is one of the few non-standard things about JMS. Messaging administration is another… • Existing EnyWare 4.0 Server Connections • imq.IMQServerConnection • imq3.IMQServerConnection • JBossMQServerConnection • OpenJMSServerConnection • SeeBeyondServerConnection • TibcoJMSConnection • Future • imq.IMQ44ServerConnection • New Jboss & OpenJMS connections ? • INI • messaginghost • messagingport • messagingprotocol • Basics • Create TopicConnectionFactory • setTopicConnection to a TopicConnection from the Factory

40. Publishers Creating a Publisher Publisher aPublisher = new com.tradewellsystems.communication.Publisher(aStringName); aPublisher.createCipher(); aPublisher.start(); • publish() • request() • savemessageswhiledisconnected=true\false • messagingrequesttimeout=10000 The EnyWare implementation of Publishers allows the system to be agnostic about the actual JMS implementation. Just change out the systems configuration for the Server Connection and everything else still works. Subclass of Connection • Caches TopicConnection • Each Connector gets it’s own Topic Session • transactedmessaging=true\false • connectionretries=1 • connectionretrysleeptime=5000 • usecipher=true\false • savedmessageslocation=aDirectoryName

41. Subscribers Creating a Subscriber Subscriber subscriber = new com.tradewellsystems.communication.Subscriber(aStringName, durableName, this); subscriber.createCipher(); subscriber.start(); • onMessage() • onMessageWithReturn() • handleNewTextMessage() vs. handleNewObjectMessage() • sendMessageToFeedback() The EnyWare implementation of Publishers allows the system to be agnostic about the actual JMS implementation. Just change out the systems configuration for the Server Connection and everything else still works. Subclass of Connection • Caches TopicConnection • Each Connector gets it’s own Topic Session • transactedmessaging=true\false • connectionretries=1 • connectionretrysleeptime=5000 • usecipher=true\false • savedmessageslocation=aDirectoryName

42. Message Listeners • Interface for classes that have Subscribers. When a subscriber receives a JMS message it will interpret the message into an Object or Text Message. It will also determine if the received message is a simple message send or a request for information. EnyWare currently only send Text Messages but was coded to allow for Object Messages. • handleException(EnyWareMessagingException) • handleNewObjectMessage() • handleNewObjectMessageRequest() • handleNewTextMessage() • handleNewTextMessageRequest()

43. Exceptions • While processing messages errors can occur. EnyWare categorizes them into two basic types: • MessageProcessingException • All messages being sent and received start as Text. • If a text message is assumed to be an Event and cannot be parsed into an Event, then a MessageProcessingException is thrown. • EventProcessingException • Once a text message becomes and Event, EnyWare will wrap any errors thrown into a new class of Exception. • Event Exceptions can be categorized and tracked because we know more things about the message. • Type • ID • Human Readable Identifier ? • With this information we can track Success\Error in a presentable and trackable way to a user.

44. Database Much like messaging, EnyWare has abstracted the concept of a database. It needs a Session, a Transaction and a way to query information. EnyWareDatabaseSession JDBCDatabaseSession NullDatabaseSession TopLinkDatabaseSession Transaction JDBCTransaction NullSession TopLinkTransaction NamedQueryCreator JDBCNamedQueryCreator TopLinkNamedQueryCreator

45. Exercises WebLogic Server Connection JDBC additions

46. Consoles

47. Administration Console Provides an interface for monitoring, configuring and maintaining your EnyWare installation. Pages for System, Applications, Events, Routing, Error Code, Configuration, Event Status, Diagnostic, User Preferences and Validation. Was actually the second console developed for EnyWare. Was originally just a place to get status about Services. The System tab never worked very well, mainly due to inconsistent and bad implementations of Request logic from the JMS service providers. Options – provides a way to get to User Profiles and manage them.

48. System Provides for current status and control of the various services connected to EnyWare. A service is anything sub-classed from BasicService. User can start\stop Reporting, Logging and Processing, as well as Reset a service or shut it down. The Reporting page allows the user to see whatever the program is currently writing to it’s logs if the service has been told to start reporting. The Configuration page allows the user to query the service for it’s current configuration.

49. Applications List of Applications that EnyWare has knowledge of. This information is necessary for EnyWare to create Identity for Applications as well as provide Routing and other services. The Definition is the only required element for an Application. Configuration can also be set for ALL Applications connected to EnyWare. By default, all the Core Applications are configured here, but other Applications may as well. OOMs and their configuration can also be maintained here for an Application. Application UID – unique ID for the application. System UID – An ID EnyWare uses for Identity Relationships.

50. Events Allows the user to View, Edit and Create the definition of event types in EnyWare. Name – The non-qualified Java class name. Class Name – The qualified Java class name. Display Name – The display name. Public – Yes \ No Leaf – Yes \ No Owners – List of External Applications that ownership will be enforced for. Definition – XSD name – will be displayed in text box if present – NOT used for anything other than display & documentation. Export – Can export this information to the eventmappings format for File loading of the information. EnyWare Event parsing relies on this information.