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