IExecutableExtension


1   /*******************************************************************************
2    * Copyright (c) 2000, 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.runtime;
12  
13  import org.eclipse.core.runtime.CoreException;
14  
15  /**
16   * Interface for executable extension classes that require access to 
17   * their configuration element, or implement an extension adapter.
18   * <p>
19   * Extension adapters are typically required in cases where the extension
20   * implementation does not follow the interface rules specified
21   * by the provider of the extension point. In these
22   * cases, the role of the adapter is to map between the extension point
23   * interface, and the actual extension implementation. In general, adapters
24   * are used when attempting to plug-in existing Java implementations, or
25   * non-Java implementations (e.g., external executables).
26   * </p><p>
27   * This interface can be used without OSGi running.
28   * </p><p>
29   * Clients may implement this interface.
30   * </p>
31   * 
32   * @see IConfigurationElement#createExecutableExtension(String)
33   */
34  public interface IExecutableExtension {
35      /**
36       * This method is called by the implementation of the method
37       * <code>IConfigurationElement.createExecutableExtension</code>
38       * on a newly constructed extension, passing it its relevant configuration 
39       * information. Most executable extensions only make use of the first 
40       * two call arguments.
41       * <p>
42       * Regular executable extensions specify their Java implementation 
43       * class name as an attribute of the configuration element for the 
44       * extension. For example
45       * <pre>
46       *     &lt;action run="com.example.BaseAction"/&gt;
47       * </pre>
48       * In the above example, this method would be called with a reference
49       * to the <code>&lt;action&gt;</code> element (first argument), and
50       * <code>"run"</code> as the name of the attribute that defined
51       * this executable extension (second argument).
52       * </p>
53       * <p>
54       * The last parameter is for the specific use of extension adapters
55       * and is typically not used by regular executable extensions.
56       * </p>
57       * <p>
58       * There are two supported ways of associating additional
59       * adapter-specific data with the configuration in a way that
60       * is transparent to the extension point implementor:
61       * </p>
62       * <p>
63       * (1) by specifying adapter data as part of the implementation
64       * class attribute value. The Java class name can be followed
65       * by a ":" separator, followed by any adapter data in string
66       * form. For example, if the extension point specifies an attribute
67       * <code>"run"</code> to contain the name of the extension implementation,
68       * an adapter can be configured as
69       * <pre>
70       *     &lt;action run="com.example.ExternalAdapter:./cmds/util.exe -opt 3"/&gt;
71       * </pre>
72       * </p>
73       * <p>
74       * (2) by converting the attribute used to specify the executable
75       * extension to a child element of the original configuration element,
76       * and specifying the adapter data in the form of xml markup.
77       * Using this form, the example above would become
78       * <pre>
79       *     &lt;action&gt;
80       *         &lt;<it>run</it> class="com.xyz.ExternalAdapter"&gt;
81       *             &lt;parameter name="exec" value="./cmds/util.exe"/&gt;
82       *             &lt;parameter name="opt"  value="3"/&gt;
83       *         &lt;/<it>run</it>&gt;
84       *     &lt;/action&gt;
85       * </pre>
86       * </p>
87       * <p>
88       * Form (2) will typically only be
89       * used for extension points that anticipate the majority of
90       * extensions configured into it will in fact be in the form
91       * of adapters.
92       * </p>
93       * <p>
94       * In either case, the specified adapter class is instantiated using its
95       * 0-argument public constructor. The adapter data is passed as the
96       * last argument of this method. The data argument is defined as Object.
97       * It can have the following values:
98       * <ul>
99       * <li><code>null</code>, if no adapter data was supplied</li>
100      * <li>in case (1), the initialization data
101      *      string is passed as a <code>String</code></li>
102      * <li>in case (2), the initialization data is passed
103      *      as a <code>Hashtable</code> containing the actual
104      *      parameter names and values (both <code>String</code>s)</li>
105      * </ul>
106      * </p>
107      *
108      * @param config the configuration element used to trigger this execution. 
109      *      It can be queried by the executable extension for specific
110      *      configuration properties
111      * @param propertyName the name of an attribute of the configuration element
112      *      used on the <code>createExecutableExtension(String)</code> call. This
113      *      argument can be used in the cases where a single configuration element
114      *      is used to define multiple executable extensions.
115      * @param data adapter data in the form of a <code>String</code>, 
116      *      a <code>Hashtable</code>, or <code>null</code>.
117      * @exception CoreException if error(s) detected during initialization processing
118      * @see IConfigurationElement#createExecutableExtension(String)
119      */
120     public void setInitializationData(IConfigurationElement config, String   propertyName, Object   data) throws CoreException;
121 }
122
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags