Oracle RIB Programmers Guide
Oracle RIB Programmers Guide
Oracle RIB Programmers Guide
December 2013
Oracle® Retail Service Layer Programmer's Guide, Release 14.0
This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as
expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or
display any part, in any form, or by any means. Reverse engineering, disassembly, or
decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be
error-free. If you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated
software, any programs installed on the hardware, and/or documentation, delivered to U.S.
Government end users are "commercial computer software" pursuant to the applicable Federal
Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication,
disclosure, modification, and adaptation of the programs, including any operating system,
integrated software, any programs installed on the hardware, and/or documentation, shall be
subject to license terms and license restrictions applicable to the programs. No other rights are
granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications,
including applications that may create a risk of personal injury. If you use this software or
hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe,
backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its
affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC
International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open
Group.
This software or hardware and documentation may provide access to or information on content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible
for and expressly disclaim all warranties of any kind with respect to third-party content, products,
and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or
damages incurred due to your access to or use of third-party content, products, or services.
Value-Added Reseller (VAR) Language
iii
Contents
Send Us Your Comments ............................................................................................... vii
Preface .............................................................................................................................. ix
Audience ................................................................................................................................ ix
Documentation Accessibility ............................................................................................... ix
Related Documents ............................................................................................................... ix
Customer Support ................................................................................................................. ix
Review Patch Documentation ............................................................................................. ix
Improved Process for Oracle Retail Documentation Corrections ....................................x
Oracle Retail Documentation on the Oracle Technology Network..................................x
Conventions .............................................................................................................................x
1 Introduction .................................................................................................................. 1
2 Technical Architecture ................................................................................................ 3
Architecture Layers ................................................................................................................3
Java EE Application Model ....................................................................................................4
Oracle PL/SQL-based Application Model ..........................................................................5
3 Basic Operations ......................................................................................................... 7
Simple Service Call .................................................................................................................7
Configuration of the Stateless Session Beans ...............................................................7
Success or Failure of the Service Call ............................................................................7
Clients Starting a Transaction ........................................................................................7
4 Service Provider How-To Guide ................................................................................. 9
Service Provider Application Configuration.......................................................................9
retek/services_rsl.xml .....................................................................................................9
retek/service_flavors.xml ...............................................................................................9
Service Provider Application Layer Code for J2EE Models ..............................................9
Service Provider Application Layer Code for Oracle PL/SQL-Based Models ............. 10
5 Client How-To Guide ................................................................................................. 11
Client Application Layer Configuration ............................................................................ 11
retek/services_rsl.xml ................................................................................................... 11
retek/service_flavors.xml ............................................................................................. 11
retek/jndi_providers.xml ............................................................................................. 11
Client Application Layer Code ........................................................................................... 12
6 RSLTestClient Utility ................................................................................................. 13
Installation and Configuration ............................................................................................ 13
Execution ................................................................................................................................ 13
A Appendix: Configuration Files ................................................................................. 15
Services Framework Configuration .................................................................................... 15
jndi_providers.xml......................................................................................................... 15
services_rsl.xml .............................................................................................................. 15
v
service_flavors.xml ........................................................................................................ 15
service_context_factory.xml ......................................................................................... 15
JDK Logging Configuration ................................................................................................ 15
J2ee-logging .................................................................................................................... 15
Other Configuration ............................................................................................................. 15
commons-logging.properties ....................................................................................... 15
B Appendix: Common Libraries .................................................................................. 17
Common Components ......................................................................................................... 17
platform-server.jar ......................................................................................................... 17
platform-api.jar .............................................................................................................. 17
platform-conf.jar ............................................................................................................ 17
platform-resources.jar ................................................................................................... 17
platform-common.jar..................................................................................................... 17
RSL/Integration .................................................................................................................... 17
oo-jaxb-bo-converter.jar ................................................................................................ 17
rib-public-payload-java-beans.jar ................................................................................ 17
rib-public-api.jar ............................................................................................................ 18
rib-private-kernel.jar ..................................................................................................... 18
rsl.jar ................................................................................................................................ 18
rsl-<service provider application>-access.jar ............................................................. 18
rsl-<service provider application>-business-logic.jar ............................................... 18
Third Party Provided ............................................................................................................ 18
castor-1.0.5-xml.jar ......................................................................................................... 18
ojdbc6.jar ......................................................................................................................... 18
commons-lang.jar........................................................................................................... 18
dom4j.jar.......................................................................................................................... 18
commons-collections.jar ................................................................................................ 19
commons-logging.jar ..................................................................................................... 19
vi
Send Us Your Comments
Oracle Retail Service Layer Programmer's Guide, Release 14.0
Oracle welcomes customers' comments and suggestions on the quality and usefulness of
this document.
Your feedback is important, and helps us to best meet your needs as a user of our
products. For example:
Are the implementation steps correct and complete?
Did you understand the context of the procedures?
Did you find any errors in the information?
Does the structure of the information help you with your tasks?
Do you need different information or graphics? If so, where, and in what format?
Are the examples correct? Do you need more examples?
If you find any errors or have any other suggestions for improvement, then please tell us
your name, the name of the company who has licensed our products, the title and part
number of the documentation and the chapter, section, and page number (if available).
vii
Preface
The purpose of this manual is to provide a basic understanding of the Oracle Retail
Service Layer components, including the flow of a synchronous call between two
applications.
Audience
This manual is designed for System Administrators, Developers, and Applications
Support personnel.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility
Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Related Documents
For more information, see the following documents in the Oracle Retail Service Layer
Release 14.0 documentation set:
Oracle Retail Service Layer Installation Guide
Oracle Retail Service Layer Release Notes
Customer Support
To contact Oracle Customer Support, access My Oracle Support at the following URL:
https://support.oracle.com
When contacting Customer Support, please provide the following:
Product version and program/module name
Functional and technical description of the problem (include business impact)
Detailed step-by-step instructions to re-create
Exact error message received
Screen shots of each step you take
ix
related to the base release, as well as information about code changes since the base
release.
Conventions
Navigate: This is a navigate statement. It tells you how to get to the start of the procedure
and ends with a screen shot of the starting point and the statement “the Window Name
window opens.”
This is a code sample
It is used to display examples of code
x
1
Introduction
Oracle Retail Service layer (RSL) handles the interface between a client application and a
server application. The client application typically runs on a different host from the
service. However, RSL allows for the service to be called internally in the same program
or Java Virtual Machine as the client without the need for code modification.
All services are defined using the same basic paradigm -- the input and output to the
service, if any, is a single set of values. Errors are communicated through Java Exceptions
that are thrown by the services. The normal behavior when a service throws an exception
is for all database work performed in the service call being rolled back.
RSL works within the Java EE framework. All services are contained within an interface
offered by a Stateless Session Bean. To a client application, each service appears to be
only a method call.
Some Oracle Retail applications, such as RMS, are implemented in the PL/SQL language,
which runs inside of the Oracle Database. RSL uses a generalized conversion process that
converts the input java object to a native Oracle Object and any output Oracle Objects to
the returned java object from the service. There is a one-to-one correspondence for all
fields contained in the Java parameters as in the Oracle Objects used.
A client does not need to know if the business logic is implemented as an Oracle Stored
Procedure or in some other language.
Introduction 1
2
Technical Architecture
This chapter describes the overall architecture of the Oracle Retail Service Layer. The RSL
architecture is built on Java EE Java Enterprise Bean technology. It comprises different
architecture layers that perform specific task within the overall workflow of integration
between two applications.
RSL provides two different models for service providers. The election of what model to
use depends on what type of application to which the “service provider” developer is
adding the RSL layer. For applications that follow the Java EE or simple Java
architecture, a Java EE model will be a better fit. An Oracle PL/SQL model is a better fit
for applications that heavily rely on database business logic, such as Oracle Forms-based
applications (RMS).
“Client application” developers do not need to be aware of this distinction. The
developer needs only to implement the code that retrieves an instance of the service
proxy using the service interface and the Common Components provided
ServiceAccessor class and makes the calls using a predefined set of payload objects for
argument and return type.
Architecture Layers
The RSL is divided into a series of layers. These layers are as follow:
The Client Application Layer (CAL). This layer is developed by client application
developers. The code for this is dependent on the business processes of the Client.
The Service Access Layer (SAL). This layer is generated by the Oracle Retail
Integration Team. Its purpose is to provide a typed set of interfaces and
implementations for accessing services. The SAL is the only set of interfaces that the
CAL developer needs to be aware of. Although different implementations of the SAL
might be used by the Client application, depending on the local or remote location of
the required services, the CAL developer doesn’t need to be aware of this.
The Service Provider Layer (SPL). This layer is implemented by the developers
belonging to the service provider or knowledgeable in the service application
domain. Each service must implement its corresponding interface as declared in the
SAL. For RMS, RWMS or other Oracle Forms applications, each service will be
offered via a PL/SQL Stored Procedure and use Oracle Object technology for input
and output parameters. For Java EE offered services, input and output parameters
will be generated through Value Objects – old fashioned Java beans that implement a
defined interface. They consist of “getter”, “setter” and “adder” methods. See the
following sections for a discussion of the Java EE and Oracle PL/SQL-based models.
Technical Architecture 3
Java EE Application Model
Application 1 Application 2
(J2EE or Java) (J2EE)
getService(ApplicationService.class)
ApplicationService.srvcCall(ClientContext, PayloadIn)
PayloadOut
Figure 1
Technical Architecture 5
Oracle PL/SQL-based Application Model
getService(ApplicationService.class)
SERVICE_HANDLER(RIB_OBJECT_IN)
RIB_OBJECT_OUT
PayloadOut
Figure 2
Basic Operations 7
4
Service Provider How-To Guide
This chapter provides information about how to configure the service provider
application.
retek/services_rsl.xml
<?xml version="1.0" encoding="UTF-8"?>
<services-config>
<customizations>
<interface package="com.retek.rsl.<app>">
<impl package="<application specific>" />
</interface>
</customizations>
</services-config>
The name of the package for the interface usually follows the com.retek.rsl.<app>
convention, where <app> is substituted by the name of the service provider application,
such as rms and rpm.
The implementation package name is provided by the service provider once the code is
developed; this name is irrelevant for the client application.
retek/service_flavors.xml
<?xml version="1.0" encoding="UTF-8"?>
<services-config>
<flavors set="server">
<flavor name="java"
locator="com.retek.platform.service.SimpleServiceLocator" suffix="Java"/>
</flavors>
</services-config>
package com.retek.rpm.service;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import com.retek.platform.exception.RetekBusinessException;
import com.retek.platform.service.ClientContext;
import com.retek.platform.service.FallbackHandler;
import com.retek.rib.binding.payload.PrcInqDesc;
import com.retek.rib.binding.payload.PrcInqReq;
import com.retek.rsl.rpm.PriceInquiryService;
retek/services_rsl.xml
<?xml version="1.0" encoding="UTF-8"?>
<services-config>
<customizations>
<interface package="com.retek.rsl.<app>" app="<app>">
<impl package="" />
</interface>
</customizations>
</services-config>
An entry like the following should exist in the client application’s services_rsl.xml file.
The name of the package for the interface usually follows the “com.retek.rsl.<app>”
convention, where <app> is substituted by the name of the service provider application,
such as rms and rpm.
The implementation package name is irrelevant in the client application, since this will
go through the CommandExecutionService EJB to make the service calls.
retek/service_flavors.xml
<?xml version="1.0" encoding="UTF-8"?>
<services-config>
<flavors set="client">
<flavor name="ejb" locator="com.retek.platform.service.EjbServiceLocator"
remote-suffix="Remote" home-suffix="RemoteHome"/>
</flavors>
</services-config>
retek/jndi_providers.xml
<?xml version="1.0" ?>
<ejb_context_overrides>
<provider app="rms" map-name="rsl-rms" csm-wallet="../conf">
<encrypted-context-property name="java.naming.security.principal"
key="rms-alias" value-type="PC_USERNAME" />
<encrypted-context-property
name="java.naming.security.credentials" key="rms-alias" value-type="PC_PASSWORD"
/>
<context-property name="java.naming.provider.url"
value="t3://<host>:<port>" />
<context-property name="java.naming.factory.initial"
value="weblogic.jndi.WLInitialContextFactory" />
</provider>
</ejb_context_overrides>
Execution
Make sure the RSL Service Provider Application is up and running. Execute the
rsltestclient.sh script. It will prompt for the username/password for the WebLogic server
where the RSL service provider application is running. After all tests have been
completed, the following message is displayed to indicate that all tests completed
successfully:
>>>>> Test completed successfully <<<<<
Or the following message may be displayed to indicate that errors may have occurred
during the execution of one of the tests:
>>>>> Test completed with possible errors, see sections above <<<<<
Once an error has been detected, the other tests will not be performed. Examine the
output to determine the cause of the error.
RSLTestClient Utility 13
Execution
When executing this test against an RSL Service Provider that follows the Java EE
Application Model, and if steps 1 and 2 in the “Installation and Configuration” section
were not followed, the following message is displayed, even if all tests passed
successfully:
>>>>> Test completed with possible errors, see sections above <<<<<
If the last test that ran was the SERVICE_HANDLER stored procedure test, ignore this
message and assume all tests passed successfully; because this is the last test, and it is not
relevant for Java EE Application Models.
jndi_providers.xml
The file must be in the classpath located in a retek directory. The JNDI providers’s XML is
used by the EJBServiceLocator to lookup Services in remote JNDIs. See the section,
“Common Components,” for specific formatting of this file.
services_rsl.xml
The file must be in the classpath located in a retek directory. Within this file are the
package locations of the Service Implementations, which are used to configure the
ServiceFactory. See the section, “Common Components,” for specific formatting of this
file.
service_flavors.xml
The file must be in the classpath located in a retek directory. Within this file are flavorsets,
which are used to configure the ServiceFactory. See the section, “Common Components,”
for specific formatting of this file.
service_context_factory.xml
The file must be in the classpath located in a retek directory. This specifies the factory
class used by Common Components to retrieve a service context implementation for
RSL.
J2ee-logging
This file must be in the classpath. This is the main configuration file for JDK logging.
Other Configuration
commons-logging.properties
This file must be in the classpath. It contains the correct logging factory to instantiate for
RSL. We utilize the Jdk14Logger, but you may configure you application differently
through this file.
Common Components
The following .jar files are common components.
platform-server.jar
This jar contains common components specific code for Oracle Retail. This includes the
Service framework. All services developed will be dependant on this jar for its use of
AbstractService and Service related classes.
platform-api.jar
This jar contains common components specific code for Oracle Retail. This includes
Exceptions and other Objects that could be transferred “over the wire”.
platform-conf.jar
This jar contains common components specific configuration files.
platform-resources.jar
This jar contains common components specific resource files for Oracle Retail.
platform-common.jar
This jar contains common components specific code for Oracle Retail.
RSL/Integration
oo-jaxb-bo-converter.jar
This jar contains specific code for Oracle Retail to convert Oracle Objects to Java and vice
versa.
rib-public-payload-java-beans.jar
This jar contains the java bean representation of business objects. They are collectively
referred to as payloads. The payloads are generated utilizing the RIB artifact generator.
They are dependant on castor for marshalling and unmarshalling. Payloads located in
this jar are type specific, this may cause interoperability issues with legacy applications
that are non-type specific, but follows in the future path of the project.
rib-private-kernel.jar
This jar contains bulk of the RIB kernel code. This jar contains various utilities for use
with Oracle Retail projects. Included is an OracleStructDumper, which aides in the
debugging of converting objects. There are also various string and factory objects that
may be of use.
rsl.jar
This jar contains utility, helper and exception classes used by the RSL framework.
castor-1.0.5-xml.jar
This jar contains classes related to the castor subsystem. Payloads for marshalling and
un-marshalling between XML and Java Bean representations utilize it. Documentation
and related information is located here: http://castor.exolab.org
ojdbc6.jar
This jar contains classes related to the Oracle JDBC driver. It is utilized within the
conversion utilities in the rsl.jar. This jar file has been updated for JDK 1.5
commons-lang.jar
This jar contains various utility classes for use in math, string and time operations.
Documentation and related information is located here:
http://jakarta.apache.org/commons/lang/
dom4j.jar
This jar contains XML DOM processing ability. It is needed for processing of the
configuration file in xml format. Documentation and related information is located here:
http://www.dom4j.org/
commons-logging.jar
This jar contains various utility classes for use with Java Logging. It provides an
additional abstraction layer to common logging functionality. Documentation and
related information is located here: http://jakarta.apache.org/commons/logging/