| Oracle® Retail Service Backbone Developers Guide 15.0 E67904-01 |
|
 Previous |
 Next |
This chapter introduces RSB integration flows and describes how to setup development and test environments.
The underlying infrastructure for RSB is built using OSB (Oracle Service Bus). Any RSB programming activity invariably involves OSB programming. The tools provided by OSB are the same tools used for RSB programming.
The primary recommended development tool for RSB programming is JDeveloper.
There are two ways to make programmatic changes to web services hosted in OSB server: OSB console and JDeveloper. However, OSB console is an operational tool and is not recommended as a programming tool, even though OSB console provides the feature to make programmatic changes. The recommended approach is to use JDeveloper for any programming changes to OSB/RSB components and use OSB console for operational changes to the OSB components. Also, it is important to note that when OSB projects/jars are re-deployed in OSB server, any operational changes made to the earlier version deployed in the server will be lost and these operational settings will need to be configured again in the new deployed projects.
Use this JDeveloper for your OSB/RSB programming tasks.
JDeveloper does not need to be installed in the same machine where RSB builder tool is located. JDeveloper can be installed in a development environment, and the RSB jars can be copied to that machine. After making changes to the jars, they can be copied back to RSB builder and then deployed. The complete development lifecycle is explained later in this chapter.
RSB provides Decorator PAKs for Oracle Retail applications. There is one PAK for each Oracle Retail application. Each PAK contains a set of jar files which are OSB deployable jars and are also known as decorators in the RSB context. Decorators are generated using Retail SOA Enabler (RSE) tool. The RSE tool uses the service definition XML file as input for generating the decorators. RSE generates one decorator for each service defined in the service definition XML. The decorator jar contains OSB artifacts related to that service. Each decorator jar contains a proxy service and a business service which are related to the service for which the decorator jar is generated. For more information about RSB builder tool and how it is used to compile and deploy the decorators, see the Oracle Retail RSB Implementation Guide.
The list of all application service decorator PAKs in this release is provided in Appendix A.
RSB Functional Integration Flows are OSB integration services that are not decorators. Decorators have one proxy service and one business service related to the application service but service integration flows are not tied to a specific service. The purpose of service integration flows is to provide capabilities that range across multiple application services.
RsbServiceIntegrationFlowPak15.0.0ForRibOmsToRsbOmsRouting_eng_ga.zip is the only PAK available for this release. This PAK contains a proxy service which routes the data coming from RIB-OMS to various RSB decorator services.
RSB workbench is a development area for integration developers who want to modify the existing RSB decorator projects for various purposes such as adding new functionality or integration with third-party applications.
Workbench area should be in the same machine where JDeveloper has been installed. In this document we will refer to that location as RSB_WORK_AREA.
RSB has two types of OSB projects which can be customized: app service decorators and service integration flows. Therefore, it is recommended to have a directory for each type of project in RSB_WORK_AREA. The following is a screenshot of the recommended directory structure:
As shown above, the app-service-decorators folder has an application specific folder which contains the decorator jars for that application. Service integration flows are not application specific, therefore those types of jars can be directly within that folder.
When an OSB jar is imported in JDeveloper, it extracts the jar inside the JDeveloper workspace. The extracted folder will have all the OSB project related files that were packaged in the jar. You can create the workspace at any location in the machine. For this document purpose, we will create a workspace folder inside RSB_WORK_AREA. We will refer to that location as OSB_WORK_SPACE in this document.
To summarize, RSB_WORK_AREA is the location where jars are copied to and from the RSB builder location and OSB_WORK_AREA is the location where jars are imported as OSB projects and are worked upon.
When working on modifying RSB decorator jars or service integration flow jars, it should follow a certain lifecycle. This lifecycle should work in conjunction with RSB lifecycle. For details about all the lifecycle phases, see Oracle Retail RSB documentation.
For development lifecycle, the decorator jars or service integration flow jars must be copied from rsb-home/service-assembly-home folder.
Following are the steps that should be followed in the order mentioned below:
Copy the decorator jar or service integration flow jar that you want to modify from rsb-home/service-assembly-home to an appropriate location in RSB_WORK_AREA. The folder structure for RSB_WORK_AREA has been shown above in the screenshot.
Import the jar into JDeveloper where the JDeveloper workspace is OSB_WORK_SPACE. The steps for importing jar have been shown below.
JDeveloper will extract the jar and create an OSB project. The extracted jar will be saved in OSB_WORK_SPACE. The steps in the next section will show a screenshot of how the extracted jar looks like.
Make changes to the OSB project as needed.
Export the updated project as a jar to RSB_WORK_AREA. The name and location of the jar should be same as the jar that was imported.
Copy the updated jar to rsb-home/service-assembly-home at the same location from where it was copied.
Follow the RSB compilation and deployment process to deploy the modified jar in server.
|
Note: After copying modified jars into rsb-home/service-assembly-home, do not run the download-home/bin/check-version-and-unpack.sh script because that will overwrite the jars with the original jars from the PAKs. |
This section provides a step-by-step guide for how to import RSB decorator jar into JDeveloper workspace.
To create a new Service Bus Application, do the following:
Select File>New>Application>Service Bus Application.
Provide Application Name and click Finish to create a new Service Bus Application.
This creates an OSB Configuration Project, in which you can import RSB decorator or service integration flow jar files.
To import a decorator jar, select File>Import. The following screen is displayed: 
Select Service Bus Resources and click OK.
Select Configuration jar and click Next.
Specify the path to the jar file that you want to import and click Next. 
Click Finish to import decorator jar. 
The decorator jar will be imported into workspace, and the jar will be extracted inside the workspace. It will also show the project name in the Project Explorer window of JDeveloper. With this the workbench area is setup for the OSB project development. Any changes you make here will be saved in the workspace. After you finish making changes, you can export the project to a jar file.
|
Note: While making changes to OSB projects, it may be cumbersome to copy the jar to rsb-home/service-assembly-home every-time and go through compilation and deployment phases to test the changes. Instead, you can test the OSB project by deploying the jar in a development OSB server environment and test that all the changes are working fine. Once the changes are working as desired, the jar file can be copied to rsb-home/service-assembly-home for final deployment. |
After importing a decorator jar into workspace, the directory structure looks like following:
<appName>-<ServiceName>-AppServiceDecorator
BusinessService
<ServiceName>AppServiceBiz.biz
ProxyService
<ServiceName>AppServiceLocalProxy.proxy
<ServiceName>AppServiceProxy.proxy
WSDL
BusinessService
<ServiceName>Service.wsdl
ProxyService
<ServiceName>Service.wsdl
<appName>-<ServiceName>-AppServiceDecoratorAlert.alert
rsb-decorator-instrumentation-<version>.jar
setFaultInResponseBody.xq
An example screenshot when oms-CustomerOrder-AppServiceDecorator.jar is imported is shown below.
RSB Decorator projects include one business service by default. This business service is based on the WSDL which is available in WSDL BusinessService folder. By default, the WSDLs of Proxy and Business Services are similar. When customizing a decorator to work with an external service, the WSDL of that service should be copied in this folder. Following, is the naming convention for business service file: <ServiceName>AppServiceBiz
For example, in oms-CustomerOrder-AppServiceDecorator project, the name of business service will be CustomerOrderAppServiceBiz
RSB Decorator projects include two proxy services by default. They have naming convention as follows:
<ServiceName>AppServiceLocalProxy
<ServiceName>AppServiceProxy
<ServiceName>AppServiceProxy: This proxy service is based on HTTP transport protocol. Clients invoking the service from remote JVM should invoke this proxy service. This service takes request from the web service client and routes it to <ServiceName>AppServiceLocalProxy service. This proxy service does not have any business logic, its only purpose is to allow invocation from remote clients and it is recommended to be kept that way.
<ServiceName>AppServiceLocalProxy: This proxy service is based on local transport. All the message processing takes place in this proxy service.
Why two proxy services in decorator jar? Every decorator project has two proxy services packaged inside it. The reason for that is to provide the flexibility to call the service either from remote or from local JVM. It also provides the flexibility to configure the security as needed. When a proxy service needs to invoke another proxy service, it can directly invoke the local proxy service which will save the overhead of processing security headers of that message.
Every decorator project has two WSDL files packaged in it.
Proxy Service WSDL: This WSDL is available under WSDL>ProxyService folder. The proxy services packaged in a decorator jar are based on this WSDL. This WSDL should never be modified as consumers invoke the decorator services based on this WSDL, any change to this WSDL will break the service contract.
Business Service WSDL: This WSDL is available under WSDL>BusinessService folder.
Every decorator jar has an alert destination packaged in it. The filename of the destination follows the format:
<appName>-<ServiceName>-AppServiceDecoratorAlert.alert
This is the default alert destination which logs the alert as well as sends the alert to default reporting JMS provider. Any pipeline or SLA alerts configured in decorator will be sent to this destination.
Proxy Service client > Remote Proxy Service > Local Proxy Service > Business Service > Edge-app Application Service.
Once you have completed changes in a decorator project, you can export it back to the jar and deploy and test.
To export the decorator project to the jar do the following:
Select File > Export > Service Bus Resources and click OK. 
Select Configuration jar and click Next. 
Select resource, provide jar file location and click Finish. 
Click Yes. It will update the jar file with latest changes. The export process is complete.
