Refresh Authentication
Page 5 of 7

Reference Section

The REFRESH Command

Cloudscape allows you to set properties in the REFRESH command. These properties are retrievable at the source in the target connection attributes.

For example:

REFRESH PROPERTIES pin = "aksdfh&%"

At the source, you retrieve the property within the refresh authentication callback class like this:

String pin = target.getConnectionAttributes().getProperty("pin"); 

For more information, see REFRESH.

NEW: The PROPERTIES clause of the REFRESH command is new in Version 3.6.

NOTE: The property values must be String literals. Since those Strings are SQL-J identifiers, delimit those strings unless they are all uppercase.

The Refresh Authentication Callback Class

A refresh authentication callback class must implement the interface COM.cloudscape.authentication.Interface.MessageAuthenticationScheme. This interface defines two methods, as follows:

/**
    Pre-connect refresh request callback.
    Called at the source for a refresh request before
    a JDBC connection is opened. Allows applications
    to authenticate requests and/or set the refresh user.
    This call does not disable any authentication on the
    subsequent JDBC connection.

    @exception AuthenticationException abort the refresh
    
*/
public void preConnect(TargetDescription target)
    throws AuthenticationException

/**
    Post-connect refresh request callback.
    Called at the source for a refresh request after
    a JDBC connection is opened and before any work from
    the target is applied.
    Allows applications to authenticate requests using
    data with the source database.

    @exception SQLException abort the refresh
    @exception AuthenticationException abort the refresh
    
*/
public void postConnect(Connection conn, TargetDescription target)
    throws SQLException, AuthenticationException

NOTE: Calls to getCurrentConnection() are disabled in both methods.

Here is an example of a class that implements this interface:

import COM.cloudscape.authentication.Interface.MessageAuthenticationScheme;
import COM.cloudscape.authentication.Interface.AuthenticationException;
import COM.cloudscape.synchronization.TargetDescription;
import java.sql.SQLException;
import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
/**
 *  Refresh authentication callback class. Must be in the class path
 *  of the server, and you must also set the property
 *  cloudscape.authentication.refresh to the name of this class.
 *  
 */
public class RefreshCallback implements MessageAuthenticationScheme{
    /**
     *  Pre-connect refresh request callback. Called at the source
     *  for a refresh request before a JDBC connection is opened.
     *  This method provides a (generic)  valid user ID
     *  and password so the refresh request can pass 
     *  the JDBC user authentication.
     *  The postConnect method will perform the actual user-defined
     *  authentication.
     *  @exception AuthenticationException abort the refresh
     */
    public void preConnect(TargetDescription target)
        throws AuthenticationException {
        System.out.println("preConnect got called.");
        // get the target's connection attributes
        Properties p = target.getConnectionAttributes();
        // add the user and password property to the attributes
        p.put("user", "salesRefresh"); 
        p.put("password", "kkj&*9-H14M");
        //the source will automatically look for those 
        //properties and use
        //them for the JDBC connection request if needed
    }
     /**
     * Post-connect refresh request callback.
     *  Called at the source for a refresh request after
     *  a JDBC connection is opened and before any work from
     *  the target is applied.
     *  This method authenticates the ID and PIN provided by the
     *   target in its REFRESH PROPERTIES against a table in the
     *  database.
     *  @exception SQLException abort the refresh
     *  @exception AuthenticationException abort the refresh
     *  
     */
       public void postConnect(Connection conn, TargetDescription target)
        throws SQLException, AuthenticationException {
         //find out the pin
        Properties p = target.getConnectionAttributes();
        String pin = p.getProperty("pin"); 
        if (pin == null)
            //throwing an exception aborts the refresh
            throw new SQLException("no pin provided");
        System.out.println("pin is " + pin);
        //find out the id
        String rep_id_string = p.getProperty("rep_id");
        if (rep_id_string == null)
            throw new SQLException("no rep_id provided");
        int rep_id = new Integer(rep_id_string).intValue();
        // more likely this would be a stored procedure   
        // checkpin(account, pin) 
        // and pins would be stored in an encrypted form
        // in the table
        PreparedStatement ps = conn.prepareStatement(
            "SELECT rep_id FROM refreshIds WHERE rep_id = ? "
            "AND pin = ?");
        ps.setInt(1,rep_id); 
        ps.setString(2, pin); 
        ResultSet rs = ps.executeQuery();
        //if there is no such row, it's an invalid target
        if (!rs.next()) {
            throw new SQLException("Invalid PIN");
        }
        rs.close(); 
        ps.close();
        
    }

Target Connection Attributes

Refresh requests have connection attributes, which are standard java Properties. They are returned by the method getConnectionAttributes() from an instance of the class COM.cloudscape.synchronization.TargetDescription, which is available at the source database when the refresh attempt is made.

You can add to the connection attributes at the target or the source, and you can retrieve the connection attributes at the source. In addition, in some situations, the source automatically looks for the specific properties user and password.

You can set connection attributes directly in the following ways:

In addition, you can specifically set the property user indirectly in the following ways:

  • at the source indirectly, by setting the cloudscape.database.sourceUser property. Where conditions are met (see The user Property: Reference), the value of this property is added to the user property in connection attributes for targets.
  • at the source indirectly, by setting a property called user in the startup parameters of the servlet COM.cloudscape.core.ServletHandler. Where conditions are met (see The user Property: Reference), the value of this property is added to the user property in connection attributes for targets refreshing via the servlet.
  • at the target indirectly, by setting the cloudscape.database.sourceUser property. Where conditions are met (see The user Property: Reference), the value of this property is added to the user property in connection attributes for the target.

The user Property: Reference

When user authentication is turned on at the source, target refresh requests need to provide a valid user to make the JDBC connection. Cloudsync authenticates the refresh request based on the value of the property user returned by the refresh request's connection attributes (described in Target Connection Attributes).

Cloudscape determines the value of the property user for a refresh request's connection attributes in one of the following ways, in order of priority. (For example, number 3 overrides method number 4).

  1. refresh authentication callback

    The refresh authentication callback class sets the user property directly on the target's connection attributes in the method.

  2. servlet startup parameter (when using the Servlet API)

    The system administrator sets the user property as a servlet startup parameter to COM.cloudscape.core.ServletHandler. When systems are configured for refreshes through the servlet API, Cloudscape automatically adds the servlet's startup property user to all target refresh request's connection attributes.

  3. value of cloudscape.database.sourceUser set as a database-wide property at the source

    For all targets in all publications in the database, Cloudscape adds this property to targets' connection attributes

  4. value of cloudscape.database.sourceUser set as a system-wide property at the source

    For all targets in all publications in all the source's databases, Cloudscape adds this property to targets' connection attributes

  5. Value in the target's REFRESH PROPERTIES clause

    The target sets the property user directly in the PROPERTIES clause of the REFRESH command.

  6. value of cloudscape.database.sourceUser set at the target
  7. if one was provided, the user of the JDBC connection at the target