Documentation Center

Services Framework Overview

The SDK services framework contains static and abstract classes that define and provide the mechanism through which WorldServer executes custom access methods. There are two execution models: the stand-alone execution model and the pluggable component model. In both models, the framework defines how the custom access module should be created, and how access to the WSContext is acquired. In general, the WSContext object is provided to the custom access module by the services framework.

The services framework provides the instance of the WSContext at execution time. The services framework handles all environment initialization. User login information is either provided via the custom code for stand-alone modules or else derived from the system for pluggable components.

The primary difference between the component and external modules is that WorldServer controls the execution of component modules. You control the execution of the external modules directly using the WSContextManager class. The details of this are presented below.

Transaction Control

The services framework also manages transactions. Within the services framework, the SDK user cannot explicitly create transactions. Instead, the transactions are created by the services framework via an internal transaction runner. These transactions are associated with the WSContext instances, which are also provided by the service framework. Within a single run service call, there is only one active transaction and only one WSContext instance. This transaction is either committed or rolled back based on the return value of the custom run/execution method. The custom code controls this by returning a TRUE value to commit, and a FALSE value to roll back changes. Additionally, exceptions trigger the run services framework to perform a rollback.

The transaction only applies to WorldServer components being created, modified or deleted using the WSContext. Every object manager is bound to a specific WSContext instance. Within the custom access module, the developer can still use JDBC connectivity to effect arbitrary database changes. However, the transactions related to these explicit JDBC calls or user-defined transactions are not the same as the transaction embedded in the WSContext object. Committing an explicitly user-defined transaction does not commit changes associated with the WSContext. Similarly, if the WSContext is forced to rollback associated changes, explicitly created transactions that have been committed within the call will not be rolled back.

This is the sequence diagram for a generic external service module. It illustrates how transactions are handled within the services framework. (The component module process is similar.) The steps in the diagram is summarized as follows:
  1. WSContextManager.runAsUser(Username, Password, WSRunnable) method is invoked with a custom class that extends the service framework WSRunnable interface. (User login information is required as well.)
  2. The WSContextManager delegates to the internal TransactionRunner, which:
    1. Initializes the system (this step is not shown).
    2. Creates a new transaction.
    3. Logs in the user.
    4. Executes the WSRunnable.run(WSContext) providing the WSContext that is now associated with the created transactions.
  3. A new transaction for the WSContext is created.
  4. The user credentials are validated.
  5. Process enters custom WSRunnable.run method.
  6. Uses the WSContext object to get an instance of an object manager object.
  7. Uses the object manager to gain access to a particular SDK object for accessing services.
  8. Uses the SDK object to access WorldServer service or to manipulate data.
  9. Returns TRUE to commit changes, or FALSE to roll back. TransactionRunner receives the return value and either commits or rolls back changes.
  10. Process completes.

Implicit Transactions

Some processes exposed in the SDK contain an implicit transaction for handling specialized requirements. While they can run with other processes within a WSRunnable implementation, these processes will not be subject to the external transaction control of the run services. Once such a process completes, its results or outcome is committed.

The APIs that have implicit transactions will not impact other processes that are explicitly associated with the WSContext object supplied by the run services. Even if the implicit process has completed successfully or failed, the changes associated with the non-implicit APIs can still be rolled back or committed by the run services based on how the WSRunnable process completed. (See the the Transaction Control and Services Framework sections, above.)