When building your BDB XML application, you should consider how you will run recovery. If you are building a single threaded, single process application, it is fairly simple to run recovery when your application first opens its environment. In this case, you need only decide if you want to run recovery every time you open your application (recommended) or only some of the time, presumably triggered by a start up option controlled by your application's user.
However, for multi-threaded and multi-process applications, you need to carefully consider how you will design your application's startup code so as to run recovery only when it makes sense to do so.
If your application uses only one environment handle, then handling recovery for a multi-threaded application is no more difficult than for a single threaded application. You simply open the environment in the application's main thread, and then pass that handle to each of the threads that will be performing BDB XML operations. We illustrate this with our final example in this book (see Transaction Example for more information).
Alternatively, you can have each worker thread open its own environment handle. However, in this case, designing for recovery is a bit more complicated.
Generally, when a thread performing container operations fails or hangs, it is frequently best to simply restart the application and run recovery upon application startup as normal. However, not all applications can afford to restart because a single thread has misbehaved.
If you are attempting to continue operations in the face of a misbehaving thread, then at a minimum recovery must be run if a thread performing container operations fails or hangs.
Remember that recovery clears the environment of all outstanding locks, including any that might be outstanding from an aborted thread. If these locks are not cleared, other threads performing database operations can back up behind the locks obtained but never cleared by the failed thread. The result will be an application that hangs indefinitely.
To run recovery under these circumstances:
Suspend or shutdown all other threads performing database operations.
Discarding any open environment handles. Note that attempting to gracefully close these handles may be asking for trouble; the close can fail if the environment is already in need of recovery. For this reason, it is best and easiest to simply discard the handle.
Open new handles, running recovery as you open them. See Normal Recovery for more information.
Restart all your container threads.
A traditional way to handle this activity is to spawn a watcher thread that is responsible for making sure all is well with your threads, and performing the above actions if not.
However, in the case where each worker thread opens and maintains its own environment handle, recovery is complicated for two reasons:
For some applications and workloads, it might be worthwhile to give your database threads the ability to gracefully finalize any on-going transactions. If this is the case, your code must be capable of signaling each thread to halt BDB XML activities and close its environment. If you simply run recovery against the environment, your container threads will detect this and fail in the midst of performing their container operations.
Your code must be capable of ensuring only one thread runs recovery before allowing all other threads to open their respective environment handles. Recovery should be single threaded because when recovery is run against an environment, it is deleted and then recreated. This will cause all other processes and threads to "fail" when they attempt operations against the newly recovered environment. If all threads run recovery when they start up, then it is likely that some threads will fail because the environment that they are using has been recovered. This will cause the thread to have to re-execute its own recovery path. At best, this is inefficient and at worst it could cause your application to fall into an endless recovery pattern.
Frequently, BDB XML applications use multiple processes to interact with the containers. For example, you may have a long-running process, such as some kind of server, and then a series of administrative tools that you use to inspect and administer the underlying containers. Or, in some web-based architectures, different services are run as independent processes that are managed by the server.
In any case, recovery for a multi-process environment is complicated for two reasons:
In the event that recovery must be run, you might want to notify processes interacting with the environment that recovery is about to occur and give them a chance to gracefully terminate. Whether it is worthwhile for you to do this is entirely dependent upon the nature of your application. Some long-running applications with multiple processes performing meaningful work might want to do this. Other applications with processes performing container operations that are likely to be harmed by error conditions in other processes will likely find it to be not worth the effort. For this latter group, the chances of performing a graceful shutdown may be low anyway.
Unlike single process scenarios, it can quickly become wasteful for every process interacting with the containers to run recovery when it starts up. This is partly because recovery does take some amount of time to run, but mostly you want to avoid a situation where your server must reopen all its environment handles just because you fire up a command line container administrative utility that always runs recovery.
The following sections describe a mechanism that you can use to determine if and when you should run recovery in a multi-process application.
Before continuing, it is worth noting that the following sections describe recovery processes than can result in one process running recovery while other processes are currently actively performing container operations.
When this happens, the current container operation will abnormally fail, indicating a DB_RUNRECOVERY condition. This means that your application should immediately abandon any container operations that it may have on-going, discard any environment handles it has opened, and obtain and open new handles.
The net effect of this is that any writes performed by unresolved transactions will be lost. For persistent applications (servers, for example), the services it provides will also be unavailable for the amount of time that it takes to complete a recovery and for all participating processes to reopen their environment handles.
One way to handle multi-process recovery is for every process to "register" its environment. In doing so, the process gains the ability to see if any other applications are using the environment and, if so, whether they have suffered an abnormal termination. If an abnormal termination is detected, the process runs recovery; otherwise, it does not.
Note that using process registration also ensures that recovery is serialized across applications. That is, only one process at a time has a chance to run recovery. Generally this means that the first process to start up will run recovery, and all other processes will silently not run recovery because it is not needed.
To cause your application to register its environment, you specify
true to the EnvironmentConfig.setRegister()
method when you open your environment. You may also specify
true to EnvironmentConfig.setRunRecovery().
However, it is an error to specify true to
EnvironmentConfig.setRunFatalRecovery() when
you are also registering your environment with the setRegister()
method.
If during the open, BDB XML determines that recovery must be run, it will automatically run the correct
type of recovery for you, so long as you specify normal recovery
on your environment open. If you do not specify normal recovery, and you register your environment,
then no recovery is run if the registration process identifies a need for it. In this case,
the environment open simply fails by
throwing RunRecoveryException.
If you do not specify normal recovery when you open your first registered environment
in the application, then that application will fail the environment open by
throwing RunRecoveryException.
This is because the first process to register must create an internal
registration file, and recovery is forced when that file is created. To
avoid an abnormal termination of the environment open, specify recovery on
the environment open for at least the first process starting in your
application.
Be aware that there are some limitations/requirements if you want your various processes to coordinate recovery using registration:
There can be only one environment handle per environment per process. In the case of multi-threaded processes, the environment handle must be shared across threads.
All processes sharing the environment must use registration. If registration is not uniformly used across all participating processes, then you can see inconsistent results in terms of your application's ability to recognize that recovery must be run.