Package com.atlassian.bitbucket.home

Interface HomeUpdateHandler

All Known Implementing Classes:
AbstractHomeUpdateHandler
public interface HomeUpdateHandler
Invoked when the 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 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.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    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.

  • Method Details

    • apply

      void apply(@Nonnull HomeUpdate update) throws com.atlassian.bitbucket.ServiceException
      Applies whatever changes are necessary to replace references to the old shared home directory location with references to the new one.

      Throwing a ServiceException indicates a required change could not be applied and will prevent the system from being unlocked. Processing stops at the first exception, so any handlers after the one which throws will be skipped.

      If a ServiceException is thrown, its localized message is shown to users. For any other RuntimeException, the standard message will be shown instead. Because the message will be displayed to users, including unauthenticated users, it should not contain any sensitive data. For example, file system paths should not be included. Instead, the message should contain a simple, high-level summary of the failure and more comprehensive details should be written to the log for review by administrators.

      Parameters:
      update - provides the old and new shared home directory locations
      Throws:
      com.atlassian.bitbucket.ServiceException - if changes cannot be applied

    • rollback

      void rollback(@Nonnull HomeUpdate update)
      Rolls back the applied changes, restoring references to the old shared home directory location. Rolling back updates is intended to allow the system to be restarted with the old shared home directory after updating to a new location fails.

      This method is only invoked on handlers which apply successfully. If apply(HomeUpdate) throws an exception, this method will not be called. Handlers are rolled back in reverse order, so A -> B -> C would roll back B -> A if handler C threw an exception.

      Implementations are encouraged not to throw exceptions, as there is nothing more the system can do beyond calling this method when apply fails. Failure cases should be handled internally and logged, rather than being propagated to the system.

      Parameters:
      update - provides the old and new shared home directory locations