/*******************************************************************************
* Copyright (c) 2005, 2015 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;
}