| Oracle® Retail Integration Bus Integration Gateway Services Guide 14.0 E49473-01 |
|
 Previous |
 Next |
| Oracle® Retail Integration Bus Integration Gateway Services Guide 14.0 E49473-01 |
|
Previous |
Next |
This chapter discusses how to use the Oracle Retail SOA Enabler (RSE) and Artifact Generator (AG) tools to customize an Integration Gateway Services (IGS) service. Customizing an IGS service also means customizing the API for RIB and the subscribing application. While this guide focuses only on the IGS end of the process, all activities must be completed for a working flow.
For a successful customization, it is important to understand the tools and approaches described in each of the referenced documents. The process is complex and requires knowledge of tools as well as the end-point Oracle Retail application, RIB, and IGS products.
IGS customization requires a number of considerations and planning steps. Planning helps prevent reinstallation or reverting the RIB and IGS due to operational or performance problems.
The following helps to ensure a successful customization of the RIB and the IGS:
A functional RIB environment without customizations.
Familiarity with core RIB concepts, components, and architecture, including an understanding of all the following:
Oracle database triggers, RIB adapters, RIB Message envelope, RIB message payloads, and the functionality of GETNXT () and CONSUME () stored procedures.
The integration message flow paths.
The RIB life cycle.
The physical and logical requirements and limitations of the RIB components.
RIB operational considerations.
The tools used in the customization and extensions of the RIB are documented separately. The primary tools are the Oracle Retail Functional Artifact Generator and the Oracle Retail SOA Enabler.
This guide assumes that you have created the development environment for IGS, and that the RIB installation (rib-home) has working versions of the RSE and Artifact Generator tools.
|
Note: See the Oracle Retail Integration Bus Installation Guide, the Oracle Retail Integration Bus Operations Guide, the Oracle Retail Service-Oriented Architecture Enabler Tool Guide, and the Oracle Retail Functional Artifact Generator Guide for installation and configuration instructions. |
The RSE and AG are companion tools, particularly in the creation and customization of Web service providers. Generally available documents exist for each tool to describe installation, configuration, and use; they include extensive examples. These documents, combined with the Oracle Retail Integration Bus Implementation Guide, cover the recommended practices and provide examples for customizing business objects. With each release, Quality Assurance testing is completed on the tools and associated documentation, including each example cited.
The RSE and AG tools work only with Oracle Retail Business Objects, release 13.1.x (and higher). They do not work with objects from earlier releases (for example, 13.0.x and 12.x). This restriction is due to the uptake of Business Object standards that support versioning, and customization and extension.
The tools enforce this separation and will not permit anything except the best practices documented in the Oracle Retail Artifact Standards. This rule helps to preserve changes when a new release is issued. When applying business object upgrades, customers can easily preserve changes by simply applying them over the new base objects.
The AG is designed to allow customers to create extensions to base objects using the specified hooks, or to create entirely custom objects that meet Oracle Retail standards. The tools enforce these standards.
For the creation of a Web service provider, the RSE tool expects as one of its inputs one of the outputs of the AG tool to design time artifacts. There is a runtime relationship as well, as shown in the diagrams below, which illustrates the relationships for a Java EE and PL/SQL Web Service Provider.
|
Note: RSE supports Java EE and PL/SQL. This document uses RSE only for the Java side. The Artifact Generator creates all artifacts for both PL/SQL and Java EE. |
The inputs to the AG are the base GA business objects, and the custom or extended base objects. The GA base objects are installed as part of the AG installation and configuration. The creation of extensions or custom XSDs are covered in the Oracle Retail Functional Artifact Generator Guide, including:
Base XSDs and Extof XSDs
Custom XSDs
The following are AG outputs:
custom-retail-public-payload-java-beans.jar
custom-retail-public-payload-database-object-types.zip
The input for creating a service provider is a Service Definition Library XML file containing details about the Web services that must be created, the generally available business objects, and the output of the AG for extensions or custom XSDs.
For example:
The RSE tool references JAXB created java beans based on the BO source schema XSDs. These beans are contained in the retail-public-payload-java-beans.jar.
The RSE tool uses Oracle Retail BOs from retail-public-payload-java-beans.jar and custom BOs from custom-retail-public-payload-java-beans.jar.
The retail-public-payload-java-beans.jar file is created using the Retail Artifact Generator from the source BO XSDs. The retail-public-payload-java-beans.jar file is packaged in RSE. It does not need to be updated as part of the customization process.
The retail-public-payload-java-beans.jar file also contains the source XSDs themselves, which will be used, along with the XSDs in the optional custom-retail-public-payload-java-beans.jar, by the deployed service to validate all requests and responses against.
Outputs include the following:
The deployable .ear with the WSDL conforming to the objects referenced in the ServiceProviderDefLibrary.xml.
The PL/SQL or Java EE API templates that include hooks for talking to the services. These API templates contain placeholders for business logic and references to the Business Objects created by the AG.
A copy of the ServiceProviderDefLibrary.xml.
A static version of the service WSDL.
The decorator services.
The most common use case in customization is to add new elements to existing messages. This section covers that use case. The Oracle Retail Integration Bus Implementation Guide covers the same use case with examples for the Oracle Retail Integration Bus (RIB).
The Oracle Retail Service-Oriented Architecture Enabler Tool Guide and the Oracle Retail Functional Artifact Generator Guide contain detailed examples that are not repeated here. However, they are referred to as needed in the solution approach sections. The IGS product is constructed using the AG and RSE tools, so customization of IGS is a straightforward extension of that process.
The business has determined that the IGS ASNIn Service must include a new element, Fiscal ID. The Oracle Retail deployment has Oracle Retail RMS as the end-point (Subscriber) and a third party system as the source (Publisher).
The business objects for the IGS Web services are packaged and shipped (as generally available) with the Oracle Retail base objects in RetailFuncArtifact14.0.xForAll14.0.xApps_eng_ga.tar.
The following set of steps assumes installation and configuration of the AG and the RSE in the RIB installed rib-home/tools locations and that the file locations are relative to that installation. For alternative installations and locations, see the Oracle Retail Artifact Generator Guide and make adjustments as needed to these steps.
Using the Artifact Generator tool, extend the XSDs and generate the custom database objects and the custom-beans. Because this is a base object, it will have been installed with the AG tool.
|
Note: See "Addition of Optional Elements" in Chapter 3 of the Oracle Retail Artifact Generator Guide. |
Locate the correct ExtOfASNInDesc.xsd file.
find input-xsd -name ExtOfASNInDesc.xsd
Edit the ExtOfASNInDesc.xsd file to add the following:
<xs:element name="ExtOfASNInDesc">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="fiscal_id" type="varchar23">
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name="varchar23">
<xs:restriction base="xs:string">
<xs:maxLength value="5"/>
</xs:restriction>
</xs:simpleType>
Create the Java Payload and OO.
Type groovy ./com/oracle/retail/integration/artifact/generator/GenArtifacts.groovy
For the IGS effort, the focus is on using the custom-retail-public-payload-java-beans.jar in the IGS application.
|
Note: The custom RIB objects are used in the application and RIB. See the Oracle Retail Integration Bus Implementation Guide for more information on customization of RIB. Both RIB and IGS must be customized with the same custom-retail-public-payload-java-beans.jar file for a working message flow. |
Take the following steps to prepare the RSE tool:
Merge the IGS GA business objects with the new AG generated custom business objects and regenerate the IGS ear file.
Create a customization location and sub-folders (for example, /workarea/igs-customization).
Create /workarea/igs-customization/jar_update_area
Create /workarea/igs-customization/input_file
Create /workarea/igs-customization/output_file
Extract the needed files from the igs-service.ear file.
jar xvf igs-service.ear
Copy lib/ igs-services-impl.jar to /workarea/igs-customization/input_file.
Copy payload-lib/custom-igs-bo.jar to /workarea/igs-customization/input_file folder.
Extract the needed files from the igs-service-ejb.jar file.
jar xvf igs-service-ejb.jar
Copy META-INF/com.oracle.retail.soa.enabler.ServiceDef.xml to /workarea/igs-customization/input_file.
Copy custom-retail-public-payload-java-beans.jar generated by the Functional Artifact Generator, to /workarea/igs-customization/jar_update_area.
Change directory to /workarea/igs-customization/jar_update_area.
Extract the contents of custom-igs-bo.jar.
jar -xf ../input_file/custom-igs-bo.jar
Update the custom-retail-public-payload-java-beans.jar file with the contents of custom-igs-bo.jar.
jar -ufM custom-retail-public-payload-java-beans.jar co* ME*
Merge the IGS GA business objects with the new AG generated custom business objects and regenerate the IGS ear file.
Go to RSE Service Provider tab and choose the following options:
Web Service Type = SOAP
Service Provider Type = JavaEE
Service def library XML = /workarea/igs-customization/input_file/com.oracle.retail.soa.enabler.ServiceDef.xml
Custom BO jar =/workarea/igs-customization/jar_update_area/custom-retail-public-payload-java-beans.jar
Service impl jar = /workarea /igs-customization/input_file/igs-services-impl.jar
Do not provide a value for localization BO jar.
Click Generate.
Save the output igs_JavaEEServiceProvider.zip to
/workarea /igs-customization/output_file/
Extract igs_JavaEEServiceProvider.zip in current directory (output_file).
Go to output_file directory
unzip igs_JavaEEServiceProvider.zip -d igs_JavaEEServiceProvider
Take the following steps to deploy the igs-service.ear from rib-home:
Copy /workarea/igs-customization/output_file/igs_JavaEEServiceProvider/igs-service.ear to the rib-home/tools-home/integration-bus-gateway-services/ear folder.
Change directory to rib-home/tools-home/integration-bus-gateway-services/bin.
Run igs installer:igs-install.sh.
|
Note: Make sure the WebLogic Server is up and running before attempting to install igs-service.ear. |
The following steps are covered in detail in other RIB documentation.
|
Note: The use of Hermes JMS is covered in the My Oracle Support document, How to Connect Hermes JMS to Oracle AQ (ID 837999.1). |
Take the following steps to test the customized IGS:
Examine the new customized ASNIn WSDL.
Start HermesJMS and browse AQ JMS topic etASNIn.
Use SOAP user interface to publish a customized ASNInDesc message.
View the customized message in AQ using Hermes.
This section discusses the procedure to add an entirely new Web service to the IGS. This guide assumes that the family for which a new Web service is to be created is already available in the RIB systems, and edge applications can subscribe the messages from those family topics.
Consider the scenario, business decided to add a new service for the family "CoReturn"to IGS, which is not currently available.
Take the following steps to prepare the RSE tool:
Create a customization location and sub-folders (for example, /workarea/igs-customization).
Create /workarea/igs-customization/input_file.
Extract the needed files from the igs-service.ear file. This file is located in the "ear" folder of the IGS archive.
jar xvf igs-service.ear
Copy lib/ igs-services-impl.jar to /workarea/igs-customization/input_file.
Copy payload-lib/custom-igs-bo.jar to /workarea/igs-customization/input_file.
Edit the serviceDef file to add new service for the family "CoReturn".
jar xvf igs-service-ejb.jar
Copy META-INF/com.oracle.retail.soa.enabler.ServiceDef.xml to /workarea/igs-customization/input_file.
Edit the copied ServiceDef.xml file to add new service. In this use case for the family "CoReturn" following service definition to be added.
<service name="CoReturnPublishing">
<documentation>An external system will publish CoSale onto the RIB system. RMS will subscribe to CoReturn information and updates the database tables depending upon the validity of the records enclosed within the message.
Topic Name : etCOReturn
Subcribers : COReturn_sub (RMS).
</documentation>
<operation name="publishCustRetSaleCreateUsing">
<documentation> This Operation invokes the publishing of "Create" event for the CoSale.</documentation>
<input type="CustRetSaleDesc">
<documentation>
CustRetSaleDesc RBO complies with the XML schema CustRetSaleDesc.xsd, for more information on RBO structure and semantics please refer to the associated XSD.
</documentation>
<header headerName="businessObjecId" type="com.oracle.retail.integration.bus.gateway.services.businessobjectid.v1.BusinessObjectId" headerRequired="false"/>
</input>
<output type="ServiceOpStatus" custom="true">
<documentation>
ServiceOpStatus object represents the acknowledgment from the service. It encloses the information about the Successful or Failed stataus of the publish event.
</documentation>
</output>
<fault faultType="PublishingWSFaultException">
<documentation>Throw this exception when a "soap:Server" side publish problem occurs.</documentation>
</fault>
<fault faultType="IllegalStateWSFaultException" >
<documentation>Throw this exception when an unknown "soap:Server" side problem occurs.</documentation>
</fault>
</operation>
</service>
Extract the ServiceConfig.properties file from igs-services-impl.jar
jar -xvf igs-services-impl.jar ServiceConfig.properties
Edit ServiceConfig.properties file located in igs-services-impl.jar to add jms topic for the new service to publish messages. The topic name corresponding to a family can be found at rib-integration-flows.xml file. This xml is available with rib functional artifact deployment. The link could be as, http://host:port/rib-func-artifact/integration/rib-integration-flows.xml. In the case of the COReturn service, the topic is etCOReturn.
Update the igs-services-impl.jar with updated ServiceConfig.properties.
jar -ufM igs-services-impl.jar ServiceConfig.properties.
Generate javaEEServiceProvider archives using updated serviceDef file. Go to deployed RSE tool. Select RSE Service Provider tab and choose the following options:
Web Service Type = SOAP
Service Provider Type = JavaEE.
Service def library XML =
/workarea/igs-customization/input_file/com.oracle.retail.soa.enabler.ServiceDef.xml
Custom BO jar =
/workarea/igs-customization/input_file/custom-igs-bo.jar
Service impl jar =
/workarea /igs-customization/input_file/igs-services-impl.jar
Do not provide a value for localization BO jar.
Click Generate.
Save the output igs_JavaEEServiceProvider.zip to
/workarea /igs-customization/output_file/
Extract igs_JavaEEServiceProvider.zip in current directory (output_file).
Go to output_file directory.
unzip igs_JavaEEServiceProvider.zip -d igs_JavaEEServiceProvider
Take the following steps to deploy igs-service.ear from rib-home:
Copy /workarea/igs-customization/output_file/igs_JavaEEServiceProvider/igs-service.ear to the rib-home/tools-home/integration-bus-gateway-services/ear folder.
Change directory to rib-home/tools-home/integration-bus-gateway-services/bin.
Run igs installer:igs-install.sh.
|
Note: Make sure WebLogic Server is up and running before attempting to install igs-service.ear. |
The following steps are covered in detail in other RIB documentation.
|
Note: The use of Hermes JMS is covered in the My Oracle Support document, How to Connect Hermes JMS to Oracle AQ (ID 837999.1). |
Take the following steps to test the customized IGS:
Examine the new COReturn WSDL.
Start HermesJMS and browse AQ JMS topic etCOReturn.
Use SOAP user interface to publish a COReturnDesc message.
View the message in AQ using Hermes.
|
 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|