Resilient Web Service Framework

About

The Resilient Web Service (RWS) Framework supports a Web Service developer providing resilient enhanced Web Services. The framework encompasses policies in the following areas:

  • Enforcing a resilient versionig strategy
  • Adding semantics to the Web Service interface
  • Providing provenance enriched Web Service responses
  • Testing of the Web Service behaviour
  • Identifying and monitoring of Web Service dependencies
  • Notifying Web Service consumers on updates

As part of the framework we developed the following tools supporting the policies:

  • Verification tool - Used to verify the interface backward compatibility based on the previous source code version of the Web Service. In a first step the tool verifies that the annotations are applied correctly. In a second step it verifies that the attached version identification does not violate the resilient versioning strategy.
  • Java2RWSDL - Used to transform Java Web Service source code file into a resilient WSDL. It processes the applied resilience annotations and attaches them to the service’s interface
  • Dependency Collection Tool - Collects the Web Service’s dependencies by requesting the demo operations with the provided input requests. The service’s view path is presented as a context model instance. It is based on the Process Migration Framework (PMF).
  • Resilience Annotations - Provides a set of resilience annotations which have to be applied to the service source code in order to improve the semantics of the service interface.
  • Provenance Enriched Header - Attaches the provenance information to a service response header by intercepting the request.
  • Pre-commit-Hook - is responsible for triggering the verification tool on a commit.

Resilient Policies

The RWS Framework defines the following policies:

  • POLICY 1 The RWS provider has to follow the resilient versioning policy to ensure a resilient Web Service evolution.
  • POLICY 2 To enable provenance tracking of a service response, the RWS provider has to attach provenance attributes, specifically the Web Service release version, VCS revision number and the Timestamp of last update to each SOAP response header.
  • POLICY 3 A RWS provider has to attach its contact information—compliant to the UDDI contact data structure—to the public WSDL interface of its published services.
  • POLICY 4 The RWS provider has to enhance an operation description, by providing information about the parameter exchange format, supported validity period and the classification of each offered operation.
  • POLICY 5 The RWS provider has to maintain a Web Service operation for at least the guaranteed validity period.
  • POLICY 6 A Resilient Web Service’s source code must be tested till it exhibits a code coverage rate in between 70% - 80% or higher. The higher the rate, the lower is the possibility for any bugs or other uncertainties. A stable, faultless implementation will prevent the Web Service provider from ongoing update procedures.
  • POLICY 7 For each test methods, the RWS provider has to implement a rollback strategy to avoid the persisting of any state changes or data modifications.
  • POLICY 8 For each stateful Web Service operation, the Web Service provider must offer a demo operation, which performs the original functionality, without persisting any state changes. By convention, the signature of the demo operation must be equal to the original operation including a Demo suffix for the name. Those additional demo operations must be provided by the RWS interface. The service owner has to provide sample request for each demo operation. Those requests are used in a later point in time create the Web Service View Path.
  • POLICY 9 The service hosting platform provider is responsible for capturing the Web Service’s View Path.
  • POLICY 10 The service hosting platform has to provide a push notification mechanism to inform those events to Web Service users as well as providing an interface to allow them to pull the respective informations.
  • POLICY 11 The service hosting platform has to propagate occurred changes in the following format. For software updates the SoftwareReplacement event has to be used. In case of a hardware update the HardwareReplacement event has to be used.
  • POLICY 12 Update notifications have to be pushed via some channel (recommended is RSS) to subscripted consumers. Each resilient party has to establish a separate RSS channel for each resilient service.
  • POLICY 13 In case of a RWS depends on another Web Service, that remote service must also be resilient.
  • POLICY 14 The maximal lifetime of the Web Service must not exceed the maximum lifetime of any of the remote services it is depending on.

Setup

Download the following archive and extract it to a directory named 'resilient' in the root folder. Make sure that the directory and its subdirectories are writeable and executable. The directoy should contain the following items:

  • resilientAPI-1.0.jar ... API including Java annotations for enhancing the service interface and servelts for a proper redirecting.
  • verificationChecker-1.0.jar
  • java2RWSDL-1.0.jar (comming soon)
  • service.contact ... contact template which has to be updated with the Web Service owner information. Copy this file to the WEB-INF folder of the service's project.
  • .versions ... hidden folder in which the various service source code versions are stored.
  • .operations ... hidden file used to stored the serialized service operations including its annotations.
  • .framework ... hidden file storing the version history of the Web Service's source code file.
  • (pre-commit ... Subversion pre-commit hook which triggers the verificationChecker-1.0.jar.)*

* Copy the pre-commit hook file in the SVN repository hook directory.

Tooling

To transform an existing Web Service into a RWS, the Web Service provider has to apply the following steps:

  • Add the provided resilient-api-1.0.jar to the classpath of your service project.
  • Extend the basic service source code with the provided resilience annotations.
    • Add @Resilient and @Interceptors(ProvenanceInterceptor.class) on class level.
    • Add {@Stateless|@Stateful},{@Determinstic|@NoneDeterministic},@Validity to each operation declaration.
    • In case the operation make use of non-simple data types, you have to additionally add @Return and @FileFormat for the corresponding operation parameters.
  • For each service operation, a demo operation has to be provided (see POLICY 8)
    • Add the @Demo annotation and the 'Demo' suffix to the corresponding demo operation.
  • The service provider has to apply source code tests to fullfil the required code coverage (see POLICY 6,7).

A sample how to add the annotations is available here.

Applying all the aforementioned instructions will result in the following benefits:

  • The resilient versioning policy is forced by the SVN automatically.
  • Java2RWSDL generates a resilient WSDL out of the source code.
  • Each SOAP response is provenance enriched.
  • Contact information is automatically published of the provider can be found http://my.server.com/linkToWebService/contact and the RSS feed is reachable at http://my.server.com/linkToWebService/rss