Creating a Synchronized System
Page 6 of 6

Configuring the System for Refresh Requests

This section explains how to configure your system so that source and target databases can communicate with each other.

Overview

Cloudscape uses the HTTP protocol to send and receive synchronization (refresh) messages between source and target databases. The source database listens for incoming refresh requests in one of two ways:

The cloudscape.DataComm.listenType property, set at the source, determines which means of communication to use. The two values of cloudscape.DataComm.listenType are servlet and builtinHttp. The default is builtinHttp. Set this property at the source before creating publications.

Since the target initiates refresh requests in Cloudscape synchronization, the target must know the address to which to send refresh requests. Targets get this information from the cloudscape.listener.synchronization.address, which you set at the source. This property contains the following information:

  • When you are using the servlet API to listen for refresh requests, it is set to the URL of the servlet that listens for refresh requests.
  • When you are using the built-in listener, it is set to the host name of the source system and the port on which the source is listening for refresh requests.

Set this property at the source before creating publications unless you are using default value.

For information about moving the source after targets are created, see the section Moving the Source to a Different Machine.

Configuring Cloudsync for the Servlet API

With the servlet API, Cloudscape receives refresh request messages from a servlet that uses the same port as the server framework (see Configuring Cloudsync for the Servlet API).

Use the servlet API if the source database is running on a server framework that supports servlets. Cloudconnector supports servlets. See the Cloudscape Server and Administration Guide for more information on server frameworks.

To use the servlet API, set the cloudscape.DataComm.listenType property to servlet. You must also:

Registering the Servlet

The Cloudscape class name to use with the servlet API is COM.cloudscape.core.ServletHandler. How you set this class name depends on the server framework. For example, in the case of Cloudconnector, insert a line like the following in the weblogic.properties file, which registers the servlet under the name "sync":

weblogic.httpd.register.sync=COM.cloudscape.core.ServletHandler

NOTE: The word "sync" could be replaced by any other word. However, the word specified here must be the same as that used in the refresh request URL.

Refresh Request URL for the Servlet Listener

The cloudscape.listener.synchronization.address property specifies the URL of the servlet to which targets should send refresh requests. The exact value of this property depends on the server framework and how you have registered the servlet. For Cloudconnector, it would be something like the following for a machine named myhost:

cloudscape.listener.synchronization.address=http://myhost:7001/sync

Table 3-1 Summary of Cloudsync Configuration Properties For the Servlet API

Property

Default Value, Where and How to Set

cloudscape.DataComm.listenType

Specifies whether you will be using the servlet API or built-in HTTP support to manage refresh messages.

If you specify servlet you must also register COM.cloudscape.core.ServletHandler with the HTTP server. See Registering the Servlet. You must also set cloudscape.listener.synchronization.address.

default: builtinHttp

Set it at the source as a system property, or as a database property.

cloudscape.DataComm.url

Optional configuration property. Enables the standard JDK URL support for POST. Automatically set to true when using the servlet HTTP support. If this were set to false, you would get the following error when you tried to refresh:

"Unexpected HTTP reply code: 400 Bad Request"

If you are using the built-in listen type, you must set this property to false (the default). If you have it set to true instead, you get the following error when you try to refresh:

ERROR X0RP0: I/O failure in sending or receiving a
Refresh message to 'http://stephenslt1:2005
application'
ERROR XJ001: Java exception: ':
java.io.EOFException'.

default: false, unless cloudscape.DataComm.listenType is set to servlet.

In that case, it defaults to true.

Set it on the target as a database property (either in the publication, or locally), or as a system property. (You will have to reboot the database.)

cloudscape.listener.synchronization.address

Required configuration property. Sets the URL to which targets send refresh messages

If using the servlet HTTP support and you forget to set this property, you get the following error when trying to create a copy file:

ERROR X0R0U: A Refresh Address
(cloudscape.listener.synchronization.address) has
 not been configured for this database.

If using the built-in listen type, the default is: http://<hostNameofSourceDB>:2001/application

If using the servlet HTTP support, there is no default.

Set it at the source as a system property, or as a database property.

If using Cloudconnector and a cloudscape.DataComm.listenType of servlet:

weblogic.httpd.register.sync=COM.cloudscape.core.ServletHandler

Registers the servlet that listens for refresh requests with the http server.

To verify that this is set correctly:

go to http://<hostname>:<CloudconnectorPortNumber>/T3AdminMain, click Properties, then search for "sync"

Set it in the weblogic.properties file.

Configuring Cloudsync for Built-in HTTP Support

With built-in HTTP support, Cloudscape opens a new port to listen for messages directly.

If you use built-in HTTP support, you may not have to set any configuration properties if the default port number and address are acceptable. If you are not using the default port number and address, you will have to set:

Only in very unusual cases would you have to set the network address as well (see Network Addresses).

Port Numbers

By default, the source listens on port 2001. To set the source to listen on a different port number, assign a different value to the cloudscape.DataComm.port property in the source database system before creating publications.

If another source database will run concurrently on the same host computer in a different Cloudscape system, specify unique port numbers for each source database.

When using a non-default port number, you also need to set cloudscape.listener.synchronization.address (see Network Addresses).

Network Addresses

When using the default port number (2001), you don't need to set the cloudscape.listener.synchronization.address property. By default, Cloudscape assumes that the URL to which targets send refresh requests is:

http://hostname:port/application

where hostname is the host on which the source is running when a publication is created and the port is 2001.

If you're using a non-default port number, you need to set the cloudscape.listener.synchronization.address property so that the port number matches the port number set by cloudscape.DataComm.port.

You may also wish to set a non-default host name (for example, if you will be deploying the source database on a different host). To set a different network address from the default, alter the cloudscape.listener.synchronization.address property as follows:

  • replace hostname with the hostname you want
  • specify the port number, even if it is the default (2001)
  • be sure to include /application at the end of the address

For example, the following URL may be a valid network address using built-in HTTP support:

http://myhost:2003/application

See Chapter 13, "Cloudsync Properties", for information on the synchronization properties. Also see Tuning Cloudscape for more information on using properties.

Table 3-2 Summary of Cloudsync Properties for Built-In HTTP Support

Property

Default Value, Where and How to Set

cloudscape.DataComm.listenType

Specifies whether you will be using the servlet API or built-in HTTP support to manage refresh messages.

default: builtinHttp

Set it at the source as a system property, or as a database property.

cloudscape.DataComm.port

Required configuration parameter on source if using the built-in listen type and not using the default port number.

Specifies the port number on which the source databases of the given Cloudscape system expect to receive refresh messages.

If you set this parameter, you must also set cloudscape.listener.synchronization.address.

default: 2001

Set it at the source as a system property, or as a database property.

cloudscape.DataComm.url

Optional configuration property. Enables the standard JDK URL support for POST.Automatically set to true when using the servlet HTTP support. If this were set to false, you would get the following error when you tried to refresh:

"Unexpected HTTP reply code: 400 Bad Request"

If you are using the built-in listen type, you must set this property to false (the default). If you have it set to true instead, you get the following error when you try to refresh:

ERROR X0RP0: I/O failure in sending or receiving a
Refresh message to 'http://stephenslt1:2005
application'
ERROR XJ001: Java exception: ':
java.io.EOFException'.

default: false, unless cloudscape.DataComm.listenType is set to servlet.

In that case, it defaults to true.

Set it on the target as a database property (either in the publication, or locally), or as a system property. (You will have to reboot the database.)

cloudscape.listener.synchronization.address

Required configuration property. Sets the URL to which targets send refresh messages

If using the servlet HTTP support and you forget to set this property, you get the following error when trying to create a copy file:

ERROR X0R0U: A Refresh Address
(cloudscape.listener.synchronization.address) has
 not been configured for this database.

If using the built-in listen type, the default is: http://<hostNameofSourceDB>:2001/application

If using the servlet HTTP support, there is no default.

Set it at the source as a system property, or as a database property.

Moving the Source to a Different Machine

You can physically change the location of a source database provided that its refresh address does not change. (If you change the network address of the source after a target is created, the target can no longer connect to the source.) To avoid this problem, "virtualize" the refresh address of your Cloudsync system; you should be able to change the physical location to which a name points, as described below:

Systems that are configured for refreshes using the built-in http support can handle changes in the following ways:

  • If you move the source to another machine, the new machine must use the same network address as the old source machine. Create a special DNS name for the source's IP address, and configure the source to use this name in its listen address, you can move the source to another machine, correct the DNS entry at the source, and still synchronize with targets.

Systems that are configured for refreshes using the servlet API can handle changes in the following ways:

  • If the source database physically moves with respect to the server framework, change the value of the cloudscape.system.home property to the location of the new source database when starting up the server framework.
  • If the physical location of the server framework changes, map the old address of the refresh servlet to the new location of the servlet.

Debugging Network Configuration Errors

When you are first setting up a synchronization system and are having difficulties getting targets to refresh, you may wish to do the following:

  1. Check your network configuration. Run the following commands at the source. Note that it does not reflect properties set in the cloudscape.properties file:

    -- to determine which kind of HTTP support you
    -- are using
    VALUES (CLASS java.lang.System).getProperty(
        'cloudscape.DataComm.listenType',
        PropertyInfo.getDatabaseProperty(
        'cloudscape.DataComm.listenType'))

    VALUES (CLASS java.lang.System).getProperty(
        'cloudscape.listener.synchronization.address',
        PropertyInfo.getDatabaseProperty(
        'cloudscape.listener.synchronization.address'))

    -- if you're using built-in HTTP support,
    -- port number should match port number that appears
    -- in cloudscape.listener.synchronization.address
    VALUES (CLASS java.lang.System).getProperty(
        'cloudscape.DataComm.port',
        PropertyInfo.getDatabaseProperty(
        'cloudscape.DataComm.port'))

  2. Run the following commands at the target:

    -- should return the name of the source database
    VALUES PropertyInfo.getDatabaseProperty(
        'sysinfo.sourceDatabaseName')

    -- value should match the
    -- cloudscape.listener.synchronization.address
    -- at the source
    VALUES PropertyInfo.getDatabaseProperty(
        'sysinfo.sourceServerAddress')

    -- should almost always be set to true when using the
    -- servlet refresh api; should always be set to false
    -- when using the built-in refresh API
    VALUES (CLASS java.lang.System).getProperty(
        'cloudscape.DataComm.url',
        PropertyInfo.getDatabaseProperty(
        'cloudscape.DataComm.url'))