[TRINIDAD] [API] [TRINIDAD-2384] Need a notification mechanism for successful application of DocumentChange

[Prakash Udupa]

Hi,

Please review the proposed API to solve the following TRINIDAD JIRA:
[TRINIDAD-2384] Need a notification mechanism for successful application of 
DocumentChange
https://issues.apache.org/jira/browse/TRINIDAD-2384

Requirement:
----------------

The usecase is of a ChangeManager implementation that delegates to one or more other ChangeManager implementation 
instances based on certain conditions. For example in "Edit" mode in a DesignTime @ RunTime application, the delegate 
could be a ChangeManager implementation that can store changes in documents in persistent store, whereas in "View" mode, 
it could delegate to SessionChangeManager. There is need for the delegating ChangeManger to know if the delegate 
successfully applied a document change, and also notify if the delegate auto-converted a ComponentChange to a 
DocumentChange and added it (so that the top level ChangeManager can take any actions if interested - For example if a 
DocumentChange is persisted to a persistent store, any previously added ComponentChange for the same component and 
attribute can be removed).

New API proposed:
----------------------

1. Notification API.

  /**
   * This method is called on the registered ChangeManager if a ChangeManager 
in its
   * addComponentChange() implementation automatically creates an equivalent 
DocumentChange and
   * applies the change. The registered ChangeManager may choose to take some 
action based on
   * the outcome of applying the document change. For example, session based 
ChangeManager
   * implementations may choose to remove any earlier added ComponentChange if 
an equivalent
   * document change is now successfully applied
   *
   * @param component The target UIComponent instance for which the 
DocumentChange was applied
   * @param componentChange The ComponentChange for which an equivalent 
DocumentChange was applied
   *
   * @return The outcome of handling this notification
   *
   * @throws IllegalArgumentException if the supplied ComponentChange is null.
   */
  public NotificationOutcome documentChangeApplied(
    FacesContext facesContext,
    UIComponent component,
    ComponentChange componentChange)

  /**
   * Indicates whether the notification was handled:
   * 1. HANDLED - Notification was handled
   * 2. NOT_HANDLED - Notification was not handled
   *
   * @see #documentChangeApplied(FacesContext, UIComponent, ComponentChange)
   */
  public static enum NotificationOutcome
  {
    HANDLED,
    NOT_HANDLED;
  }

2. API that lets the caller know if the DocumentChange was successfully applied

  /**
   * Add a DocumentChange for a specified component, and return the outcome of 
adding the change.
   *
   * @param facesContext The FacesContext instance for the current request
   * @param uiComponent The UIComponent instance for which the DocumentChange 
is to be added
   * @param change The DocumentChange to be added
   *
   * @return The outcome of adding the document change
   *
   * @throws IllegalArgumentException if any of the supplied parameters were to
   * be null.
   *
   * @see ChangeOutcome
   */
  public ChangeOutcome addDocumentChangeWithOutcome(
    FacesContext facesContext,
    UIComponent uiComponent,
    DocumentChange change)

  /**
   * Indicates the outcome of the attempt to apply a Change. Possible outcomes 
are:
   * 1. UNKNOWN - We do not know if the change was applied or not
   * 2. CHANGE_APPLIED - Change was successfully applied
   * 3. CHANGE_NOT_APPLIED - There was a failure when applying the Change
   *
   * @see #addDocumentChangeWithOutcome(FacesContext,UIComponent,DocumentChange)
   */
  public static enum ChangeOutcome
  {
    UNKNOWN,
    CHANGE_APPLIED,
    CHANGE_NOT_APPLIED;
  }

Thanks,
Prakash