IConfigurationElement


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   * A configuration element, with its attributes and children, 
17   * directly reflects the content and structure of the extension section
18   * within the declaring plug-in's manifest (<code>plugin.xml</code>) file.
19   * <p>
20   * This interface also provides a way to create executable extension
21   * objects.
22   * </p>
23   * <p>
24   * These registry objects are intended for relatively short-term use. Clients that 
25   * deal with these objects must be aware that they may become invalid if the 
26   * declaring plug-in is updated or uninstalled. If this happens, all methods except
27   * {@link #isValid()} will throw {@link InvalidRegistryObjectException}.
28   * For configuration element objects, the most common case is code in a plug-in dealing
29   * with extensions contributed to one of the extension points it declares.
30   * Code in a plug-in that has declared that it is not dynamic aware (or not
31   * declared anything) can safely ignore this issue, since the registry
32   * would not be modified while it is active. However, code in a plug-in that
33   * declares that it is dynamic aware must be careful when accessing the extension
34   * and configuration element objects because they become invalid if the contributing
35   * plug-in is removed. Similarly, tools that analyze or display the extension registry
36   * are vulnerable. Client code can pre-test for invalid objects by calling {@link #isValid()},
37   * which never throws this exception. However, pre-tests are usually not sufficient
38   * because of the possibility of the extension or configuration element object becoming
39   * invalid as a result of a concurrent activity. At-risk clients must treat 
40   * <code>InvalidRegistryObjectException</code> as if it were a checked exception.
41   * Also, such clients should probably register a listener with the extension registry
42   * so that they receive notification of any changes to the registry.
43   * </p><p>
44   * This interface can be used without OSGi running.
45   * </p><p>
46   * This interface is not intended to be implemented by clients.
47   * </p>
48   */
49  public interface IConfigurationElement {
50      /**
51       * Creates and returns a new instance of the executable extension 
52       * identified by the named attribute of this configuration element.
53       * The named attribute value must contain a fully qualified name
54       * of a Java class. The class can either refer to a class implementing 
55       * the executable extension or to a factory capable of returning the 
56       * executable extension.
57       * <p>
58       * The specified class is instantiated using its 0-argument public constructor.
59       * <p>
60       * Then the following checks are done:<br>
61       * If the specified class implements the {@link IExecutableExtension} 
62       * interface, the method {@link IExecutableExtension#setInitializationData(IConfigurationElement, String, Object)} 
63       * is called, passing to the object the configuration information that was used to create it. 
64       * <p>
65       * If the specified class implements {@link IExecutableExtensionFactory} 
66       * interface, the method {@link IExecutableExtensionFactory#create()} 
67       * is invoked.
68       * </p>
69       * <p>
70       * Unlike other methods on this object, invoking this method may activate 
71       * the plug-in.
72       * </p>
73       *
74       * @param propertyName the name of the property
75       * @return the executable instance
76       * @exception CoreException if an instance of the executable extension
77       *   could not be created for any reason
78       * @see IExecutableExtension#setInitializationData(IConfigurationElement, String, Object)
79       * @see IExecutableExtensionFactory
80       * @throws InvalidRegistryObjectException if this configuration element is no longer valid
81       */
82      public Object   createExecutableExtension(String   propertyName) throws CoreException;
83  
84      /**
85       * Returns the named attribute of this configuration element, or
86       * <code>null</code> if none. 
87       * <p>
88       * The names of configuration element attributes
89       * are the same as the attribute names of the corresponding XML element.
90       * For example, the configuration markup 
91       * <pre>
92       * &lt;bg pattern="stripes"/&gt;
93       * </pre>
94       * corresponds to a configuration element named <code>"bg"</code>
95       * with an attribute named <code>"pattern"</code>
96       * with attribute value <code>"stripes"</code>.
97       * </p>
98       * <p> Note that any translation specified in the plug-in manifest
99       * file is automatically applied.
100      * </p>
101      *
102      * @param name the name of the attribute
103      * @return attribute value, or <code>null</code> if none
104      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
105      */
106     public String   getAttribute(String   name) throws InvalidRegistryObjectException;
107 
108     /**
109      * Returns the named attribute of this configuration element, or
110      * <code>null</code> if none. 
111      * <p>
112      * The names of configuration element attributes
113      * are the same as the attribute names of the corresponding XML element.
114      * For example, the configuration markup 
115      * <pre>
116      * &lt;bg pattern="stripes"/&gt;
117      * </pre>
118      * corresponds to a configuration element named <code>"bg"</code>
119      * with an attribute named <code>"pattern"</code>
120      * with attribute value <code>"stripes"</code>.
121      * </p>
122      * <p>
123      * Note that any translation specified in the plug-in manifest
124      * file for this attribute is <b>not</b> automatically applied.
125      * </p>
126      *
127      * @param name the name of the attribute
128      * @return attribute value, or <code>null</code> if none
129      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
130      * @deprecated The method is equivalent to the {@link #getAttribute(String)}. Contrary to its description,
131      * this method returns a translated value. Use the {@link #getAttribute(String)} method instead.
132      */
133     public String   getAttributeAsIs(String   name) throws InvalidRegistryObjectException;
134 
135     /**
136      * Returns the names of the attributes of this configuration element.
137      * Returns an empty array if this configuration element has no attributes.
138      * <p>
139      * The names of configuration element attributes
140      * are the same as the attribute names of the corresponding XML element.
141      * For example, the configuration markup 
142      * <pre>
143      * &lt;bg color="blue" pattern="stripes"/&gt;
144      * </pre>
145      * corresponds to a configuration element named <code>"bg"</code>
146      * with attributes named <code>"color"</code>
147      * and <code>"pattern"</code>.
148      * </p>
149      *
150      * @return the names of the attributes 
151      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
152      */
153     public String  [] getAttributeNames() throws InvalidRegistryObjectException;
154 
155     /**
156      * Returns all configuration elements that are children of this
157      * configuration element. 
158      * Returns an empty array if this configuration element has no children.
159      * <p>
160      * Each child corresponds to a nested
161      * XML element in the configuration markup.
162      * For example, the configuration markup 
163      * <pre>
164      * &lt;view&gt;
165      * &nbsp&nbsp&nbsp&nbsp&lt;verticalHint&gt;top&lt;/verticalHint&gt;
166      * &nbsp&nbsp&nbsp&nbsp&lt;horizontalHint&gt;left&lt;/horizontalHint&gt;
167      * &lt;/view&gt;
168      * </pre>
169      * corresponds to a configuration element, named <code>"view"</code>,
170      * with two children.
171      * </p>
172      *
173      * @return the child configuration elements
174      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
175      * @see #getChildren(String)
176      */
177     public IConfigurationElement[] getChildren() throws InvalidRegistryObjectException;
178 
179     /**
180      * Returns all child configuration elements with the given name. 
181      * Returns an empty array if this configuration element has no children
182      * with the given name.
183      *
184      * @param name the name of the child configuration element
185      * @return the child configuration elements with that name
186      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
187      * @see #getChildren()
188      */
189     public IConfigurationElement[] getChildren(String   name) throws InvalidRegistryObjectException;
190 
191     /** 
192      * Returns the extension that declares this configuration element.
193      *
194      * @return the extension
195      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
196      */
197     public IExtension getDeclaringExtension() throws InvalidRegistryObjectException;
198 
199     /**
200      * Returns the name of this configuration element. 
201      * The name of a configuration element is the same as
202      * the XML tag of the corresponding XML element. 
203      * For example, the configuration markup 
204      * <pre>
205      * &lt;wizard name="Create Project"/&gt; 
206      * </pre>
207      * corresponds to a configuration element named <code>"wizard"</code>.
208      *
209      * @return the name of this configuration element
210      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
211      */
212     public String   getName() throws InvalidRegistryObjectException;
213 
214     /**
215      * Returns the element which contains this element.  If this element
216      * is an immediate child of an extension, the
217      * returned value can be downcast to <code>IExtension</code>.
218      * Otherwise the returned value can be downcast to 
219      * <code>IConfigurationElement</code>.
220      *
221      * @return the parent of this configuration element
222      *  or <code>null</code>
223      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
224      * @since 3.0
225      */
226     public Object   getParent() throws InvalidRegistryObjectException;
227 
228     /**
229      * Returns the text value of this configuration element.
230      * For example, the configuration markup 
231      * <pre>
232      * &lt;script lang="javascript"&gt;.\scripts\cp.js&lt;/script&gt;
233      * </pre>
234      * corresponds to a configuration element <code>"script"</code>
235      * with value <code>".\scripts\cp.js"</code>.
236      * <p> Values may span multiple lines (i.e., contain carriage returns
237      * and/or line feeds).
238      * <p> Note that any translation specified in the plug-in manifest
239      * file is automatically applied.
240      * </p>
241      *
242      * @return the text value of this configuration element or <code>null</code>
243      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
244      */
245     public String   getValue() throws InvalidRegistryObjectException;
246 
247     /**
248      * Returns the untranslated text value of this configuration element.
249      * For example, the configuration markup 
250      * <pre>
251      * &lt;script lang="javascript"&gt;.\scripts\cp.js&lt;/script&gt;
252      * </pre>
253      * corresponds to a configuration element <code>"script"</code>
254      * with value <code>".\scripts\cp.js"</code>.
255      * <p> Values may span multiple lines (i.e., contain carriage returns
256      * and/or line feeds).
257      * <p>
258      * Note that translation specified in the plug-in manifest
259      * file is <b>not</b> automatically applied.
260      * For example, the configuration markup 
261      * <pre>
262      * &lt;tooltip&gt;#hattip&lt;/tooltip&gt;
263      * </pre>
264      * corresponds to a configuration element, named <code>"tooltip"</code>,
265      * with value <code>"#hattip"</code>.
266      * </p>
267      *
268      * @return the untranslated text value of this configuration element or <code>null</code>
269      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
270      * @deprecated The method is equivalent to the {@link #getValue()}. Contrary to its description,
271      * this method returns a translated value. Use the {@link #getValue()} method instead.
272      */
273     public String   getValueAsIs() throws InvalidRegistryObjectException;
274 
275     /**
276      * Returns the namespace for this configuration element. This value can be used
277      * in various global facilities to discover this configuration element's contributor.
278      * 
279      * @return the namespace for this configuration element
280      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
281      * @see IExtensionRegistry
282      * @since 3.1
283      * @deprecated As namespace is no longer restricted to the contributor name, 
284      *  use {@link #getNamespaceIdentifier()} to obtain namespace name or {@link #getContributor()}
285      *  to get the name of the contributor of this registry element.
286      * <p>
287      * In the past namespace was dictated by the name of the bundle. If bundle <code>org.abc</code> 
288      * contributed registry element with Id of <code>MyId</code>, the namespace of 
289      * the element was always set to <code>org.abc</code>, producing the qualified name of 
290      * <code>org.abc.MyId</code>.
291      * </p><p>
292      * The namespace used to be the same as the bundle name. As a result, the {@link #getNamespace()} 
293      * method was used both to obtain the name of the bundle and to obtain the namespace of a registry 
294      * element.
295      * </p><p>
296      * Since 3.2, the extension registry allows elements to specify qualified name. The extension point 
297      * of the plug-in <code>org.abc</code> could specify <code>org.zzz.MyExtPoint</code> as 
298      * an Id. In this case, namespace name is <code>org.zzz</code>, but the contributor 
299      * name is <code>org.abc</code>.  
300      * </p><p>
301      * (The use of a simple Id is still a preferred way. Whenever possible, specify only the simple 
302      * Id and let runtime take care of the rest.)
303      * </p><p>
304      * If your code used the {@link #getNamespace()} to obtain the name of the contributing bundle, 
305      * use {@link #getContributor()}. The typical usage pattern here is to find a bundle name to obtain 
306      * some information from the corresponding OSGi bundle. For example, deducing the file location 
307      * specified as a relative path to the bundle install location would fall into this group.
308      * </p><p>
309      * If your code used the {@link #getNamespace()} to obtain the namespace of the registry element, 
310      * use {@link #getNamespaceIdentifier()}. Typically, this is the case when code is trying to process 
311      * registry elements belonging to some logical group. For example, processing notifications for all 
312      * elements belonging to the <code>org.abc</code> namespace would fall into this category.
313      * </p>
314      */
315     public String   getNamespace() throws InvalidRegistryObjectException;
316 
317     /**
318      * Returns the namespace name for this configuration element.
319      * 
320      * @return the namespace name for this configuration element
321      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
322      * @since org.eclipse.equinox.registry 3.2   
323      */
324     public String   getNamespaceIdentifier() throws InvalidRegistryObjectException;
325 
326     /**
327      * Returns the contributor of this configuration element.
328      * 
329      * @return the contributor for this configuration element
330      * @throws InvalidRegistryObjectException if this configuration element is no longer valid
331      * @since org.eclipse.equinox.registry 3.2   
332      */
333     public IContributor getContributor() throws InvalidRegistryObjectException;
334 
335     /* (non-javadoc) 
336      * @see Object#equals(java.lang.Object)
337      */
338     public boolean equals(Object   o);
339 
340     /**
341      * Returns whether this configuration element object is valid.
342      * 
343      * @return <code>true</code> if the object is valid, and <code>false</code>
344      * if it is no longer valid
345      * @since 3.1
346      */
347     public boolean isValid();
348 }
349
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags