Csf- Design

Contents 1. OVERVIEW ....................................................................................................................................................2 1.1.Introduction................................................................................................................................................2 1.2.Scope..........................................................................................................................................................2 1.3.Intended Audience......................................................................................................................................2 1.4.Assumptions...............................................................................................................................................2 1.5.Architecture................................................................................................................................................3 2. DESIGN VIEW................................................................................................................................................5 2.1.High Level Activity Diagram.....................................................................................................................5 2.2.Class Diagram............................................................................................................................................6 2.3.Interaction Diagrams................................................................................................................................16 2.4.Database Entities......................................................................................................................................22 2.5.Properties Configuration .........................................................................................................................30 3. ERROR HANDLING.....................................................................................................................................35

1

1. Overview 1.1. Introduction The Common Service Framework (CSF) is developed based on Accenture DLA’s common service framework. DLA’s common service framework was originally developed to work with eGate 4.5.3 and therefore has strong dependencies on eGate. In this version, most of the dependencies to eGate are removed by using standard JAVA in order to work with different integration tool platform. . This document provides a detail design description of the requirements and its implementation strategy.

1.2. Scope There are 5 major components of common services: 1. Data Access – provides basic functionally for accessing database and file. 2. Message Handling – provides utility functions for logging and exception handling messages. 3. Notification – provides mechanisms to send messages from message handling component to different destinations including database, flat file, email recipients, and/or SNMP server. 4. Parameterization – provides a generic functionality to access values of commonly used variables. It is mainly used with Mammoth Managed File Transfer Utility Service. 5. Code/Decode – provides utility function to access a code/decode table customized by developers.

1.3. Intended Audience The document is intended to provide a detail design description of technical requirements for the Common Services Framework (CSF) to the project managers, architects and developers who will utilize the common services.

1.4. Assumptions Below are the assumptions considered for this design:

a. This framework is developed in JAVA so this document assumes fundamental knowledge of Java. b.

This framework is available to both components within and outside of JAVA CAPS. But in this document examples use JAVA CAPS as integration platform. Currently Queue implementation used by CSF is done for JAVA CAPS.

c. The current common service framework does not utilize database connection pooling and therefore developers should be aware of the performance impact

2

when trying to access database with a great number of individual collaborations

d. Developers should not be accessing data access components directly. Data Access component is used to support all needs for other common service components. If developers require data access functionality, they should look into existing functionality in the integration tool or utilizing simple programming.

1.5. Architecture The architecture diagram for Message Handling Framework is shown below Application APIs

JAVA collaboration (JCD)

Common Services Framework (CSF)

Message Handling

Parameterzation Java Message Handling Class

MessaageHandling Queue

Java Parameterization Class

Code Decode Java Code Decode Class

Data Access

Java Message Formatting Class

Notification Java Notification Class Database

File

Notification Queue

Java Notification Handler Class

SNMP Server

Email

Oracle Database

File System

3

The Common Services Framework (CSF) contains 5 major components as shown in above diagram. 1. Message Handling The Message Handling framework is a subset within a group of architecture services that when packaged together delivers a robust solution for handling failed events, disseminating urgent messages through proper support channels, and enabling the EAI architecture to respond with resolutions to failed events of interest within the system. The Message Handling framework alone is designed to establish a basic infrastructure for logging messages of varying severities and creating the flexibility for developers to notify various parties using varying mechanisms of communication, of activity occurring for any interface. The Message Handling architecture is a package of Java classes, protocols and design procedures that standardize any message generated by an application. It will create all logged messages according to a common format and disseminate the log messages to a persistent storage area. This will be accomplished by providing a set of Java APIs, which can be called from any application during runtime. 2. Notification The Notification Framework is a package of functions and design steps that standardize the publication of messages to an array of possible destination mediums defined within the service. These messages may be error messages, which need to alert operations of an issue, or simple trace messages, which are logged for later use. This framework is not concerned with the content, only in determining where the message should be delivered, and in delivering it. 3. Data Access The Data Access Framework provides the services necessary to interact with data as it is persisted. This particular implementation will address data in stored in both a database and flat file medium. The framework allows a user to open and close file connections and to perform limited searches and updates to files. In addition, the framework provides the services to open and close database connections and to insert, update, delete, and select data. All other services of CSF are using Data Access to interact with database and file. 4. Parameterization The Parameterization Framework provides the architecture service to enable a eWay to dynamically load its settings for all connection point configuration files directly from a single data source. With this functionality, connection points can be maintained from a single location. As a result, connection maintenance and migrations will be greatly simplified. 5. Code Decode The Code/Decode Framework provides the architecture service to perform specialized “decode” operations in the e*Gate environment, while leveraging commonly performed methods in Java class files. The Java classes receive parameters for one or more “codes” and return the decode data specific to the relationship held within a database or a flat file (utilizing the Data Access service).

4

2.

DESIGN VIEW

2.1.High Level Activity Diagram The following high level activity diagram represents a typical CSF invocation scenario.

Client calls CSF Client sends Message code, Class Type, Severity and Message Parameters

Message Handling component of CSF receives message

File based Logging Level Configuration

/ Yes / No

Message Handling Framework determines logging level from File depending upon Severity and Class Type

Message Handling object determines logging level from Database depending upon Severity and Class Type

Log message

/ No / Yes

Publish Log Message on Queue

Message Formatting object picks up Log Message from Queue and formats message based on Message Code and Message Parameters

Message Set to Notification

/ No / Yes

Publish formatted Log Message on Notification Queue

Notification object picks up formatted Log Message from Notification Queue

Notification object determines distribution and transport medium based on Message Code and Message Severity

Transport medium is File Formatted Log Message is written to file

Transport medium is Database Formatted Log Message is persisted to database

Transport medium is Email Formatted Log Message is emailed

Transport medium is SNMP Formatted Log Message is sent as trap message

1. Client(JCD) will call CSF and pass required parameters (Message Code, Severity, Class Type, Message Parameters)

5

2. Message Handling Component will determine whether to use File based configuration or Database based configuration to get logging level. 3. Depending on configuration(file or database), logging level(whether to log message) is determined based on Message Severity and Class Type 4. If logging level is true, then message is published to queue for formatting. If logging level is false then it means that message will not be logged. 5. Message Formatting object picks up message from queue and formats it using Message Code and Message parameters. 6. Only if the message is set to notification then formatted message is then published to notification queue. 7. Notification object picks up message from notification queue and determines Distribution (which team will act upon) and transport (how to sent message) based on Message Code and Message Severity. Note that there can multiple distributions and transport can be configured for given formatted message. 8. If transport is File, then formatted message is written to file. All configuration details like file destination are retrieved from database using Data Access component.If transport is Database, then formatted message is persisted to database table. All configuration details like database table are retrieved from database using Data Access component.If transport is Email/Pager, then formatted message is sent via email/pager. All configuration details like email server details, recipient list are retrieved from database using Data Access component.If transport is SNMP, then formatted message is sent as trap message. All configuration details required by SNMP retrieved from database using Data Access component.

2.2.Class Diagram The below class diagram represents various relationships with Common Services Framework (CSF).

6

Class Name Responsibility

MessageHandling The MessageHandling class contains several methods, which accomplish the task of receiving a logged message based on a required format and verifying if the message is to be processed further based upon flags specified within the logging level table and also sending active messages to the message handling IQ. This is singleton class. Important Methods

7

Method Name Description Parameters Return Type

getInstance It is used to return singleton reference for MessageHandling object None MessageHandling

Method Name Description

messageHandler This method is to pass into the Message Handling framework a message along with specific arguments, which aid in the identification of the message. Each of the arguments passed within this method will be used to retrieve additional essential data by other methods within the framework. The messageHandler method is designed to be called across multiple applications and platforms. o msgCode - The numeric code referring to a specific event message o msgSeverity - The level of severity of the event at which it is thrown. Severity can be Trace, Informational, Warning, or Critical. o clsType - Class of team associated to the event. Class can be Architecture, Application, and Database etc. o eventType - Collaboration rule that triggered the message o localCollabRuleName – Project path of collaboration rule that triggered the message. o msgParameters - Message values to describe the event Boolean value indicating success or failure getLoggingLevel This method is called within the MessageHandling class to access the database and retrieve the level of logging that messages within the framework will follow. It will utilize the Data Access API to establish its connections with the database and retrieve specific data. The logging level is determined based on Message Severity and Class Type. None Boolean value indicating success or failure sendMessageToIQ This method is used to send messages that have active logging statuses to the Message Handling JMS IQ. It internally uses sendJMSQueueMessage method from utility class ArchCommonUtils o loggedMessage – message to be formatted Boolean value indicating success or failure

Parameters

Return Type Method Name Description

Parameters Return Type Method Name Description

Parameters Return Type Class Name Responsibility

MessageFormatting The MessageFormatting class contains several methods, which accomplish the task of receiving active messages passed along from the Message Handling class, transforming the msgCode variable into an understandable message, determining how and where the message will be distributed, and also sending the message to the Notification component. Important Methods

8

Method Name Description

Parameters Return Type Method Name Description

Parameters Return Type Method Name Description

Parameters Return Type Method Name Description

Parameters Return Type Method Name Description

Parameters Return Type Method Name Description

Parameters

Return Type Method Name Description

messageReceiver It is static method used to receive message (put by MessageHandling) from queue. It internally uses receiveJMSQueueMessage method from utility class ArchCommonUtils None Boolean value indicating success or failure getMessageCode This method is used to retrieve from a database a custom message associated to the msgCode variable passed into the Message Formatting class. The method will utilize the Data Access API to access a database and pull data from table MH_MSGCODE_TABLE o msgCode - The numeric code referring to a specific event message String containing message against given msgCode getDistributionCode The getDistributionCode method is used to retrieve from a database the values indicating the transport mechanism and also the distribution groups that will be receiving the logged messages. The method will utilize the DataAccess API to access the database and pull data from table MH_DIST_TRANS_CODE_TABLE o msgCode - The numeric code referring to a specific event message o msgSeverity - The level of severity of the event at which it is thrown Integer array containing distribution codes and transport codes getClsType This method is used to retrieve from a database a Class Type associated to the clsType variable passed into the Message Formatting class. The method will utilize the Data Access API to access a database and pull data from table MH_CLSTYPE_CODE_TABLE o clsType – integer code for class of team associated to the event String returning value for Class Type getMsgSeverity This method is used to retrieve from a database a Message Severity associated to the msgSeverity variable passed into the Message Formatting class. The method will utilize the Data Access API to access a database and pull data from table MH_SEVERITY_CODE_TABLE o msgSeverity – integer code for the level of severity of the event at which it is thrown. String returning Message Severity formatMessage This method formulates a new message, which will be received by the Notification framework. The formatMessage method will take the msgCode value and replace it with the custom message. The formatMessage method takes the custom message and replaces string tokens within, with values listed within the msgParameters string list variable o msg – message returned by getMessageCode o msgParameters – same as passed to MessageFormatting class o msgSeverity – severity returned by getMsgSeverity o clsType – class type returned by getClsType o eventType - same as passed to MessageFormatting class o localCollabRuleName - same as passed to MessageFormatting class o msgCode - same as passed to MessageFormatting class o timestamp - same as passed to MessageFormatting class String array containing formatted message sendMessageToNotification This method is calls formatMessage method to get newly formatted message, which will be sent to the Notification framework. Within this method an API 9

Class Name Responsibility

Notification This class acts as interface between MessageFormatting and actual notification handler class. It is used to publish formatted message to notification queue and then call the notification handler class Important Methods Method Name sendNotifcation Description It is used publish formatted message to notification queue and call notification handler class Parameters o transportCode – integer code representing transport medium o distributionCode – integer code representing distribution o message – formatted message Return Type None

Class Name Responsibility

NotificationHandler This class takes the necessary actions to send formatted message based on transport medium. It used Data Access API to route messages when transport medium is File or Database. This is singleton class. All properties related to Notification are kept in Arch.properties (see Properties Configuration section for more details) and are loaded first. These properties are used subsequently in various methods of this class. Important Methods

10

Method Name Description Parameters Return Type

getInstance It is used to return singleton reference for NotificationHandler object None NotificationHandler

Method Name

notificationReceiver

Description

Return Type

It is used to receive formatted message (put by Notification) from notification queue. It internally uses receiveJMSQueueMessage method from utility class ArchCommonUtils. It then calls distributeNotification method. o transportCode – integer code representing transport medium o distributionCode – integer code representing distribution None

Method Name

distributeNotification

Description

Return Type

It is method where actual implementation of notification is done. It first checks distribution matrix based on transport code and distribution code to determine destination for notification. If transport mode is File then formatted message is written to destination file. If transport mode is Database then formatted message is persisted to database table ARCH_NOTIF_DB. If transport mode is Email or Pager then formatted message to send via email or pager to recipients that are already configured. Finally if transport mode is SNMP then it forwards the message to SNMPNotification. o transportCode – integer code representing transport medium o distributionCode – integer code representing distribution Boolean value indicating success or failure

Method Name

sendEMail

Description

This method is used to send the formatted message as email notification to recipients configured. o aFromEmailAddr – string containing email address of sender o aToEmailAddr – list of receiver email addresses o aSubject – string containing subject of email o aBody – string containing body of email None

Parameters

Parameters

Parameters

Return Type

Class Name Responsibility

SNMPNotification This class is responsible for generating SNMP trap message from formatted message. Important Methods Method Name send Description It is used to create trap message from formatted message. It then internally calls another send method that creates SNMP trap message and sends that message. Parameters o snmpHost – host for SNMP o snmpPort – port used for SNMP o severity – severity of message o collabRule – collaboration rule name o projectPath – project path of collaboration o messageDetails – formatted message Return Type None

11

Class Name Responsibility

DataAccess This is abstract base class of Data Access component which enable the storage and retrieval of data from both databases and files. It provides the services necessary to interact with data as it is persisted. This particular implementation will address data stored in both a database and flat file medium. The framework allows a user to open and close file connections and to perform limited searches and updates to files. In addition, the framework provides the services to open and close database connections and to insert, update, delete, and select data. Important Methods Method Name openConnection Description It is used to establish a connection or handle to the appropriate persistence medium, whether it a database or a file. The openConnection method will be overloaded, consisting of two method implementations. One implementation will be used to establish a connection to a file and will have one input parameter, the name and path of the file (e.g. C:/temp/input.txt). The second implementation will be used to establish a connection to a database and will have the following three input parameters: database name, user name, and password. Parameters None Return Type None Method Name

closeConnection

Description

Parameters

It is used to close a connection or handle to the appropriate persistence medium, whether it a database or a file. This method will be overloaded, consisting of two method implementations. The closeConnection method will have one input parameters, either a Database object or a File object. This method will be overloaded and close the appropriate connection based on the input object. None

Return Type

None

Method Name

getData

Description

Parameters

It is used to retrieve data from the appropriate persistence medium, whether it a database or a file. The getData method will be overloaded, consisting of two implementations. Each implementation will only have one input parameter. One implementation is expecting a Database object and the other is expecting a File object. The appropriate method will be called based on the object passed. In the case that no data is retrieved, a null object will be returned. None

Return Type

None

Method Name

putData

Description

Parameters

It is used to insert data into the appropriate persistence medium, whether it’s a database or a file. The putData method will be overloaded, consisting of two implementations. Each implementation will only have one input parameter. One implementation is expecting a Database object and the other is expecting a File object. The appropriate method will be called based on the object passed. None

Return Type

None

12

Class Name Responsibility

File It is implementation of DataAccess for persistent medium as File. It allows user to open and close file connections and to perform limited searches and updates to files. It uses RandomAccessFile implementation. The filename (name and path) is passed during construction of File object and used subsequently in various methods. Important Methods Method Name openConnection Description This will be used to establish a connection to a file using RandomAccessFile The filename (name and path of the file) is already passed during construction of File object. Parameters None Return Type None Method Name

closeConnection

Description

This method will close the file object opened by openConnection.

Parameters

None

Return Type

None

Method Name

addInsertStmt

Description

Parameters

It allows the user to pass in a string which will be appended to the bottom of the file. This method only has one input parameter, the string to be added to the file. Subsequent calls to this method will concatenate the input strings to the insertStmt variable. o insertStr - string to be added to the file

Return Type

None

Method Name

putData

Description

It is used to write data to file. The data is kept in variable insertStmt.

Parameters

None

Return Type

None

Class Name Responsibility

Database It is implementation of DataAccess for persistent medium as Database. It provides the services to open and close database connections and to insert, update, delete, and select data. It takes datasource name while construction and used it to get database username, password and connection. Important Methods

13

Method Name Description Parameters Return Type

openConnection This will be used to establish a connection to database using datasource. The datasource name passed during construction of Database object. None None

Method Name

closeConnection

Description

This method will close the any opened database connection.

Parameters

None

Return Type

None

Method Name

addInsertStmt

Description

This method will create insert statements.

Parameters

o

Return Type

None

Method Name

addTableInfo

Description

Return Type

It is used to get table name and/or column names on which operation will be performed as – string array that contains table name at 0th index followed by column names if required None

Method Name

putData

Description

It is used to insert data into database.

Parameters

None

Return Type

None

Parameters

insertStr - string array containing values

Class Name Responsibility

ArchCommonUtils It is utility class that contains common functions required by various components of CSF e.g. Message Handling, Notification, Data Access Important Methods

14

Method Name Description

Return Type

sendJMSQueueMessage This will be used to send message on queue. Currently its implementation is tightly coupled with JAVA CAPS. o hostname – host name where JMS service is running o port – port where JMS service is running o queueName – JNDI name of queue o message – message to be sent None

Method Name

sendJMSQueueMessage

Description

Return Type

This will be used to receive message on queue. Currently its implementation is tightly coupled with JAVA CAPS. o hostname – host name where JMS service is running o port – port where JMS service is running o queueName – JNDI name of queue o timeout – timeout period TextMessage – JMS text message

Method Name

getArchEnvironment

Description Parameters

This will be used to load arch.properties file using FileInputStream. It gets the file path using environment variable ENV_VARIABLE_FILEPATH. None

Return Type

Properties – property file (arch.properties)

Parameters

Parameters

Class Name Responsibility

Parameterization This class is responsible for getting multiple values against the given key. Values are retrieved based on publish or subscribe action based using specified key. FTP and SFTP configuration properties are normally stored in database both for publish and subscribe operation. This is singleton class. Important Methods Method Name getInstance Description It is used to return singleton reference for Parameterization object Parameters None Return Type Parameterization Method Name Description

Parameters Return Type Class Name Responsibility

getParameters This method accepts action type (publish or subscribe) and key. If the action is publish then key is looked up in PARAM_PUBLISH_TABLE where as if action is subscribe then key is looked up in PARAM_SUBSCRIBE_TABLE. In any case, all the properties configured for given key are returned. o action – type of action i.e. publish or subscribe o key – key for which values needs to be retrieved Object containing all values stored against specified key Decode This class is responsible for getting values for given key in given table.

15

Important Methods Method Name initialize Description It is static method that used to create hashmap containing all the records for given table. The key used for decode records is the unique column name and key used by final hashmap is table name. This hashmap will be used by other methods. Parameters o keyColumnName – unique key column name o tableName – table name where records are kept Return Type Boolean value indicating success or failure Method Name Description Parameters Return Type Method Name Description Parameters

Return Type

isInitialize It is static method that is used to check whether hashmap (containing records) for given table is already created or not. o tableName – table name where records are kept Boolean value indicating success or failure getCodeRecord It is static method that is used to get the hashmap containing all the decode records for given table and unique key column name. o keyColumnName – unique key column name o keyValue - unique key column value o tableName – table name where records are kept Hashmap containing decode records

2.3.Interaction Diagrams The below sequence diagram shows interaction between various participants in class diagram. (To see diagram better you need to zoom to 200%)

16

Client(JCD)

MessageHandling

MessageFormatting

Notification

NotificationHandler

ArchCommonUtils

Database

File

SNMPNotification

getInstance

messageHandler

initialize

sendMessageToIQ sendJMSQueueMessage messageReceiver receiveJMSQueueMessage

sendMessageToNotification

formatMessage sendNotification sendJMSQueueMessage getInstance notificationReceiver receiveJMSQueueMessage

distributeNotification

addTableInfo addInsertStmt

If transport mode is database then message is persisted into database

openConnection {OR}

putData commit closeConnection

openConnection addInsertStmt

If transport mode is file then message is written to file

putData

{OR}

closeConnection

{OR}

sendEmail

If transport mode is Email or Pager then message sent via Email or Pager accordingly

send {OR}

If transport mode is SNMP then trap message is sent

17

1.

The Message Handling component primarily serves as a tool for triggering messages of various severities and meanings and formatting them into a common format that can be easily managed and routed to various groups via different transport mechanisms. Messages generated by the Message Handling component will be raised depending on changing scenarios such as a business rule/data defect, coding or design defect, technical failures, or simply to trace interface or application logic. Therefore, developers will have the responsibility of invoking calls to the Message Handling framework from within their code.

2.

Calls to the framework and the raising of messages will be handled by utilizing the Message Handling Object. The Message Handling Object will encapsulate the arguments, passed to it by developers, required in order to complete a well-structured message, which can then be passed on further through the Message Handling component. There are two methods by which the Message Handling object can determine the proper level of messages that will be logged by the system. The first is a File-Based approach, which basically serves as a fall-back alternative in the event that either a database connection cannot be made or a database simply does not exist. The second method using Database tables is the recommended approach because it provides the greatest flexibility for retrieving data in various formats and also allows easy maintenance and back up. At execution or runtime, the Message Handling Object will invoke both options routinely and will be able to determine which method the architecture team prefers. It will accomplish this by searching first for the existence of a Log Level File within a designated directory. If a file exists, the Message Handling Object will utilize the File-Based approach. If the latter is true, it will automatically default to using the Data Access framework to retrieve the log level values from a database. The Message Handling Object will utilize an API provided by the Data Access component and two of the developer provided arguments, msgSeverity and classType, to access the Logging Level table and determine to what degree messages will be created and logged. If the required Logging Level flag of “Y” is not returned to the Message Handling Object, processing of all messages corresponding to that flag will stop. Evaluating specified logging levels from within the Logging Level table will give the integration architecture team greater flexibility in managing and filtering logging messages within the systems.

3.

Messages that are associated with an active logging state are sent via the Java Messaging Service (JMS) to the Message Handling JMS IQ located within the JAVA CAPS application environment. All messages will be sent to this IQ in order to ensure that messages are persistently stored in the event of a technical failure. All messages sent to the Message Handling JMS IQ will be subscribed to by a JAVA CAPS message handling component, which utilizes the Message Formatting Object to identify a transport mechanism and distribution list required in order to properly route the message once it has been passed to the Notification framework. (JAVA CAPS specific)

4.

The Message Formatting Object relies upon the Data Access framework API to retrieve two sets of values before processing the message any further. The first value is a specific error or notification message pre-determined by the architecture team and stored within a

18

database table, which corresponds to the argument msgCode provided as a parameter by developers. Utilizing the Data Access Framework API to query the database table, the msgCode argument and msgParameters array parameters will be used to find and select a unique message associated with the msgCode value. Once a unique message string is found, string tokenizers within the message will be replaced by the msgParameters values within the array and the updated message string will be forwarded to the Message Formatter Object. Additionally, the Message Formatting Object also relies upon the Data Access framework API to retrieve both a Distribution and Transport Code from the database. Both codes are retrieved using the msgSeverity argument passed by a developer and also again the msgCode argument. Each possible combination of the two codes may yield a unique distribution and transport value or yield multiple values for the same combination. And these values will be used to formulate a new message that is integral for the next phase of the message handling process, Notifications. 5.

The new message formatted by the Message Formatting Object contains three important arguments, which are essential for the Notification framework to operate. The first value is the msgCode value, which contains the custom messages extracted from database table. The msgCode value is the actual message content that will be sent to a database table, flat file, or person to notify of an error or condition. The second argument transportCode specifies for the Notification framework, which transport mechanism to use in communicating the message to a person or passing the message to a repository. The final argument, distCode will indicate for the Notification framework, which individual, group, or groups will be notified and sent the logged messages for review.

The following figure shows sequence diagram for Parameterization.

19

Client(JCD)

Parameterization

Database

BatchPublishConnection

BatchSubscribeConnection

getInstance getParameters openConnection addTableInfo addCondition getData getResultSet

setValues

if action type is Publish then individual setter methods are called to populate values from resultset

{OR}

setValues

if action type is Subscribe then individual setter methods are called to populate values from resultset

{OR}

1. Client JCD gets reference of Parameterization and then sends action type (publish or subscribe operation) along with key to Parameterization class. 2. Parameterization class then uses Data Access (Database implementation) to get the values from database table depending on the action type passed. If action type passed is Publish then values are picked up from PARAM_PUBLISH_TABLE else if action type is Subscribe then values are picked up from PARAM_SUBSCRIBE_TABLE. 3. The values are then populated either in BatchPublishConnection (if action type is Publish) or BatchSubscribeConnection (if action type is Subscribe) and populated object is returned to client JCD. The following figure shows sequence diagram for CodeDecode.

20

Client(JCD)

Decode

HashMap (decodeHM)

Database

HashMap (decodeRecords)

HashMap (decodeTables)

getCodeRecord

isInitialize

initialize

openConnection addTableInfo getData getResultSet

new HashMap decodeTables is created if it is it is not created

new new

new getResultSetColumnNames

The HashMap decodeHM will contain columname and columnvalue pairs. Put operation(for decodeHM) is performed for all the columns

put

The HashMap decodRecords will contain decodeHM for key as value of unique column name for each record in given table

put

put

The HashMap decodeTables will contain decodeRecords with key as given table name

clear closeConnection

get HashMap decodeRecords get HashMap decodeHM HashMap decodeHM

21

1. 2. 3. 4.

The client JCD calls Decode class. It passes table name, unique column name and unique column value (code). Decode class uses Data Access component (Database) to deal with database operations. The HashMap decodeHM is used to hold column name and column value pairs for all columns for single record. The HashMap decodeRecords is used to hold all records in given table. So it will store multiple decodeHM hashmap. The key used for each record will be unique key column value for each record. 5. The HashMap decodeTables is used to hold all records from various tables. So it will store multiple decodeRecords depending on multiple tables. The key for each record will be table name. decodeTables(key is table name) | | |________decodeRecords(key is value of unique column) | | |____________decodeHM(key is column name) |_____columnName1 = columnValue1 |_____columnName2 = columnValue2 |_____ …….. |____________decodeHM |_____ …….. |________decodeRecords |_____ …….. 6. The decodeHM is returned based on table name and column value(key) passed.

2.4.Database Entities 2.5.1

Message Handling Tables

There are 5 tables required for Message Handling: a. MH_LOGGING_LEVEL

22

b. c. d. e.

MH_SEVERITY_CODE_TABLE MH_CLSTYPE_CODE_TABLE MH_MSGCODE_TABLE MH_DIST_TRANS_CODE_TABLE

a. MH_LOGGING_LEVEL This table is used to define if a message needed to be logged based on the given severity and class type. An example of the table is followed: MESSAGE_SEVERITY 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4

CLASS_TYPE 1 1 1 1 2 2 2 2 3 3 3 3 4 4 4 4

LOG_LEVEL_FLAG False False False True False False False True True True True True False False False True

In this example, a message with severity of 1 and class type of 3 will need to be logged. A message with severity of 2 and class type of 2 will not. b. MH_SEVERITY_CODE_TABLE This table is user to define the numeric code with the severity description. An example of the table is followed:

23

MESSAGE_SEVERITY_CODE 1 2 3 4

MESSAGE_SEVERITY Trace Information Warning Critical

c. MH_CLSTYPE_CODE_TABLE This table maps the class type code (integer) to a meaningful class group. An example of the table is as followed: CLASS_TYPE_CODE 1 2 3

CLASS_TYPE ARCHITECTURE INTERFACES COMMONSERVICES

In this example, a class type of 1 would stand for the class type of architecture and 2 will stand for interfaces...etc. d. MH_MSG_CODE This table maps the message code to an actual message. An example (default base code) is followed: Message Code

Message

0001

Thrown when starting a Java collaboration rule or java object: “Starting $” Thrown when ending a Java collaboration rule or java object: “Ending $” Thrown when a JVM error occurs. “A JVM error has occurred within the Architecture Service $” Thrown when an error is generated while a specific collaboration rule or function is thrown; “A $ error occurred while executing $ from $” Thrown when a code is returned from a java method call: “Code $ returned from call to $” Thrown whenever a Data Access exception occurs', “The following Data Access Exception $ occurred: $.”

0002 0003 0004 0005 0006

24

0007 0008 0009 0010 0011

Thrown when a Data Access connection can not be established: “Unable to connect to database $.” Thrown when unable to execute query: “SQLException in executeQuery(): $” Thrown when unable to connect to an external system, “Unable to Connect to external host $” Thrown when the data type in a Database table is not valid: “Wrong data type in persistence table $” Thrown when an invalid Data Access type is encountered: “Invalid Data Access Type: $”

Note: the “$” will be replaced by message parameters provided. e. MH_DIST_TRANS_CODE_TABLE This table takes message code and severity code and maps them to appropriate transport code and distribution code. An example is followed: MSG_CODE 0004 2000

MSG_SEVERTY 4 4

DISTR_CODE 1 1

TRANS_CODE 2 1

In this example, a message code of 2000 and a severity of 4 will have distribution code of 1 and transport code of 1. (See Notification tables to understand what distribution code and transport code are). 2.5.2

Notification Tables

There are 6 tables used by Notification. a. NOTIF_DATABASES b. NOTIF_DISTR_CODE c. NOTIF_DISTR_MATRIX d. NOTIF_EMAIL_GROUP_INFO e. NOTIF_EMAIL_GROUPS f. NOTIF_TRANS_CODE

25

a. NOTIF_DISTR_CODE This table maps distribution code to a specific distribution group. An example of the table: INT_DISTR_CODE

CHAR_DISTR_CODE

1

ARCH

2

INTERFACE

3

CS

b. NOTIF_TRANS_CODE This table maps transport code to a text description of the transport. The possible transport that notification currently supports is database, file, email/pager and SNMP. An example of the table is followed: INT_TRANS_CODE

CHAR_TRANS_CODE

1

DB

2

FF

3

EM

4 CHAR_TRANS _CODE

CHAR_DISTR_C ODE

DB

ARCH

ARCH_NOTIF_DB

EM

APP

INTERFACE_EMAIL

FF

CS

D:/CommonService/log/MessageHandlin g/mh.log

SNMP

ARCH

127.0.0.1:162

c. NOTIF_DISTR_MATRIX This table maps transport code and distribution code to a specific target destination with specific transport channel. An example of the table is followed:

SNMP NOTIF_DESTINATION

d. NOTIF_DATABASES If the destination defined in the table, NOTIF_DISTR_MATRIX uses database as the transport. This table defines the database details – database name, table name and column name. An example of the table is followed:

26

NOTIF_DESTINAT ION

DB_NAME

DB_TABLE

DB_COLUMN

ARCH_NOTIF_DB

DEVDB

ARCH_DATA

TIMESTAMP

APP_NOTIF_DB

DEVDB

APP_DATA

MESSAGES

TEST_NOTIF

TESTDB

ERROR_TABLE

NOTIFS

e. NOTIF_EMAIL_GROUP_INFO If the destination defined in the table, NOTIF_DISTR_MATRIX uses email or pager as the transport. This table defines the details of the email message – “from address”, “from name” and “subject”. An example of the table is followed: GROUP_NAME

FROM_ADDRESS

FROM_NAME

SUBJECT

INTERFACE_EM AIL

[email protected]

Application Team

App Message

Operations

SBYN NOTIFICATION

SBYN_OPS_PAG ER

f.

2.5.3

[email protected]

NOTIF_EMAIL_GROUPS This table defined the “to address” and “to name” if a destination uses email/pager as the transport. An example of the table is followed: GROUP_NAME

TO_ADDRESS

TO_NAME

INTERFACE_EMAIL

[email protected]

John Doe

INTERFACE_EMAIL

[email protected]

Jane Doe

SBYN_OPS_PAGER

[email protected]

Ops Team

SBYN_OPS_PAGER

[email protected]

John Public

Parameterization Tables

27

Parameterization tables are mainly utilized by Managed File Transfer, Batch and Debatch templates. There are two tables: a. PARAM_PUBLISH_TABLE b. PARAM_SUBSCRIBE_TABLE a. PARAM_PUBLISH_TABLE Column Name Key Hostname Port

Description Primary Key hostname where the data file resides Port for ftp

Username

Directory_listing_style

Username for connecting to the data file source machine Password for connecting to the data file source machine Directory listing style

File_mode

File mode

FTP_type Pre_directory_name

Type of FTP data file directory path before transfer data file name before transfer EAI machine directory path prefix for storing the data file

Password

Pre_file_name EAI_directory_prefix

Post_action_type Post_directory_name

action for the data file data file directory path after transfer

Value Unique key information Hostname or IP address String value for the port number e.g., “21” for FTP or “22” for SFTP String value of the username e.g. “admin” String value of the password e.g. “@dmin” “NT 4.0”, “UNIX”, “MVS Sequential” for FTP *Not used for when FTP_type = “SFTP” “ASCII”, “BINARY”, “EBCDIC” “SFTP”, “FTP” Full directory path on the target machine Filename to be saved as Directory path prefix for the data file resides on EAI machine. The actual data file will reside on <EAI_directory_prefix>/lnbound “RENAME”, “NONE” Post directory path on source machine after transfer when Post_action_type =”RENAME”

28

Post_file_name

data file name after transfer

Transform_required

transformation required or transfer to destination JMS destination for transformation required data file JMS message selector for transformation process JMS destination for direct transfer data file JMS message selector for subscribe process

Transform_msg_destination Transform_msg_selector Publish_message_destination Publish_message_selector

Post file name on source machine when Post_action_type = “RENAME” “TRUE”, “FALSE” JMS queue or topic name for transformation JMS message selector JMS queue or topic name for subscribe process JMS message selector

b. PARAM_SUBSCRIBE_TABLE Column Name Key Hostname Port Username Password Directory_listing_style

File_mode FTP_type Target_directory_name Target_file_name

Description Primary Key hostname where the data file resides Port for ftp Username for connecting to the data file source machine Password for connecting to the data file source machine Directory listing style

File mode Type of FTP data file directory path before transfer data file name before transfer

Value Unique key information Hostname or IP address String value for the port number e.g., “21” for FTP or “22” for SFTP String value of the username e.g. “admin” String value of the password e.g. “@dmin” “NT 4.0”, “UNIX”, “MVS Sequential” for FTP *Not used for when FTP_type = “SFTP” “ASCII”, “BINARY”, “EBCDIC” “SFTP”, “FTP” Full directory path on the target machine Filename to be saved as

29

EAI_directory_name Post_action_type EAI _directory_prefix

EAI machine directory path for storing the data file action for the data file EAI machine directory path prefix for storing the data file

Post_directory_name

Target machine data file directory path after transfer

Post_file_name

Target machine data file name after transfer

Full directory path for the data file resides on EAI machine “RENAME”, “NONE” Directory path prefix for the data file resides on EAI machine. The actual data file will reside on <EAI_directory_prefix>/lnbound Post directory path on target machine when Post_action_type =”RENAME” Post file name on target machine when Post_action_type = “RENAME”

2.5.Properties Configuration The common services framework uses one property file, arch.properties, to configure the basic configurations. It contains configuration properties for Message Handling, Notification and Data Access components. Property

Description

Default Value

Message Handling properties MH_EVENT_TOPIC MH_HOST_NAME

JMS Queue name where message for formatting is sent and received JMS host

MH_Queue

MH_PORT_NUMBER

JMS port

MH_DB

Database logical name for message handling

MH_MSG_TOKEN

$

MH_RECEIVER_TIMEOUT

Token used while tokenizing values from message Timeout period used by subscriber

MH_LOG_LEVEL_TABLE

Table name where log levels are kept

mh_logging_level

MH_SEVERITY_COLUMN

Column name that contains Message Severity value

msg_severity

NA (Need to configure according to environment) NA (Need to configure according to environment) archdb

10

30

MH_CLSTYPE_COLUMN

Column name that contains Class Type value

cls_type

MH_LOG_FLAG_COLUMN

Column name that contains Logging Level value Table name where Messages are kept according to Message Codes Column name that contains Message Code value Column name that contains Message value

log_level_flag

Table name where Class Type information is kept Column name that contains Class Type Code value Column name that contains Class Type value

mh_clstype_code_table

Table name where Message Severity information is kept Column name that contains Message Severity Code value Column name that contains Message Severity value Table name where distribution transport matrix is kept Column name that contains Message Severity Code value Column name that contains Message Code value Column name that contains Distribution Code value Column name that contains Transport Code value

mh_severity_code_table

MH_MSGCODE_TABLE MH_MSGCODE_MSGCODE_COLUM N MH_MSG_COLUMN MH_CLSTYPE_CODE_TABLE MH_CLSTYPE_CLSTYPECODE_COL UMN MH_CLSTYPE_CLSTYPE_COLUMN MH_SEVERITY_CODE_TABLE MH_SEVERITY_SEVCODE_COLUM N MH_SEVERITY_SEVERITY_COLUM N MH_DIST_TRANS_CODE_TABLE MH_DIST_SEVERITY_COLUMN MH_DIST_MSGCODE_COLUMN MH_DIST_DISTCODE_COLUMN MH_DIST_TRANSCODE_COLUMN

mh_msgcode_table mh_msgcode_msgcode mh_msg

cls_type_code cls_type

mh_severity_sevcode mh_severity_severity mh_dist_trans_code_table msg_severity msg_code dist_code trans_code

Notification properties NOTIF_QUEUE_NAME NOTIF_HOST_NAME

JMS Queue name where formatted message for notification is sent and received JMS host

NotifQueue

NOTIF_PORT_NUMBER

JMS port

NOTIF_FW_DB

Database logical name for notification

NA (Need to configure according to environment) NA (Need to configure according to environment) archdb

NOTIF_RECEIVER_TIMEOUT

Timeout period used by subscriber

10

NOTIF_ERROR_LOG_FILE

File path where errors are logged during notification

NA (Need to configure according to environment)

31

NOTIF_BACKUP_FILENAME

File path where backup file

NOTIF_DEF_LOG_FILE

File path where notification failure is logged

mail.smtp.host

Default email contact when notification failures

NA (Need to configure according to environment) NA (Need to configure according to environment) NA (Need to configure according to environment)

NOTIF_EMAIL_DEF_FROM_ADDRES S NOTIF_EMAIL_DEF_SUBJECT NOTIF_EMAIL_DEF_TO_ADDRESS1 NOTIF_EMAIL_DEF_TO_NAME1 NOTIF_EMAIL_DEF_TO_ADDRESS2 NOTIF_EMAIL_DEF_TO_NAME2 NOTIF_TRANS_CODE_TABLE NOTIF_TRANS_INT_COLUMN

Table and associated column names used to get distribution and transport codes and values

notif_trans_code int_trans_code

NOTIF_TRANS_CODE_COLUMN

char_trans_code

NOTIF_DISTR_CODE_TABLE

notif_distr_code

NOTIF_DISTR_INT_COLUMN

int_distr_code

NOTIF_DISTR_CODE_COLUMN

char_distr_code

NOTIF_DISTR_MATRIX_TABLE

Table and associated column names used to get distribution and matrix

notif_distr_matrix

NOTIF_MATRIX_TRANS_COLUMN

char_trans_code

NOTIF_MATRIX_DISTR_COLUMN

char_distr_code

NOTIF_MATRIX_DESTINATION

notif_destination

32

NOTIF_DATABASES_TABLE

Table and associated column names used to get destination info during database transport

notif_databases

NOTIF_DB_DESTINATION

notif_destination

NOTIF_DB_NAME

db_name

NOTIF_DB_TABLE

db_table

NOTIF_DB_COLUMN

db_column

NOTIF_EMAIL_INFO_TABLE

Table and associated column names used to get destination info during email transport

notif_email_group_info

NOTIF_EMAIL_INFO_GROUP_NAME

group_name

NOTIF_EMAIL_INFO_FROM_ADDRE SS NOTIF_EMAIL_INFO_FROM_NAME

from_address

NOTIF_EMAIL_INFO_SUBJECT

subject

NOTIF_EMAIL_TABLE

from_name

Table and associated column names used to get group info during email transport

notif_email_groups

NOTIF_EMAIL_GROUP_NAME

group_name

NOTIF_EMAIL_TO_ADDRESS

to_address

NOTIF_EMAIL_TO_NAME

to_name

NOTIF_DB_TRANS_CODE

Database transport code

DB

NOTIF_FF_TRANS_CODE

File transport code

FF

NOTIF_EM_TRANS_CODE

Email transport code

EM

NOTIF_PG_TRANS_CODE

Pager transport code

PG

NOTIF_SNMP_TRANS_CODE

SNMP transport code

SNMP

DATA_ACCESS_LOG

File path where all messages related to data access are logged Context used to retrieve binding properties

Data Access Properties

FILE_CONTEXT

NA (Need to configure according to environment) NA (Need to configure according to environment)

Code Decode Properties

33

CODEDECODE_DATASOURCE_NAM E

Database logical name for code decode

archdb

Parameterization properties PARAM_DATABASE_NAME

Database logical name for parameterization

archdb

34

3.

Error Handling

The below class diagram shows various classes and their relationships that are participating in exception handling. Exception

ArchServicesException -cause +printStackTrace() +getCause() +StringExceptionInfo() +stringStackTrace() +toString()

NotificationException

DataAccessException

ParameterizationException

CodeLookupException

As shown in above diagram, ArchServicesException is base exception class that extends from java.lang.Exception class. The exception classes extends ArchServicesException class and their name suggests which component of CSF has thrown error. CSF Component Notification Data Access Parameterization Code Decode

Exception Class used NotificationException DataAccessException ParameterizationException CodeLookupException

35

36