Basics of XPath used in SOA

XPath is used to navigate through an XML document. It has some XPath predefined functions owned by W3schools to fetch parts of the XML document. On top of these functions Oracle SOA has defined some custom functions to suite Oracle SOA requirements. In this document we will discuss the basic XPath functions used is Oracle SOA.

Consider below XML document that can be sent to a SOA webservice, and let us see some XPath expressions and their results.

The root element in this document is <inputVar> which is represented by “/” in XPath.

1. To get order number:

Expression: /ns:orderDetails/ns:orderHeader/ns:orderNumber

Oracle SOA returns: ORD1231 OR <ns:orderNumber>ORD1231</ns:orderNumber>

Expression: /ns:orderDetails/ns:orderHeader/ns:orderNumber/text()

Result: ORD1231

2. To get order line:

Expression:  /ns:orderDetails/ns:orderHeader/ol:orderLine

Result:      <ol:orderLine lineIdentifier="1231_11">

               <ol:item>Hard Disk</ol:item>

               <ol:unitPrice>TS</ol:unitPrice>

             </ol:orderLine>

3. To get lineIdentifier:

Expression: /ns:orderDetails/ns:orderHeader/ol:orderLine/@lineIdentifier

Result:     1234_11

Below is another XML document which has more hierarchal structure. We will see how to deal with fetching first and last elements/nodes and element at a given index.

1. To get the first order orderNumber:

   Possible expressions:

        /ns:orderDetails/ns:orderHeader[position()=1]/ns:orderNumber

     /ns:orderDetails/ns:orderHeader[position()=first()]/ns:orderNumber

        /ns:orderDetails/ns:orderHeader[first()]/ns:orderNumber

        /ns:orderDetails/ns:orderHeader[1]/ns:orderNumber

   Result: <ns:orderNumber>ORD1231</ns:orderNumber>    OR    ORD1231

2. To get last order unitPrice:

   Possibel expressions:

/ns:orderDetails/ns:orderHeader[position()=last()]/ol:orderLine/ol:unitPrice

/ns:orderDetails/ns:orderHeader[last()]/ol:orderLine/ol:unitPrice

/ns:orderDetails/ns:orderHeader/ol:orderLine[../last()]/ol:unitPrice

   Result: <ol:unitPrice>12452</ol:unitPrice>   OR  12452

3. To get orderNumber whoes orderId is 1232:

Expression: /ns:orderDetails/ns:orderHeader[ns:orderId=1232]/ns:orderNumber

Result: <ns:orderNumber>ORD1232</ns:orderNumber>    OR ORD1232

4. To get orderId where item is MONITOR:

/ns:orderDetails/ns:orderHeader[ol:orderLine/ol:item="MONITOR"]/ns:orderId

result : <ns:orderId>1233</ns:orderId>  OR  1233

5. To get unitPrice of orderNumber ORD1232

Expression:

/ns:orderDetails/ns:orderHeader[ns:orderNumber="ORD1232"]/ol:orderLine/ol:unitPrice

/ns:orderDetails/ns:orderHeader/ol:orderLine[../orderNumber="ORD1232"]/ol:unitPrice

Result: 312

6. To find number of orderHeaders in xml.

Expression: count(/ns:orderDetails/ns:orderHeader)

Result: 3

7. To get orderNumber where lineIdentifier is 1232_12

Expression: /ns:orderDetails/ns:orderHeader[ol:orderLine/@lineIdentifier=1232_12]/ns:orderNumber

Result: <ns:orderNumber>ORD1232</ns:orderNumber>   OR    ORD1232

8. To get orderNumber based on runtime position value.

Expression:

   /ns:orderDetails/ns:orderHeader[position()=$indexVar]/ns:orderNumber

        /ns:orderDetails/ns:orderHeader[$indexVar]/ns:orderNumber

        Heare indexVar is index variable.

Result: orderNumber of order at index indexVar

Above discussed expression cover most of the Oracle SOA project requirements. There are additional conditional expressions where you can use logical operators and functions.

Understanding XML namespaces

In an XML element names are user defined and there could arise conflicts. One possible scenario is, consider a WSDL in which a message consists of parts referencing elements, with the same name but from different XSDs. For example, consider below code that is snipped from a WSDL (though not valid due to no namespace references). Here the requestMessage has two parts one refers to ID from employee schema imported from EmpRequest.xsd and another part refers to an ID from salary schema imported from SalRequest.xsd. But there is no logical relation between elements in the part and the referenced schema document.

These name conflicts in XML can be avoided by implementing namespaces. Each XSD can be assigned a targetNamespace and the referencing part use ID elements by using xmlns (called as namespace). Here targetNamespace is a logical name of the XML document. This targetNamespace is used as xmlns in the referencing document. This way the child XML can import multiple parent documents and reference their elements by using parent’s targetNamespace as xmlns in child document.

In XML family language there are three types of namespaces – targetNamespace, xmlns (read as namespace) and default namespace.

• targetNamespace: targetNamespace as a logical name of a document similar to class name in java class and is defined by the developer. Usually targetNamespace would be an attribute within the root element of the XML document. The value provided for namespace is called URI (Unique Resource Identifier) and is always defined by the developer. In below figure, an XSD in its root schema element has targetNamespace attribute. 

•       xmlns (read as namespace): xmlns can be thought of as an instance of targetNamespace. One XML document can refer multiple targetNamespaces by creating corresponding xmlns. In the world of webservices, XML documents contain elements that most of the times refer other elements from a parent document. Technically xmlns is used as an attribute in every node to identify element’s targetNamespace. But to avoid using a long string value for xmlns, you can use qualifiers. Qualifier is a user defined keyword that holds the value of xmlns. In figure3, line5 to line8 defines xmlns for different target Namespaces. In each of these lines targetNamespace is referenced by using xmlns and qualifier delimited by “:”. For example, at line6 EmpRequest.xsd document is referenced with xmlns:empReqNS. Here empReqNS is called a qualifier. Every element, attribute and pre-defined keyword is prefixed with qualifier. In the figure below the root element, definition, is a keyword defined in xml document with targetNamespace http://schmas.xmlsoap.org/wsdl. Therefore, definition element is prefixed with “wsdl:”, and qualifier wsdl is defined in the same root node with value http://schmas.xmlsoap.org/wsdl. There are many elements in this document refer to targetNamespace http://schmas.xmlsoap.org/wsdl, and this targetNamespace defines most of the keywords used in a WSDL document. Another frequently used targetNamespace is http://www.w3.org/2001/XMLSchema. Almost all keywords used in types block of the WSDL refer elements from this targetNamespace, and this is owned by w3 schools. In an XML document, you can have element refer another element in the same document. For example, the input message used inside operation block refers to the message defined in message block.By connecting xmlns and targetNamespace parser validates each of the element present in the XML. Therefore, it is good practice to have elements always prefixed by its corresponding xmlns qualifier. Below figure 4 shows a sample input file that is used to invoke execute operation in the WSDL shown in figure 3.Root element has xmlns attribute pointing to the input schema XSD with targetNamespace http://www.clarityconsulting.com/trng/helloworld/xsd/Request. Please note that this not the targetNamespace of the XSD and not WSDL. Parser validates the input elements against the definition of types in XSD.

• default namespace: Elements in an XML can contain multiple xmlns, each identified by a unique qualifier and optionally one xmlns without a qualifier. The xmlns without a qualifier is called default namespace. The scope of the default namespace is the element and its children. If there are elements in an XML without a qualifier prefix, parser climbs up to its parents’, grandparents’ and great grandparents’ nodes till it finds a default namespace.

Notes:

1.     An XML document that has keywords defined by developers should have developer defined targetNamespace, so that the keywords in this document can be refered by its child documents.

2.     An XML document that has no developer defined keywords and have keywords referred from another document should have xmlns defined in the root element pointing to the targetNamespace referred.

Understanding WSDL

Understanding WSDL

WSDL (web service description language) is an XML family document describing how to interact with the web service described. Web services can be consumed by the code, generated using WSDL definition, that knows precisely how to interact with the web service. In a nutshell WSDL document contains details about data definition, operations, transport protocols and address of the web service.

WSDL document mainly consists of two sections – Abstract definitions and concrete descriptions. The abstract definition details about data definitions, messages and operations. Concrete section describes bindings or data format specification for operations, and the network address of the service host. A WSDL containing only abstract section is called an abstract WSDL and the one that contains bindings and network details as well is called a concrete WSDL. WSDL build during Oracle SOA development will be abstract in nature. The WSDL, obtained from the server, after deployment is concrete in nature.

Figure 1 WSDL Structure

Figure 1 WSDL Structure

Rest of this document discuss different sections of the WSDL in detail with code examples. During this walk through I have snipped code samples from WSDL provided by www.webservicex.com. To access the WSDL please click on below link. globalweather.asmx?wsdl

·       Abstract section

o   types: Types basically defines the data types used in the messages. A WSDL can have multiple types blocs, each of them can have multiple schema blocks (XSDs).

o   message: An abstract typed definition of the data that could be an input to or output from an operation. A WSDL can have multiple message blocks, each block containing one or more parts referring to elements defined in types block.

o   portType: portType defines an abstract set of operations. operation represents a method signature with parameters referring to the messages defined in message section. A WSDL can have multiple portType blocks, with multiple operations.

An operation block can have three types of parameters, input, output and fault. Every operation contains a mandatory input block, an optional output block, and multiple optional fault blocks followed by an existence of output block.

·       Concrete section

o   binding: binding implements portType. binding is a concrete protocol and data format specification for a particular portType. There could be more than one bindings for a given portType depending on the protocol and data format specification.  Below codes snippet shows that the same portType GlobalWeatherSoap (type = GlobalWeatherSoap in wsdl:binding element) has two different bindings one with soap protocol (targetNamespace = http://schemas.xmlsoap.org/wsdl/soap/) protocol and another with soap12 (targetNamespace = http://schemas.xmlsoap.org/wsdl/soap12/) protocol.

o   service: service is a collection of endpoints or ports. port is an end point, which is a combination of binding and a network address.

While invoking a webservice, the input XML data sent by the client is passed and validated against XSD (defined in types block) used for input message parameters in operation. The output XML data generated by the webservice is again parsed and validated against corresponding XSD defined in types block of the WSDL. In all the above XML code snippets each node has a tag that contains prefix, colon and element name. Here the prefix is called namespace qualifier. This qualifier plays a very important role in validating XMLs agains XSDs, and cross referencing the XML documents. We will understand more details about XML namespaces in the next post.

Understanding XML & XSD in SOAP webservice context

In the world of integration applications, we have been hearing about webservices mainly of types REST and SOAP. In general, a SOAP webservice publishes its definition file with WSDL (Webservice definition language) extension that belongs to XML (Extensible Markup Language) family. A typical webservice definition file contains details about services/operations, input & output definitions of these operations along with the network addresses. The input and output definitions are part of the WSDL and belong to XML family. As they are of family XML and defines a specific format, these files, if stored separately, uses XSD (XML schema definition) extension. In this post we will discuss basics of XML and XSD that are needed to work with webservices.

To consume a service defined in a webservice, users should have its definition WSDL file. While consuming the service, the input file has to follow the format defined by XSD inside the WSDL. Therefore, input XML, XSD and WSDL belong to XML family and the dependency moves in the direction of WSDL to XSD to XML. We will discuss about WSDL in detail in the next post. Any XML document should be well-formed in the sense every node should be closed properly. The nodes could be of type simple or complex. Complex node is a combination of a set of either simple or simple and complex nodes.

Figure 1 Simple element example from XSD file

Figure 2  Simple element example from input XML file

Figure 3  Complex element example from XSD file

Figure 4  Complex element example from input XML file

Usually in context of webservices input or output XMLs are well-formed and should be valid against the XSD definition. XMLs are created as per the definition provided by XSD file, that contains definition of simple and complex elements, their attributes and restrictions. To understand the relation between an XML and XSD consider a webservice that accepts as shown in below figure.

Figure 5 Relating XML and XSD elements

In this example inside XSD content the first node contains process instructions. Employee Information (EMPLOYEE_INFO) is a complex element of child elements - EMPLOYEE_ID, EMAIL_ADDRESS and MAIL_ADDRESS as input. Here MAIL_ADDRESS is another complex element containing further child elements. Each of these tags have proper logical closure, and therefore this XSD is well-formed. If you observer the element with name attribute equal to EMPLOYEE_ID, this element defines the data type to be an integer forcing the input XML defined over this XSD should have an integer value for element EMPLOYEE_ID.

Here the input XML on the right side of above figure is created based on the definition of XSD. As you can observe it is a well-formed document. In addition, this input XML document contains simple and complex elements with appropriate data types as forced by the XSD document. Therefore, this is a valid XML against the XSD document. We will discuss about WSDL in details in our next post.

OAF (Oracle Applications Framework) Introduction

Oracle uses Oracle Applications Framework, aka OAF, to build web based pages in Oracle EBS applications. OAF is XML and JAVA based framework. End users or consultants can customize Oracle EBS applications using OAF technology. Following are the types of customizations that end users can do using OAF.

• Controller Extension
• BC4J Substitution
• VO Substitution
• AM Substitution
• Enhancements to existing applications like building new pages.

OAF is built based on the MVC architecture. MVC stands for model, view and controller and this MVC architecture has been widely spread across industry.


Below is a layered architecture followed by OAF framework which is based on the MVC architecture.

In OAF, code components are majorly classified into view components, BC4J components and controller components. Each database table record that is part of the application is represented by an EO (Entity Object). A list of database table records that are represented by EOs are collected into VO (View Object). AM (Application Module) behaves as a content container within the model layer that holds all the VOs pertaining to a transaction. CO (Controller Object) responds to user actions and talks to AM to fetch data or perform transactions. In OAF UI (User Interface) components are built in XML technology. Below is a simplified representation of OAF, aka Onion structure. This picture is borrowed from Oracle Crop.

Frequently Asked Questions (FAQs) in OAF

Page customizations in OAF

·     How to print the page definition/find file version of page or region?

set serveroutput on;

exec jdr_utils.listCustomizations('/oracle/apps/per/wpm/objectives/webui/ObjectivesSubTabsRN’);

·    How to list customizations in a page?

set serveroutput on;

exec jdr_utils.listCustomizations('/oracle/apps/per/wpm/objectives/webui/ObjectivesSubTabsRN');

·    How to migrate customizations across instances. – Using JDR_UTILS package

Printing customizations on the page or region using below command.

exec jdr_utils.listCustomizations('<document name with full path>');

eg: exec jdr_utils.printDocument('/oracle/apps/per/selfService/review/webui/ReviewRN');

This returns a list of file names that contain the customizations.

Now print any of the document from above results using the command

exec jdr_utils.printDocument('<document name with full path>');

Delete customizations:

Instead of removing the customizations from application, we can directly delete the OAF customization using the following

exec jdr_utils.deleteDocument('<customization document path along with file name>');

Once this is done bounce oacore usnig the following commands to see the results.

adoacorectl.sh stop

adoacorectl.sh start

·    How to upload a PG or an RN to an instance?

   java oracle.jrad.tools.xml.importer.XMLImporter /abc/xyz/pqr/oracle/apps/.../webui/AbcXyzPG.xml -rootdir /abc/xyz/pqr/ -username apps -password $APPSPWD -dbconnection "(description=(address_list=(address=(community=tcp.world)(protocol=tcp)(host=$HOST)(port=$PORT)))(connect_data=(sid=$SID)))"
   
   In the above $APPSPWD $HOST, $PORT and $SID need to be supplied.

File versions in OAF application

·    How to find the java file version on the instance UI?

Login to the instance and Navigate to the page where the java file is used.

On this page replace the url with a new url appended with jsp/fnd/fndversion.jsp

For example:

If the url is http://abccorp.com:8000/OA_HTML/RF.jsp?function_id=30255...

Replace this url with http://abccorp.com:8000/OA_HTML/jsp/fnd/fndversion.jsp

This lists all the java files with the file versions.

·    How to find the java file version from server?Login to the unix box and execute the following command.

Ident <Complete file path>

Example: ident $JAVA_TOP/oracle/apps/per/selfservice/review/webui/ReviewCO.class

·     How to find the file version of a package file?

select *  

  from all_source where name='HR_PERF_MGMT_PLAN_INTERNAL' 

   and type='PACKAGE BODY' and text like '%$Header: pepmpbsi.pkb%';

·    How to redirect Trace Output to DBMS_OUT?

hr_utility.trace_on;

hr_utility.set_trace_options('TRACE_DEST:DBMS_OUTPUT');

Custom objects in DB

·    How to find the custom user Hooks?

SELECT module_name

     , module_package

     , c.*

  FROM hr_api_modules m

     , hr_api_hooks h

     , hr_api_hook_calls c

 WHERE (   m.module_name IN ('PER_APPRAISALS','PER_OBJECTIVES','PER_ASSESSMENTS')

        OR m.module_package IN ('HR_APPRAISALS_API','HR_OBJECTIVES_API','HR_ASSESSMENTS_API')

       )

   AND h.api_module_id = m.api_module_id

   AND h.api_hook_id = c.api_hook_id;

·    How to find if the customer is having any triggers on a Table?

SELECT * 

  FROM all_triggers

 WHERE table_name = 'PER_APPRAISALS';

XDK Version in Database

·    How to Identify the Version of XDK for Java Installed Inside the Database ?

 Create following function after logging in through SQL*Plus as any user:

CREATE OR REPLACE FUNCTION XMLVersion 

  RETURN VARCHAR2 

IS 

  LANGUAGE JAVA 

      NAME 'oracle.xml.parser.v2.XMLParser.getReleaseVersion() returns java.lang.String';

  - Run the query to display the version of XDK for Java

  SELECT xmlversion 

    FROM dual;

·    How to add debug/diagnostic statements?

·          Adding diagnostics in Application Module code: 

  OADBTransaction txn = getOADBTransaction();

  String str = "--------START ORACEL TRACE---------";

  if(tx.isLoggingEnabled(2))

    getOADBTransaction().writeDiagnostics(this, str, 2);

·          Adding diagnostics in Controller code: 

  String str = "--------START ORACLE TRACE--------";

  if(pageContext.isLoggingEnabled(2))

            pageContext.writeDiagnostics(this, str, 2);

DBA Concepts for OAF Application

·    How to add a zip to class path of a 11i Instance?

1.  Login to code tree with user who is the owner of the code tree. 

2.  Let instance name be INST 

Move to the directory INSTora/iAS/Apache/Jserv/etc/ 

3.  There will be file jserv.properties in the directory.  

4.  Find classpath entries in the file with lines as follows 

wrapper.classpath=....... 

5.  Prepend a new line with the zip file location.

For example wrapper.classpath=/tmp/test.zip;... 

·    How to add a zip to class path of a R12 Instance?

Add <library path="Your class path" /> as the first entry in the file present at location $INST_TOP/ora/10.1.3/j2ee/oacore/application-deployments/oacore/orion-application.xml

    Bounce apache for the changes to reflect.

·    How to bounce services?

 Let instance name be INST 

Go to directory INSTcomn/admin/scripts/INST/

     OR

Go to the directory $ADMIN_SCRIPTS_HOME

Apache 

   Stop  - adapcctl.sh stop

   Start – adapcctl.sh start

OPMN

   Stop  - adopmnctl.sh stop

   Start – adopmnctl.sh start

Clear OACore

   Stop  - adoacorectl.sh stop

   Start – adoacorectl.sh start

Listener

   Stop  - adalnctl.sh stop

   Start – adalnctl.sh start

Forms

   Stop  - adformsctl.sh stop

   Start – adformsctl.sh start

All Services

   Stop  - adstpall.sh

   Start – adstrtal.sh

   Running these scripts require apps login to the DB.

Note: In case if the variable ADMIN_SCRITPS_HOME is not set then check for something like $INST_TOP/admin/scripts/