CORAL Component documentation: FrontierAccess

Radovan Chytracek

CERN

December 2005


1. Introduction

1.1. Purpose of the component

The FrontierAccess package is a plugin library providing an implementation of the IRelationalDomain interface for accessing an Oracle database via distributed set of cache systems using Squid web-cache technology. The cache contents is populated via application server based on Frontier technology. The package is based on the Frontier client C/C++ API. Client application can retrieve data either connecting to application server directly or going via cache. The fail-over is also supported for the application servers as well as for the caches.

1.2. Known problem and restrictions

The package is for the moment tested against Oracle 9i & 10g database servers. Earlier server versions are not supported.

1.3. Repository of the component

:pserver:anonymoys@coral.cvs.cern.ch:/cvs/coral/coral/FrontierAccess

2. FrontierAccess Semantics

2.1. The logical data hierarchy

In order to connect to an Oracle database using Frontier one should specify a connection string which typically used to have the format as

    frontier://FrontierServerName:port/serviceBaseURL/SCHEMA_NAME
   
which gets translated automatically into valid Frontier URL in form:
    http://FrontierServerName:port/serviceBaseURL
   
where the port number is optional but one has to pay attention to it as the same connection string can differ only in port number which may indicate that the server is cache instead of an application server.

The schema name is in practice the user name of an oracle user. A user has access to the tables defined in the schema of another user for which all the relevant privileges have been granted. Frontier application server usually connects only via one acount, so when the tables are created in an Oracle database to which Frontier application server connects, then is required that the proper SELECT access rights on these tables are granted to the Frontier user, otherwise FrontierAccess will not work.

The FrontierAccess now decodes and passes down to the underlying frontier_client library the new conneciton string format which may look like:

    frontier://(proxyurl=http://srv.fnal.gov:3128)(proxyurl=http://srv15.fnal.gov:3128)
               (serverurl=http://frontier.cern.ch:8000/Frontier)(serverurl=http://frontier1.cern.ch:8000/Frontier)
               (retrieve-ziplevel=5)
              /SCHEMA_NAME
   
The complex connection string now contains all the parameters to let the frontier_client library to perform load-balancing and fail-over itself and configure the compression level used for data transfer.

2.2. Controlling Frontier-specific parameters

2.2.1. Refreshing cache contents

FrontierAccess is primarily going to access the cached information. There are, however, situations where it is not desired or a fresh information is needed. This typically happens when database schema has been updated. In order to make sure that FrontierAccess uses the most recent database objects it forces a cache to be refreshed for data dictionary queries. For the the data queries the cache access is enabled & preferred. In cases where there is a need to refresh cache contents due to updates in the back-end databases one can control the refresh behavior by using coral::IWebCacheControl API. This interface allows to inform the FrontierAccess plug-in to execute its queries with refresh parameter enabled, thus causing the refresh of all the Squid caches on the way up to a Frontier server. The access to the coral::IWebCacheControl interface is via coral::ConnectionService component. Once the web cache control handle is obtained one can force reloading of a whole database schema, e.g. the queries involving any table in the given schema will be executed with refresh enabled or one can do finer selection by registering specific table names so the FrontierAccess plug-in enables refresh only for the queries which involve any of the registred tables.

Imagine the following data source setup using CORAL data service lookup mechanism reading input from dblookup.xml file:

    
    <?xml version="1.0" ?>
     <servicelist>
       <logicalservice name="/coral/CoolFrontier">
         <service name="frontier://afrontier.cern.ch:8080/Frontier/CORAL" accessMode="readonly" />
       </logicalservice>
     <servicelist>
    
    
then the application code needs to do the following to switch on refresh for the all queries to schema CORAL as follows:
      // Locate the CORAL ConnectionService component
      seal::IHandle<coral::IConnectionService>
      connectionService = appcontext->query<coral::IConnectionService>( "CORAL/Services/ConnectionService" );
      // Setup refresh
      coral::IWebCacheControl& webcache = connectionService->webCacheControl();
      // Set refresh for the whole schema, e.g. each query in this schema will skip Squid cache
      // NOTE! One must specify the physical connection string as the plugins don't know about the logical ones!!!
      webcache.refreshSchemaInfo( "http://atlasfrontier.cern.ch:8080/Frontier" );
    
Please note the fact that one needs to specify the real physical connection string being actually used to connect to the Frontier server and with the "frontier://" prefix being already rewritten as "http://". The same applies for the new complex conneciton string syntax just the "http://" will not be there because is not needed anymore. One can select also the particular tables in the target schema to become subject to refresh for each query run against them. See the API of coral::IWebCacheControl interface.

2.2.2. Enabling Frontier client debug log

A user can trigger the more verbose log output, by setting the environment variable FRONTIER_LOG_LEVEL=Debug.

3. Implementation specifics

The package is based on the the Frontier client C/C++ API.

4. Related components

  • RelationalAccess, is the package where the CORAL abstract interfaces are defined.

  • CoralCommon, is the package where some developer-level interfaces and some common implementation classes are defined.

5. FrontierAccess Reference

5.1. Other environment variables

  • FRONTIER_LOG_LEVEL : if set to "Debug", it enables the debug log output for the frontier client.