org.eclipse.core.runtime.IExecutableExtension Maven / Gradle / Ivy
/*******************************************************************************
* 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.
*
* 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).
*
* This interface can be used without OSGi running.
*
* Clients may implement this interface.
*
*
* @see IConfigurationElement#createExecutableExtension(String)
*/
public interface IExecutableExtension {
/**
* This method is called by the implementation of the method
* IConfigurationElement.createExecutableExtension
* on a newly constructed extension, passing it its relevant configuration
* information. Most executable extensions only make use of the first
* two call arguments.
*
* Regular executable extensions specify their Java implementation
* class name as an attribute of the configuration element for the
* extension. For example
*
* <action run="com.example.BaseAction"/>
*
* In the above example, this method would be called with a reference
* to the <action> element (first argument), and
* "run" as the name of the attribute that defined
* this executable extension (second argument).
*
*
* The last parameter is for the specific use of extension adapters
* and is typically not used by regular executable extensions.
*
*
* 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:
*
*
* (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
* "run" to contain the name of the extension implementation,
* an adapter can be configured as
*
* <action run="com.example.ExternalAdapter:./cmds/util.exe -opt 3"/>
*
*
*
* (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
*
* <action>
* <run class="com.xyz.ExternalAdapter">
* <parameter name="exec" value="./cmds/util.exe"/>
* <parameter name="opt" value="3"/>
* </run >
* </action>
*
*
*
* 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.
*
*
* 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:
*
* null, if no adapter data was supplied- in case (1), the initialization data
* string is passed as a
String
* - in case (2), the initialization data is passed
* as a
Hashtable containing the actual
* parameter names and values (both Strings)
*
*
*
* @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 createExecutableExtension(String) 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 String,
* a Hashtable, or null.
* @exception CoreException if error(s) detected during initialization processing
* @see IConfigurationElement#createExecutableExtension(String)
*/
public void setInitializationData(IConfigurationElement config, String propertyName, Object data) throws CoreException;
}