bundles/org.eclipse.core.expressions/src/org/eclipse/core/expressions/ElementHandler.java

/*******************************************************************************
 * Copyright (c) 2000, 2007 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.expressions;

import org.w3c.dom.Element;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IConfigurationElement;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;

import org.eclipse.core.internal.expressions.CompositeExpression;
import org.eclipse.core.internal.expressions.ExpressionMessages;
import org.eclipse.core.internal.expressions.ExpressionPlugin;
import org.eclipse.core.internal.expressions.StandardElementHandler;


/**
 * An element handler converts an {@link IConfigurationElement} into a 
 * corresponding expression object. 
 * <p>
 * The class should be subclassed by clients wishing to provide an element
 * handler for special expressions.
 * </p>
 * @since 3.0 
 */
public abstract class ElementHandler {
	
	private static final ElementHandler INSTANCE= new StandardElementHandler();
	
	/**
	 * The default element handler which can cope with all XML expression elements
	 * defined by the common expression language.
	 * 
	 * @return the default element handler
	 */
	public static ElementHandler getDefault() {
		return INSTANCE;
	}
	
	/**
	 * Creates the corresponding expression for the given configuration element.
	 * 
	 * @param converter the expression converter used to initiate the
	 *  conversion process
	 * 
	 * @param config the configuration element to convert
	 * 
	 * @return the corresponding expression
	 * 
	 * @throws CoreException if the conversion failed
	 */
	public abstract Expression create(ExpressionConverter converter, IConfigurationElement config) throws CoreException;
	
	/**
	 * Creates the corresponding expression for the given DOM element. This is
	 * an optional operation that is only required if the handler supports conversion
	 * of DOM elements.
	 * 
	 * @param converter the expression converter used to initiate the
	 *  conversion process
	 * 
	 * @param element the DOM element to convert
	 * 
	 * @return the corresponding expression
	 * 
	 * @throws CoreException if the conversion failed
	 * 
	 * @since 3.3
	 */
	public Expression create(ExpressionConverter converter, Element element) throws CoreException {
		throw new CoreException(new Status(IStatus.ERROR, ExpressionPlugin.getPluginId(),
				IStatus.ERROR, 
				ExpressionMessages.ElementHandler_unsupported_element,
				null));
	}

	/**
	 * Converts the children of the given configuration element and adds them 
	 * to the given composite expression.
	 * <p>
	 * Note this is an internal method and should not be called by clients.
	 * </p> 
	 * @param converter the converter used to do the actual conversion
	 * @param element the configuration element for which the children 
	 *  are to be processed
	 * @param expression the composite expression representing the result
	 *  of the conversion
	 * 
	 * @throws CoreException if the conversion failed
	 */
	protected void processChildren(ExpressionConverter converter, IConfigurationElement element, CompositeExpression expression) throws CoreException {
		converter.processChildren(element, expression);
	}

	/**
	 * Converts the children of the given DOM element and adds them to the
	 * given composite expression.
	 * <p>
	 * Note this is an internal method and should not be called by clients.
	 * </p> 
	 * @param converter the converter used to do the actual conversion
	 * @param element the DOM element for which the children are to be processed
	 * @param expression the composite expression representing the result
	 *  of the conversion
	 * 
	 * @throws CoreException if the conversion failed
	 * 
	 * @since 3.3
	 */
	protected void processChildren(ExpressionConverter converter, Element element, CompositeExpression expression) throws CoreException {
		converter.processChildren(element, expression);
	}
}