Copyright (c) 2005, 2015 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2005, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.commands;


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.


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.


This class will typically be extended so the subclass can be referenced from
the converter attribute of the
commandParameterType elemement of the
org.eclipse.ui.commands extension-point. Objects implementing this interface may also be passed directly to ParameterType.define(String, AbstractParameterValueConverter) by clients. 
See Also:
ParameterType.define(String, AbstractParameterValueConverter)
ParameterizedCommand.serialize()
Since:
3.2/**
 * <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.
Params:
parameterValue – 
           a command parameter value string describing an object; may be
           null
Throws:
ParameterValueConversionException – 
            if an object cannot be produced from the
            parameterValue string
Returns:
the object described by the command parameter value string; may
        be null/**
	 * 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.
Params:
parameterValue – 
           an object to convert into an identifying string; may be
           null
Throws:
ParameterValueConversionException – 
            if a string reference or serialization cannot be provided for
            the parameterValue
Returns:
a string describing the provided object; may be null/**
	 * 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;

}