HomeUpdateHandler

Class Overview

Invoked when the com.atlassian.bitbucket.server.StorageService#getSharedHomeDir() shared home directory is updated. In general, it is a best practice not to move the shared home directory. However, for cases where a move is necessary, all registered handlers are invoked to allow components which depend on the absolute path to the shared home directory to update themselves to reflect its new location.

When a move is detected, the system locks access, including hosting operations such as push and pull, and invokes all registered update handlers. Handlers have no mechanism to prevent or revert the shared home directory change; that is configured outside of the application. However, if any registered handler throws an exception while applying the update, it will prevent the system from being unlocked again. The exception message will be displayed to unauthenticated users, so it should not contain sensitive information, such as file paths. It should provide a high-level message about what went wrong, but the detailed information about the failure should be written to the log files instead, to assist administrators in addressing the issue. When all handlers have been invoked, if no exceptions were thrown, the system is unlocked and access is restored.

When multiple HomeUpdateHandlers are registered, it is possible one or more handlers may apply their changes successfully before one fails. Successful handlers are rolled back, to allow them to undo the changes they applied. Handlers are strongly encouraged to implement rollback support. Doing so allows administrators to move the shared home directory back to its old location and start the system normally. Handlers are rolled back in reverse order from how they are applied, and the handler that failed is not rolled back.

Consider the following scenario:

• 4 HomeUpdateHandlers have been registered
• Handler 1 applies all of its changes successfully
• Handler 2 applies all of its changes successfully
• Handler 3 applies some changes successfully, then one change fails and it throws a custom ServiceException
  • Handler 3 is not rolled back
  • Handler 2 is rolled back
  • Handler 1 is rolled back
• Handler 4 is never applied

After the failure, administrators have two options:

1. Fix the issue which caused the failure and restart the system still using the new location
   • HomeUpdateHandlers are invoked again to try and apply the update
2. Move the shared home directory back and restart the system using the old location
   • HomeUpdateHandlers are not invoked on startup, because the shared home directory has not moved
   • In this scenario, if Handler 1 or Handler 2 did not implement rollback support, simply moving the shared home directory back to its old location would likely cause obscure failures because the updates that were applied mean some aspects of the system now expect the new location where others still expect the old one.

In addition to simple path changes, where a shared home directory is moved to a new location on the same machine, it is also possible that the operating system was changed as well. Implementations must not assume that the old and new paths provided by the update are both for the same operating system.

Note: Due to change of the home directory structure, this class is updated to work on the shared home (where the data directory will live from now on). When the directory structure is upgraded the associated HomeUpdateHandler will be invoked to prepare the instance after the upgrade.

Summary

Public Methods
void	apply(HomeUpdate update) Applies whatever changes are necessary to replace references to the old shared home directory location with references to the new one.
void	rollback(HomeUpdate update) Rolls back the applied changes, restoring references to the old shared home directory location.