[jira] [Created] (TRINIDAD-2384) Need a notification mechanism for successful application of DocumentChange

["Prakash Udupa (JIRA)" <de...@myfaces.apache.org>]

Prakash Udupa created TRINIDAD-2384:
---------------------------------------

             Summary: Need a notification mechanism for successful application of DocumentChange
                 Key: TRINIDAD-2384
                 URL: https://issues.apache.org/jira/browse/TRINIDAD-2384
             Project: MyFaces Trinidad
          Issue Type: Improvement
          Components: Archetype
    Affects Versions: 2.0.1-core
            Reporter: Prakash Udupa



The usecase is of a ChangeManager implementation that delegate to one or more other ChangeManager implementation instances based on certain conditions. For example in Edit mode in a DesignTime at 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. This usecase needs these two new API:

1. Some mechanism for the ChangeManager delegate to notify the top level ChangeManager (the one registered in web.xml) whenever a document change is automatically created added to document in persistent store, this is so that the top level ChangeManager may choose to take actions like removing the change stored in session store, if any. This asks for the following 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. Some mechanism for the top level ChangeManager to know if the document change was applied successfully by the delegate ChangeManager. This asks for the following API:

  /**
   * 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;
  }

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira