2
Installation

This chapter describes the basic installation and configuration Oracle Syndication Server.

The installation requires that the person installing this software have sysadmin privileges, is a database administrator, and has application development skills.

After you have completed the installation steps described in this chapter, you will have an understanding of the system requirements needed to install Syndication Server, you will have installed the Syndication Server schema, and you can begin using Syndication Server to syndicate content to subscribers.

To understand how to manage Syndication Server, you must first configure and run the OSSAdmin utility as described in Chapter 3. Then you can manage subscribers, manage affiliates or content providers, manage subscriptions, and do Syndication Server system administration operations, which are all described in Chapter 5.

The primary steps necessary to install and configure Oracle Syndication Server software are as follows:

1. Install the required software: Oracle9i Standard Edition or Enterprise Edition Release 1 (9.0.1) and Oracle Dynamic Services. See Section 2.1.
2. Install, configure, and test Oracle Syndication Server. See Section 2.3.
3. Configure the sample content provider adaptors and the set of Dynamic Services services for each sample content provider. See Section 2.4.

Section 2.1, Section 2.3, and Section 2.4 describe each of these steps in more detail.

2.1 System Requirements

The following are the system requirements:

• Oracle release: Oracle9i Standard Edition or Enterprise Edition Release 1 (9.0.1), which also includes Oracle Dynamic Services.

  Note: <ORACLE_HOME> is referred to as the installation directory of the Oracle9i Standard Edition or Enterprise Edition Release 1 (9.0.1) distribution.

• Syndication Server supports Oracle9i Standard Edition and Enterprise Edition running JDK 1.2.2.
• Java version: JDK 1.2.2 or later (Java2) distribution.

  Note: <JAVA2_HOME> is the installation directory of the JDK 1.2.2 or later distribution.

Be sure you have a full installation of Oracle9i Standard Edition or Enterprise Edition Release 1 (9.0.1) (a full installation in this case includes a typical Oracle9i Standard Edition or Enterprise Edition Release 1 (9.0.1) installation. Follow Oracle9i installation instructions to complete a full installation.

2.2 Syndication Server Distribution

For release 9.0.1, Oracle Syndication Server is distributed as a zip archive file. Future distributions will be packaged with the Oracle Universal Installer. Unzip the archive file in the syndication directory within your <ORACLE_HOME> directory. The distribution contains the subdirectories shown in Table 2-1.

Table 2-1 Oracle Syndication Server syndication Directory Contents  

Subdirectories	Description
admin	Contains a collection of SQL scripts.
admin/redist	Dynamic Services Gateway SQL scripts,
bin	Contains the OSSAdmin command-line utility for managing subscribers, affiliates, and subscriptions and system monitoring. Also contains the Syndication Server services configuration script.
demo	Contains the sample Syndication Server client.
doc	Contains the documentation about Dynamic Services including the README.txt file, the Oracle Dynamic Services FAQ file (syndfaq.txt), and the JavaDoc API (syndclientapi.zip), which contains those classes that are necessary for developers to build and run Syndication Server.
etc	Contains the Syndication Server properties file.
etc/ossadmin	Contains a properties file.
etc/services	Contains the services needed for Syndication Server and the configuration files.
lib	Contains the jar files of the Syndication Server and Syndication Client code and the Syndication Server properties file.
lib/redist	Contains the Dynamic Services Gateway jar (dsgw.jar) file.

2.3 Installing, Configuring, and Testing Oracle Syndication Server

Before you install Oracle Syndication Server, make sure your servlet engine can access your Oracle Dynamic Services library.

The following libraries from Oracle9i Standard Edition or Enterprise Edition Release 1 (9.0.1) are required by Oracle Syndication Server:

• <ORACLE_HOME> /lib/classgen.jar -- Oracle Class Generator
• <ORACLE_HOME> /lib/xmlparserv2.jar -- Oracle XML Parser (version 2.1.0.0 or later)
• <ORACLE_HOME> /jdbc/lib/classes12.zip -- Oracle JDBC Driver (compliant with JDK 1.2 (version 9.0.1))
• <ORACLE_HOME>/ds/lib/ds.jar -- Oracle Dynamic Services Library
• <ORACLE_HOME>/syndication/lib/redist/dsgw.jar -- Oracle Dynamic Services Gateway Library
• <ORACLE_HOME>/syndication/lib/syndserver.jar -- Oracle Syndication Server Library

The first three libraries are installed upon installing the Oracle9i Standard Edition or Enterprise Edition. The ds.jar library is installed with an Oracle Dynamic Services installation and the dsgw.jar and syndserver.jar libraries are installed with the Oracle Syndication Server installation. If you are using Apache Jserv, you must put these libraries into your jserv.properties file specified as wrapper.classpaths.

Oracle Syndication Server works with any servlet engine behind any Web listener, for example, it works with Apache Jserv installed with Oracle9i Standard Edition or Enterprise Edition Release 1 (9.0.1). The following steps assume you are using the Apache Jserv servlet engine:.

1. Modify jserv.conf in <ORACLE_HOME>/Apache/Jserv/etc to add a virtual path syndserver by adding the following lines to the ApJservMount area:

   # Syndication Server mountpoint
   ApJServMount /syndserver /syndserver
   
   

2. Create a zone for Oracle Syndication Server.
   1. Follow your servlet engine/container instructions for creating a zone.

      For example, if you are using iAS Apache, modify the jserv.properties file located in <ORACLE_HOME>/Apache/Jserv/etc and add the zone of syndserver, if your servlet engine permits, for example:

      zones= <existing zones>,syndserver 
      
      

      You must also add a property file to the zones as follows:

      syndserver.properties=<SYNDICATION_HOME>/etc/syndserver.properties
      
      

   2. Ensure the repository of that zone points to the Oracle Syndication Server library in your zone configuration file, syndserver.properties, which is located in <SYNDICATION_HOME>/etc.

      The Syndication Server library is located as:

      <SYNDICATION_HOME>/lib/syndserver.jar

      For example, using iAS Apache, the repository is:

      repositories=<ORACLE_HOME>/syndication/lib/syndserver.jar
      
      

3. Create a more recognizable name or alias for the servlet to access the server in the syndserver.properties file.

   Create an alias, for example, "OSS" and point it to the class in the zone's property file as follows:

   "servlet.OSS.code=oracle.syndication.server.servlet.OSS"
   
   

4. Modify the <ORACLE_HOME>/Apache/Jserv/jserv.properties file and include the wrapper classpath for the Dynamic Services Gateway jar (dsgw.jar) file as follows:

   wrapper.classpath=${ORACLE_HOME}/syndication/lib/redist/dsgw.jar
   wrapper.classpath=${ORACLE_HOME}/ds/lib/ds.jar
   
   

5. Create the tables and packages for Oracle Syndication Server.
   1. If the DSGATEWAY is not installed, go to /admin/redist/ and run the dsgatewayinstall.sql file as user dba. For example,

      sqlplus "sys/change_on_install as sysdba"
      
      

   2. Go up one level to the /admin directory, then connect as DSGATEWAY/DSGATEWAY and run the SQL script, ossinstall.sql.

      By default, running the PL/SQL script ossinstall.sql under the /admin directory creates the tables and packages for the database schema DSGATEWAY for exclusive use by Syndication Server and makes DSGATEWAY the basis of communication for the OSS servlet.

6. Create an Oracle Dynamic Services Gateway Context for Oracle Syndication Server.

   Each Dynamic Services Gateway Context defines the properties for establishing an Oracle Dynamic Services Connection for the purposes of services execution. You must create one for Syndication Server.

   1. Modify the sample SQL file of Gateway Context Creation ossinit.sql under the /admin directory by entering your database tnsname for oci8 or the thin driver for where your Dynamic Services (DS) engine is installed. For example:

      'jdbc:oracle:oci8:@<tns-name-entry-to-where-DSengine-is-installed>'
      or 
      'jdbc:oracle:thin@<your-host-name>:<your-port-number>:<tns-name-entry-to
      -where-DSengine-is-installed>'
      
      

   2. Run the ossinit.sql script as user DSGATEWAY/<DSGATEWAY-password> to create the new gateway context for Oracle Syndication Server.
7. Configure the init parameters for your OSS servlet in the syndserver.properties file.
   1. Find the sample syndserver.properties file in etc/syndserver.properties.

      There is a list of parameters that must be added to the Aliased Servlet Init Parameters section that the servlet picks up to configure a database connection to the Gateway Context that was created in Step 6.

      The parameters are:

      servlets.OSS.initArgs=GWCTX_DBURL=<gwctx-db-url>
      servlets.OSS.initArgs=GWCTX_USERNAME=<gwctx-db-username>
      servlets.OSS.initArgs=GWCTX_PASSWORD=<gwctx-db-password>
      servlets.OSS.initArgs=GWCTX_DBPOOLSIZE=<gwctx-db-pool>
      servlets.OSS.imitArgs=OSS_PUSH_GWCTX_ID=<gwctx-push-gatewat-context-id>
      
      

      where <gwctx-db-url> is either jdbc:oracle:oci8:@<your-TNS-NAME-ENTRY> or jdbc:oracle:thin:@<your-host-name>:<your-port-number>:<your-TNS-NAME-ENTRY>, <gwctx-db-username> is the user DSGATEWAY, <gwctx-db-password> is the password for user DSGATEWAY, <gwctx-db-pool> is the gateway context connection pool parameter value, and <gwctx-push-gateway-context-id> is the gateway context entry you created in Step 6, OSS_Context_Id_0x0001.

   2. Enter the values for each of these parameters mentioned in the previous step and save the file.

      Note: The value 5 for the GWCTX_DBPOOLSIZE parameter is a recommended value. You can change this value as needed.

8. Test your Oracle Syndication Server installation.
   1. Start or restart your Web server.

      For example, if you are using the Apache Web server, restart Apache.

      To restart Apache on UNIX systems, execute the commands shown as follows:

      cd <Apache installation directory>
      bin/apachectl restart
      
      

      On Windows NT, restart the Apache server from the Start bar. For Oracle9i 9.0.1, start from your Oracle home, select Oracle HTTP Server, then Start HTTP Server powered by Apache.

   2. Test the servlet installation by going to a browser and opening the following link:

      http://<your-web-server>:<port>/syndserver/OSS
      
      

      You should see on the resulting page that your Syndication Server is up and running.

   3. If your resulting page indicates a problem, you can check the log files of your Web server.

      For example, if you are using the Apache Web server, inspect the contents of the error_log file in the <ORACLE_HOME>/Apache/Apache/logs directory as well as the contents of the jserv.log and mod_jserv.log files in the ORACLE_HOME>/Apache/Jserv/logs directory.

2.4 Configuring the Sample Content Provider Adaptors and Services

Oracle Syndication Server has an extensibility layer for the content providers that feed into it. This is achieved through the Oracle Dynamic Services integration. Packaged with the default installation of Oracle Syndication Server, are three sample content providers that communicate with Oracle Syndication Server through the Oracle Dynamic Services framework.

The first sample content provider "eShop" is a demonstration of how a set of database-based Oracle Dynamic Services services can be used to provide content to Oracle Syndication Server.

The second sample content provider "File" is a demonstration of how a set of file-based Oracle Dynamic Services services can be used to provide content to Oracle Syndication Server.

The third sample content provider "Web" is a demonstration of how a set of Web-based Oracle Dynamic Services services can be used to provide content to Oracle Syndication Server.

These three sample content providers have been provided with the package, and can be registered and readily used, provided the appropriate properties are configured for your installation as follows:

1. Install the schema used by database-based Dynamic Services for the sample content provider "eShop" and its set of database-based Dynamic Services services.

   Naturally, for the database-based Oracle Dynamic Services set of services to function, there must be a schema sitting somewhere in some database instance containing the information for which the service is asking. This is done by running the eShop_init.sql script in any schema (user) on any database instance that you have running. For example, you can use the scott sample schema. Read the SQL script before running it and make sure that there are no table name conflicts. For future reference, remember which schema or database on which this schema is installed because you will need this information during configuration of the services in Step 3.

   NOTE: Refer to Chapter 10 Managing Job Queues in Oracle9i Database Administrator's Guide to make sure that you have enabled processes for executing jobs. The two issues to be concerned about are: The value for the dynamic initialization parameter, JOB_QUEUE_PROCESSES. For example, sqlplus "sys/change_on_install as sysdba" ALTER SYSTEM SET JOB_QUEUE_PROCESSES=20 Disabling a restricted session in an Oracle9i instance using the initialization parameter, DISABLE RESTRICTED SESSION. For example, sqlplus "sys/change_on_install as sysdba" ALTER SYSTEM DISABLE RESTRICTED SESSION Because both of these initialization parameters are dynamic, any changes you make will take effect immediately without having to stop and restart the database instance.

2. Add the categories and register the Dynamic Services services for the three sample content providers by running the DSAdmin utility script install.dss, which is located in <SYNDICATION_HOME>/etc/services.

   To add the categories and register the services needed for the three sample content providers, you must run the Dynamic Services DSAdmin utility script install.dss.

   Change the directory to the Oracle Syndication Server home directory at <SYNDICATION_HOME> and execute the following command on UNIX:

   <DS_HOME>/bin/dsadmin -u <DS_USERNAME>/<DS_PASSWORD>@<DS_NICKNAME> 
              -i etc/services/install.dss
   
   

   Or, execute the following command on Windows NT:

   <DS_HOME>\bin\dsadmin.bat -u <DS_USERNAME>/<DS_PASSWORD>@<DS_NICKNAME>
                   -i etc\services\install.dss
   
   

   <DS_USERNAME> and <DS_PASSWORD> are the Oracle Dynamic Services username/password pair that is needed to connect to an Oracle Dynamic Services engine when running the DSAdmin utility. <DS_NICKNAME> is comparable to a TNS_NAME_ENTRY for Oracle Dynamic Services (see Oracle Dynamic Services User's and Administrator's Guide for more information on how to run the DSAdmin utility).

   Usually, this task should be delegated to an Oracle Dynamic Services Administrator (which may be synonymous to the Oracle Syndication Server Administrator). After this step, the services necessary for the three sample content providers are installed.

3. Configure the services for these three sample content providers.

   To configure the services for these sample content providers to make them usable, you must edit a configuration file before proceeding.

   1. Find and open the sample version of the following configuration file in an editor. For example, on UNIX:

      <SYNDICATION_HOME>/etc/services/config_sample.xml
      
      

      Or, on Windows NT:

      <SYNDICATION_HOME>\etc\services\config_sample.xml
      
      

      The fields you must modify in this file are (using the XPath (XML Path Language) convention):

      //OSSConfig/DSUser: 
      
      

      The DSUser DSSYS, is the Oracle Dynamic Services consumer name that you want to have all Oracle Dynamic Services connections using. This should correspond to the Oracle Dynamic Services user name specified in your gateway context (see the contents of the ossinit.sql file in Step 6 in Section 2.3 to check for the presence of the DSSYS DSUser name).

      //OSSConfig/Services/DB/URL: 
      
      

      This is the database URL to connect to for the database-based Oracle Dynamic Services service "eShop". Refer to Step 1 in this section for this information.

      //OSSConfig/Services/DB/Username: 
      
      

      The database user name to connect to the URL mentioned previously is:

      //OSSConfig/Services/DB/Password: 
      
      

      The database password to connect to the URL mentioned previously is:

      //OSSConfig/Services/File/RootPath: 
      
      

      This is the path to start traversing from for all File "Catalog" listings.

      Note: There is no //OSSConfig/Services/Web section. This is because the Web content provider does not need to be configured.

      After you have made all necessary modifications to this file, save it.

   2. Next, you must run the configure (UNIX) or configure.bat (Windows NT) file with the input file, config_sample.xml. For example, on UNIX:

      <SYNDICATION_HOME>/bin/configure.sh <SYNDICATION_
      HOME>/etc/services/config_sample.xml
      
      

      Or, on Windows NT:

      <SYNDICATION_HOME>\bin\configure.bat <SYNDICATION_
      HOME>\etc\services\config_sample.xml
      
      

      Running this configuration file and its associated input file adds the necessary properties to the Oracle Dynamic Services user that your installation of Oracle Syndication Server uses.

      If you are running this script for the first time, you will see some error messages, such as "object not found". You can ignore these error messages.

You are now ready to start syndicating content to your subscribers using Oracle Syndication Server by using the sample content providers to help you get started.

2.5 Syndication Server Configuration

After the installation is complete, you can begin using Syndication Server to syndicate content to subscribers. To understand how to manage Syndication Server, you must first configure and run the OSSAdmin utility as described in Chapter 3. Then you can manage subscribers, manage affiliates, manage subscriptions, and do Syndication Server system administration operations. In addition, you can also begin to develop your own content provider adaptors, which is described in Chapter 4.