package com.atlassian.stash.internal.participant;

import javax.annotation.Nonnull;

/**
 * Common interface for managing participants on a participable entity.
 *
 * @since 2.11
 */
public interface InternalParticipable<P extends InternalParticipant> {

    /**
     * Accepts the provided {@link ParticipableVisitor visitor} and invokes the appropriate {@code visit} overload
     * for this participable type, returning its result.
     * <p>
     * Note: Nullability for the return value is intentionally not documented one way or another. It is expected that
     * the <i>caller</i> will know the nullability of the visitor implementation they are passing and code accordingly.
     *
     * @param visitor
     * @param <T> The object returned
     * @return the result of the invoked {@code visit} method
     */
    <T> T accept(@Nonnull ParticipableVisitor<T> visitor);

    /**
     * Adds the provided participant to the entity.
     *
     * @param participant the participant to add
     */
    void addParticipant(@Nonnull P participant);

    /**
     * Removes the specified participant from the entity, if they are participating.
     *
     * @param participant the participant to remove
     */
    void removeParticipant(@Nonnull P participant);
}
