13 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 in Oracle Communications Services Gatekeeper (Services Gatekeeper).

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 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

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

Example 13-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>

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

Example 13-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:

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()
   ...
```
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.
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);
```
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.
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.