xmlflowbuilder.java

spring的WEB开发插件,支持多状态WEB开发

/*
 * Copyright 2002-2005 the original author or authors.
 *
 * Licensed 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.springframework.webflow.config;

import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;

import org.springframework.binding.MutableAttributeSource;
import org.springframework.binding.convert.ConversionExecutor;
import org.springframework.binding.expression.ExpressionFactory;
import org.springframework.binding.format.InvalidFormatException;
import org.springframework.binding.format.support.LabeledEnumFormatter;
import org.springframework.binding.support.MapAttributeSource;
import org.springframework.binding.support.Mapping;
import org.springframework.core.io.Resource;
import org.springframework.util.Assert;
import org.springframework.util.ClassUtils;
import org.springframework.util.StringUtils;
import org.springframework.util.xml.DomUtils;
import org.springframework.util.xml.SimpleSaxErrorHandler;
import org.springframework.webflow.Action;
import org.springframework.webflow.ActionState;
import org.springframework.webflow.AnnotatedAction;
import org.springframework.webflow.DecisionState;
import org.springframework.webflow.EndState;
import org.springframework.webflow.Flow;
import org.springframework.webflow.FlowAttributeMapper;
import org.springframework.webflow.State;
import org.springframework.webflow.SubflowState;
import org.springframework.webflow.Transition;
import org.springframework.webflow.TransitionCriteria;
import org.springframework.webflow.TransitionCriteriaFactory;
import org.springframework.webflow.TransitionableState;
import org.springframework.webflow.ViewDescriptorCreator;
import org.springframework.webflow.ViewState;
import org.springframework.webflow.access.AutowireMode;
import org.springframework.webflow.access.BeanFactoryFlowServiceLocator;
import org.springframework.webflow.access.FlowServiceLocator;
import org.springframework.webflow.action.CompositeAction;
import org.springframework.webflow.action.MultiAction;
import org.springframework.webflow.support.FlowScopeExpression;
import org.springframework.webflow.support.ParameterizableFlowAttributeMapper;
import org.springframework.webflow.support.TransitionCriteriaChain;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import org.xml.sax.EntityResolver;
import org.xml.sax.SAXException;

/**
 * Flow builder that builds a flow based on the definitions found in an XML
 * file. The XML files read by this class should use the following doctype:
 * 
 * <pre>
 *    &lt;!DOCTYPE webflow PUBLIC &quot;-//SPRING//DTD WEBFLOW//EN&quot;
 * 		&quot;http://www.springframework.org/dtd/spring-webflow.dtd&quot;&gt;
 * </pre>
 * 
 * Consult the <a href="http://www.springframework.org/dtd/spring-webflow.dtd">web flow DTD</a>
 * for more information on the XML definition format.
 * An object of this class is normally configured in the Spring application
 * context.
 * <p>
 * <b>Exposed configuration properties: </b> <br>
 * <table border="1">
 * <tr>
 * <td><b>name </b></td>
 * <td><b>default </b></td>
 * <td><b>description </b></td>
 * </tr>
 * <tr>
 * <td>location</td>
 * <td><i>null</i></td>
 * <td>Specifies the XML file location from which the flow definition is loaded.
 * This is a required property.</td>
 * </tr>
 * <tr>
 * <td>validating</td>
 * <td><i>true</i></td>
 * <td>Set if the XML parser should validate the document and thus enforce a
 * DTD.</td>
 * </tr>
 * <tr>
 * <td>entityResolver</td>
 * <td><i>{@link WebFlowDtdResolver}</i></td>
 * <td>Set a SAX entity resolver to be used for parsing.</td>
 * </tr>
 * <tr>
 * <td>flowServiceLocator</td>
 * <td><i>{@link BeanFactoryFlowServiceLocator}</i></td>
 * <td>Set the flow service location strategy to use.</td>
 * </tr>
 * </table>
 * 
 * @see org.springframework.webflow.config.FlowFactoryBean
 * 
 * @author Erwin Vervaet
 * @author Keith Donald
 */
public class XmlFlowBuilder extends BaseFlowBuilder {
	
	// recognized XML elements and attributes

	private static final String ID_ATTRIBUTE = "id";

	private static final String START_STATE_ATTRIBUTE = "start-state";

	private static final String ACTION_STATE_ELEMENT = "action-state";

	private static final String ACTION_ELEMENT = "action";

	private static final String BEAN_ATTRIBUTE = "bean";

	private static final String CLASS_ATTRIBUTE = "class";

	private static final String AUTOWIRE_ATTRIBUTE = "autowire";

	private static final String CLASSREF_ATTRIBUTE = "classref";

	private static final String NAME_ATTRIBUTE = "name";

	private static final String METHOD_ATTRIBUTE = "method";

	private static final String VALUE_ATTRIBUTE = "value";

	private static final String TYPE_ATTRIBUTE = "type";

	private static final String VIEW_STATE_ELEMENT = "view-state";

	private static final String VIEW_ATTRIBUTE = "view";

	private static final String DECISION_STATE_ELEMENT = "decision-state";

	private static final String IF_ELEMENT = "if";

	private static final String TEST_ATTRIBUTE = "test";

	private static final String THEN_ATTRIBUTE = "then";

	private static final String ELSE_ATTRIBUTE = "else";

	private static final String SUBFLOW_STATE_ELEMENT = "subflow-state";

	private static final String FLOW_ATTRIBUTE = "flow";

	private static final String ATTRIBUTE_MAPPER_ELEMENT = "attribute-mapper";

	private static final String INPUT_ELEMENT = "input";

	private static final String OUTPUT_ELEMENT = "output";

	private static final String AS_ATTRIBUTE = "as";

	private static final String END_STATE_ELEMENT = "end-state";

	private static final String TRANSITION_ELEMENT = "transition";

	private static final String ON_ATTRIBUTE = "on";

	private static final String TO_ATTRIBUTE = "to";

	private static final String FROM_ATTRIBUTE = "from";

	private static final String PROPERTY_ELEMENT = "property";

	private static final String VALUE_ELEMENT = "value";
	
	private static final String ENTRY_ELEMENT = "entry";

	private static final String EXIT_ELEMENT = "exit";
	
	
	/**
	 * Internal helper class capturing flow artifact definition info.
	 * 
	 * @author Erwin Vervaet
	 */
	private static class FlowArtifact {
		
		public String bean;
		public Class classRef;
		public Class clazz;
		public AutowireMode autowire;

		public boolean isBeanRef() {
			return StringUtils.hasText(bean);
		}
		
		public boolean isClassRef() {
			return classRef != null;
		}
		
		public boolean shouldCreate() {
			return clazz != null;
		}
	}
	
	private Resource location;

	private boolean validating = true;

	private EntityResolver entityResolver = new WebFlowDtdResolver();

	/**
	 * The DOM document object for the XML loaded from the resource.
	 */
	protected Document doc;

	/**
	 * Create a new XML flow builder.
	 */
	public XmlFlowBuilder() {
	}

	/**
	 * Create a new XML flow builder.
	 * @param location resource to read XML flow definitions from
	 */
	public XmlFlowBuilder(Resource location) {
		this.location = location;
	}

	/**
	 * Create a new XML flow builder.
	 * @param location resource to read XML flow definitions from
	 * @param flowServiceLocator the flow service location strategy to use
	 */
	public XmlFlowBuilder(Resource location, FlowServiceLocator flowServiceLocator) {
		this.location = location;
		setFlowServiceLocator(flowServiceLocator);
	}

	/**
	 * Returns the XML resource from which the flow definition is read.
	 */
	public Resource getLocation() {
		return location;
	}

	/**
	 * Set the resource from which the XML flow definition will be read.
	 */
	public void setLocation(Resource location) {
		this.location = location;
	}
	
	/**
	 * Returns whether or not the XML parser will validate the document.
	 */
	public boolean isValidating() {
		return validating;
	}

	/**
	 * Set if the XML parser should validate the document and thus enforce a
	 * DTD. Defaults to true.
	 */
	public void setValidating(boolean validating) {
		this.validating = validating;
	}

	/**
	 * Returns the SAX entity resolver used by the XML parser.
	 */
	public EntityResolver getEntityResolver() {
		return entityResolver;
	}

	/**
	 * Set a SAX entity resolver to be used for parsing. By default,
	 * WebFlowDtdResolver will be used. Can be overridden for custom entity
	 * resolution, for example relative to some specific base path.
	 * 
	 * @see org.springframework.webflow.config.WebFlowDtdResolver
	 */
	public void setEntityResolver(EntityResolver entityResolver) {
		this.entityResolver = entityResolver;
	}

	public Flow init() throws FlowBuilderException {
		Assert.notNull(location, "location is a required property");
		Assert.notNull(getFlowServiceLocator(), "flowServiceLocator is a required property");
		try {
			loadFlowDefinition();
		}
		catch (IOException e) {
			throw new FlowBuilderException("Cannot load the XML flow definition resource '" + location + "'", e);
		}
		catch (ParserConfigurationException e) {
			throw new FlowBuilderException("Cannot configure parser to parse the XML flow definition", e);
		}
		catch (SAXException e) {
			throw new FlowBuilderException("Cannot parse the flow definition XML document '" + location + "'", e);
		}
		parseFlowDefinition();
		return getFlow();
	}

	public void buildStates() throws FlowBuilderException {
		parseStateDefinitions();
	}

	public void dispose() {
		setFlow(null);
		doc = null;
	}

	/**
	 * Load the flow definition from the configured resource.
	 * This helper method initializes the {@link #doc} member variable.
	 */
	protected void loadFlowDefinition() throws IOException, ParserConfigurationException, SAXException {
		InputStream is = null;
		try {
			DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
			factory.setValidating(isValidating());
			DocumentBuilder docBuilder = factory.newDocumentBuilder();
			docBuilder.setErrorHandler(new SimpleSaxErrorHandler(logger));
			docBuilder.setEntityResolver(getEntityResolver());
			is = location.getInputStream();
			doc = docBuilder.parse(is);
		}
		finally {
			if (is != null) {
				try {
					is.close();
				}
				catch (IOException ex) {
					logger.warn("Could not close InputStream", ex);
				}
			}
		}
	}
	
	// helpers to parse a flow 'artifact' definition
	
	/**
	 * Parse a class reference from named attribute of given element.
	 */
	protected Class parseClass(Element element, String attributeName) {
		return (Class)fromStringTo(Class.class).execute(element.getAttribute(attributeName));
	}
	
	/**
	 * Parse and return the autowire mode specified in given element.
	 */
	protected AutowireMode parseAutowireMode(Element element) {
		if (element.hasAttribute(AUTOWIRE_ATTRIBUTE)) {
			try {
				return (AutowireMode)
					new LabeledEnumFormatter().parseValue(element.getAttribute(AUTOWIRE_ATTRIBUTE), AutowireMode.class);
			}
			catch (InvalidFormatException e) {
				throw new FlowBuilderException("Unsupported autowire mode '" + element.getAttribute(AUTOWIRE_ATTRIBUTE) + "'", e);
			}
		}
		else {
			// no autowire mode specified, so default is used
			return AutowireMode.DEFAULT;
		}
	}
	
	/**
	 * Parse a flow artifact definition contained in given XML element.
	 * A flow artifact is defined by a number of XML attributes, some of which are optional:
	 * "bean" (a reference to a managed bean by name), "classref" (a reference to a managed bean
	 * by type) and "class" (a request to instantiate given type) in combination with
	 * "autowire" (the autowire mode to use).
	 */
	protected FlowArtifact parseFlowArtifactDefinition(Element element) {
		FlowArtifact res = new FlowArtifact();
		res.bean = element.getAttribute(BEAN_ATTRIBUTE);
		if (element.hasAttribute(CLASSREF_ATTRIBUTE)) {
			res.classRef = parseClass(element, CLASSREF_ATTRIBUTE);
		}
		if (element.hasAttribute(CLASS_ATTRIBUTE)) {
			res.clazz = parseClass(element, CLASS_ATTRIBUTE);
		}
		res.autowire = parseAutowireMode(element);
		return res;
	}
	
	// XML parsing logic

	/**
	 * Parse the XML flow definitions and construct a Flow object.
	 * This helper method will set the "flow" property.
	 */
	protected void parseFlowDefinition() {
		Element element = doc.getDocumentElement();
		FlowArtifact flowDef = parseFlowArtifactDefinition(element);
		Flow flow;
		if (flowDef.isBeanRef()) {
			flow = getFlowServiceLocator().getFlow(flowDef.bean);
		}