You are on page 1of 36

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 Code Decode

Java Message Handling Class Java Java


Parameterization Code Decode
Class Class

MessaageHandling
Queue
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 / Yes Message Handling Framework determines


Logging Level logging level from File depending upon
Configuration Severity and Class Type
/ No

Message Handling object determines


logging level from Database depending upon
Severity and Class Type

/ No
Log
message
/ 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 / No
Set to
Notification / 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 Transport medium Transport medium Transport medium


medium is File is Database is Email is SNMP

Formatted Log Message Formatted Log Message Formatted Log Message Formatted Log Message
is written to file is persisted to database is emailed 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 MessageHandling
Responsibility 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 getInstance
Description It is used to return singleton reference for MessageHandling object
Parameters None
Return Type MessageHandling

Method Name messageHandler


Description 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.
Parameters 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
Return Type Boolean value indicating success or failure
Method Name getLoggingLevel
Description 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.
Parameters None
Return Type Boolean value indicating success or failure
Method Name sendMessageToIQ
Description 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
Parameters o loggedMessage – message to be formatted
Return Type Boolean value indicating success or failure

Class Name MessageFormatting


Responsibility 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 messageReceiver
Description It is static method used to receive message (put by MessageHandling) from
queue. It internally uses receiveJMSQueueMessage method from utility class
ArchCommonUtils
Parameters None
Return Type Boolean value indicating success or failure

Method Name getMessageCode


Description 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
Parameters o msgCode - The numeric code referring to a specific event message
Return Type String containing message against given msgCode
Method Name getDistributionCode
Description 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
Parameters 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
Return Type Integer array containing distribution codes and transport codes
Method Name getClsType
Description 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
Parameters o clsType – integer code for class of team associated to the event
Return Type String returning value for Class Type
Method Name getMsgSeverity
Description 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
Parameters o msgSeverity – integer code for the level of severity of the event at which it
is thrown.
Return Type String returning Message Severity
Method Name formatMessage
Description 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
Parameters 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
Return Type String array containing formatted message
Method Name sendMessageToNotification
Description 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 Notification
Responsibility 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 NotificationHandler


Responsibility 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 getInstance
Description It is used to return singleton reference for NotificationHandler object
Parameters None
Return Type NotificationHandler

Method Name notificationReceiver

Description 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.
Parameters o transportCode – integer code representing transport medium
o distributionCode – integer code representing distribution
Return Type None

Method Name distributeNotification

Description 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.
Parameters o transportCode – integer code representing transport medium
o distributionCode – integer code representing distribution
Return Type 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.
Parameters 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
Return Type None

Class Name SNMPNotification


Responsibility 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 DataAccess
Responsibility 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 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.
Parameters None

Return Type None

Method Name getData

Description 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.
Parameters None

Return Type None

Method Name putData

Description 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.
Parameters None

Return Type None

12
Class Name File
Responsibility 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 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.
Parameters 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 Database


Responsibility 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 openConnection
Description This will be used to establish a connection to database using datasource. The
datasource name passed during construction of Database object.
Parameters None
Return Type 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 insertStr - string array containing values

Return Type None

Method Name addTableInfo

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

Method Name putData

Description It is used to insert data into database.

Parameters None

Return Type None

Class Name ArchCommonUtils


Responsibility 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 sendJMSQueueMessage
Description This will be used to send message on queue. Currently its implementation is
tightly coupled with JAVA CAPS.
Parameters 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
Return Type None

Method Name sendJMSQueueMessage

Description This will be used to receive message on queue. Currently its implementation is
tightly coupled with JAVA CAPS.
Parameters 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
Return Type TextMessage – JMS text message

Method Name getArchEnvironment

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

Return Type Properties – property file (arch.properties)

Class Name Parameterization


Responsibility 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 getParameters


Description 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.
Parameters o action – type of action i.e. publish or subscribe
o key – key for which values needs to be retrieved
Return Type Object containing all values stored against specified key

Class Name Decode


Responsibility 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 isInitialize


Description It is static method that is used to check whether hashmap (containing records)
for given table is already created or not.
Parameters o tableName – table name where records are kept
Return Type Boolean value indicating success or failure
Method Name getCodeRecord
Description It is static method that is used to get the hashmap containing all the decode
records for given table and unique key column name.
Parameters o keyColumnName – unique key column name
o keyValue - unique key column value
o tableName – table name where records are kept
Return Type 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
openConnection then message is persisted
into database
{OR} putData

commit

closeConnection

openConnection

addInsertStmt If transport mode is file


then message is written
putData to file
{OR}
closeConnection

If transport mode is Email or Pager


{OR} sendEmail then message sent via
Email or Pager accordingly

send
If transport mode is SNMP
{OR}
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
if action type is Publish then
individual setter methods are
called to populate values from resultset
setValues
{OR}

if action type is Subscribe then


individual setter methods are
called to populate values from resultset
setValues
{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 Database HashMap HashMap HashMap
(decodeHM) (decodeRecords) (decodeTables)

getCodeRecord

isInitialize

initialize

openConnection

addTableInfo

getData

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

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

The HashMap decodRecords


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

The HashMap decodeTables


will contain decodeRecords
put with key as given table name

clear

closeConnection

get

HashMap decodeRecords

get

HashMap decodeHM 21
HashMap decodeHM
1. The client JCD calls Decode class. It passes table name, unique column name and unique column value (code).
2. Decode class uses Data Access component (Database) to deal with database operations.
3. The HashMap decodeHM is used to hold column name and column value pairs for all columns for single record.
4. 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. MH_SEVERITY_CODE_TABLE
c. MH_CLSTYPE_CODE_TABLE
d. MH_MSGCODE_TABLE
e. 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 CLASS_TYPE LOG_LEVEL_FLAG


1 1 False
2 1 False
3 1 False
4 1 True
1 2 False
2 2 False
3 2 False
4 2 True
1 3 True
2 3 True
3 3 True
4 3 True
1 4 False
2 4 False
3 4 False
4 4 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 MESSAGE_SEVERITY
1 Trace
2 Information
3 Warning
4 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 CLASS_TYPE
1 ARCHITECTURE
2 INTERFACES
3 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 $”
0002 Thrown when ending a Java collaboration rule or java object: “Ending
$”
0003 Thrown when a JVM error occurs. “A JVM error has occurred within
the Architecture Service $”
0004 Thrown when an error is generated while a specific collaboration rule
or function is thrown; “A $ error occurred while executing $ from $”
0005 Thrown when a code is returned from a java method call: “Code $
returned from call to $”
0006 Thrown whenever a Data Access exception occurs', “The following
Data Access Exception $ occurred: $.”

24
0007 Thrown when a Data Access connection can not be established:
“Unable to connect to database $.”
0008 Thrown when unable to execute query: “SQLException in
executeQuery(): $”
0009 Thrown when unable to connect to an external system, “Unable to
Connect to external host $”
0010 Thrown when the data type in a Database table is not valid: “Wrong
data type in persistence table $”
0011 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 MSG_SEVERTY DISTR_CODE TRANS_CODE


0004 4 1 2
2000 4 1 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
c. NOTIF_DISTR_MATRIX
1 DB
This table maps transport code and distribution code
2 FF to a specific target destination with specific transport
3 EM channel. An example of the table is followed:
4 SNMP
CHAR_TRANS CHAR_DISTR_C NOTIF_DESTINATION
_CODE 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

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 DB_NAME DB_TABLE DB_COLUMN
ION
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 appteam@work.com Application Team App Message
AIL
SBYN_OPS_PAG Operations SBYN
ops@work.com
ER NOTIFICATION

f. 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 jdoe@work.com John Doe
INTERFACE_EMAIL doej@work.com Jane Doe
SBYN_OPS_PAGER 2025551234@pager.net Ops Team
SBYN_OPS_PAGER 2025555678@pager.net John Public

2.5.3 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 Description Value


Key Primary Key Unique key information
Hostname hostname where the data file resides Hostname or IP address
Port Port for ftp String value for the port number
e.g., “21” for FTP or “22” for
SFTP
Username Username for connecting to the data String value of the username e.g.
file source machine “admin”
Password Password for connecting to the data String value of the password e.g.
file source machine “@dmin”
Directory_listing_style Directory listing style “NT 4.0”, “UNIX”, “MVS
Sequential” for FTP
*Not used for when FTP_type =
“SFTP”
File_mode File mode “ASCII”, “BINARY”,
“EBCDIC”
FTP_type Type of FTP “SFTP”, “FTP”
Pre_directory_name data file directory path before Full directory path on the target
transfer machine
Pre_file_name data file name before transfer Filename to be saved as
EAI_directory_prefix EAI machine directory path prefix Directory path prefix for the data
for storing the data file file resides on EAI machine. The
actual data file will reside on
<EAI_directory_prefix>/lnbound
Post_action_type action for the data file “RENAME”, “NONE”
Post_directory_name data file directory path after transfer Post directory path on source
machine after transfer when
Post_action_type =”RENAME”

28
Post_file_name data file name after transfer Post file name on source
machine when Post_action_type
= “RENAME”
Transform_required transformation required or transfer “TRUE”, “FALSE”
to destination
Transform_msg_destination JMS destination for transformation JMS queue or topic name for
required data file transformation
Transform_msg_selector JMS message selector for JMS message selector
transformation process
Publish_message_destination JMS destination for direct transfer JMS queue or topic name for
data file subscribe process
Publish_message_selector JMS message selector for subscribe JMS message selector
process

b. PARAM_SUBSCRIBE_TABLE

Column Name Description Value


Key Primary Key Unique key information
Hostname hostname where the data file Hostname or IP address
resides
Port Port for ftp String value for the port number e.g.,
“21” for FTP or “22” for SFTP
Username Username for connecting to the String value of the username e.g.
data file source machine “admin”
Password Password for connecting to the data String value of the password e.g.
file source machine “@dmin”
Directory_listing_style Directory listing style “NT 4.0”, “UNIX”, “MVS
Sequential” for FTP
*Not used for when FTP_type =
“SFTP”
File_mode File mode “ASCII”, “BINARY”, “EBCDIC”
FTP_type Type of FTP “SFTP”, “FTP”
Target_directory_name data file directory path before Full directory path on the target
transfer machine
Target_file_name data file name before transfer Filename to be saved as

29
EAI_directory_name EAI machine directory path for Full directory path for the data file
storing the data file resides on EAI machine
Post_action_type action for the data file “RENAME”, “NONE”
EAI _directory_prefix EAI machine directory path prefix Directory path prefix for the data file
for storing the data file resides on EAI machine. The actual
data file will reside on
<EAI_directory_prefix>/lnbound
Post_directory_name Target machine data file directory Post directory path on target
path after transfer machine when Post_action_type
=”RENAME”
Post_file_name Target machine data file name after Post file name on target machine
transfer 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 JMS Queue name where message for MH_Queue
formatting is sent and received
MH_HOST_NAME JMS host NA (Need to configure according
to environment)
MH_PORT_NUMBER JMS port NA (Need to configure according
to environment)
MH_DB Database logical name for message handling archdb

MH_MSG_TOKEN Token used while tokenizing values from $


message
MH_RECEIVER_TIMEOUT Timeout period used by subscriber 10

MH_LOG_LEVEL_TABLE Table name where log levels are kept mh_logging_level

MH_SEVERITY_COLUMN Column name that contains Message msg_severity


Severity value

30
MH_CLSTYPE_COLUMN Column name that contains Class Type value cls_type

MH_LOG_FLAG_COLUMN Column name that contains Logging Level log_level_flag


value
MH_MSGCODE_TABLE Table name where Messages are kept mh_msgcode_table
according to Message Codes
MH_MSGCODE_MSGCODE_COLUM Column name that contains Message Code mh_msgcode_msgcode
N value
MH_MSG_COLUMN Column name that contains Message value mh_msg

MH_CLSTYPE_CODE_TABLE Table name where Class Type information is mh_clstype_code_table


kept
MH_CLSTYPE_CLSTYPECODE_COL Column name that contains Class Type Code cls_type_code
UMN value
MH_CLSTYPE_CLSTYPE_COLUMN Column name that contains Class Type value cls_type

MH_SEVERITY_CODE_TABLE Table name where Message Severity mh_severity_code_table


information is kept
MH_SEVERITY_SEVCODE_COLUM Column name that contains Message mh_severity_sevcode
N Severity Code value
MH_SEVERITY_SEVERITY_COLUM Column name that contains Message mh_severity_severity
N Severity value
MH_DIST_TRANS_CODE_TABLE Table name where distribution transport mh_dist_trans_code_table
matrix is kept
MH_DIST_SEVERITY_COLUMN Column name that contains Message msg_severity
Severity Code value
MH_DIST_MSGCODE_COLUMN Column name that contains Message Code msg_code
value
MH_DIST_DISTCODE_COLUMN Column name that contains Distribution Code dist_code
value
MH_DIST_TRANSCODE_COLUMN Column name that contains Transport Code trans_code
value
Notification properties
NOTIF_QUEUE_NAME JMS Queue name where formatted message NotifQueue
for notification is sent and received
NOTIF_HOST_NAME JMS host NA (Need to configure according
to environment)
NOTIF_PORT_NUMBER JMS port NA (Need to configure according
to environment)
NOTIF_FW_DB Database logical name for notification archdb

NOTIF_RECEIVER_TIMEOUT Timeout period used by subscriber 10

NOTIF_ERROR_LOG_FILE File path where errors are logged during NA (Need to configure according
notification to environment)

31
NOTIF_BACKUP_FILENAME File path where backup file NA (Need to configure according
to environment)
NOTIF_DEF_LOG_FILE File path where notification failure is logged NA (Need to configure according
to environment)
mail.smtp.host Default email contact when notification NA (Need to configure according
failures 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 Table and associated column names used to notif_trans_code


get distribution and transport codes and
NOTIF_TRANS_INT_COLUMN values 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 notif_distr_matrix


get distribution and 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 notif_databases
get destination info during database transport
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 notif_email_group_info


get destination info during email transport
NOTIF_EMAIL_INFO_GROUP_NAME group_name

NOTIF_EMAIL_INFO_FROM_ADDRE from_address
SS
NOTIF_EMAIL_INFO_FROM_NAME from_name

NOTIF_EMAIL_INFO_SUBJECT subject

NOTIF_EMAIL_TABLE Table and associated column names used to notif_email_groups


get group info during email transport
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 Properties


DATA_ACCESS_LOG File path where all messages related to data NA (Need to configure according
access are logged to environment)
FILE_CONTEXT Context used to retrieve binding properties NA (Need to configure according
to environment)
Code Decode Properties

33
CODEDECODE_DATASOURCE_NAM Database logical name for code decode archdb
E
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 Exception Class used


Notification NotificationException
Data Access DataAccessException
Parameterization ParameterizationException
Code Decode CodeLookupException

35
36

You might also like