Oracle OSB 12c – Java Callout and Routing Table example

In this article, we will explore the use of Java Callout & Routing Table nodes in OSB 12c

We will re-use the last article and modify business case requirements and then accordingly implement the solution using “Java Callout” & “Routing Table” nodes

1. Java Callout :

  • Java callout action lets you access the methods in a Java archive (JAR) file to add processing logic to your pipelines and split-joins

2. Key points of Java Callout node :

  • POJOs are registered as JARs with Service Bus project, then we can invoke these methods using Java Callout
  • So, Java classes needs to be packaged as JARs and stored for use in the Service Bus project
  • Sometime we may have legacy application coded in core Java or EJB which can be used & invoked using Java Callout
  • Invoking methods from Java Callout in Service Bus projects should be “public” and “static
  • When you configure the callout, you can specify arguments for the method
  • And you can optionally specify a service account for security purposes
  • The parameters can be mapped to message context variables
  • Data Types supported listed below

2.1 Data Types supported for Input Arguments :

  • boolean, byte, char, double, float, int, long, short and its arrays type
  • Objects of above mentioned java primitive types and String and its arrays type i.e.;
    a. java.lang.Boolean
    b. java.lang.Byte
    c. java.lang.Character
    d. java.lang.Double
    e. java.lang.Float
    f. java.lang.Integer
    g. java.lang.Long
    h. java.lang.Short
    i. java.lang.String
  • java.lang.BigInteger & java.lang.BigDecimal and its arrays type
  • org.apache.xmlbeans.XmlObject and its arrays type

2.2 Data Types supported for Output or Return parameter :

  • all data types mentioned for Input Arguments are valid except their arrays type
  • void

2.3 Best Practices for Java Callout & POJOs :

  • In general, Oracle recommends that the JARs are small and simple
  • Any large bodies of code that a JAR invokes or large frameworks that are used are best included in the system classpath
  • If you make a change to the system classpath, you must reboot the server
  • The JAR files are dynamically class loaded when they are first referenced
  • A single POJO can be invoked by one or more services
  • POJOs must be thread safe

3. Routing Table :

  • A routing table is a set of routes wrapped in a switch-style condition table. It is a short-hand construct that allows different routes to be selected based upon the results of a single XQuery expression

4. Business case requirement :

  • This is the same use case for Employee Loan process in an organization used in the last article with little modification
  • When an employee of the organization submit the request for a loan, it goes through various process to get it approved
  • Employee enters basic details like employee id, name, grade and loan amount requested in dollars and comments if any
  • Employee details are validated invoking a Java class “EmployeeValidationJavaCallout” (having one method validateEmployeeDetail) which will be packaged & stored as JAR in the Service Bus project
  • Outcome of this invocation is either Yes or No
  • And this employee validation outcome needs to be set in the request before routing to the business service (from there to invoke an actual enterprise web service)
  • This time, we are going to route the service based on the loan amount (in dollars) at the Routing Table level (unlike conditional branch node in one of the previous article)
  • If entered loan amount in dollars is less than or equal to 4 thousands ($4K), then it goes through the default loan approval process
  • Otherwise, if entered loan amount in dollars is greater than 4 thousands ($4K), then it goes to HR Manager for approval
00_OSB-12c_Java_Callout_and_Routing_Table_example_Problem_statement_in_figure

5. Assumptions :

  • There are two web services for Employee Loan Process up & running on the application server
  • This web services can be invoked only through OSB
  • Two web services are
    1. Default Loan approval service
    2. HR Manager Loan approval service
  • And there will be Java Class which will be packaged & stored as JAR in the Service Bus project (under jars folder –> Resources –> main project)
  • For demo purpose, we will copy the WSDL and Schema files and paste in our Service Bus project under “Resources” folder
    This web service roughly based on this article, go through this article to understand the underlying web services part
  • Download this web service & JAR project used in this demo example from download section (scroll to last)

Let’s get started with designing OSB modules for Java Callout & Routing Table example in Oracle JDeveloper 12c IDE

6. Java Callout and Routing Table example :

Step 1: Open New Project

File Menu –> New –> Project

1_OSB-12c_Java_Callout_and_Routing_Table_example_New_Project

Step 2: Select Service Bus Tier from available categories

Service Bus Tier –> Service Bus Project –> OK

This opens up wizard for New Service Bus Project

2_OSB-12c_Java_Callout_and_Routing_Table_example_New_Service_Bus_Project

Note: Comparing this wizard with the one we have created in this article, the major difference is “Service Bus Project” option is enabled since we have one Service Bus Application in the user/developer workspace (already created)

Step 3: Enter Project Name and its directory location for the new Service Bus Project

Leave the default values for demo; otherwise we can give more specific names in accordance with naming convention followed in the project

Project Name: JavaCalloutAndRoutingTable

Click Finish

3_OSB-12c_Java_Callout_and_Routing_Table_example_New_Service_Bus_Project_name

New Service Bus project will be created with required artifacts

Step 4: Create required folders in accordance with project standards (naming conventions)

Generally, there should be

  • ProxyService folder to place/store/save the proxy services which ends with .proxy
  • BusinessService folder to place/store/save the business services which ends with .bix
  • Resources folder to store all other required artifacts like WSDL, Schema and transformations files

Now, we will create above listed folders

Right click on the Service Bus project –> New –> Folder…

Opens up a new wizard

4_OSB-12c_Java_Callout_and_Routing_Table_example_create_folder_new

Note: If you don’t find “folder” option directly, then click on “From Gallery” and from there choose folder option and continue with below next steps

Create Folder wizard –> enter folder name like, for example “BusinessService” for Business Service

Finally click OK –> to create folder

5_OSB-12c_Java_Callout_and_Routing_Table_example_new_folder_name

Similarly, we can create “ProxyService” and “Resources” folders

After creating all three folders namely ProxyService, BusinessService and Resources, our project will look like below screenshot

Note:

  • create “entities” & “wsdl” folders under “Resources” to store/keep Schema and WSDL files (separately)
  • create “jars” folder under “Resources” to store/keep Java Archives (JAR file)
6_OSB-12c_Java_Callout_and_Routing_Table_example_after_all_folders_create_step

Step 5: Enterprise Information System (EIS) or Exposed Web Services

As we discussed in the assumption section, there are two web services up & running at below URLs in the application servers

  1. http://localhost:8080/EmployeeLoanService/services/DefaultLoanApprovalService?wsdl
  2. http://localhost:8080/EmployeeLoanService/services/HRManagerLoanApprovalService?wsdl

So we will copy Schema and WSDL files && paste it to the Resources folder as directed below

  • XML Schema –> under “entities” folder
  • WSDL –> under “wsdl” folder
7_OSB-12c_Java_Callout_and_Routing_Table_example_coping_entities_wsdl

Note: Make sure those two web services are running

6.1 Business Service :

Step 6: Create Business Service to invoke the exposed Web Service

There are two Business Services

  • Default Loan Approval Service
  • HR Manager Loan Approval Service

Drag and drop HTTP component from Technology palate to External Services lane (Business Service in 11g)

8_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_HTTP_component

Upon dropping, a new wizard pops up to enter the required details for Business Service or External Service

Step 6.a: Fill up the mandatory details for Business Service (i.e .bix file)

  • Service Name: DefaultLoanApprovalServiceBS (append BS to the business service as a naming standard)
  • Location: browse through “BusinessService” folder we created in earlier step
  • Transport: http (keep it as it is)

Click Next

9_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_6a

Step 6.b: Select “WSDL” from four available options

And browse to wsdl location by clicking first icon with green arrow mark pointing towards right hand side (i.e.; wsdl is placed under “Resources/wsdl” folder)

Choose “Application” and select correct WSDL we have stored for this project

Finally click OK and then click Next

10_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_6b

Step 6.c: In step 2 of Create Business Service wizard –> populates wsdl file with port after reading the WSDL file we have chosen in the previous step

Click Next

11_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_6c

Step 6.d: In step 3 of Create Business Service wizard –> populates the endpoint URI for the exposed web service to be invoked

Click Finish

12_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_6d

Similarly, we will create business service for second service i.e.; HR Manager Loan Approval Service

Step 7.a: Fill up the mandatory details for Business Service (i.e .bix file)

  • Service Name: HRManagerLoanApprovalServiceBS (append BS to the business service as a naming standard)
  • Location: browse through “BusinessService” folder we created in earlier step
  • Transport: http (keep it as it is)

Click Next

13_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_7a

Step 7.b: Select “WSDL” from four available options

And browse to wsdl location by clicking first icon with green arrow mark pointing towards right hand side (i.e.; wsdl is placed under “Resources/wsdl” folder)

Choose “Application” and select correct WSDL we have stored for this project

Finally click OK and then click Next

14_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_7b

Step 7.c: In step 2 of Create Business Service wizard –> populates wsdl file with port after reading the WSDL file we have chosen in the previous step

Click Next

15_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_7c

Step 7.d: In step 3 of Create Business Service wizard –> populates the endpoint URI for the exposed web service to be invoked

Click Finish

16_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Business_Service_wizard_7d

Finally two Business Services for Default Loan approval & HR Manager Loan approval services are created

Business Service is created on the External Services lane and this resides under “BusinessService” folder

17_OSB-12c_Java_Callout_and_Routing_Table_example_2_Business_Services_created

6.2 Proxy Service :

Step 8: Create Proxy Service and add pipeline

Drag and drop HTTP component from Technology palate to Proxy Services

18_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_HTTP_component_to_Proxy

Upon dropping, a new wizard pops up to enter the required details for Proxy Service

Step 9.a: Fill up the mandatory details for Proxy Service (i.e .proxy file)

  • Service Name: EmployeeLoanProcessPS (append PS to the proxy service as a naming standard)
  • Location: browse through “ProxyService” folder we created in earlier step
  • Transport: http (keep it as it is)

Keep “Generate Pipeline” checked for creating pipeline along with Proxy Service

Click Next

19_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Proxy_Service_wizard_9a

Step 9.b: Select “WSDL” from four available options

And browse to wsdl location by clicking first icon with green arrow mark pointing towards right hand side (i.e.; wsdl is placed under “Resources/wsdl” folder)

Choose “Application” and select correct WSDL we have stored for this project

Finally click OK and then click Next

Note: WSDL file of EmployeeLoanApprovalService(PS) & other two loan approval service namely viz., DefaultLoanApprovalService(BS) and HRManagerLoanApprovalService(BS) are roughly similar and their request/response pattern are almost similar with one extra element for Business Service for Employee Validation (employeeDetailValidated)

20_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Proxy_Service_wizard_9b

Step 9.c: In step 2 of Create Proxy Service wizard –> populates wsdl file with port after reading the WSDL file we have chosen in the previous step

Click Next

21_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Proxy_Service_wizard_9c

Step 9.d: In step 3 of Create Proxy Service wizard –> populates endpoint URI

Click Finish

22_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Proxy_Service_wizard_9d

Finally Proxy Service is created

Proxy Service is created on the Proxy Services lane and this resides under “ProxyService” folder

23_OSB-12c_Java_Callout_and_Routing_Table_example_HTTP_Proxy_Service_created

Step 10: Create Java Project called “EmployeeValidationService” in Eclipse IDE

  • Java Project: EmployeeValidationService
  • Class: EmployeeValidationJavaCallout.java
  • Package: in.bench.resources.servicebus.javacallout.demo;
  • Method: validateEmployeeDetail(String, String, String)
  • Input arguments: employeeId, employeeName, employeeGrade
  • Output/Return value:  String (Yes/No)

EmployeeValidationJavaCallout.java

package in.bench.resources.servicebus.javacallout.demo;

public class EmployeeValidationJavaCallout {

	public static String validateEmployeeDetail(String employeeId, String employeeName, String employeeGrade){

		String employeeValidationResponse = null;

		// this dummy method, just check user entered the values or not
		if(null != employeeId && !employeeId.equalsIgnoreCase("") &&
				null != employeeName && !employeeName.equalsIgnoreCase("") &&
				null != employeeGrade && !employeeGrade.equalsIgnoreCase("")){

			employeeValidationResponse = "Yes";
		}
		else {

			employeeValidationResponse = "No";
		}

		// finally return response type, after setting the VALIDATED values (Yes/No)
		return employeeValidationResponse;
	}
}
24_OSB-12c_Java_Callout_and_Routing_Table_example_employee_validation_POJO

Finally import this Java Project from Eclipse IDE and place/store/keep into Service Bus Project (under main service bus project –> Resources –> jars folder)

6.3 To import the Java project from Eclipse IDE :

  1. Right click on the Eclipse Java project
  2. Choose the option Export
  3. Select JAR file option in the next step
  4. Select project to be exported
  5. And also provide destination JAR file location using browse option
  6. Next –> Next –> Finish

Step 11: Copy + Paste the JAR file into Service Bus project (under main service bus project –> Resources –> jars folder)

Note: Refresh complete Application or this particular project before proceeding with further steps

25_OSB-12c_Java_Callout_and_Routing_Table_example_export_JAR_file_from_eclipse_and_paste_in_SB_project

Step 12: Double-click on the EmployeeLoanProcessPSPipeline which opens up in a new editor with .pipeline extension (green-color round-cornered rectangle type figure in the Pipelines/Split Joins)

Opens up EmployeeLoanProcessPSPipeline.pipeline file in an editor

26_OSB-12c_Java_Callout_and_Routing_Table_example_Proxy_Service_pipeline_editor

Step 13: Java Callout node

As per our business case requirement stated in the first section of this article, we need to invoke employee validation service which stored under “Resources/jars” folder using “Java Callout” node to get to know whether employee details are validated or not

Outcome of Employee Validation Service is: Yes or No

And this value needs to be set in the request document/body before invoking the Business Service (using “Routing Table” node in this example)

Step 14: Drag and drop “Pipeline Pair” from “Message Flow” under the category “Nodes

Note: We can’t directly drag & drop “Java Callout” node to Proxy Service’s Message Flow. So, first drag & drop “Pipeline Pair” node and then drag & drop “Java Callout” node inside stage1 of Request Pipeline of the PipelinePairNode1

27_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Pipeline_Pair_node

Drag and drop “Java Callout” from “Message Flow” under the category “Message Processing

Note: Drag & drop “Java Callout” inside Stage1 of Request Pipeline of the PipelinePairNode1

28_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Java_Callout_node

Error: Red-ribbon type error mark on top-right corner is because, we haven’t set correct mandatory values for Java Callout node (after setting correct values & saving would vanishes all errors)

Step 14: Next step is to set mandatory values for Java Callout –> which will vanishes all errors after saving

First select the JAR file i.e.; in this example, EmployeeValidationService.jar

Finally click OK

29_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Java_Callout_select_JAR_file

Select a Java Method to be invoked –> then OK

30_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Java_Callout_select_java_method

Next step is to map the incoming request to the inputs arguments of the Java method selected above

31_OSB-12c_Java_Callout_and_Routing_Table_example_Java_Callout_click_fx_to_map_value_from_request_body

Select variable from request body –> Insert Into Expression –> then manually add “text()” at the end of expression selected

Finally click OK

32_OSB-12c_Java_Callout_and_Routing_Table_example_Java_Callout_map_values_using_expression_builder

Similarly, set/map values for other variables from request body (for employeeName & employeeGrade)

Set “Return” variable (message context variable)

  • Type: java.lang.String
  • Variable: employeeValidated
33_OSB-12c_Java_Callout_and_Routing_Table_example_Java_Callout_set_Return_variable

Step 15: Insert message context variable “employeeValidated” in the original request body (before invoking either of the Business Service)

Drag and drop “Insert” from “Message Flow” under the category “Message Processing

Insert Properties:

  • Value*: click “fx” and move to next step for setting the Expression
  • Position*: after
  • Location*: body
  • XPath: $body/loan:ProcessLoanRequestType/loan:amountInDollars

Note: Insert node should be placed after Java Callout node

34_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Insert_node

Click “fx” and set below Expression

Expression:

<loan:employeeDetailValidated>{$employeeValidated}</loan:employeeDetailValidated>

Finally click OK

35_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Insert_node_mandatory_expression

Step 16: Routing Table node

Routing Table: It is a set of routes wrapped in a switch-style condition table

Drag and drop “Routing Table” from “Message Flow” under the category “Route

  • Value*: $body/loan:ProcessLoanRequestType/loan:amountInDollars/text()

6.4 Advantage of OSB 12c over OSB 11g :

  • When we drag and drop the Routing or Routing Table node, it automatically have a Route node in place
  • Whereas in 11g, we need to drag and drop Route node first before Routing or Routing Table node
36_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Routing_Table_node

Error: Red-ribbon type error mark on each top-right corner is because, we haven’t choose/set any specific business service

Click fx which opens XQuery Expression Builder and set the below expression

Expression:

$body/loan:ProcessLoanRequestType/loan:amountInDollars/text()

Finally click OK

Note: manually need to add “/text()” at end of Expression selected

37_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Routing_Table_node_set_expression

Step 17:

Case 1: amount <= 4000

Click first case under Routing Table

Select “<=” operator from drop-down and set the value to “4000” using Expression Builder

38_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Routing_Table_node_set_case_1

Add business service to Routing node in the Routing Table

Click on Routing –> opens corresponding properties in the dialog box below

Click browse icon next to Service* –> opens “Resource Chooser” –> select service to be routed

Finally Click OK

39_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Routing_Table_node_set_Routing_for_case_1

Similarly, repeat the same steps for the second case (>4000)

Case 2: amount > 4000

Click second case under Routing Table

Select “>” operator from drop-down and set the value to “4000” using Expression Builder

40_OSB-12c_Java_Callout_and_Routing_Table_example_Routing_node_set_case_2

Add business service to Routing node in the Routing Table

Click on Routing –> opens corresponding properties in the dialog box below

Click browse icon next to Service* –> opens “Resource Chooser” –> select service to be routed

Finally Click OK

41_OSB-12c_Java_Callout_and_Routing_Table_example_drag_drop_Routing_Table_node_set_Routing_for_case_2

Similarly, repeat the same steps for the default case

In this example, actually we don’t need that but this needs to be set. So, repeat the same steps and select Default Loan Approval Service

Step 18: Time to test !!

Testing Service Bus project –> deploying into IntegratedWeblogicServer

42_OSB-12c_Java_Callout_and_Routing_Table_example_testing_Run

Step 19: Testing

This will open our traditional OSB console, where we can input and execute this sample mock service.

Enter necessary employee details requesting a loan amount of $. 3750

Note: Amount entered by the user is less than $ 4K, therefore OSB will route to default loan approval service

43_OSB-12c_Java_Callout_and_Routing_Table_example_testing_Run_Execute

Note: Make sure enterprise web service is up and running, otherwise error will be thrown

Request document and Response document

44_OSB-12c_Java_Callout_and_Routing_Table_example_testing_Run_Execute_case_1

Similarly, we can test for other case i.e.; entering loan amount of greater than $ 4K where OSB routes to HR Manager Approval service

45_OSB-12c_Java_Callout_and_Routing_Table_example_testing_Run_Execute_case_2

The same can be tested through Service console (OSB console) at http://localhost:7101/sbconsole (change the port number, if you have configured something else)

7. Download project :

EmployeeLoanService_JavaCallout_RoutingTable (7kB)

EmployeeValidation_JavaCallout_RoutingTable_JAR_file (2kB)

Related Articles :

References :

Happy Coding !!
Happy Learning !!

Oracle OSB 12c - File Polling/Reading and Writing using File Transport
Oracle OSB 12c - Service Callout and Routing Table example