RELEASE_2_1_13/src/blocks/forms/java/org/apache/cocoon/forms/formmodel/Form.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.cocoon.forms.formmodel;

import java.util.HashSet;
import java.util.Locale;
import java.util.Set;

import org.apache.cocoon.forms.FormContext;
import org.apache.cocoon.forms.event.FormHandler;
import org.apache.cocoon.forms.event.ProcessingPhase;
import org.apache.cocoon.forms.event.ProcessingPhaseEvent;
import org.apache.cocoon.forms.event.ProcessingPhaseListener;
import org.apache.cocoon.forms.event.WidgetEvent;
import org.apache.cocoon.forms.event.WidgetEventMulticaster;
import org.apache.cocoon.forms.validation.ValidationError;
import org.apache.cocoon.forms.validation.ValidationErrorAware;
import org.apache.commons.collections.list.CursorableLinkedList;
import org.apache.commons.lang.BooleanUtils;
import org.apache.commons.lang.StringUtils;

/**
 * A widget that serves as a container for other widgets, the top-level widget in
 * a form description file.
 *
 * @version $Id$
 */
public class Form extends AbstractContainerWidget
                  implements ValidationErrorAware {

    /** Form parameter containing the submit widget's id */
    public static final String SUBMIT_ID_PARAMETER = "forms_submit_id";

    private static final String FORM_EL = "form";

    private final FormDefinition definition;

    /**
     * If non-null, indicates that form processing should terminate at the end of the current phase.
     * If true, interaction with the form is finished. It doesn't imply that the form is valid though.
     * If false, interaction isn't finished and the form should be redisplayed (processing was triggered
     * by e.g. and action or a field with event listeners).
     */
    private Boolean endProcessing;
    private Locale locale = Locale.getDefault();
    private FormHandler formHandler;
    private Widget submitWidget;
    private boolean isValid;
    private ProcessingPhaseListener listener;

    //In the "readFromRequest" phase, events are buffered to ensure that all widgets had the chance
    //to read their value before events get fired.
    private boolean bufferEvents;
    private CursorableLinkedList events;

    /** Widgets that need to be updated in the client when in AJAX mode */
    private Set updatedWidgets;

    /** Widgets that have at least one descendant that has to be updated */
    private Set childUpdatedWidgets;

    /** Optional id which overrides the value from the form definition */
    private String id;


    public Form(FormDefinition definition) {
        super(definition);
        this.definition = definition;
        this.listener = definition.getProcessingPhaseListener();
    }

    /**
     * Initialize the form by recursively initializing all its children. Any events occuring within the
     * initialization phase are buffered and fired after initialization is complete, so that any action
     * from a widget on another one occurs after that other widget has been given the opportunity to
     * initialize itself.
     */
    public void initialize() {
        try {
            // Start buffering events
            this.bufferEvents = true;
            super.initialize();
            // Fire events, still buffering them: this ensures they will be handled in the same
            // order as they were added.
            fireEvents();
        } finally {
            // Stop buffering events
            this.bufferEvents = false;
        }
    }

    public WidgetDefinition getDefinition() {
        return this.definition;
    }

    /**
     * Events produced by child widgets should not be fired immediately, but queued in order to ensure
     * an overall consistency of the widget tree before being handled.
     *
     * @param event the event to queue
     */
    public void addWidgetEvent(WidgetEvent event) {

        if (this.bufferEvents) {
            if (this.events == null) {
                this.events = new CursorableLinkedList();
            }

            // FIXME: limit the number of events to detect recursive event loops ?
            this.events.add(event);
        } else {
            // Send it right now
            event.getSourceWidget().broadcastEvent(event);
        }
    }

    /**
     * Mark a widget as being updated. When it Ajax mode, only updated widgets will be redisplayed
     *
     * @param widget the updated widget
     * @return <code>true</code> if this widget was added to the list (i.e. wasn't alredy marked for update)
     */
    public boolean addWidgetUpdate(Widget widget) {
        if (this.updatedWidgets != null) {
            if (this.updatedWidgets.add(widget.getRequestParameterName())) {
                // Wasn't already there: register parents
                Widget parent = widget.getParent();
                while (parent != this && parent != null) {
                    if (this.childUpdatedWidgets.add(parent.getRequestParameterName())) {
                        parent = parent.getParent();
                    } else {
                        // Parent already there, and therefore its own parents.
                        break;
                    }
                }
                return true;
            }
        }
        return false;
    }

    public Set getUpdatedWidgetIds() {
        return this.updatedWidgets;
    }

    public Set getChildUpdatedWidgetIds() {
        return this.childUpdatedWidgets;
    }

    /**
     * Fire the events that have been queued.
     * Note that event handling can fire new events.
     */
    private void fireEvents() {
        if (this.events != null) {
            try {
                CursorableLinkedList.Cursor cursor = this.events.cursor();
                while (cursor.hasNext()) {
                    WidgetEvent event = (WidgetEvent) cursor.next();
                    event.getSourceWidget().broadcastEvent(event);
                    if (formHandler != null) {
                        formHandler.handleEvent(event);
                    }
                }
                cursor.close();
            } finally {
                this.events.clear();
            }
        }
    }

    /**
     * Inform the form that the values will be loaded.
     */
    public void informStartLoadingModel() {
        // nothing to do here
        // TODO - we could remove this method?
    }

    /**
     * Inform the form that the values are loaded.
     */
    public void informEndLoadingModel() {
        // Notify the end of the load phase
        if (this.listener != null) {
            this.listener.phaseEnded(new ProcessingPhaseEvent(this, ProcessingPhase.LOAD_MODEL));
        }
    }

    /**
     * Inform the form that the values will be saved.
     */
    public void informStartSavingModel() {
        // nothing to do here
        // TODO - we could remove this method?
    }

    /**
     * Inform the form that the values are saved.
     */
    public void informEndSavingModel() {
        // Notify the end of the save phase
        if (this.listener != null) {
            this.listener.phaseEnded(new ProcessingPhaseEvent(this, ProcessingPhase.SAVE_MODEL));
        }
    }

    /**
     * Get the locale to be used to process this form.
     *
     * @return the form's locale.
     */
    public Locale getLocale() {
        return this.locale;
    }

    /**
     * Get the widget that triggered the current processing. Note that it can be any widget, and
     * not necessarily an action or a submit.
     *
     * @return the widget that submitted this form.
     */
    public Widget getSubmitWidget() {
        return this.submitWidget;
    }

    /**
     * Set the widget that triggered the current form processing.
     *
     * @param widget the widget
     */
    public void setSubmitWidget(Widget widget) {
        if (this.submitWidget == widget) {
            return;
        }

        if (this.submitWidget != null) {
            throw new IllegalStateException("Submit widget already set to " + this.submitWidget +
                                            ". Cannot set also " + widget);
        }

        // Check that the submit widget is active
        if (widget.getCombinedState() != WidgetState.ACTIVE) {
            throw new IllegalStateException("Widget " + widget + " that submitted the form is not active.");
        }

        // If the submit widget is not an action (e.g. a field with an event listener),
        // we end form processing after the current phase and redisplay the form.
        // Actions (including submits) will call endProcessing() themselves and it's their
        // responsibility to indicate how form processing should continue.
        if (!(widget instanceof Action)) {
            endProcessing(true);
        }
        this.submitWidget = widget;
    }

    public boolean hasFormHandler() {
       return (this.formHandler != null);
    }

    public void setFormHandler(FormHandler formHandler) {
        this.formHandler = formHandler;
    }

    public void addProcessingPhaseListener(ProcessingPhaseListener listener) {
        this.listener = WidgetEventMulticaster.add(this.listener, listener);
    }

    public void removeProcessingPhaseListener(ProcessingPhaseListener listener) {
        this.listener = WidgetEventMulticaster.remove(this.listener, listener);
    }

    /**
     * Processes a form submit. If the form is finished, i.e. the form should not be redisplayed to the user,
     * then this method returns true, otherwise it returns false. To know if the form was sucessfully
     * validated, use the {@link #isValid()} method.
     * <p>
     * Form processing consists in multiple steps:
     * <ul>
     *  <li>all widgets read their value from the request (i.e.
     *      {@link #readFromRequest(FormContext)} is called recursively on
     *       the whole widget tree)
     *  <li>if there is an action event, call the FormHandler
     *  <li>perform validation.
     * </ul>
     * This processing can be interrupted by the widgets (or their event listeners) by calling
     * {@link #endProcessing(boolean)}.
     * <p>
     * Note that this method is synchronized as a Form is not thread-safe. This should not be a
     * bottleneck as such concurrent requests can only happen for a single user.
     */
    public synchronized boolean process(FormContext formContext) {
        // Is this an AJAX request?
        if (formContext.getRequest().getParameter("cocoon-ajax") != null) {
            this.updatedWidgets = new HashSet();
            this.childUpdatedWidgets = new HashSet();
        }

        // Fire the binding phase events
        fireEvents();

        // setup processing
        this.submitWidget = null;
        this.locale = formContext.getLocale();
        this.endProcessing = null;
        this.isValid = false;

        // Notify the end of the current phase
        if (this.listener != null) {
            this.listener.phaseEnded(new ProcessingPhaseEvent(this, ProcessingPhase.PROCESSING_INITIALIZE));
        }

        try {
            // Start buffering events
            this.bufferEvents = true;
            this.submitWidget = null;

            doReadFromRequest(formContext);

            // Find the submit widget, if not an action
            // This has to occur after reading from the request, to handle stateless forms
            // where the submit widget is recreated when the request is read (e.g. a row-action).

            // Note that we don't check this if the submit widget was already set, as it can cause problems
            // if the user triggers submit with an input (which sets 'forms_submit_id'), then clicks back
            // and submits using a regular submit button.
            if (getSubmitWidget() == null) {
                String submitId = formContext.getRequest().getParameter(SUBMIT_ID_PARAMETER);
                if (!StringUtils.isEmpty(submitId)) {
                    // if the form has an ID, it is used as part of the submitId too and must be removed
                    if(!StringUtils.isEmpty(this.getId())) {
                        submitId = submitId.substring(submitId.indexOf('.')+1);
                    }
                    Widget submit = this.lookupWidget(submitId.replace('.', '/'));
                    if (submit == null) {
                        throw new IllegalArgumentException("Invalid submit id (no such widget): " + submitId);
                    }
                    setSubmitWidget(submit);
                }
            }

            // Fire events, still buffering them: this ensures they will be handled in the same
            // order as they were added.
            fireEvents();

        } finally {
            // No need for buffering in the following phases
            this.bufferEvents = false;
        }

        // Notify the end of the current phase
        if (this.listener != null) {
            this.listener.phaseEnded(new ProcessingPhaseEvent(this, ProcessingPhase.READ_FROM_REQUEST));
        }

        if (this.endProcessing != null) {
            return this.endProcessing.booleanValue();
        }

        return validate();
    }

    /**
     * End the current form processing after the current phase.
     *
     * @param redisplayForm indicates if the form should be redisplayed to the user.
     */
    public void endProcessing(boolean redisplayForm) {
        // Set the indicator that terminates the form processing.
        // If redisplayForm is true, interaction is not finished and process() must
        // return false, hence the negation below.
        this.endProcessing = BooleanUtils.toBooleanObject(!redisplayForm);
    }

    /**
     * Was form validation successful ?
     *
     * @return <code>true</code> if the form was successfully validated.
     */
    public boolean isValid() {
        return this.isValid;
    }

    public void readFromRequest(FormContext formContext) {
        throw new UnsupportedOperationException("Please use Form.process()");
    }

    private void doReadFromRequest(FormContext formContext) {
        // let all individual widgets read their value from the request object
        super.readFromRequest(formContext);
    }

    /**
     * Set a validation error on this field. This allows the form to be externally marked as invalid by
     * application logic.
     *
     * @return the validation error
     */
    public ValidationError getValidationError() {
        return this.validationError;
    }

    /**
     * set a validation error
     */
    public void setValidationError(ValidationError error) {
        this.validationError = error;
    }

    /**
     * Performs validation phase of form processing.
     */
    public boolean validate() {
        // Validate the form
        this.isValid = super.validate();

        // FIXME: Is this check needed, before invoking the listener?
        if (this.endProcessing != null) {
            this.wasValid = this.endProcessing.booleanValue();
            return this.wasValid;
        }

        // Notify the end of the current phase
        if (this.listener != null) {
            this.listener.phaseEnded(new ProcessingPhaseEvent(this, ProcessingPhase.VALIDATE));
        }

        if (this.endProcessing != null) {
            // De-validate the form if one of the listeners asked to end the processing
            // This allows for additional application-level validation.
            this.isValid = false;
            this.wasValid = this.endProcessing.booleanValue();
            return this.wasValid;
        }

        this.wasValid = this.isValid && this.validationError == null;
        return this.wasValid;
    }

    public String getXMLElementName() {
        return FORM_EL;
    }

    /**
     * @see org.apache.cocoon.forms.formmodel.AbstractWidget#getId()
     */
    public String getId() {
        if (this.id != null) {
            return this.id;
        }
        return super.getId();
    }

    /**
     * Set the optional id.
     * @param value A new id.
     */
    public void setId(String value) {
        this.id = value;
    }
}