Professional Documents
Culture Documents
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
1.4. Assumptions
2
when trying to access database with a great number of individual
collaborations
1.5. Architecture
Application APIs
MessaageHandling
Queue
Data Access
Notification
Database File
Notification
Queue
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
/ No
Log
message
/ Yes
Message / No
Set to
Notification / Yes
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
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
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
10
Method Name getInstance
Description It is used to return singleton reference for NotificationHandler object
Parameters None
Return Type NotificationHandler
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
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
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
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
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
Description This method will close the file object opened by openConnection.
Parameters None
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
Description It is used to write data to file. The data is kept in variable insertStmt.
Parameters None
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
Description This method will close the any opened database connection.
Parameters None
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
Parameters None
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
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
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
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
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
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.
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}
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.
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
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
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:
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:
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: $”
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:
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).
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:
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:
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
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
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.
30
MH_CLSTYPE_COLUMN Column name that contains Class Type value cls_type
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_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_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_FROM_ADDRE from_address
SS
NOTIF_EMAIL_INFO_FROM_NAME from_name
NOTIF_EMAIL_INFO_SUBJECT subject
NOTIF_EMAIL_TO_ADDRESS to_address
NOTIF_EMAIL_TO_NAME to_name
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()
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.
35
36