Oracle9iAS Portal Developer Kit (PDK)
Provider Group Server Setup

Introduction

A Provider Group is a logical collection of Web Providers which is defined by a remote Provider Groups Service. A Portal Administrator can register Provider Groups for use with their Portal. Once registered, a Provider Group simplifies the process of registering the Providers in the group.

A Provider Group Server provides information about one or more groups of providers to an Oracle 9iAS Portal. Oracle 9iAS Portal communicates with the Provider Group Server using SOAP over HTTP. The default Provider Group Server that is distributed with Oracle 9iAS Portal is implemented as an Oracle SOAP service and uses an XML file to store definitions of groups of Providers.

This article explains how to setup and configure the default Provider Group Server using Oracle SOAP. A more detailed introduction to Provider Groups and their use within Oracle 9iAS Portal can be found in the article Understanding Provider Groups.

Oracle SOAP Setup

1. Oracle SOAP runs as a J2EE application, in the following description it is assumed that it will be deployed under the 'home' OC4J instance. To deploy Oracle SOAP, use the dcmctl command line tool as follows:

> dcmctl deployApplication -f $ORACLE_HOME/soap/lib/soap.ear -a soap -co home -v

2. Visiting the SOAP server's URL (i.e. http://<host>:<port>/soap/servlet/soaprouter) using a browser provides a simple way to verify that the SOAP web application is running. You should see the following screen:

3. The ORACLE_HOME/soap/bin directory contains scripts that you can use to administer the SOAP server. Before using the scripts you need to source the clientenv.sh script (for UNIX platforms) or run the clientenv.bat file (for Windows) to setup the client environment. These files are also in the ORACLE_HOME/soap/bin directory. Verify that the SOAP_URL set by the clientenv script is the correct URL for your SOAP server.

4. Before the admin scripts can be used to administer Oracle SOAP, the admin service itself must be enabled. By default this service is disabled for security reasons. It is very important that once the administrative operations described in this article are complete, the admin service is disabled again. Failure to do this will make it possible for a third party to invoke the admin service and possibly compromise your Oracle SOAP server.

To enable the admin service, add the following element to the ORACLE_HOME/j2ee/home/applications/soap/soap/WEB-INF/soap.xml file (in the deployed J2EE application):

<osc:serviceManager>
  <osc:option name="autoDeploy" value="true"/>
</osc:serviceManager>

Then restart the 'home' OC4J instance using the following command:

> dcmctl restart -co home

The two SOAP admin scripts that are used to deploy the Provider Groups service are: providerMgr (providerMgr.sh on UNIX platforms or providerMgr.bat on Windows) and serviceMgr (serviceMgr.sh on UNIX platforms or serviceMgr.bat on Windows). These will be in your path once the clientenv script has been run.

The providerMgr script runs the SOAP client that manages SOAP providers. SOAP providers allow the SOAP container to interface with SOAP services. The Provider Groups SOAP service requires a custom SOAP Provider to be deployed before it can be used.

The serviceMgr script runs the SOAP client that manages SOAP services. SOAP Services receive SOAP requests, via the SOAP container and a SOAP Provider, perform some action based on the request and return a SOAP response.

Running the admin scripts with no arguments gives usage information. Both scripts have list options which query either the SOAP services or SOAP providers available on your server (depending on which script you use).

For example, when running these scripts (on a UNIX client) a typical server, with no custom SOAP services or SOAP providers deployed, gives:

> serviceMgr.sh list
Using SOAP URL of http://myserver.com:7778/soap/servlet/soaprouter
Deployed Services:
urn:soap-provider-manager
urn:soap-service-manager

and

> providerMgr.sh list
Using SOAP URL of http://myserver.com:7778/soap/servlet/soaprouter
Deployed Providers:
java-provider

More information about the configuration and use of Oracle SOAP can be found in Appendix A of the Web Services Developer's Guide book from the Oracle 9iAS documentation library.

Provider Groups Service Setup

Once the Oracle SOAP server is running, the Provider Groups service can be deployed.

1. The Java classes that implement the Provider Group service are packaged in pdkjava.jar and ptlshare.jar. In Oracle 9iAS Portal Enterprise Edition, these files are located in the ORACLE_HOME/portal/jlib directory. For other Oracle 9iAS installations, copy these files from the libCommon/portal/jlib directory of the PDK downloaded from Oracle9iAS Portal Studio into ORACLE_HOME/portal/jlib.

2. To avoid having multiple copies of the pdkjava.jar and ptlshare.jar files, they should be referenced as shared libraries by Oracle SOAP. To do this add the following elements to the ORACLE_HOME/j2ee/home/application-deployments/soap/orion-application.xml file under the <orion-application> element:

<library path="../../../../portal/jlib/pdkjava.jar"/>
<library path="../../../../portal/jlib/ptlshare.jar"/>

Restart the home OC4J instance when the orion-application.xml file has been modified.

3. The SOAP server is told about the Provider Groups service (and the initializable-object-provider provider which the service uses) by running the serviceMgr (and providerMgr) scripts with the deploy option. The ServiceDescriptor.xml and ProviderDescriptor.xml files, are used in conjunction with the serviceMgr and providerMgr scripts respectively. The contents of the ServiceDescriptor.xml and ProviderDescriptor.xml files required for the Provider Groups service are given in Appendix C and Appendix D of this article and the files can also be found in the ORACLE_HOME/portal/pdkjava/providerGroups directory of an Oracle 9iAS Enterprise Edition installation.

First, deploy the SOAP provider.

On UNIX, use the following command:

> providerMgr.sh deploy ProviderDescriptor.xml

> providerMgr.bat deploy ProviderDescriptor.xml

The ServiceDescriptor.xml file defines the location of the Provider Groups XML file used by the default 'FileProviderGroupMgr' Provider Groups service implementation. This file is used to define the Provider Group(s) and the registration metadata for the Web Providers they contain. An example of this file, named iasProviders.xml, can be found in the ORACLE_HOME/portal/pdkjava/providerGroups directory of an Oracle 9iAS Enterprise Edition installation and in Appendix B of this article. The XML schema to which the file must adhere can be found in Appendix A of this article.

Note that the example ServiceDescriptor.xml file references the example Provider Groups XML file. This should be changed to reference your Provider Groups XML file on the server's filesystem, prior to deploying the Provider Groups service, by modifying the value attributes of the isd:service/isd:provider/isd:option elements with key attribute values of FileProviderGroupMgr.dir and FileProviderGroupMgr.file.

The ServiceDescriptor.xml file can then be used to deploy the Provider Groups service.

On UNIX, use the following command:

> serviceMgr.sh deploy ServiceDescriptor.xml

> serviceMgr.bat deploy ServiceDescriptor.xml

3. The deployment of the Oracle SOAP service and provider can be verified using the serviceMgr or providerMgr admin scripts as described in the previous section.

The Provider Groups defined by the service can now be registered with Oracle 9iAS Portal as described in the article Understanding Provider Groups. Note: the name of the Provider Group entered during registration is the same as the value of providerGroups/providerGroup/@name for the particular group in the Provider Groups XML file.

Errors relating to the configuration of the Provider Groups service are logged to the Oracle SOAP servlet's error log.

Remember to disable the Oracle SOAP admin service once the Provider Groups service has been deployed. Do this by removing the osc:serviceManager element, added in step 3 of the previous section, from the ORACLE_HOME/j2ee/home/applications/soap/soap/WEB-INF/soap.xml file and restarting the 'home' OC4J instance.

Appendix A - Provider Groups XML File Schema

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.oracle.com/portal/providerGroup/1.0"
           xmlns:tns="http://www.oracle.com/portal/providerGroup/1.0" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           elementFormDefault="qualified">
           
  <xs:element name="providerGroups">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="providerGroup" type="tns:ProviderGroupType" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  
  <xs:complexType name="ProviderGroupType">
    <xs:sequence>
      <xs:element name="displayName" type="tns:DisplayNameType"/>
      <xs:element name="provider" type="tns:ProviderType" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="name" type="xs:string" use="required"/>
    <xs:attribute name="baseLanguage" type="xs:string" use="required"/>
  </xs:complexType>
  
  <xs:complexType name="ProviderType">
    <xs:sequence>
      <xs:element name="displayName" type="tns:DisplayNameType"/>
      <xs:element name="timeout" type="xs:integer"/>
      <xs:element name="timeoutMessage" type="tns:TimeoutMessageType"/>
      <xs:element name="loginFrequency" type="tns:LoginFrequencyType"/>
      <xs:element name="httpURL" type="xs:anyURI"/>
      <xs:element name="serviceId" type="xs:string" minOccurs="0"/>
      <xs:element name="requireSessionData" type="xs:boolean" minOccurs="0"/>
      <xs:element name="httpAppType" type="tns:HttpAppTypeType"/>
      <xs:element name="cookieDomain" type="xs:string"/>
      <xs:element name="subscriptionKey" type="xs:string" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="name" type="xs:string" use="required"/>
    <xs:attribute name="baseLanguage" type="xs:string" use="required"/>
  </xs:complexType>
  
  <xs:complexType name="DisplayNameType">
    <xs:attribute name="language" type="tns:LanguageType" use="required"/>
    <xs:attribute name="translation" type="xs:string" use="required"/>
  </xs:complexType>
  
  <xs:complexType name="TimeoutMessageType">
    <xs:attribute name="language" type="tns:LanguageType" use="required"/>
    <xs:attribute name="translation" type="xs:string" use="required"/>
  </xs:complexType>
  
  <xs:simpleType name="LanguageType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="en"/>
      <xs:enumeration value="ar"/>
      <xs:enumeration value="cs"/>
      <xs:enumeration value="de"/>
      <xs:enumeration value="da"/>
      <xs:enumeration value="es"/>
      <xs:enumeration value="el"/>
      <xs:enumeration value="es-AR"/>
      <xs:enumeration value="fr"/>
      <xs:enumeration value="fr-CA"/>
      <xs:enumeration value="hu"/>
      <xs:enumeration value="it"/>
      <xs:enumeration value="he"/>
      <xs:enumeration value="ja"/>
      <xs:enumeration value="ko"/>
      <xs:enumeration value="no"/>
      <xs:enumeration value="nl"/>
      <xs:enumeration value="pl"/>
      <xs:enumeration value="pt"/>
      <xs:enumeration value="pt-BR"/>
      <xs:enumeration value="ro"/>
      <xs:enumeration value="ru"/>
      <xs:enumeration value="sv"/>
      <xs:enumeration value="fi"/>
      <xs:enumeration value="sk"/>
      <xs:enumeration value="tr"/>
      <xs:enumeration value="th"/>
      <xs:enumeration value="zh-CN"/>
      <xs:enumeration value="zh-TW"/>
      <xs:enumeration value="zh-HK"/>
      <xs:enumeration value="zh-SG"/>
      <xs:enumeration value="es-BO"/>
      <xs:enumeration value="es-CL"/>
      <xs:enumeration value="es-CO"/>
      <xs:enumeration value="es-CR"/>
      <xs:enumeration value="es-DO"/>
      <xs:enumeration value="es-EC"/>
      <xs:enumeration value="es-GT"/>
      <xs:enumeration value="es-HN"/>
      <xs:enumeration value="es-MX"/>
      <xs:enumeration value="es-NI"/>
      <xs:enumeration value="es-PA"/>
      <xs:enumeration value="es-PY"/>
      <xs:enumeration value="es-PE"/>
      <xs:enumeration value="es-PR"/>
      <xs:enumeration value="es-UY"/>
      <xs:enumeration value="es-VE"/>
    </xs:restriction>
  </xs:simpleType>
  
  <xs:simpleType name="HttpAppTypeType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="PORTAL"/>
      <xs:enumeration value="EXTERNAL"/>
    </xs:restriction>
  </xs:simpleType>
  
  <xs:simpleType name="LoginFrequencyType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Never"/>
      <xs:enumeration value="Once Per Session"/>
      <xs:enumeration value="Always"/>
      <xs:enumeration value="Public"/>
    </xs:restriction>
  </xs:simpleType>
  
</xs:schema>

Appendix B - Example Provider Groups XML File

<?xml version="1.0" encoding="UTF-8"?>
<providerGroups xmlns="http://www.oracle.com/portal/providerGroup/1.0">
    <providerGroup name="oracle.ias.providers" baseLanguage="en">
        <displayName language="en" translation="Oracle9iAS Providers"/>
        <provider name="oracle.ias.providers.UltraSearch" baseLanguage="en">
            <displayName language="en" translation="Ultra Search"/>
            <timeout>60</timeout>
            <timeoutMessage language="en" translation="Ultra Search Provider Timed Out"/>
            <loginFrequency>Never</loginFrequency>
            <httpURL>http://host:port/provider/ultrasearch/servlet/soaprouter</httpURL>
            <serviceId>urn:ultrasearch</serviceId>
            <httpAppType>PORTAL</httpAppType>
            <cookieDomain>host:port</cookieDomain>
        </provider>
        <provider name="oracle.ias.providers.WebComponent" baseLanguage="en">
            <displayName language="en" translation="Web Component Provider"/>
            <timeout>60</timeout>
            <timeoutMessage language="en" translation="Web Component Provider Timed Out"/>
            <loginFrequency>Once Per Session</loginFrequency>
            <httpURL>http://host:port/wcp/servlet/soaprouter</httpURL>
            <serviceId>urn:wcp</serviceId>
            <requireSessionData>true</requireSessionData>
            <httpAppType>PORTAL</httpAppType>
            <cookieDomain>host:port</cookieDomain>
            <subscriptionKey>DSProviderAdmin</subscriptionKey>
        </provider>
    </providerGroup>
    <providerGroup name="oracle.sample.providers" baseLanguage="en">
        <displayName language="en" translation="PDK-Java Sample Providers"/>
        <provider name="oracle.sample.providers.Basic" baseLanguage="en">
            <displayName language="en" translation="Basic Samples"/>
            <timeout>60</timeout>
            <timeoutMessage language="en" translation="Basic Samples Provider Timed Out"/>
            <loginFrequency>Once Per Session</loginFrequency>
            <httpURL>http://host:port/jpdk/providers</httpURL>
            <serviceId>urn:sample</serviceId>
            <httpAppType>PORTAL</httpAppType>
            <cookieDomain>host:port</cookieDomain>
        </provider>
        <provider name="oracle.sample.providers.Event" baseLanguage="en">
            <displayName language="en" translation="Event/Parameter Passing Samples"/>
            <timeout>60</timeout>
            <timeoutMessage language="en" translation="Event/Parameter Passing Provider Timed Out"/>
            <loginFrequency>Never</loginFrequency>
            <httpURL>http://host:port/jpdk/providers</httpURL>
            <serviceId>urn:event</serviceId>
            <httpAppType>PORTAL</httpAppType>
            <cookieDomain>host:port</cookieDomain>
        </provider>
    </providerGroup>
</providerGroups>

Appendix C - ProviderDescriptor.xml File for Provider Groups Service

<?xml version="1.0" encoding="UTF-8"?>
<isd:provider xmlns:isd="http://xmlns.oracle.com/soap/2001/04/deploy/provider" 
              id="initializable-object-provider" 
              class="oracle.webdb.utils.xml.soap.InitializableObjectProvider">
</isd:provider>

Appendix D - ServiceDescriptor.xml File for Provider Groups Service

<?xml version="1.0" encoding="UTF-8"?>
<isd:service xmlns:isd="http://xmlns.oracle.com/soap/2001/04/deploy/service"
             id="http://www.oracle.com/portal/providerGroup/RPC/1.0">
    <isd:provider id="initializable-object-provider"
                  methods="register getProvider getProviders getProviderGroup getLastModified"
                  scope="Application">
        <isd:java class="oracle.webdb.providerGroup.v1.service.ProviderGroupService"
                  static="false"/>
        <isd:option key="managerClass"
                    value="oracle.portal.providerGroup.v1.service.FileProviderGroupMgr"/>
        <isd:option key="FileProviderGroupMgr.dir"
                    value="$ORACLE_HOME/portal/pdkjava/providerGroups/"/>
        <isd:option key="FileProviderGroupMgr.file"
                    value="iasProviders.xml"/>
    </isd:provider>
    <!-- includes stack trace in fault -->
    <isd:faultListener class="org.apache.soap.server.DOMFaultListener"/>

    <isd:mappings>
        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:providerGroup"
                 javaType="oracle.portal.providerGroup.v1.ProviderGroup"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:providerGroupNames"
                 javaType="oracle.portal.providerGroup.v1.ProviderGroupNames"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:providerMetadata"
                 javaType="oracle.portal.providerGroup.v1.ProviderMetadata"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:providerMetadata"
                 javaType="oracle.portal.providerGroup.v1.ProviderMetadataBean"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:externalApplication"
                 javaType="oracle.portal.providerGroup.v1.ExternalApplicationMetadata"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:externalApplication"
                 javaType="oracle.portal.providerGroup.v1.DefaultExternalApplicationMetadata"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:translation"
                 javaType="oracle.portal.providerGroup.v1.Translation"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:translation"
                 javaType="oracle.portal.providerGroup.v1.DefaultTranslation"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:fieldNameValue"
                 javaType="oracle.portal.providerGroup.v1.FieldNameValue"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

        <isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                 xmlns:x="http://www.oracle.com/portal/providerGroup/RPC/1.0"
                 qname="x:fieldNameValue"
                 javaType="oracle.portal.providerGroup.v1.DefaultFieldNameValue"
                 java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
                 xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>

    </isd:mappings>
</isd:service>