# Oracle9iAS Portal Developer Kit (PDK)
Provider Group Server Setup

Creation Date: | October 21, 2002
Status: | Production
Version: | PDK Release 2, (9.0.2 and later)

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

Alternatively, use the Enterprise Manager web site as described in Chapter 8 of the Oracle9i Application Server Administrator's Guide Book from the Oracle 9iAS documentation library.

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

On Windows, use the following command:

    > 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

On Windows, use the following command:

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

Revision History: |
Revision No | Last Update
1.0 | October 21, 2002

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ | Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 | Copyright and Corporate Info