12 Subscriber-centric Policy

Making subscriber personalization easy and offering superior subscriber data protection is key to growing and maintaining a loyal subscriber base. The Oracle Communications Services Gatekeeper (Services Gatekeeper) Platform Development Studio offers a straightforward way to extend the power of Services Gatekeeper's flexible policy-based control to the operator's subscriber base.

There is an example Profile Provider in Middleware_Home/ocsg_pds_5.1/example.

Service Classes and the Subscriber SLA

The first step in adding subscriber-centric policy to Services Gatekeeper is to create a Subscriber SLA. This is an XML file based on the sub_sla_file.xsd schema.

The schema file can be found in the wlng.jar file located in the Middleware_Home/ocsg_pds_5.1/lib/wlng directory.

The SLA is used to define classes of service in the context of existing Service Provider and Application Groups.(For more information on Service Provider and Application Groups, see “Managing Application Service Providers” in Concepts Guide, a separate document in this set. These service classes can then be associated with subscribers, based on their preferences and permissions, defining individualized relationships between subscribers and Service Provider and Application Group functionality.

The <reference> element

The <reference> element specifies the operator's already-established Application and Service Provider Groups that are to be associated with this service class. There are two reference types that define the groups: the ApplicationGroupReference and the ServiceProviderGroupReference. In addition there are two additional reference types, the ServiceReference and the MethodReference that indicate specific service interfaces and methods, respectively, covered by those groups. In the Example 12-1 snippet, the service class news_subscription is defined. Evaluation of matches in the class occurs using the following rules:

If no reference type is specified, everything of that type is a match
Two or more entries of the same reference type creates an OR relationship
The default relationship is AND

So, in the case of Example 12-1, the class covers any request that matches:

Any of the service interfaces of the silver_app_group

(No ServiceReference type is specified, so everything is a match)
OR the gold_app_group

(Two ApplicationGroupReference entries creates an OR)
- AND the SendSMS service interface of the gold_app_group
  
  (The default relationship)
- AND the content_sp_group
  
  (The default relationship)
- AND the SendSMS service interface of the content_sp_group
  
  (The default relationship)
- AND either the sendSms OR the getSmsDeliveryStatus methods
  
  (Two MethodReference entries creates an OR)

Example 12-1 The <reference> element

<ServiceClass name="news_subscription">
        <references>
            <ApplicationGroupReference id="silver_app_group"/> 
            <ApplicationGroupReference id="gold_app_group"> 
                <ServiceReference serviceInterface="com.bea.wlcp.wlng.px21.plugin.SendSmsPlugin"/>
            </ApplicationGroupReference>
            <ServiceProviderGroupReference id="content_sp_group">
                <ServiceReference serviceInterface="com.bea.wlcp.wlng.px21.plugin.SendSmsPlugin">
                    <MethodReference methodName="sendSms" />
                    <MethodReference methodName="getSmsDeliveryStatus" />
                </ServiceReference>
            </ServiceProviderGroupReference>
        </references>

Use of the empty <references/> element matches everything.

The <restriction> element

In addition to the <reference> element, service classes may have a <restriction> element. This element is used to attach default rates and quotas that are used to create budgets for the classes. These rates and quotas can be replaced in specific contracts.

Note:

The XSD requires you either to specify a rate/quota restriction or to use the <restrictAllType/> element.

Example 12-2 The <restriction> element

<restriction>
            <rate>
              <reqLimit>5</reqLimit>
              <timePeriod>1000</timePeriod>
            </rate>
            <quota>
              <qtaLimit>600</qtaLimit>
              <days>3</days>
              <limitExceedOK>true</limitExceedOK>
            </quota>
</restriction>

These elements function exactly as they do in the other SLAs in Oracle Communications Services Gatekeeper. For more information on these elements, see the Contract structure section of the “Defining Service Provider Group and Application Group SLAs” chapter of Managing Accounts and SLAs, a separate document in this set. If the <limitExceedOK> element is set to true, the request is allowed even when quota has been exceeded, but an alarm (Alarm id 200000) is fired.

There is also a <restrictAllType/> element. This element, as its name implies, denies access to all requests.

Managing the Subscriber SLA

There are three management methods in the Service Level Agreement MBean for managing a Subscriber SLA. They are covered in detail in the “Managing SLAs” chapter of Managing Accounts and SLAs, a separate document in this set. The methods allow you to load a Subscriber SLA as a string, to load a Subscriber SLA from a URL, and to retrieve a loaded Subscriber SLA.

The Profile Provider SPI and Subscriber Contracts

Once the Subscriber SLA is established, the various service classes it defines must be associated with individual subscribers. The combination of a subscriber (identified by URI) and a service class is called a subscriber contract. A subscriber (a URI) can have multiple subscriber contracts associated with it.

The subscriber contract object contains a URI designating the subscriber and the service class type with which it is associated. It also contains an expiration time, represented as a java.util.Date.

The subscriber contract constructor will throw an exception if the URI, service class type, and expiration time are not specified.

The subscriber contract may also replace the default rate and/or quota settings in the service class, or set this subscriber to RestrictAll, that is, to deny access for all requests.

The operator or integrator is responsible for creating the mechanism, a Profile Provider, that supplies these subscriber contracts.

Note:

All class files related to creating Profile Providers are in the com.bea.wlcp.wlng.spi.subscriberdata package, and can be found in the wlng.jar file in the Middleware_Home/ocsg_pds_5.1/lib/wlng directory. The JavaDoc for the files can be found in the Middleware_Home/ocsg_pds_5.1/doc/javadoc directory. An example implementation can be found in the Middleware_Home/ocsg_pds_5.1/example/profile_providers/src directory. This sample implementation assumes the use of a properties file to assign subscriber URIs to particular service classes. An example properties file, exampleSubscriberContractMappingFile.properties, can be found in the Middleware_Home/ocsg_pds_5.1/example/profile_providers/resource directory.

The Profile Provider must implement the Profile Provider SPI. The SPI defines three methods;

init: Oracle Communications Services Gatekeeper initializes the Profile Provider by passing in a list of the service classes that are defined in the Subscriber SLA and a list of any previously defined subscriber contracts. The Provider returns a list of updated subscriber contracts.
contractExpired: Oracle Communications Services Gatekeeper sends the Provider a list of service classes and a list of expired contracts. The Provider returns an updated list of contracts for those that have expired. The Provider can remove or add contracts to the returned list.
serviceClassesUpdated: Whenever the Subscriber SLA is updated, and the service classes are thus modified, Oracle Communications Services Gatekeeper sends the Provider a list of the updated service classes and a list of all current contracts. The Provider returns an updated list of contracts. The Provider can make any necessary updates to the subscriber contracts.

The Profile Provider implementation must have a public constructor with no parameters or a static method which returns ProfileProvider.

Deploying the Custom Profile Provider

Once the ProfileProviderImpl has been created, the JAR file containing it must be added to the app-inf/lib directory in the profile_providers.ear file, which can be found in the Middleware_Home/ocsg_5.1/applications directory. You must also modify the app-inf/classes/ProfileProviders.prop file, adding a line containing the package and implementation file name of each of your providers (multiple providers are possible). For example:

com.mycompany.mypackage.MyProfileProviderImpl

Once the EAR file is modified, it can be deployed in the normal manner. For more information on deploying EAR files in Oracle Communications Services Gatekeeper, see the “Deployment model for Communication Services and Container Services” chapter in the System Administrator's Guide, a separate document in this set.

Subscriber Policy Enforcement

Once the providers.ear is deployed, the singleton SubscriberProfileService initializes the Profile Provider(s) and receives the relevant subscriber contracts. It uses the Budget Service to create budgets for the contracts, based on the specified rates and quotas, and also creates and schedules a timer based on the expiration times in the contracts. Both the Subscriber SLA and the subscriber contracts are persisted using the Storage Service.

Note:

For more information on budgets in Oracle Communications Services Gatekeeper, see the “Managing and Configuring Budgets” chapter in the System Administrator's Guide, a separate document in this set.

When a request from an application arrives at Oracle Communications Services Gatekeeper, it passes through the Interceptor Stack for policy evaluation. The EnforceSubscriberBudget interceptor manages policy enforcement for subscriber contracts. The process within the interceptor has two phases:

Do Relevant Subscriber Contracts Exist
Is There Adequate Budget for the Contracts?

Do Relevant Subscriber Contracts Exist

The first thing the interceptor must determine is whether one or more contracts exist that are relevant to the particular request that is being evaluated. The interceptor iterates through all the target URIs in the application request, and evaluates whether or not there are contracts in effect that it should enforce.

If there are no contracts at all associated with a particular URI, the request is simply passed on to the next interceptor in the sequence.
If there are contracts associated with a particular URI, a set of evaluations must be carried out. The figures below show the decision flow for the evaluations. All three sections must evaluate to true for there to be an enforceable contract.

Note:
The XML snippets correspond to the relevant sections of Example 12-1.
- Is there an ApplicationGroupReference and is it relevant? See Figure 12-1.

Figure 12-1 Application Group Reference Evaluation

Description of "Figure 12-1 Application Group Reference Evaluation"

Note:

The evaluation for methodExists is covered in Figure 12-3.

Is there a ServiceProviderGroupReference and is it relevant? See Figure 12-2.

Figure 12-2 Service Provider Group Reference Evaluation

Description of "Figure 12-2 Service Provider Group Reference Evaluation"

Note:

The evaluation for methodExists is covered in Figure 12-3.

Is there a Service Reference (and possibly a MethodReference) and are they relevant? See Figure 12-3.

Figure 12-3 Service and Method Reference Evaluation

Description of "Figure 12-3 Service and Method Reference Evaluation"

Is There Adequate Budget for the Contracts?

Once the interceptor determines that an enforceable contract exists, it first determines whether the contract includes a <restriction> element set to <restrictAll/>. If so, the request is immediately denied, and processing on the request ceases.

If the <restriction> element is not set to <restrictAll/>, the decision flow is identical to the other budget evaluations that take place in Services Gatekeeper.

If there are no relevant contracts, or there are relevant contracts and there is adequate budget to cover them, budgets are adjusted as necessary and the request passes on to the next interceptor. If there are relevant contracts and there is not adequate budget to cover them, the request is denied.