API review request for RT-18980

[Richard Bair]

Hi Anton,

Looks cool! Some thoughts:

	- What if we call it WebHistory? I've been thinking we might add a "History" class at the app framework level at some point such that your app can have navigation history as well, so it would be nice to avoid a potential name class. Since we have WebView & WebEngine already, WebHistory seems appropriate.

	- Can the URL, Title, or Last Visited Date of an Entry change? That is, are they immutable properties? If not, we need to add some read only property methods so we can listen to changes
	- currentIndexProperty is missing (should be read only property) so that we can observe changes
	- Should rename asList method. This is a "getter", but doesn't follow the getter naming convention (so tools won't know how to use this). It seems like "getEntries" is the right name for it?
	- maxLengthProperty() should exist and be fully writable
	- the go(shift) method is interesting, just wondering why it is a shift vs. an index. Not important though I'm just curious.

Thanks!
Richard

On May 2, 2012, at 10:40 AM, Anton V. Tarasov wrote:

> Hi All,
> 
> Please review the new API for WebView [1]
> 
> JIRA: http://javafx-jira.kenai.com/browse/RT-18980
> 
> It introduces History class which could be used to view the browser session history and navigate through it.
> The class provides quite basic functionality enough to meet the requirements.
> 
> The javadoc as a draft and so it may be corrected lately.
> 
> Thanks,
> Anton.
> 
> [1]
> 
> package javafx.scene.web;
> 
> import javafx.collections.ObservableList;
> import java.net.URL;
> import java.util.Date;
> 
> /**
> * The {@code History} class represents a session history associated with
> * a {@link WebEngine} instance.
> *
> * There is a single instance of this class per {@code WebEngine} that
> * can be obtained via the {@link WebEngine#getHistory()} method.
> *
> * The {@link #asList()} method provides a view of the history in terms of a
> * list of entries. Each {@link Entry} represents a visited page and provides
> * access to relevant page info such as URL, title and visited date.
> *
> * The history and thus the list of entries change as {@code WebEngine} navigates
> * across the web. It may expand or shrink depending on browser actions. These
> * changes can be listened to with help of the {@link javafx.collections.ObservableList}
> * API that the list exposes.
> *
> * There is a notion of the current entry which is associated with the page currently
> * visited by {@code WebEngine}. Its index in the history list can be obtained via
> * a call to the {@link #getCurrentIndex()} method. The current index then can be used
> * to navigate to any entry in the history with help of the {@link #go(int)} method.
> * The simple {@link #goBack()} and {@link #goForward()} methods are convenient
> * methods to navigate one entry back and forward respectively.
> *
> * It is possible to limit the maximum history length, which is the length of the
> * history list, by means of the {@link #setMaxLength(int)} method.
> */
> public final class History {
> 
>    /**
>     * The {@code Entry} class represents a single entry in the session history.
>     * An entry instance is associated with a visited page.
>     */
>    public final class Entry {
> 
>        /**
>         * Returns the {@link java.net.URL} of the page.
>         *
>         * @return the url of the page
>         */
>        public URL getUrl();
> 
>        /**
>         * Returns the title of the page.
>         *
>         * @return the title of the page
>         */
>        public String getTitle();
> 
>        /**
>         * Returns the {@link java.util.Date} the page was last visited.
>         *
>         * @return last visited date
>         */
>        public Date getLastVisitedDate();
>    }
> 
>    /**
>     * Returns the index of the current {@code Entry} in the history
>     * in the range of [0..length-1]. The current entry is the entry
>     * that corresponds to the currently displayed page.
>     *
>     * @return index of the current {@code Entry} in the history
>     */
>    public int getCurrentIndex();
> 
>    /**
>     * Returns an unmodifiable observable list of all entries in the history.
>     * Changes in the history, such as addition or removal of entries, cause
>     * changes in the list.
>     *
>     * @return list of all entries in the history
>     */
>    public ObservableList<Entry> asList();
> 
>    /**
>     * Causes {@link WebView} to navigate to the page corresponding to
>     * the {@code Entry} within the specified position relative to the current
>     * entry. Negative (positive) {@code shift} value specifies the position
>     * left (right) to the current entry. For instance, -1 points to the previous
>     * entry and 1 points to the next entry.
>     *
>     * Zero {@code shift} value is silently ignored (no-op).
>     *
>     * The effective entry position should belong to the rage of [0..length-1],
>     * otherwise IndexOutOfBoundsException is thrown.
>     *
>     * @param shift negative (positive) value specifies a position relative
>     *        to the left (right) from the current entry, zero value causes
>     *        no effect
>     * @throws IndexOutOfBoundsException if the effective entry position is out
>     *         of range
>     */
>    public void go(int shift) throws IndexOutOfBoundsException;
> 
>    /**
>     * Causes {@link WebView} to navigate to the previous page in the
>     * history. A call to this method is equivalent to a {@code go(-1)} call.
>     * If the current entry is the first entry in the list, the call has no effect.
>     *
>     * @return true if the previous entry exists in the list, otherwise false
>     */
>    public boolean goBack();
> 
>    /**
>     * Causes {@link WebView} to navigate to the next page in the history.
>     * A call to this method is equivalent to a {@code go(1)} call.
>     * If the current entry is the last entry in the list, the call has no effect.
>     *
>     * @return true if the next entry exists in the list, otherwise false
>     */
>    public boolean goForward();
> 
>    /**
>     * Specifies the maximum length of the history list. When the list reaches
>     * its maximum and a subsequent entry is added to it, the first entry gets
>     * removed automatically.
>     *
>     * By default the maximum length is set to 100.
>     *
>     * @param length maximum length of the history list
>     * @see {@link #getMaxLength()}
>     */
>    public void setMaxLength(int length);
> 
>    /**
>     * Returns the maximum length of the history list.
>     *
>     * By default the maximum length is set to 100.
>     *
>     * @return maximum length of the history list
>     * @see {@link #setMaxLength()}
>     */
>    public int getMaxLength();
> }
> 
>