1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2000,2008 Oracle. All rights reserved. 5 * 6 * $Id: EventHandler.java,v 1.9 2008/01/17 05:04:53 mjc Exp $ 7 */ 8package com.sleepycat.db; 9 10/* 11 * An interface class with prototype definitions of all event functions that 12 * can be called via the Berkeley DB event callback mechanism. 13 * A user can choose to implement the EventHandler class, and implement 14 * handlers for all of the event types. Or they could extend the 15 * EventHandlerAdapter class, and implement only those events relevant to 16 * their application. 17 */ 18/** 19An interface classs with prototype definitions of all event functions that 20can be called via the Berkeley DB event callback mechanism. 21<p> 22A user can choose to implement the EventHandler class, and implement handlers 23for all of the event types. Alternatively it is possible to extend the 24EventHandlerAdapter class, and implement only those events relevant to the 25specific application. 26<p> 27The {@link com.sleepycat.db.EnvironmentConfig#setEventHandler EnvironmentConfig.setEventHandler} is used to provide 28a mechanism for reporting event messages from the Berkeley DB library 29to the application. 30<p> 31Berkeley DB is not re-entrant. Callback functions should not attempt 32to make library calls (for example, to release locks or close open 33handles). Re-entering Berkeley DB is not guaranteed to work correctly, 34and the results are undefined. 35*/ 36public interface EventHandler { 37 /** 38 A callback function to be called when a panic event is sent from the Berkeley DB library. 39 <p> This event callback is received when an error occurs in the Berkeley DB 40 library where the only solution is to shut down the application and run 41 recovery. In such cases, the Berkeley DB methods will throw 42 {@link com.sleepycat.db.RunRecoveryException RunRecoveryException} exceptions. It is often easier to simply exit 43 the application when such errors occur, rather than gracefully return up 44 the stack. 45 <p> 46 When this callback is received the database environment has failed. All 47 threads of control in the database environment should exit the environment 48 and recovery should be run. 49 */ 50 public void handlePanicEvent(); 51 52 /** 53 A callback function to be called when a Replication Client event is sent 54 from the Berkeley DB library. 55 <p> 56 This event callback is received when this member of a replication group is 57 now a client site. 58 */ 59 public void handleRepClientEvent(); 60 61 /** 62 A callback function to be called when an event is sent from the 63 Berkeley DB library. 64 <p> 65 This event callback is received when this site has just won an election. An 66 Application using the Base replication API should arrange for a call to 67 the {@link com.sleepycat.db.Environment#startReplication Environment.startReplication} method after receiving this 68 event to, reconfigure the local environment as a replication master. 69 <p> 70 Replication Manager applications may safely igore this event. The 71 Replication Manager calls {@link com.sleepycat.db.Environment#startReplication Environment.startReplication} 72 automatically on behalf of the application when appropriate (resulting in 73 firing of the {@link com.sleepycat.db.EventHandler#handleRepMasterEvent EventHandler.handleRepMasterEvent} event). 74 */ 75 public void handleRepElectedEvent(); 76 77 /** 78 A callback function to be called when an event is sent from the 79 Berkeley DB library. 80 <p> 81 This event callback is received when this site is now the master site of 82 its replication group. It is the application's responsibility to begin 83 acting as the master environment. 84 */ 85 public void handleRepMasterEvent(); 86 87 /** 88 A callback function to be called when an event is sent from the 89 Berkeley DB library. 90 <p> 91 This event callback is received when the replication group of which this 92 site is a member has just established a new master; the local site is not 93 the new master. 94 @param envId 95 The environment ID of the new master site. 96 */ 97 public void handleRepNewMasterEvent(int envId); 98 99 /** 100 A callback function to be called when an event is sent from the 101 Berkeley DB library. 102 <p> 103 This event callback is received when the replication manager did not 104 receive enough acknowledgements (based on the acknowledgement policy 105 configured with {@link com.sleepycat.db.EnvironmentConfig#setReplicationManagerAckPolicy EnvironmentConfig.setReplicationManagerAckPolicy}) 106 to ensure a transaction's durability within the replication group. The 107 transaction will be flushed to the master's local disk storage for 108 durability. 109 */ 110 public void handleRepPermFailedEvent(); 111 112 /** 113 A callback function to be called when an event is sent from the 114 Berkeley DB library. 115 <p> 116 This event callback is received when the client has completed startup 117 synchronization and is now processing live log records received from the 118 master. 119 */ 120 public void handleRepStartupDoneEvent(); 121 122 /** 123 A callback function to be called when an event is sent from the 124 Berkeley DB library. 125 <p> 126 This event callback is received when a Berkeley DB write to stable storage 127 failed. 128 @param errorCode 129 If an operating system specific error code is available for the failure it 130 will be passed in the errorCode parameter. 131 */ 132 public void handleWriteFailedEvent(int errorCode); 133} 134