1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
/*******************************************************************************
* Copyright (c) 2000, 2006 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* 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;
}
|
