B Oracle RAC Fast Application Notification

Overview of Oracle RAC Fast Application Notification

The Oracle RAC Fast Application Notification (FAN) feature provides a simplified API for accessing FAN events through a callback mechanism. This mechanism enables application code to receive a callback when a FAN event occurs. These APIs are referred to as Oracle RAC FAN APIs in this appendix.

The Oracle RAC FAN APIs provide FAN event notification for developing more responsive applications that can take full advantage of Oracle Database HA features. If you do not want to use Universal Connection Pool, but want to work with FAN events implementing your own connection cache, then you should use Oracle RAC Fast Application Notification.

The Oracle RAC FAN APIs enable application code to receive and respond to FAN event notifications sent by Oracle RAC. This is achieved by enabling the code to respond to FAN events in the following way:

• Listening for Oracle RAC service down, service up, and node down events

• Listening for load balancing advisory events and responding to them

This feature exposes a subset of FAN events, which are the notifications sent by a cluster running Oracle RAC, to inform the subscribers about the configuration changes within the cluster. The supported FAN events are the following:

• Service up

  The service up events notify that the managed resources are up and available. The cluster sends service up events when a cluster managed Database service becomes active, that is, available to accept work on an instance within the cluster.

• Service down

  The service down events notify that the managed resources are down and currently not available for access. There are two kinds of service down events:

  • Events indicating that a particular instance of a service is down and the instance is no longer able to accept work.

  • Events indicating that all instances of a service are down and the service is no longer able to accept work.

  When the last instance of a service goes down, then the subscriber receives both events. The events may or may not arrive together.

• Node down

  The node down events notify that the Oracle RAC node identified by the host identifier is down and not reachable. The cluster sends node down events when a node is no longer able to accept work.

• Load balancing advisory

  The load balancing advisory events provide metrics for load balancing algorithms. Load balancing advisories are sent regularly to inform subscribers of the recommended distribution of work among the available nodes.

Installing and Configuring Oracle RAC Fast Application Notification

You can install the Oracle RAC FAN APIs by performing the following steps:

1. Download the simplefan.jar file from the following link

   http://www.oracle.com/technology/tech/java/sqlj_jdbc/index.html
   

2. Add the simplefan.jar file to the classpath.

3. Perform the following in your Java code:

   1. Get an instance of the FanManager class by using the getInstance method.

   2. Configure the event daemon using the configure method of the FanManager class. The configure method sets the following properties:

      onsNodes: A comma separated list of host:port pairs of ONS daemons that the ONS runtime in this Java VM should communicate with. The host in a host:port pair is the host name of a system running the ONS daemon. The port is the local port configuration parameter for that daemon.

      onsWalletFile: The path name of the ONS wallet file. The wallet file is the path to a local wallet file used by SSL to store SSL certificates. Same as wallet file configuration parameter to ONS daemon.

      onsWalletPassword: The password for accessing the ONS wallet file.

For a detailed description of the Oracle RAC FAN APIs, refer to Oracle Database RAC FAN Events Java API Reference.

# This is an example ons.config file
#
# The first three values are required
localport=4100
remoteport=4200
nodes=racnode1.example.com:4200,racnode2.example.com:4200

Using Oracle RAC Fast Application Notification

Example B-2 provides an example to use Oracle RAC Fast Application Notification in your code. This example code prints the event data to the standard output device.

This example code demonstrates sample usages of Oracle RAC FAN APIs by overloading the handleFanEvent method to accept different FAN event notifications as arguments. The example code also displays event data such as

• Name of the system sending the FAN event notification

• Timestamp of the FAN event notification

• Load status of the FAN event notification

...
...Properties props = new Properties();
props.putProperty(“serviceName”, “gl”);
FanSubscription sub = FanManager.getInstance().subscribe(props);
sub.addListener(new FanEventListener()) {
  public void handleFanEvent(ServiceDownEvent event) {
    try {
      System.out.println(event.getTimestamp());
      System.out.println(event.getServiceName());
      System.out.println(event.getDatabaseUniqueName());
      System.out.println(event.getReason());
      ServiceMemberEvent me = se.getServiceMemberEvent();
      if (me != null) {
        System.out.println(me.getInstanceName());
        System.out.println(me.getNodeName());
        System.out.println(me.getServiceMemberStatus());
      }
      ServiceCompositeEvent ce = se.getServiceCompositeEvent();
      if (ce != null) {
        System.out.println(ce.getServiceCompositeStatus());
      }
    }
    catch (Throwable t) {
      // handle all exceptions and errors
      t.printStackTrace(System.err);
    }
  }
  public void handleFanEvent(NodeDownEvent event) {
    try {
      System.out.println(event.getTimestamp());
      System.out.println(ne.getNodeName());
      System.out.println(ne.getIncarnation());
    }
    catch (Throwable t) {
      // handle all exceptions and errors
      t.printStackTrace(System.err);
    }
  }
  public void handleFanEvent(LoadAdvisoryEvent event) {
    try {
      System.out.println(event.getTimestamp());
      System.out.println(le.getServiceName());
      System.out.println(le.getDatabaseUniqueName());
      System.out.println(le.getInstanceName());
      System.out.println(le.getPercent());
      System.out.println(le.getServiceQuality());
      System.out.println(le.getLoadStatus());
    }
    catch (Throwable t) {
      // handle all exceptions and errors
      t.printStackTrace(System.err);
    }
  }
});

Implementing a Connection Cache

You must implement your own connection cache for using Oracle RAC FAN APIs. Consider the following points before you implement a connection cache using the Oracle RAC FAN APIs:

• Oracle RAC FAN APIs provide a minimal subset of FAN events.

• Oracle RAC FAN APIs support only ONS events. If you want your application to support corresponding supercluster events, then you may require additions to the subscription properties.

• Oracle RAC FAN APIs do not enable application code to send FAN events.