oracle soa logger framework - · pdf file oracle soa logger framework by kathiravan...

http://oraclearchworld.wordpress.com/

Oracle SOA Logger Framework By Kathiravan Udayakumar`

SOA Logger is a very key framework that needs to be in place before SOA Developers community starts development of SOA Components. Logging Process related information is very important to trace the process execution details. Logging Process related information is also an Audit requirement for most of the enterprise. Process state and metadata details of any financial transaction process are mandated to be logged by SOX Compliance Requirements. These are key drivers to have SOA Logging Framework to be in place for all Enterprise SOA Implementation. This article will describe in detail about the below details of SOA Logger Framework

SOA Logger Framework Summary

SOA Logger Component Details

SOA Logger Features

SOA Logger Implementation Summary

SOA Logging Implementation – Using Native Logging Mechanism

SOA Logger Implementation - As Custom XPath

SOA Logging Standards

SOA Logger Framework Summary SOA Components need to log the process specific information and message details into file systems or database. Logging the details should be possible through Java, Web Service, XPath Interfaces and through DB Calls. The Logger should be able to log the details to the specific logger based on the incoming log level and SOA Platform logger configuration

Component Diagram provided below show the features that are required to be enabled to qualify the Logger in any SOA Platform. Logger component should be able to connect the Critical Alert Monitoring Components to send email messages based on the notification rules or error codes that are logged through the Logger.

SOA Logger Component Details SOA Logger Framework should be supported by three major components they are SOA Log Configuration, SOA Logger Scripts/Utilities and SOA Notification and Error Lookup Services.

The table below shows SOA Logger component details and components description details.

Components Component Description

SOA Log Configurator

SOA Log Configurator is a components used to configure the different loggers with Logging Message Format, Log File Size, Log Rotation Policy, Log Output Format and etc.

SOA Logger Utility

SOA Logger Utility is a component used to read the Logger configuration and log the error messages into log file. SOA Logger Utility is core component of the SOA Logger Framework. Implementation of the utility should be done using Java by extending the existing logging framework such as ilog or custom logging framework with pre-described rotation and archival policies for the log files.

SOA Notification and Error Lookup Service

SOA Notification and Error Lookup Service component will notify the error messages logged through the SOA Logger based on the SOA Logger Configuration

SOA Logger Features SOA Logger Components should be supported by below listed features.

Logger Component should be able to log the information into file or db.

Logger Component should determine the logging mode and logging parameters based on the configuration set for each log type.

Logger Utility Implementation should be exposed through XPath, Java and Web Service Interfaces.

Logger Configuration Component should provide the features to log the messages in required format (HTML, XML, txt, CSV or any custom format decide by the implementation team)

Logger Configuration Component should provide the features to create multiple loggers and associate it with the Logger Utility Component to log the messages in the required format.

Below screenshot shows the SOA Logger Component Details for a basic SOA Logger using HTML format for logging the messages.

SOA Logger Framework Implementation Summary Below snapshot shows the technical implementation view of SOA Logger Framework. Clients would access the SOA Logger Implementation through different wrapper interfaces that are exposed. Wrappers should push the messages to Logger Queue. SOA Logger BPEL Component would dequeue the messages from Logger Queue and complete the logging process based on the logger configuration.

Logger Component should expose below list of fields to the external world to interact with the component.

o Log Level, Logger Name/ID,

o Log Date Time (ISO Format)

o Application Name, Component Name

o Log Message, Additional Attributes Strings

o SOA Header String (We will discuss in detail about SOA Header Details in later section of this chapter).

SOA Header Details: Below snapshot contains the SOA Header details which will be used to describe an instance of a process. SOA Header should be populated in all BPEL flows to describe the process. The information provided in SOA Header will be passed to SOA Logger to Log the messages into SOA Logger. During process failures, SOA Administrators will be able to trace the process at instance level using the SOA Logs.

Code Reference:

Listing A: SOA Header Structure is shown in below code snippet

<?xml version="1.0" encoding="windows-1252" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.companyuri.org" targetNamespace="http://www.companyuri.org" elementFormDefault="qualified">

<xsd:element name="SOAHeader">

<xsd:complexType>

<xsd:sequence>

<xsd:element name="ProcessIndentifier"/>

<xsd:element name="ProcessName"/>

<xsd:element name="ProcessInstanceNo"/>

<xsd:element name="Application"/>

<xsd:element name="Component"/>

<xsd:element name="BusinessObjectName"/>

<xsd:element name="BusinessKey"/>

<xsd:element name="DateTimeStamp"/>

<xsd:element name="AdditionalAttribute1"/>



</xsd:sequence>

</xsd:complexType>

</xsd:element>

</xsd:schema>

SOA Logger Implementation – Using Oracle SOA Native Loggers Logging Message from SOA Process such as BPEL and Mediator can be achieved using Oracle SOA Native Loggers (extends iLog Framework). It is a tedious and code crowd approach. It puts additional over-ahead on the developers to import and set the log levels for every log message. This can be avoided by using the Custom XPath Implementation which is described in the next section. However to benefit the readers the approach is introduced in this section of the article.

Listing B: SOA Logging using native Java and Oracle SOA Logger; the below code should be placed after the process table in BPEL Process. It will import the required packages for implementation.



<bpelx:exec import="java.util.logging.Logger"/>

<bpelx:exec import="java.util.logging.Level"/>

<bpelx:exec import="oracle.fabric.logging.LogFormatter"/>

The below screenshot shows the Java Embedding used to Log the Process Start Status.

Listing C: SOA Logging using native Java and Oracle SOA Logger; Logging statements for start of the process

String SOAHeaderString = getVariableData("SOAHeaderStr");

Logger logger =Logger.getLogger("oracle.soa.Logger");

LogFormatter.configFormatter(logger);

logger.log(Level.INFO, "Start of Process"+SOAHeaderString);

Listing D: SOA Logging using native Java and Oracle SOA Logger; Logging statements for end of the process

String SOAHeaderString = getVariableData("SOAHeaderStr");



logger.log(Level.INFO, "End of Process"+SOAHeaderString);

SOA Logger Implementation – As a Custom XPath How to create Custom XPath Functions for creating SOA Header and Custom SOALogger? Custom XPath Function is key feature of Oracle SOA Suite that allows extending the functionalities provided by XPath Libraries in Oracle SOA Suite. XPath Functions are shared between all the below listed components to access the service data.

o BPEL

o Mediator

o Human Workflow

o XSLT (Implementation Style is different from above specified components)

The below diagram shows the key components that are required to be enable a custom XPath.

Below are list of steps to be followed in creating and using Custom XPath Functions.

Key Note:

XSLT Mapper Custom XPath function requires a corresponding public static method from a public static java class. The Custom XPath function name and Java Method name must same.

XSLT Mapper function namespaces should conform to below namespace http://www.oracle.com/XSL/Transform/java/package. XPathFunctionClass, where package.XPathFunctionClass is the fully qualified class name of the public static class containing the public static methods for the functions.

We will illustrate the creation of the custom XPath Function step by step in the following section.

Listing E: Java Class to be called as XPath Function from BPEL, Mediator, Human Workflow to create a SOA Header String.

package custom.soa.xpath;

import java.util.List;

import oracle.fabric.common.xml.xpath.IXPathContext;

import oracle.fabric.common.xml.xpath.XPathFunctionException;

public class createSOAHeaderString {

public Object call(IXPathContext context,

List list) throws XPathFunctionException {

String response = "";

try {

if (list.size() == 11)

{

response = createSOAHeaderStr((String)list.get(0),

(String)list.get(1),









(String)list.get(10));

} else {throw new XPathFunctionException(“Invalid Invoke, check the parameters”);}

return response;

} catch (Exception e) {

e.printStackTrace();

throw new XPathFunctionException(e.getMessage());

}

}

private static String createSOAHeaderStr(String ProcessIdentifier,

String ProcessName, String ProcessInstanceNo, String Application,

String Component, String BusinessObjectName, String BusinessKey,

String DateTimeStamp, String AdditionalAttribute1,

String AdditionalAttribute2, String AdditionalAttribute3)

throws Exception {

String SOAHeader;

SOAHeader = "<SOAHeader xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://www.companyuri.org xsd/SOAHeader.xsd\" xmlns=\"http://www.companyuri.org\">" +

"<ProcessIdentifier>" + ProcessIdentifier + "</ProcessIdentifier>" +

"<ProcessName>" + ProcessName + "</ProcessName>" +

"<ProcessInstanceNo>" + ProcessInstanceNo + "<ProcessInstanceNo/>" +

"<Application>" + Application + "</Application>" +

"<Component>" + Component + "</Component>" +

"<BusinessObjectName>" + BusinessObjectName + "</BusinessObjectName>" +

"<BusinessKey>" + BusinessKey + "</BusinessKey>" +

"<DateTimeStamp>" + DateTimeStamp + "</DateTimeStamp>" +

"<AdditionalAttribute1>" + AdditionalAttribute1 + "</AdditionalAttribute1>" +

“<AdditionalAttribute2>" + AdditionalAttribute2 + "</AdditionalAttribute2>" +

"<AdditionalAttribute3>" + AdditionalAttribute3 + "</AdditionalAttribute3>" + " </SOAHeader>";

return SOAHeader;

}

}

Listing F: Java Class to be called as XPath Function from BPEL, Mediator, Human Workflow to log the messages at INFO Level.

package custom.soa.xpath;

import java.util.List;

import java.util.logging.Logger;

import java.util.logging.Level;

import oracle.fabric.logging.LogFormatter;

import oracle.fabric.common.xml.xpath.IXPathContext;

import oracle.fabric.common.xml.xpath.XPathFunctionException;

public class SOALogger {

public Object call(IXPathContext context,

List list) throws XPathFunctionException {

String response = "";

try {

if (list.size() == 12)

{

response = logMessage((String)list.get(0),











(String)list.get(11));

}

else if (list.size() == 2)

{

response = logMessage((String)list.get(0),(String)list.get(1));

}

{throw new XPathFunctionException("Invalid Invoke, check the parameters");}

return response;

} catch (Exception e) {

e.printStackTrace();

throw new XPathFunctionException(e.getMessage());

}

}

private static String logMessage(String logMessage, String ProcessIdentifier,

String ProcessName, String ProcessInstanceNo, String Application,

String Component, String BusinessObjectName, String BusinessKey,

String DateTimeStamp, String AdditionalAttribute1,

String AdditionalAttribute2, String AdditionalAttribute3)

throws Exception {

String logMessagetxt = logMessage+

" ProcessIdentifier:" + ProcessIdentifier +

" ProcessName:" + ProcessName +

" ProcessInstanceNo:" + ProcessInstanceNo +

" Application:" + Application +

" Component:" + Component +

" BusinessObjectName:" + BusinessObjectName +

" BusinessKey:" + BusinessKey +

" DateTimeStamp:" + DateTimeStamp +

" AdditionalAttribute1:" + AdditionalAttribute1 +

" AdditionalAttribute2:" + AdditionalAttribute2 +

" AdditionalAttribute3:" + AdditionalAttribute3;



logger.log(Level.INFO, logMessagetxt);

return logMessage;

}

private static String logMessage(String logMessage, String SOAHeaderString)

throws Exception {

String logMessagetxt = logMessage+

" SOAHeaderString:" + SOAHeaderString;



logger.log(Level.INFO, logMessagetxt);

return logMessage;

}

}

Listing g: Create XPath Configuration File ext-soa-xpath-functions-config.xml and place the content below in it

<?xml version = '1.0' encoding = 'UTF-8'?>

<soa-xpath-functions xmlns="http://xmlns.oracle.com/soa/config/xpath"

version="11.1.1" resourceBundle="oracle.tip.tools.ide.common.resource.IDEMessageBundle"

xmlns:ora="http://schemas.oracle.com/xpath/extension"

xmlns:xref="http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPathFunctions"

xmlns:xp20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20"

xmlns:dvm="http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue"

xmlns:oraext="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc"

xmlns:customXPathSOAHeader="http://www.oracle.com/XSL/Transform/java/com.soa.xpath.createSOAHeaderString">

xmlns:customXPathSOALogger="http://www.oracle.com/XSL/Transform/java/com.soa.xpath.SOALogger">

<function name="customXPathSOAHeader:createSOAHeaderString">

<className>custom.soa.xpath.createSOAHeaderString</className>

<return type="string" />

<params>

<param name="ProcessIdentifier" type="string" />

<param name="ProcessName" type="string" />

<param name="ProcessInstanceNo" type="string" />

<param name="Application" type="string" />

<param name="Component" type="string" />

<param name="BusinessObjectName" type="string" />

<param name="BusinessKey" type="string" />

<param name="DateTimeStamp" type="string" />

<param name="AdditionalAttribute1" type="string" />



</params>

<desc resourceKey="createSOAHeaderString" />

<detail>

<![CDATA[Create SOA Header, Usage Details: customXPathSOAHeader:createSOAHeaderStr(String ProcessIdentifier,String ProcessName,String ProcessInstanceNo,String Application,String Component,

String BusinessObjectName, String BusinessKey,String DateTimeStamp,String AdditionalAttribute1,String AdditionalAttribute2,String AdditionalAttribute3) returns Header String]]>

</detail>

</function>

<function name="customXPathSOALogger:logMessage">

<className>custom.soa.xpath.SOALogger</className>


<params>

<param name="logMessage" type="string" />

<param name="ProcessIdentifier" type="string" />

<param name="ProcessName" type="string" />

<param name="ProcessInstanceNo" type="string" />

<param name="Application" type="string" />

<param name="Component" type="string" />

<param name="BusinessObjectName" type="string" />

<param name="BusinessKey" type="string" />

<param name="DateTimeStamp" type="string" />




</params>

<desc resourceKey="SOALogger" />

<detail>

<![CDATA[Create SOA Header, Usage Details: customXPathSOALogger:logMessage(String logMessage, String ProcessIdentifier,String ProcessName, String ProcessInstanceNo, String Application,String Component, String BusinessObjectName, String BusinessKey,String DateTimeStamp, String AdditionalAttribute1,String AdditionalAttribute2, String AdditionalAttribute3) returns logger String]]>

</detail>

</function>

<function name="customXPathSOALogger:logMessage">

<className>custom.soa.xpath.SOALogger</className>


<params>

<param name="logMessage" type="string" />

<param name="SOHeaderString" type="string" />

</params>

<desc resourceKey="SOALogger" />

<detail>

<![CDATA[Create SOA Header, Usage Details: customXPathSOALogger:logMessage(String logMessage, String SOAHeaderString) returns logger String]]>

</detail>

</function>

</soa-xpath-functions>

Deploying the jar to developer has below listed sub-steps,; follow the below specified steps to achieve the required result.

1. Compile the class

2. Add the custom XPath Configuration to the manifest folder of the jar to enable the custom XPath function in Design-time Environment.

3. Copy the jar to $ORACLE_HOME\Oracle_SOA1\soa\modules\oracle.soa.ext_11.1.1

4. Configure JAR to Oracle JDeveloper as shown in below screenshot.

Custom XPath can be accessed from the XPath Expression Builder with Functions column as “User Defined Extensions Functions”

Restart SOA Suite Admin Server get affect as we have copied the jar to SOA Extension module already.

SOA Logging Standards SOA Logger Components should be used as described below.

SOA Loggers should be used to log in start and end of the BPEL Process

SOA Loggers should be used in catch and catchall blocks to Log the Fault/Error Messages

SOA Header variables should be created before logging the Start or End of the Process.

Below snapshot shows the process that Logs the message in different essential sections of the process.

The below screen shot shows the Logging of error/fault messages in the catch block.

oracle soa logger framework - · pdf file oracle soa logger framework by kathiravan...

Documents