API review request for RT-18980

[Richard Bair]

Looks good to me!

On May 4, 2012, at 3:20 PM, Anton V. Tarasov wrote:

> Hi, Richard,
> 
> On 5/3/12 10:51 PM, Richard Bair wrote:
>>>> 	- 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.
>>> Am I right, that you're talking about _another_ History class that you're planning to add to public API? (If so, I'm just curious what kind of history it's to present?)
>>> Anyway, WebHistory name is fine for sure.
>> Ya, and not necessarily something to be added in the near future (pending app framework discussions). See JFXFlow and Ensemble for examples. In these cases the application is built of "pages" -- although not HTML pages the concept is the same. You can also have history in Ensemble and hit back / forward buttons. So it isn't about navigating from one web page to another, but from one "screen" or page in your application to another.
>> 
> Ok, I see. Thanks for the details.
> 
> 
>>> So, I'll make the API conform to FX concepts according to your suggestions.
>> Sounds good! Can you just post another message with the updated API when it is completed?
>> 
> 
> Sure! =) Below is the updated version. Please, share your thoughts if you have any other ideas.
> 
> /**
> * The {@code WebHistory} 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 history is basically a list of entries each of them represents a visited page
> * and provides access to relevant page info such as URL, title and visited date.
> * The list can be obtained with help of the {@link #getEntries()} method.
> *
> * 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 is represented by the
> * {@link currentIndexProperty}. The current index 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 size, which is the size of the
> * history list, by means of the {@link maxSizeProperty()}.
> */
> public final class WebHistory {
> 
>    /**
>     * 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();
> 
>        /**
>         * Defines the title of the page.
>         */
>        public ReadOnlyObjectProperty<String> titleProperty();
> 
>        public String getTitle();
> 
>        /**
>         * Defines the {@link java.util.Date} the page was last visited.
>         */
>        public ReadOnlyObjectProperty<Date> lastVisitedDateProperty();
> 
>        public Date getLastVisitedDate();
>    }
> 
>    /**
>     * Defines the index of the current {@code Entry} in the history.
>     * The current entry is the entry associated with the currently displayed page.
>     * The index belongs to the range (<tt>index &gt;= 0 && index &lt; getEntries().size()</tt>)
>     */
>    public ReadOnlyIntegerProperty currentIndexProperty();
> 
>    public int getCurrentIndex();
> 
>    /**
>     * Defines the maximum size of the history list.
>     * If the list reaches its maximum and a new entry is added to the history,
>     * the first entry gets removed automatically.
>     * <p>
>     * A value of less than 0 will be treated as 0.
>     *
>     * @defaultValue 100
>     */
>    public IntegerProperty maxSizeProperty();
> 
>    public void setMaxSize(int value);
> 
>    public int getMaxSize();
> 
>    /**
>     * Returns an unmodifiable observable list of all entries in the history.
>     *
>     * @return list of all history entries
>     */
>    public ObservableList<Entry> getEntries();
> 
>    /**
>     * 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();
> }
> 
> ---
> Thanks,
> Anton.
>