/*******************************************************************************
 * Copyright (c) 2005, 2006 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.commands;

/**
 * <p>
 * Supports conversion between objects and strings for command parameter values.
 * Extenders must produce strings that identify objects (of a specific command
 * parameter type) as well as consume the strings to locate and return the
 * objects they identify.
 * </p>
 * <p>
 * This class offers multiple handlers of a command a consistent way of
 * converting string parameter values into the objects that the handlers would
 * prefer to deal with. This class also gives clients a way to serialize
 * object parameters as strings so that entire parameterized commands can be
 * serialized, stored and later deserialized and executed.
 * </p>
 * <p>
 * This class will typically be extended so the subclass can be referenced from
 * the <code>converter</code> attribute of the
 * <code>commandParameterType</code> elemement of the
 * <code>org.eclipse.ui.commands</code> extension-point. Objects implementing
 * this interface may also be passed directly to
 * {@link ParameterType#define(String, AbstractParameterValueConverter)} by
 * clients.
 * </p>
 * 
 * @see ParameterType#define(String, AbstractParameterValueConverter)
 * @see ParameterizedCommand#serialize()
 * @since 3.2
 */
public abstract class AbstractParameterValueConverter {

	/**
	 * Converts a string encoded command parameter value into the parameter
	 * value object.
	 * 
	 * @param parameterValue
	 *            a command parameter value string describing an object; may be
	 *            <code>null</code>
	 * @return the object described by the command parameter value string; may
	 *         be <code>null</code>
	 * @throws ParameterValueConversionException
	 *             if an object cannot be produced from the
	 *             <code>parameterValue</code> string
	 */
	public abstract Object convertToObject(final String parameterValue)
			throws ParameterValueConversionException;

	/**
	 * Converts a command parameter value object into a string that encodes a
	 * reference to the object or serialization of the object.
	 * 
	 * @param parameterValue
	 *            an object to convert into an identifying string; may be
	 *            <code>null</code>
	 * @return a string describing the provided object; may be <code>null</code>
	 * @throws ParameterValueConversionException
	 *             if a string reference or serialization cannot be provided for
	 *             the <code>parameterValue</code>
	 */
	public abstract String convertToString(final Object parameterValue)
			throws ParameterValueConversionException;

}