API review request for RT-18980

[Anton V. Tarasov]

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.