AbstractParameterValueConverter


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.commands;
12  
13  /**
14   * <p>
15   * Supports conversion between objects and strings for command parameter values.
16   * Extenders must produce strings that identify objects (of a specific command
17   * parameter type) as well as consume the strings to locate and return the
18   * objects they identify.
19   * </p>
20   * <p>
21   * This class offers multiple handlers of a command a consistent way of
22   * converting string parameter values into the objects that the handlers would
23   * prefer to deal with. This class also gives clients a way to serialize
24   * object parameters as strings so that entire parameterized commands can be
25   * serialized, stored and later deserialized and executed.
26   * </p>
27   * <p>
28   * This class will typically be extended so the subclass can be referenced from
29   * the <code>converter</code> attribute of the
30   * <code>commandParameterType</code> elemement of the
31   * <code>org.eclipse.ui.commands</code> extension-point. Objects implementing
32   * this interface may also be passed directly to
33   * {@link ParameterType#define(String, AbstractParameterValueConverter)} by
34   * clients.
35   * </p>
36   * 
37   * @see ParameterType#define(String, AbstractParameterValueConverter)
38   * @see ParameterizedCommand#serialize()
39   * @since 3.2
40   */
41  public abstract class AbstractParameterValueConverter {
42  
43      /**
44       * Converts a string encoded command parameter value into the parameter
45       * value object.
46       * 
47       * @param parameterValue
48       *            a command parameter value string describing an object; may be
49       *            <code>null</code>
50       * @return the object described by the command parameter value string; may
51       *         be <code>null</code>
52       * @throws ParameterValueConversionException
53       *             if an object cannot be produced from the
54       *             <code>parameterValue</code> string
55       */
56      public abstract Object   convertToObject(final String   parameterValue)
57              throws ParameterValueConversionException;
58  
59      /**
60       * Converts a command parameter value object into a string that encodes a
61       * reference to the object or serialization of the object.
62       * 
63       * @param parameterValue
64       *            an object to convert into an identifying string; may be
65       *            <code>null</code>
66       * @return a string describing the provided object; may be <code>null</code>
67       * @throws ParameterValueConversionException
68       *             if a string reference or serialization cannot be provided for
69       *             the <code>parameterValue</code>
70       */
71      public abstract String   convertToString(final Object   parameterValue)
72              throws ParameterValueConversionException;
73  
74  }
75
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags