# Platform Development Studio - Developer’s Guide

# Subscriber-centric Policy

Making subscriber personalization easy and offering superior subscriber data protection is key to growing and maintaining a loyal subscriber base. The Platform Development Studio offers a straightforward way to extend the power of Oracle Communications Services Gatekeeper’s flexible policy-based control to the operator’s subscriber base. The mechanism can be divided into three parts:

- Service Classes and the Subscriber SLA
- The Profile Provider SPI and Subscriber Contracts
- Subscriber Policy Enforcement

Note: | There is an example Profile Provider in `$PDS_HOME/example`

## Service Classes and the Subscriber SLA

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

Note: | The schema file can be found in the `wlng.jar` file located in the `$PDS_HOME/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 and Architectural Overview, 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> tag

The `<reference>` tag 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 Listing 13-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 Listing 13-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)

Listing 13-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 tag, `<references/>`, matches everything.

### The <restriction> tag

In addition to the `<reference>` tag, service classes may have a `<restriction>` tag. This tag 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/>` tag.

Listing 13-2 The <restriction> tag

    <restriction>

                <rate>

                  <reqLimit>5</reqLimit>

                  <timePeriod>1000</timePeriod>

                </rate>

                <quota>

                  <qtaLimit>600</qtaLimit>

                  <days>3</days>

                  <limitExceedOK>true</limitExceedOK>

                </quota>

    </restriction>

These tags function exactly as they do in the other SLAs in Oracle Communications Services Gatekeeper. For more information on these tags, 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>` tag 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/>` tag. This tag, 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 j`ava.util.Date`.

Note: | 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 `$PDS_HOME/lib/wlng` directory. The JavaDoc for the files can be found in the `$PDS_HOME/doc/javadoc` directory. An example implementation can be found in the `$PDS_HOME/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 `$PDS_HOME/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 of the `profile_providers.ear` file, which can be found in the `$BEA_HOME/ocsg_4.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 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 Listing 13-1:

- Is there an `ApplicationGroupReference` and is it relevant? See Figure 13-1
Figure 13-1 Application Group Reference Evaluation

Note: | The evaluation for methodExists is covered in Figure 13-3

- Is there a `ServiceProviderGroupReference` and is it relevant? See Figure 13-2.
Figure 13-2 Service Provider Group Reference Evaluation

Note: | The evaluation for methodExists is covered in Figure 13-3

- Is there a `Service Reference` (and possibly a `MethodReference`) and are they relevant? See Figure 13-3
Figure 13-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>` tag set to `<restrictAll/>`. If so, the request is immediately denied, and processing on the request ceases.

If the `<restriction>` tag is not set to `<restrictAll/>, t`he decision flow here is identical to the other budget evaluations that take place in Oracle Communications 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.