# Platform Development Studio - Developer’s Guide

# Custom Service Level Agreements

This section describes how to implement enforcement of custom service level agreements (SLAs) and the relationship between the custom SLAs, their XSDs, and the enforcement logic:

- Introduction
- Custom SLAs and XSDs
- Custom SLA Enforcement

- Get an SLA using a DOM Object
- Get an SLA using a Custom Parser

- Example

- Custom SLA Schema and Example SLA
- Enforcement Logic

## Introduction

Custom service level agreements (SLAs), offer a mechanism to add custom SLA enforcement in addition to the SLA enforcement provided out-of-the-box with Oracle Communications Services Gatekeeper. In contrast to the system SLA types that have static XSDs and enforcement logic, the custom SLAs offer configuration time loading of SLA XSDs and runtime deployment of the enforcement logic. It is a framework for definition and enforcement of custom SLAs.

The entities involved include:

- Custom SLA XSDs
- Custom SLAs
- Enforcement logic for the custom SLAs

The custom SLA XSDs are loaded and assigned an SLA type using the management interfaces. Then SLAs are loaded, and associated with a service provider group, application group, or globally. After this is done, the SLA type is used and the custom SLAs are validated against the XSDs.

At run-time, when the custom SLAs are enforced, the enforcement logic is responsible for fetching the enforcement logic relevant for the custom SLA type.

## Custom SLAs and XSDs

The SLAs must be expressed in XML and be formatted according to their SLA XSDs. There are no other requirements on the SLAs.

At load time, the custom SLA XSD is validated and associated with an SLA type. This type is used when loading the custom SLA, and the SLA is validated against the XSD.

The XSD and SLA are loaded using the management interfaces. See section Managing SLAs in Oracle Communications Services Gatekeeper Managing Accounts and SLAs.

## Custom SLA Enforcement

The custom SLA enforcement is implemented as one or more service interceptors. Thus gives the operator the ability to deploy and undeploy the enforcement logic in runtime. It also gives the enforcement logic access to all data about a request from the context object through the class com.bea.wlcp.wlng.api.interceptor.Context.

The service interceptor is responsible for:

- Resolving the request data it needs from the Context object.
- Loading the representation of the custom SLA
- Fetching any other data needed for the enforcement logic
- Manipulating the Context with new data, if necessary
- Allowing or denying the request, if necessary

For information on how to access the data from the Context object, see Service Interceptors.

The Java representation of the custom SLA is fetched from `com.bea.wlcp.wlng.api.sla.CustomSlaManager`.

This class exposes the following methods:

    Document getApplicationGroupCustomSla(String slaType)

    Document getServiceProviderGroupCustomSla(String slaType)

    Document getGlobalCustomSla(String slaType)

    Object getApplicationGroupCustomSla(String slaType, String parserId)

    Object getServiceProviderGroupCustomSla(String slaType, String parserId)

    Object getGlobalCustomSla(String slaType, String parserId)

    void registerSlaParserCallback(String slaType, String parserId, SlaParserCallback parser)

    void unregisterSlaParserCallback(String slaType, String parserId)

There are two ways to get the Java representation of the SLA, through a DOM object or from a custom XML parser:

- Get an SLA using a DOM Object
- Get an SLA using a Custom Parser

Note: | A custom SLA parser can produce a more efficient Java representation of the SLA than the more general DOM representation.

The `CustomSlaManager` automatically resolves which custom SLA should be fetched, so there is no need to resolve which group the originator of the request belongs to. In the case of a global SLA, only the custom SLA type is of significance since this scope does not take into account the originator of the request, but is relevant for all requests.

If the combination of SLA data and enforcement logic is intended to add or replace data about the request, the service interceptor must manipulate the `Context` object accordingly.

If the combination of SLA data and enforcement logic is intended to function to deny or allow the request , the service interceptor must throw an exception and break the chain of interceptors or pass on the request to the next interceptor as described in Service Interceptors.

### Get an SLA using a DOM Object

When using get methods that return the SLA as an `org.w3c.dom.Document`, a standard DOM parser is used to construct the Java representation of the SLA:

    Document getApplicationGroupCustomSla(String slaType)

    Document getServiceProviderGroupCustomSla(String slaType)

    Document getGlobalCustomSla(String slaType)

The `slaType` identifies the XSDs and returns the custom SLA for the service provider group, application group, or global, respectively. Depending on the scope of the enforcement logic, the corresponding method is used. In this case there is no need to implement and register any parser.

### Get an SLA using a Custom Parser

When using get methods to return the SLA as an `Object,` the custom parser parses the SLA and returns an object in a known format:

    Object getApplicationGroupCustomSla(String slaType, String parserId)

    Object getServiceProviderGroupCustomSla(String slaType, String parserId)

    Object getGlobalCustomSla(String slaType, String parserId)

All of the above methods require the ID of parser to use for creating the `Object`. The parser must be registered using:

    void registerSlaParserCallback(String slaType, String parserId, SlaParserCallback parser)

It can be unregistered using:

    unregisterSlaParserCallback(String slaType, String parserId

The custom SLA parser must implement the interface `com.bea.wlcp.wlng.api.sla.SlaParserCallback`, which defines the method:

    Object parse(String sla)

The parameter sla contains a text-representation of the SLA, and originates from the SLA as loaded using the Account Service. Oracle Communications Services Gatekeeper is responsible for caching and keeping the SLA in sync with the loaded SLA. The implementation of parse(String sla) returns the object that is returned by the get methods.

The two methods are equivalent in every aspect except the custom SLA implementation and the parser ID.

## Example

Below is an example of how a custom SLA that combines data from an application’s request, the contents of a custom SLA and data from an external source can be implemented. A DOM parser for the SLA is used.

The use case assumes that service provider groups are used to differentiate between different content providers. For example, service provider groups are created for content providers of entertainment, sports, and weather. End-users of the services can opt in to get content of a certain category, and this data is accessible by Service Gatekeeper.

A simple custom SLA schema with entries for allowed content types is created. See Custom SLA Schema and Example SLA. The custom SLA XSD is loaded in Oracle Communications Services Gatekeeper using the management interfaces. Custom SLAs are created that list the content types from these service provider groups. Service provider groups are created for different content types. Each SLA is associated with the corresponding service provider group using the management interfaces.

The enforcement logic for the SLA is created. The logic is deployed as a service interceptor.

When an application uses Service Gatekeeper to deliver content, the request travels through the communication service until the custom service interceptor is reached. The interceptor gets the custom SLA XSD, and - depending on the originator of the request - fetches the appropriate SLA and matches the addressee’s preferences. Based on that information, it allows or blocks the request. For detailed information, see Enforcement Logic.

### Custom SLA Schema and Example SLA

Listing 12-1 is an example of a SLA schema that allows a set of content types to be defined.

Listing 12-1 Example SLA Schema

    <?xml version="1.0"?>

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"

               targetNamespace="http://www.example.com"

               xmlns="http://www.example.com"

               elementFormDefault="qualified">

      <xs:element name="contentFilter">

        <xs:complexType>

         <xs:sequence>

          <xs:element name="allowContents">

           <xs:complexType>

            <xs:sequence>

              <xs:element name="allowContentType"

                          type="xs:string"

                          maxOccurs="unbounded"

                          minOccurs="1"/>

            </xs:sequence>

           </xs:complexType>

          </xs:element>

         </xs:sequence>

        </xs:complexType>

      </xs:element>

    </xs:schema>

Listing 12-2 is an SLA that adheres to the schema in Listing 12-1. It allows the content type Entertainment.

Listing 12-2 ContentFilterSla.xml

    <?xml version="1.0"?>

     <contentFilter xmlns="http://www.example.com"

                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

                    xsi:schemaLocation="http://www.example.com contentFilter.xsd">

      <allowContents>

       <allowContentType>Entertainment</allowContentType>

      </allowContents>

     </contentFilter>

### Enforcement Logic

The enforcement logic of the SLA is implemented as a service interceptor, so it must register itself and de-register itself using the `InterceptorManagerFactory`, see Service Interceptors.

Below are the main steps involved in implementing the enforcement logic:

1. A request enters the interceptor. The destination address of the request is retrieved from `com.bea.wlcp.wlng.api.interceptor.Context` by iterating over the `RequestInfo` objects until the `AddressRequestInfo` is found.

    for (RequestInfo requestInfo : context.getRequestInfos()) {

      if (requestInfo instanceof AddressRequestInfo) {

       URI uri = ((AddressRequestInfo) requestInfo).getAddress()

       ...

2. A lookup of which content types are allowed by the subscriber identified by the destination address is done. This lookup could be done on a subscriber database.
3. The custom SLA for the service provider group is fetched from the `CustomSlaManager`. The SLA is fetched by name and the SLA type given when the XSD for the custom SLA was loaded using the management interfaces. The SLA for the service provider group that is associated with the originating application is resolved automatically by the `CustomSlaManager`. Different methods are used to fetch the custom SLA on service provider group, application group, and global level.

    Document spSla = slaManager.getServiceProviderGroupCustomSla(CONTENT_FILTER);

4. The custom SLA is returned as a org.w3c.dom.Document, and the Document is parsed to get the data, in this case the content of the `<allowContentType>` elements.
5. The content of the SLA is compared to the list of allowed contents for the destination address. If there is a mismatch, an exception is thrown to stop the service interceptor chain. If the request is allowed, it is passed on to the next service interceptor.