package org.litesoft.GWT.client.historian;

import com.google.gwt.event.logical.shared.*;
import com.google.gwt.user.client.*;

/**
 * Interface to History related events. Provides nice
 * isolation for unit testing, and allows pre- or post-processing of tokens.
 * Methods correspond to the like named methods on {@link History}.
 */
public interface Historian {
    /**
     * Adds a {@link com.google.gwt.event.logical.shared.ValueChangeEvent}
     * handler to be informed of changes to the browser's history stack.
     * <p/>
     * Note: As this message does NOT return the Handler Registration, once registered there is not way to remove it.
     */
    void addValueChangeHandler( ValueChangeHandler<String> valueChangeHandler );

    /**
     * @return the current token.
     */
    String getToken();

    /**
     * Programmatic equivalent to the user pressing the browser's 'back' button.
     * <p/>
     * Note that this does not work correctly on Safari 2.
     */
    void back();

    /**
     * Adds a new browser history entry. Calling this method will cause
     * {@link ValueChangeHandler#onValueChange(ValueChangeEvent)}
     * to be called as well.
     */
    void newItem( String token, boolean issueEvent );
}