4
Syndication Server Development

This chapter describes the process of developing your own content provider adaptors using Oracle Dynamic Services and how you can test your custom content provider adaptor after you build one.

4.1 Adding Your Own Content Provider Adaptors Using Oracle Dynamic Services

One way to extend the list of content provider types is through Oracle Dynamic Services. As mentioned in Section 1.4.3, there is a content provider adaptor that is dedicated to implementing content provider feature through Oracle Dynamic Services services.

That is, there is a service used to implement the get-catalog feature as well as one for the get-package feature, and so forth. This is a very powerful concept in that it allows Oracle Syndication Server to syndicate content from any sources that the Oracle Dynamic Services framework allows.

4.1.1 Writing New Services

The best way to start writing new services is to copy each of the service packages for one of the shipped content providers (eShop Audio, File, or Web) to a new name, and then unzip them into some directory so you can modify them. Before modifying these files, read the following sections for instructions on rules to follow during modifications.

This is the recommended way to write your services because the schema/DTD files that the service requests/responses conform to are already packaged with these services. If you want to write your own services, you must copy these schema/DTD files into your own service package and point to them in your service descriptor.

4.1.2 Using Syndication Server Naming Conventions for Naming the Services

There is a heuristic that Oracle Syndication Server follows in retrieving services for the Oracle Dynamic Services content provider adaptor. The identifier for the service that needs to be registered must have the following format:

urn:com.<cp-prefix>:<cp-function>.oss

In this example, <cp-prefix> is your choice for the new content provider that will be using Oracle Dynamic Services and the <cp-function> corresponds to values like get-catalog, on-subscribe, and so forth. The value of <cp-prefix> shall be constant for all the services that implement one content provider. That is, for a new content provider called samplecpa, services with the following three identifiers should be registered:

"urn:com.samplecpa:get-catalog.oss"
"urn:com.samplecpa:on-subscribe.oss"
"urn:com.samplecpa:get-package.oss"

4.1.3 Conforming to Some Service Interface

Naturally, each of these services must conform to some service interface so that the Oracle Dynamic Services content provider adaptor can return a sensible ICE version 1.1 compliant response. The following are the service interfaces to which each of the services must conform. The name of the interface is given with the paths (within the shipped service packages) of the schemas.

4.1.3.1 Function for "ice-get-catalog"

Interface Name: SyndicationGetCatalog
Input Schema Path: /www.icestandard.org/spec/GetCatalog-ICE11.dtd
Output Schema Path: /www.icestandard.org/spec/Catalog-ICE11.dtd

4.1.3.2 Function for "ice-offer" (Subscribe)

Interface Name: SyndicationOnSubscribe
Input Schema Path: /www.icestandard.org/spec/OnSubscribe-ICE11.dtd
Output Schema Path: /www.icestandard.org/spec/Subscription-ICE11.dtd

4.1.3.3 Function for "ice-get-package"

Interface Name: SyndicationGetPackage
Input Schema Path: /www.icestandard.org/spec/GetPackage-ICE11.dtd
Output Schema Path: /www.icestandard.org/spec/Package-ICE11.dtd

With this information in mind, you can design new services that Oracle Syndication Server can use when using the Oracle Dynamic Services content provider adaptor. But in addition to registering these services, you must update Oracle Syndication Server using SQL*Plus as described in Section 4.2 and Section 4.2.1.

4.2 Adding a New Content Provider to Oracle Syndication Server

When you ran the ossinit.sql script file in Step 6 in Section 2.3 as part of the installation and configuration of Syndication Server, it updated Oracle Syndication Server for the three provided sample content providers. For now, this is one way to add content providers to Syndication Server using SQL*Plus commands. To add a new content provider, do the following:

1. Connect as DSGATEWAY or whichever schema the Gateway Context is installed in Step 5b in Section 2.3.
2. Issue the INSERT statement (the example shown here is for the database-based Oracle Dynamic Services service):

   "INSERT INTO OSSAffiliateProfile (
          CP_ID  
          BIZ_TERM
          DELIVERY_POL
          ADAPTOR_CLASS_NAME
          SERVICE_PREFIX
          GTWCTX_ID )
   VALUES (
          '<Content Provider ID>',
          EMPTY_CLOB(),
          EMPTY_CLOB(),
          'oracle.syndication.server.cpa.ice.ds.' || 
          'ICEDSSimpleContentProviderAdaptor',
          'eshopaudio',
          '<Gateway Context ID>'
    );"
   
   

The <Gateway Context ID> should point to the one created in Step 6a in Section 2.3, and the <Content Provider ID> can be named as you choose. Make sure that you do not have two content providers with the same ID.

4.2.1 Allowing Subscribers to See the New Content Provider

After Oracle Syndication Server has been updated to see the new content provider, it needs to give its subscribers the privilege to see contents from your new content provider. Using SQL*Plus, grant a content provider to a subscriber by doing the following:

1. Connect as DSGATEWAY or whichever schema the Gateway Context is installed in Step 5b in Section 2.3.
2. Issue the INSERT statement (the example shown here is for the database-based Oracle Dynamic Services service):

   "INSERT INTO OSSSubscriberAccount (
      SUBSCRIBERID
      CONTENTPROVIDERID )
   VALUES (
     '<Subscriber ID>',
     '<Content Provider ID>'
   );"
   
   

The <Subscriber ID> is the UUID (unique user ID) given to each subscriber by the system manager. The <Content Provider ID> should refer to the ones inserted in Section 4.2.

Now, you are ready to syndicate to your subscribers content from the new content provider that you have created.

4.3 Adding Push Delivery Mechanisms Using Oracle Dynamic Services

The mechanism used to extend the scope of push delivery is through Oracle Dynamic Services. Built into Oracle Syndication Server is an extensible framework for plugging in new push delivery channels. The push mechanism that is prescribed by ICE is through an HTTP POST request to an HTTP listener that is hosted by the subscriber. Oracle Dynamic Services is used to extend the scope of push delivery by allowing Oracle Syndication Server to push content through other protocols, this time to handle the delivery path, thus allowing for easy extensibility.

Whenever the scheduler informs Oracle Syndication Server of an update to be pushed to the subscriber, an Oracle Dynamic Services service is invoked with the content package as the service request. Currently, Oracle Syndication Server extensibility maps one delivery protocol to one Dynamic Services service. In the case of HTTP delivery, the service is an HTTP Dynamic Services service that takes the content package and makes a POST request to the HTTP listener on the subscriber's side.

Being extensible to allow different channel protocols for push delivery has an implication on the selection of the Dynamic Services service at runtime. The mechanism is one in which the subscriber URL is used to determine the channel protocol and therefore the Dynamic Services service that is needed. For example, the subscriber URL http://www.oracle.com/syndication/Client triggers the invocation of the push service associated with HTTP, and the subscriber URL mailto:oss@oss.com triggers the invocation of the push service associated with the mailto URL.

4.3.1 Writing New Push Services

The best way to start writing new push services is to copy the HTTP push service package (SyndicationPushPackage, located in the /etc/services directory on UNIX systems or \etc\services directory on Windows NT systems) to a new name, and then unzip them into some directory so you can modify them. Before modifying these files, read Section 4.3.2 and Section 4.3.3 for instructions on rules to follow during modifications.

4.3.2 Using Syndication Server Naming Conventions for Naming the Services

There is a heuristic that Oracle Syndication Server follows in retrieving push Dynamic Services services. The identifier for the service must have the following format:

"urn:com.push:<push-protocol>.oss"

Where <push-protocol> is the channel protocol with which to push the content. The heuristic followed maps HTTP for http and SMTP to mailto and so forth.

4.3.3 Push Service Interface: SyndicationPushPackage

Each of these services must conform to some service interface as defined by the Dynamic Services architecture, so that it allows Oracle Syndication Server to always be able to pass in the content package as a service request and receive an acknowledgment back as a service response.

4.3.3.1 Input Schema

The input schema envelopes the ice-package element with an ice-push-package element containing an attribute specifying the push URL. The service can forward this URL to the protocol handler to perform the protocol-specific actions for this URL.

4.3.3.2 Output Schema

The output schema models the ice-code element returning either an OK message or the error encapsulated in a comprehensive structure.

4.3.4 Registering the Service

After you have developed and registered your new push service, it is ready for use. The next subscription that contains a subscriber URL with a protocol matching the registered service will be able to start using your new service during push delivery.