Skip Headers
Oracle® Retail POS Suite Implementation Guide, Volume 5 – Mobile Point-of-Service
Release 14.1
  Go To Table Of Contents


4 Mobile POS Frameworks

There are several frameworks at work in the Mobile POS server application. These include the service REST service layer, the tour runner framework, and the view object hierarchy. Each is discussed in detail.

RESTful Web Services

This section describes the service layer and security for the web services.

REST Service Layer

The REST service layer is composed of a REST-annotated shell class backed by a service implementation class. Each service class follows the same pattern, as seen in the AuthWebService example in Figure 4-1.

Figure 4-1 Service Framework

The WebService classes are tagged with REST annotations that the Jersey libraries use to marshal messages in and out of the API. Since only concrete classes can be annotated, the implementation of the services is delegated to a paired ServiceImpl class. The two are kept in API synchronization by implementing the same ServiceIfc. These pairings are defined in the ServiceContext.xml file to allow for extension and customization. The out-of-the-box ServiceImpl classes all implement the base AbstractRegisterWebService class that provides common session management functionality, along with other shared behaviors. The ContextAwareServiceIfc is used to pass the request context into the delegated ServiceImpl instance since the Jersey libraries only inject the request context into the annotated class. All out-of-the-box ServiceImpl classes implement this interface.

Figure 4-3 shows the lifecycle of a Mobile POS service call.

Figure 4-2 Service Call Sequence

When the client application calls a service API, the Jersey library's registered servlet intercepts the call and directs it to the API mapped to the URL requested, extracting parameters where necessary. Once the class and method are identified, the Jersey library instantiates the class and injects the request information into the new instance. The constructors of the provided REST classes look up their paired implementation class from the Spring container and inject the provided request context into them, provided they implement the ContextAwareServiceIfc.

By default, the ServiceImpl classes are singletons, so they are only instantiated once and simply retrieved on each subsequent call to the same service area. After Jersey has successfully instantiated the target REST class, it executes the mapped method. The REST class simply takes those parameters and passes them to the paired class' matching method.


Authentication for services is handled by the WebLogic Application Server, using a custom plug-in, which validates the user name and password specified by a legitimate user for the Point-of-Service database. The session is maintained using a secure cookie, containing the JSESSIONID, which is returned by the application server upon successful login.

Authorization is handled by the Mobile POS server. When a service is called, the MPOS server checks to see if the logged in user has the appropriate role and privileges to perform the requested action. If the user does not have the required privileges, the web service call fails.

Tour Runner and Tour Access

Most of the methods in the ServiceImpl classes are backed by a POS tour. The only four that are not are:

  • AboutServiceImpl.getVersion()

  • AuthServiceImpl.logout()

  • RegisterServiceImpl.getRegisterProfile()

  • SaleTransactionServiceImpl.getSaleTransaction()

Inside the remaining ServiceImpl method, the parameters are validated and then used to populate the TourParameters instance appropriate for the tour to be executed.

Figure 4-3 Tour Runner

Once populated, the tour parameters instance is sent into the configured tour runner instance and the mapped tour is executed. The tour runner configuration is done through the ServiceContext.xml file, where you can configure what tour script to execute and which launch and return shuttles to use. Example 4-1 is an example of the Item Delete API configuration:

Example 4-1 Tour Runner Configuration

<bean id="service_ItemDeleteTourRunner"
      lazy-init="true" singleton="false">
  <property name="tourScript"
  <property name="launchShuttleClass"
  <property name="returnShuttleClass"

For more information on POS tours and their development and extension model, see Oracle Retail POS Suite Implementation Guide, Volume 2 - Extension Solutions.Another aspect of the TourRunner that can be configured is the UI manager used while the tour is being executed. The out-of-the-box Mobile POS uses a customized UI manager called the InstructibleUIManager. This UI manager allows the tours to run to completion without displaying any screens. Traditional POS tours have a mixture of business logic and view logic. In order to reuse these tours, the Mobile POS API needs a way to avoid showing screens, as this blocks the tour thread preventing the tour from completing.

Example 4-2 InstructibleUIManager Configuration

<bean id="service_ItemModifySalesAssocTourRunner"
      lazy-init="true" singleton="false">
  <property name="tourScript"
  <property name="launchShuttleClass"
  <property name="returnShuttleClass"
  <property name="managerData">
       <entry key="UIManager" value-ref="service_ManagerData" />
  <property name="siteLetters">
         <entry key="ModifyItemMenu" value="SalesAssociate" />
         <entry key="ModifyItemSalesAssociate" value="Next" />

The InstructibleUIManager allows the tour runner to inject the letters that need to be sent when a show screen event is fired for a particular site. In most cases, this is simply a Yes or Continue type letter on a dialog. However, some situations require a little more information. For those situations, an instruction can be configured that the InstructibleUIManager will use to decide how to handle that particular screen.

Status and Tour Parameter Object Frameworks

The view objects are used to return information to the calling application. They are collected into the Status object hierarchy.

Figure 4-4 Status Object Hierarchy

The Status base class provides an error collection that allows the API to return error codes and messages to the calling application. Each Status sub-class represents the state of a particular retail object: Register, Item, Transaction, and so on.

The Tour Parameter objects provide the inputs to the tours run by the service API.

Figure 4-5 Tour Parameter Object Hierarchy

The inputs to the service API are collected into various tour parameter objects and passed into the tour associated with mapped tour runner. The API instantiates these classes using the MobilePOSObjectFactoryIfc. This allows the objects to be extended and customized in a manner similar to POS domain objects.