API review request for RT-18980

[Anton V. Tarasov]

Thanks for the review, Richard!

On 5/5/12 2:48 AM, Richard Bair wrote:
> 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.
>>