API review request for RT-18980

[Anton V. Tarasov]

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();
}