Documentation Center

The services framework

The SDK services framework contains static and abstract classes that define and provide the mechanism through which WorldServer executes custom access models. There are two execution models: the stand-alone execution model and the pluggable component model. In both models, the framework defines how you should create your custom access modules and how to gain access to the WSContext object.

In general, the services framework provides the instance of the WSContext object to the custom access module at execution time. It also handles environment initialization. User login information is gathered either via the custom code (for stand-alone modules) or from the system (for pluggable components).

The main difference between the component and the external modules is that WorldServer controls how component modules are executed. You can control the execution of the external modules through the WSContextManager class.

Transaction Control

The services framework also manages transactions. Within the services framework, you cannot explicitly create transactions. Instead, the services framework creates transactions via an internal transaction runner. These transactions are associated with the WSContext instances, which are also provided by the services framework. There are one active transaction and one WSContext instance within a single run service call. 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 roll back changes.

The transaction only applies to WorldServer components that you created, modified, or deleted using the WSContext object. Every object manager is bound to have a specific WSContext instance. Within the custom access module, you can still use JDBC connectivity to perform arbitrary database changes. However, the transactions related to these explicit JDBC calls or to 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 roll back its associated changes, the explicitly created transactions that have been committed within the call will not be rolled back.A generic external service module
This diagram presents a generic external service module and the way in which transactions are handled within the services framework. The steps in the diagram can be summarized as follows:
  1. The WSContextManager.runAsUser (Username, Password, WSRunnable) method is invoked with a custom class that extends the service framework WSRunnable interface. User login information is also required.
  2. The WSContextManager delegates to the internal TransactionRunner, which:
    1. Initializes the system.
    2. Creates a new transaction.
    3. Logs in the user to the system.
    4. Executes the WSRunnable.run (WSContext) providing the WSContext that is now associated with the created transactions.
  3. A new transaction is created for the WSContext object.
  4. User credentials are validated.
  5. The process enters the custom WSRunnable.run method.
  6. The WSContext object is used to get an instance of an object manager object.
  7. The object manager is used to gain access to a particular SDK object for accessing services.
  8. The SDK object is used to access WorldServer services or to manipulate data.
  9. Returns TRUE to commit changes or FALSE to roll back. TransactionRunner receives the return value and either commits the changes or rolls them back.
  10. The process is completed.

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 is completed, its results are 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 fails or is performed successfully, the run services can still roll back or commit the changes associated with the non-implicit APIs based on how the WSRunnable process ended.