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

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 2.0.1-core
• Fix Version/s: 2.1.0-core
• Component/s: Archetype
• Assignee: Gabrielle Crawford
• Reporter: Prakash Udupa
• Created: 13/May/13 20:04
• Updated: 17/May/13 20:33
• Resolved: 17/May/13 20:33

Description

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