| /******************************************************************************* |
| * Copyright (c) 2000, 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.runtime; |
| |
| import org.eclipse.core.runtime.CoreException; |
| |
| /** |
| * Interface for executable extension classes that require access to |
| * their configuration element, or implement an extension adapter. |
| * <p> |
| * Extension adapters are typically required in cases where the extension |
| * implementation does not follow the interface rules specified |
| * by the provider of the extension point. In these |
| * cases, the role of the adapter is to map between the extension point |
| * interface, and the actual extension implementation. In general, adapters |
| * are used when attempting to plug-in existing Java implementations, or |
| * non-Java implementations (e.g., external executables). |
| * </p><p> |
| * This interface can be used without OSGi running. |
| * </p><p> |
| * Clients may implement this interface. |
| * </p> |
| * |
| * @see IConfigurationElement#createExecutableExtension(String) |
| */ |
| public interface IExecutableExtension { |
| /** |
| * This method is called by the implementation of the method |
| * <code>IConfigurationElement.createExecutableExtension</code> |
| * on a newly constructed extension, passing it its relevant configuration |
| * information. Most executable extensions only make use of the first |
| * two call arguments. |
| * <p> |
| * Regular executable extensions specify their Java implementation |
| * class name as an attribute of the configuration element for the |
| * extension. For example |
| * <pre> |
| * <action run="com.example.BaseAction"/> |
| * </pre> |
| * In the above example, this method would be called with a reference |
| * to the <code><action></code> element (first argument), and |
| * <code>"run"</code> as the name of the attribute that defined |
| * this executable extension (second argument). |
| * </p> |
| * <p> |
| * The last parameter is for the specific use of extension adapters |
| * and is typically not used by regular executable extensions. |
| * </p> |
| * <p> |
| * There are two supported ways of associating additional |
| * adapter-specific data with the configuration in a way that |
| * is transparent to the extension point implementor: |
| * </p> |
| * <p> |
| * (1) by specifying adapter data as part of the implementation |
| * class attribute value. The Java class name can be followed |
| * by a ":" separator, followed by any adapter data in string |
| * form. For example, if the extension point specifies an attribute |
| * <code>"run"</code> to contain the name of the extension implementation, |
| * an adapter can be configured as |
| * <pre> |
| * <action run="com.example.ExternalAdapter:./cmds/util.exe -opt 3"/> |
| * </pre> |
| * </p> |
| * <p> |
| * (2) by converting the attribute used to specify the executable |
| * extension to a child element of the original configuration element, |
| * and specifying the adapter data in the form of xml markup. |
| * Using this form, the example above would become |
| * <pre> |
| * <action> |
| * <<it>run</it> class="com.xyz.ExternalAdapter"> |
| * <parameter name="exec" value="./cmds/util.exe"/> |
| * <parameter name="opt" value="3"/> |
| * </<it>run</it>> |
| * </action> |
| * </pre> |
| * </p> |
| * <p> |
| * Form (2) will typically only be |
| * used for extension points that anticipate the majority of |
| * extensions configured into it will in fact be in the form |
| * of adapters. |
| * </p> |
| * <p> |
| * In either case, the specified adapter class is instantiated using its |
| * 0-argument public constructor. The adapter data is passed as the |
| * last argument of this method. The data argument is defined as Object. |
| * It can have the following values: |
| * <ul> |
| * <li><code>null</code>, if no adapter data was supplied</li> |
| * <li>in case (1), the initialization data |
| * string is passed as a <code>String</code></li> |
| * <li>in case (2), the initialization data is passed |
| * as a <code>Hashtable</code> containing the actual |
| * parameter names and values (both <code>String</code>s)</li> |
| * </ul> |
| * </p> |
| * |
| * @param config the configuration element used to trigger this execution. |
| * It can be queried by the executable extension for specific |
| * configuration properties |
| * @param propertyName the name of an attribute of the configuration element |
| * used on the <code>createExecutableExtension(String)</code> call. This |
| * argument can be used in the cases where a single configuration element |
| * is used to define multiple executable extensions. |
| * @param data adapter data in the form of a <code>String</code>, |
| * a <code>Hashtable</code>, or <code>null</code>. |
| * @exception CoreException if error(s) detected during initialization processing |
| * @see IConfigurationElement#createExecutableExtension(String) |
| */ |
| public void setInitializationData(IConfigurationElement config, String propertyName, Object data) throws CoreException; |
| } |
