package com.atlassian.stash.internal.maintenance;

import com.atlassian.bitbucket.AuthorisationException;
import com.atlassian.bitbucket.permission.Permission;
import com.atlassian.bitbucket.user.ApplicationUser;

import javax.annotation.Nonnull;

/**
 * Provides a context for working with the {@link MaintenanceService#lock() maintenance lock}.
 *
 * @since 2.1
 */
public interface MaintenanceLock {
    /**
     * Retrieves the maintenance owner, which is the user who acquired the lock and started maintenance processing.
     *
     * @return the maintenance's owner
     */
    @Nonnull
    ApplicationUser getOwner();

    /**
     * Retrieves the token which can be used to {@link #unlock(String) unlock} the system.
     *
     * @return the unlock token
     */
    @Nonnull
    String getUnlockToken();

    /**
     * Releases the maintenance lock, restoring access to the system.
     * <p>
     * Note: While this method is available in unsecured contexts, it can only be called by users with
     * {@link Permission#SYS_ADMIN SYS_ADMIN} permissions.
     *
     * @param token the unlock token generated when the system was {@link MaintenanceService#lock() locked}
     * @throws AuthorisationException if the caller is not a SYS_ADMIN
     */
    void unlock(@Nonnull String token);
}
