RELEASE_2_1_13/src/blocks/forms/java/org/apache/cocoon/forms/util/WidgetFinder.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.util;

import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.apache.cocoon.forms.event.RepeaterEvent;
import org.apache.cocoon.forms.event.RepeaterEventAction;
import org.apache.cocoon.forms.event.RepeaterListener;
import org.apache.cocoon.forms.event.WidgetEventMulticaster;
import org.apache.cocoon.forms.formmodel.Repeater;
import org.apache.cocoon.forms.formmodel.Widget;
import org.apache.commons.lang.StringUtils;

/**
 * An utility class to manage list of widgets.
 * 
 * <p>
 * The {@link org.apache.cocoon.forms.formmodel.Widget#lookupWidget(String)} method is able
 * to only return one widget, while this class returns a list of widgets. It uses a path syntax containing a /./,
 * <code>repeater/./foo</code>, which repreesents all the instances of the foo widget inside the repeater,
 * one per row. Note that it also supports finding a widgets inside multi level repeaters, something like 
 * invoices/./movements/./amount or courseYears/./exams/./preparatoryCourses/./title . 
 * </p>
 * <p>
 * Class has been designed to offer good performances, since the widget list is built only once and
 * is automatically updated when a repeater row is added or removed.
 * {@link org.apache.cocoon.forms.event.RepeaterListener}s can be attached directly to receive notifications
 * of widget additions or removals. 
 * </p>
 * <p>
 * This class is used in {@link org.apache.cocoon.forms.formmodel.CalculatedField}s and 
 * {@link org.apache.cocoon.forms.formmodel.CalculatedFieldAlgorithm}s. 
 * </p>
 * @version $Id$
 */
public class WidgetFinder {

    private boolean keepUpdated = false;
   
    // Holds all the widgets not child of a repeater.
    private List noRepeaterWidgets = null;
    // Map repeater -> Set of Strings containing paths
    private Map repeaterPaths = null;
    // Map repeater -> Set of Widgets
    private Map repeaterWidgets = null;
    // A List of recently added widgets, will get cleared when getNewAdditions is called.
    private List newAdditions = new ArrayList();
    
    private RefreshingRepeaterListener refreshingListener = new RefreshingRepeaterListener();
    
    private RepeaterListener listener;
    
    /**
     * Searches for widgets. It will iterate on the given paths and find all
     * corresponding widgets. If a path is in the forms repeater/* /widget
     * then all the rows of the repeater will be iterated and subwidgets
     * will be fetched. 
     * @param context The context widget to start from.
     * @param paths An iterator of Strings containing the paths.
     * @param keepUpdated If true, listeners will be installed on repeaters
     * to keep lists updated without polling.
     */
    public WidgetFinder(Widget context, Iterator paths, boolean keepUpdated) {
        this.keepUpdated = keepUpdated;
        while (paths.hasNext()) {
            String path= (String)paths.next();
            path = toAsterisk(path);
            if (path.indexOf('*') == -1) {
                addSimpleWidget(context, path);
            } else {
                recurseRepeaters(context, path, true);
            }
        }
    }
    
    /**
     * Searches for widgets. If path is in the forms repeater/* /widget
     * then all the rows of the repeater will be iterated and subwidgets
     * will be fetched. 
     * @param context The context widget to start from.
     * @param path Path to search for..
     * @param keepUpdated If true, listeners will be installed on repeaters
     * to keep lists updated without polling.
     */
    public WidgetFinder(Widget context, String path, boolean keepUpdated) {
        path = toAsterisk(path);
        this.keepUpdated = keepUpdated;
        if (path.indexOf('*') == -1) {
            addSimpleWidget(context, path);
        } else {
            recurseRepeaters(context, path, true);
        }        
    }

    private String toAsterisk(String path) {
        return StringUtils.replace(path, "/./", "/*/");
    }

    /**
     * Recurses a repeater path with asterisk.
     * @param context The context widget.
     * @param path The path.
     */
    private void recurseRepeaters(Widget context, String path, boolean root) {
        String reppath = path.substring(0, path.indexOf('*') - 1);
        String childpath = path.substring(path.indexOf('*') + 2);
        Widget wdg = context.lookupWidget(reppath);
        if (wdg == null) {
            if (root) {
                throw new IllegalArgumentException("Cannot find a repeater with path " + reppath + " relative to widget " + context.getName());
            } else {
                return;
            }
        }
        if (!(wdg instanceof Repeater)) {
            throw new IllegalArgumentException("The widget with path " + reppath + " relative to widget " + context.getName() + " is not a repeater!");
        }
        Repeater repeater = (Repeater)wdg;
        if (context instanceof Repeater.RepeaterRow) {
            // Add this repeater to the repeater widgets
            addRepeaterWidget((Repeater) context.getParent(), repeater);
        }
        
        addRepeaterPath(repeater, childpath);
        if (childpath.indexOf('*') != -1) {
            for (int i = 0; i < repeater.getSize(); i++) {
                Repeater.RepeaterRow row = repeater.getRow(i);
                recurseRepeaters(row, childpath, false);
            }
        } else {
            for (int i = 0; i < repeater.getSize(); i++) {
                Repeater.RepeaterRow row = repeater.getRow(i);
	            Widget okwdg = row.lookupWidget(childpath);
	            if (okwdg != null) {
	                addRepeaterWidget(repeater, okwdg);
	            }
            }
        }
    }
    
    /**
     * Adds to the list a widget descendant of a repeater.
     * @param repeater The repeater.
     * @param okwdg The widget.
     */
    private void addRepeaterWidget(Repeater repeater, Widget okwdg) {
        if (this.repeaterWidgets == null) this.repeaterWidgets = new HashMap();
        Set widgets = (Set) this.repeaterWidgets.get(repeater);
        if (widgets == null) {
            widgets = new HashSet();
            this.repeaterWidgets.put(repeater, widgets);
        }
        widgets.add(okwdg);
        newAdditions.add(okwdg);
    }

    /**
     * Adds a repeater monitored path.
     * @param repeater The repeater.
     * @param childpath The child part of the path.
     */
    private void addRepeaterPath(Repeater repeater, String childpath) {
        if (this.repeaterPaths == null) this.repeaterPaths = new HashMap();
        Set paths = (Set) this.repeaterPaths.get(repeater);
        if (paths == null) {
            paths = new HashSet();
            this.repeaterPaths.put(repeater, paths); 
            if (keepUpdated) repeater.addRepeaterListener(refreshingListener);
        }
        paths.add(childpath);
    }

    /**
     * Called when a new row addition event is received from a monitored repeater.
     * @param repeater The repeated that generated the event.
     * @param index The new row index.
     */
    protected void refreshForAdd(Repeater repeater, int index) {
        Repeater.RepeaterRow row = repeater.getRow(index);
        if (this.repeaterPaths == null) this.repeaterPaths = new HashMap();
        Set paths = (Set) this.repeaterPaths.get(repeater);
        for (Iterator iter = paths.iterator(); iter.hasNext();) {
            String path = (String) iter.next();
            if (path.indexOf('*') != -1) {
                recurseRepeaters(row, path, false);
            } else {
                Widget wdg = row.lookupWidget(path);
                if (wdg == null) {
                    throw new IllegalStateException("Even after row addition cannot find a widget with path " + path + " in repeater " + repeater.getName());
                }
                addRepeaterWidget(repeater, wdg);
            }
        }
    }
    
    /**
     * Called when a row deletion event is received from a monitored repeater.
     * @param repeater The repeated that generated the event.
     * @param index The deleted row index.
     */
    protected void refreshForDelete(Repeater repeater, int index) {
        Repeater.RepeaterRow row = repeater.getRow(index);
        Set widgets = (Set) this.repeaterWidgets.get(repeater);
        for (Iterator iter = widgets.iterator(); iter.hasNext();) {
            Widget widget = (Widget) iter.next();
            boolean ischild = false;
            Widget parent = widget.getParent();
            while (parent != null) {
                if (parent == row) {
                    ischild = true;
                    break;
                }
                parent = parent.getParent();
            }
            if (ischild) {
                iter.remove();
                if (widget instanceof Repeater) {
                    if (this.repeaterPaths != null) this.repeaterPaths.remove(widget);
                    this.repeaterWidgets.remove(widget);
                }
            }
        }
    }

    /**
     * Called when a repeater clear event is received from a monitored repeater.
     * @param repeater The repeated that generated the event.
     */  
    protected void refreshForClear(Repeater repeater) {
        Set widgets = (Set) this.repeaterWidgets.get(repeater);
        for (Iterator iter = widgets.iterator(); iter.hasNext();) {
            Widget widget = (Widget) iter.next();
            if (widget instanceof Repeater) {
                if (this.repeaterPaths != null) this.repeaterPaths.remove(widget);
                this.repeaterWidgets.remove(widget);
            }
        }
        widgets.clear();
    }
    
    /**
     * Adds a widget not contained in a repeater.
     * @param context
     * @param path
     */
    private void addSimpleWidget(Widget context, String path) {
        Widget widget = context.lookupWidget(path);
        if (widget == null) throw new IllegalArgumentException("Cannot find a widget with path " + path + " relative to widget " + context.getName());
        if (this.noRepeaterWidgets == null) this.noRepeaterWidgets = new ArrayList();
        this.noRepeaterWidgets.add(widget);
        newAdditions.add(widget);        
    }
    
    /**
     * Return all widgets found for the given paths.
     * @return A Collection of {@link Widget}s.
     */
    public Collection getWidgets() {
        List list = new ArrayList();
        if (this.noRepeaterWidgets != null) list.addAll(this.noRepeaterWidgets);
        if (this.repeaterWidgets != null) {
	        for (Iterator iter = this.repeaterWidgets.keySet().iterator(); iter.hasNext();) {
	            Repeater repeater = (Repeater) iter.next();
	            list.addAll((Collection)this.repeaterWidgets.get(repeater));
	        }
        }
        return list;
    }
    
    /**
     * @return true if this finder is mutable (i.e. it's monitoring some repeaters) or false if getWidgets() will always return the same list (i.e. it's not monitoring any widget).
     */
    public boolean isMutable() {
        return (this.repeaterPaths != null) && this.repeaterPaths.size() > 0;
    }
    
    
    class RefreshingRepeaterListener implements RepeaterListener {
        public void repeaterModified(RepeaterEvent event) {
            if (event.getAction() == RepeaterEventAction.ROW_ADDED) {
                refreshForAdd((Repeater)event.getSourceWidget(), event.getRow());
            }
            if (event.getAction() == RepeaterEventAction.ROW_DELETING) {
                refreshForDelete((Repeater)event.getSourceWidget(), event.getRow());
            }
            if (event.getAction() == RepeaterEventAction.ROWS_CLEARING) {
                refreshForClear((Repeater)event.getSourceWidget());
            }
            if (listener != null) {
                listener.repeaterModified(event);
            }
        }
    }
    
    /**
     * @return true if new widgets have been added to this list (i.e. new repeater rows have been created) since last time getNewAdditions() was called. 
     */
    public boolean hasNewAdditions() {
        return this.newAdditions.size() > 0;
    }
    
    /**
     * Gets the new widgets that has been added to the list, as a consequence of new repeater rows additions, since
     * last time this method was called or the finder was initialized. 
     * @return A List of {@link Widget}s.
     */
    public List getNewAdditions() {
        List ret = new ArrayList(newAdditions);
        newAdditions.clear();
        return ret;
    }
    
    /**
     * Adds a repeater listener. New widget additions or deletions will be notified thru this listener (events received
     * from monitored repeaters will be forwarded, use {@link #getNewAdditions()} to retrieve new widgets).
     * @param listener The listener to add.
     */
    public void addRepeaterListener(RepeaterListener listener) {
        this.listener = WidgetEventMulticaster.add(this.listener, listener);
    }

    /**
     * Removes a listener. See {@link #addRepeaterListener(RepeaterListener)}.
     * @param listener The listener to remove.
     */
    public void removeRepeaterListener(RepeaterListener listener) {
        this.listener = WidgetEventMulticaster.remove(this.listener, listener);
    }

    /**
     * @return true if there are listeners registered on this instance. See {@link #addRepeaterListener(RepeaterListener)}.
     */
    public boolean hasRepeaterListeners() {
        return this.listener != null;
    }
}