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 * <action run="com.example.BaseAction"/> 47 * </pre> 48 * In the above example, this method would be called with a reference 49 * to the <code><action></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 * <action run="com.example.ExternalAdapter:./cmds/util.exe -opt 3"/> 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 * <action> 80 * <<it>run</it> class="com.xyz.ExternalAdapter"> 81 * <parameter name="exec" value="./cmds/util.exe"/> 82 * <parameter name="opt" value="3"/> 83 * </<it>run</it>> 84 * </action> 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