Class Overview
Invoked when the com.atlassian.stash.server.ApplicationPropertiesService#getHomeDir() home directory is
updated. In general, it is a best practice not to move the 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 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 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
HomeUpdateHandler
s 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 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
HomeUpdateHandler
s 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 com.atlassian.stash.exception.ServiceException ServiceException
- Handler 4 is never
applied
After the failure, administrators have two options:
- Fix the issue which caused the failure and restart the system still using the new location
HomeUpdateHandler
s are invoked again to try and apply the update
- Move the home directory back and restart the system using the old location
HomeUpdateHandler
s are not invoked on startup, because the home directory has not moved
- In this scenario, if Handler 1 or Handler 2 did not implement
rollback
support
, simply moving the 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 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.