1 | /******************************************************************************* |
2 | * Copyright (c) 2007, 2008 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.pde.api.tools.internal; |
12 | |
13 | import java.io.File; |
14 | import java.io.FileInputStream; |
15 | import java.io.IOException; |
16 | import java.io.InputStream; |
17 | import java.util.zip.ZipEntry; |
18 | import java.util.zip.ZipFile; |
19 | |
20 | import org.eclipse.core.runtime.CoreException; |
21 | import org.eclipse.core.runtime.IStatus; |
22 | import org.eclipse.core.runtime.Path; |
23 | import org.eclipse.core.runtime.Status; |
24 | import org.eclipse.pde.api.tools.internal.provisional.ApiPlugin; |
25 | import org.eclipse.pde.api.tools.internal.provisional.Factory; |
26 | import org.eclipse.pde.api.tools.internal.provisional.IApiDescription; |
27 | import org.eclipse.pde.api.tools.internal.provisional.ProfileModifiers; |
28 | import org.eclipse.pde.api.tools.internal.provisional.RestrictionModifiers; |
29 | import org.eclipse.pde.api.tools.internal.provisional.VisibilityModifiers; |
30 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IElementDescriptor; |
31 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IFieldDescriptor; |
32 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IMethodDescriptor; |
33 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IPackageDescriptor; |
34 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IReferenceTypeDescriptor; |
35 | import org.eclipse.pde.api.tools.internal.provisional.scanner.ScannerMessages; |
36 | import org.eclipse.pde.api.tools.internal.util.Util; |
37 | import org.w3c.dom.Element; |
38 | import org.w3c.dom.NodeList; |
39 | |
40 | /** |
41 | * Provides tools for scanning/loading/parsing component.xml files. |
42 | * |
43 | * @since 1.0.0 |
44 | */ |
45 | public class SystemApiDescriptionProcessor { |
46 | /** |
47 | * Constructor |
48 | * can not be instantiated directly |
49 | */ |
50 | private SystemApiDescriptionProcessor() {} |
51 | |
52 | /** |
53 | * Parses a component XML into a string. The location may be a jar, directory containing the component.xml file, or |
54 | * the component.xml file itself |
55 | * |
56 | * @param location root location of the component.xml file, or the component.xml file itself |
57 | * @return component XML as a string or <code>null</code> if none |
58 | * @throws IOException if unable to parse |
59 | */ |
60 | public static String serializeComponentXml(File location) { |
61 | if(location.exists()) { |
62 | ZipFile jarFile = null; |
63 | InputStream stream = null; |
64 | try { |
65 | String extension = new Path(location.getName()).getFileExtension(); |
66 | if (extension != null && extension.equals("jar") && location.isFile()) { //$NON-NLS-1$ |
67 | jarFile = new ZipFile(location, ZipFile.OPEN_READ); |
68 | ZipEntry manifestEntry = jarFile.getEntry(IApiCoreConstants.SYSTEM_API_DESCRIPTION_XML_NAME); |
69 | if (manifestEntry != null) { |
70 | stream = jarFile.getInputStream(manifestEntry); |
71 | } |
72 | } else if(location.isDirectory()) { |
73 | File file = new File(location, IApiCoreConstants.SYSTEM_API_DESCRIPTION_XML_NAME); |
74 | if (file.exists()) { |
75 | stream = new FileInputStream(file); |
76 | } |
77 | } |
78 | else if(location.isFile()) { |
79 | if(location.getName().equals(IApiCoreConstants.SYSTEM_API_DESCRIPTION_XML_NAME)) { |
80 | stream = new FileInputStream(location); |
81 | } |
82 | } |
83 | if(stream != null) { |
84 | return new String(Util.getInputStreamAsCharArray(stream, -1, IApiCoreConstants.UTF_8)); |
85 | } |
86 | } catch(IOException e) { |
87 | ApiPlugin.log(e); |
88 | } finally { |
89 | try { |
90 | if (stream != null) { |
91 | stream.close(); |
92 | } |
93 | } catch (IOException e) { |
94 | ApiPlugin.log(e); |
95 | } |
96 | try { |
97 | if (jarFile != null) { |
98 | jarFile.close(); |
99 | } |
100 | } catch (IOException e) { |
101 | ApiPlugin.log(e); |
102 | } |
103 | } |
104 | } |
105 | return null; |
106 | } |
107 | /** |
108 | * Throws an exception with the given message and underlying exception. |
109 | * |
110 | * @param message error message |
111 | * @param exception underlying exception, or <code>null</code> |
112 | * @throws CoreException |
113 | */ |
114 | private static void abort(String message, Throwable exception) throws CoreException { |
115 | IStatus status = new Status(IStatus.ERROR, ApiPlugin.PLUGIN_ID, message, exception); |
116 | throw new CoreException(status); |
117 | } |
118 | |
119 | /** |
120 | * Parses the given xml document (in string format), and annotates the specified |
121 | * {@link IApiDescription} with {@link IPackageDescriptor}s, {@link IReferenceTypeDescriptor}s, {@link IMethodDescriptor}s |
122 | * and {@link IFieldDescriptor}s. |
123 | * |
124 | * @param settings API settings to annotate |
125 | * @param xml XML used to generate settings |
126 | * @throws CoreException |
127 | */ |
128 | public static void annotateApiSettings(IApiDescription settings, String xml) throws CoreException { |
129 | Element root = null; |
130 | try { |
131 | root = Util.parseDocument(xml); |
132 | } |
133 | catch(CoreException ce) { |
134 | abort("Failed to parse API description xml file", ce); //$NON-NLS-1$ |
135 | } |
136 | if (!root.getNodeName().equals(IApiXmlConstants.ELEMENT_COMPONENT)) { |
137 | abort(ScannerMessages.ComponentXMLScanner_0, null); |
138 | } |
139 | NodeList packages = root.getElementsByTagName(IApiXmlConstants.ELEMENT_PACKAGE); |
140 | NodeList types = null; |
141 | IPackageDescriptor packdesc = null; |
142 | Element type = null; |
143 | for (int i = 0; i < packages.getLength(); i++) { |
144 | Element pkg = (Element) packages.item(i); |
145 | // package visibility comes from the MANIFEST.MF |
146 | String pkgName = pkg.getAttribute(IApiXmlConstants.ATTR_NAME); |
147 | packdesc = Factory.packageDescriptor(pkgName); |
148 | annotateDescriptor(settings, packdesc, pkg); |
149 | types = pkg.getElementsByTagName(IApiXmlConstants.ELEMENT_TYPE); |
150 | for (int j = 0; j < types.getLength(); j++) { |
151 | type = (Element) types.item(j); |
152 | String name = type.getAttribute(IApiXmlConstants.ATTR_NAME); |
153 | if (name.length() == 0) { |
154 | abort("Missing type name", null); //$NON-NLS-1$ |
155 | } |
156 | IReferenceTypeDescriptor typedesc = packdesc.getType(name); |
157 | annotateDescriptor(settings, typedesc, type); |
158 | annotateMethodSettings(settings, typedesc, type); |
159 | annotateFieldSettings(settings, typedesc, type); |
160 | } |
161 | } |
162 | } |
163 | |
164 | /** |
165 | * Annotates the backing {@link IApiDescription} from the given {@link Element}, by adding the visibility |
166 | * and restriction attributes to the specified {@link IElementDescriptor} |
167 | * |
168 | * @param settings the settings to annotate |
169 | * @param descriptor the current descriptor context |
170 | * @param element the current element to annotate from |
171 | */ |
172 | private static void annotateDescriptor(IApiDescription settings, IElementDescriptor descriptor, Element element) { |
173 | settings.setVisibility(descriptor, VisibilityModifiers.API); |
174 | settings.setRestrictions(descriptor, RestrictionModifiers.NO_RESTRICTIONS); |
175 | settings.setAddedProfile(descriptor, retrieveElementAttribute(element, IApiXmlConstants.ATTR_ADDED_PROFILE)); |
176 | settings.setRemovedProfile(descriptor, retrieveElementAttribute(element, IApiXmlConstants.ATTR_REMOVED_PROFILE)); |
177 | settings.setSuperclass(descriptor, retrieveStringElementAttribute(element, IApiXmlConstants.ATTR_SUPER_CLASS)); |
178 | settings.setSuperinterfaces(descriptor, retrieveStringElementAttribute(element, IApiXmlConstants.ATTR_SUPER_INTERFACES)); |
179 | settings.setInterface(descriptor, retrieveBooleanElementAttribute(element, IApiXmlConstants.ATTR_INTERFACE)); |
180 | } |
181 | /** |
182 | * Tests if the given restriction exists for the given element |
183 | * and returns an updated restrictions flag. |
184 | * |
185 | * @param element XML element |
186 | * @param name attribute to test |
187 | * @param flag bit mask for attribute |
188 | * @param res flag to combine with |
189 | * @return updated flags |
190 | */ |
191 | private static int retrieveElementAttribute(Element element, String name) { |
192 | String value = element.getAttribute(name); |
193 | if (value.length() > 0) { |
194 | return Integer.parseInt(value); |
195 | } |
196 | return ProfileModifiers.NO_PROFILE_VALUE; |
197 | } |
198 | /** |
199 | * Tests if the given restriction exists for the given element |
200 | * and returns an updated restrictions flag. |
201 | * |
202 | * @param element XML element |
203 | * @param name attribute to test |
204 | * @param flag bit mask for attribute |
205 | * @param res flag to combine with |
206 | * @return updated flags |
207 | */ |
208 | private static String retrieveStringElementAttribute(Element element, String name) { |
209 | String value = element.getAttribute(name); |
210 | if (value.length() > 0) { |
211 | return value; |
212 | } |
213 | return null; |
214 | } |
215 | /** |
216 | * Tests if the given restriction exists for the given element |
217 | * and returns an updated restrictions flag. |
218 | * |
219 | * @param element XML element |
220 | * @param name attribute to test |
221 | * @param flag bit mask for attribute |
222 | * @param res flag to combine with |
223 | * @return updated flags |
224 | */ |
225 | private static boolean retrieveBooleanElementAttribute(Element element, String name) { |
226 | String value = element.getAttribute(name); |
227 | if (value.length() > 0) { |
228 | return Boolean.toString(true).equals(value); |
229 | } |
230 | return false; |
231 | } |
232 | /** |
233 | * Annotates the supplied {@link IApiDescription} from all of the field elements |
234 | * that are direct children of the specified {@link Element}. {@link IFieldDescriptor}s are created |
235 | * as needed and added as children of the specified {@link IReferenceTypeDescriptor}. |
236 | * |
237 | * @param settings the {@link IApiDescription} to add the new {@link IFieldDescriptor} to |
238 | * @param typedesc the containing type descriptor for this field |
239 | * @param type the parent {@link Element} |
240 | * @throws CoreException |
241 | */ |
242 | private static void annotateFieldSettings(IApiDescription settings, IReferenceTypeDescriptor typedesc, Element type) throws CoreException { |
243 | NodeList fields = type.getElementsByTagName(IApiXmlConstants.ELEMENT_FIELD); |
244 | Element field = null; |
245 | IFieldDescriptor fielddesc = null; |
246 | String name = null; |
247 | for(int i = 0; i < fields.getLength(); i++) { |
248 | field = (Element) fields.item(i); |
249 | name = field.getAttribute(IApiXmlConstants.ATTR_NAME); |
250 | if(name == null) { |
251 | abort(ScannerMessages.ComponentXMLScanner_1, null); |
252 | } |
253 | fielddesc = typedesc.getField(name); |
254 | annotateDescriptor(settings, fielddesc, field); |
255 | } |
256 | } |
257 | |
258 | /** |
259 | * Annotates the supplied {@link IApiDescription} from all of the method elements |
260 | * that are direct children of the specified {@link Element}. {@link IMethodDescriptor}s are created |
261 | * as needed and added as children of the specified {@link IReferenceTypeDescriptor}. |
262 | * |
263 | * @param settings the {@link IApiDescription} to add the new {@link IMethodDescriptor} to |
264 | * @param typedesc the containing type descriptor for this method |
265 | * @param type the parent {@link Element} |
266 | * @throws CoreException |
267 | */ |
268 | private static void annotateMethodSettings(IApiDescription settings, IReferenceTypeDescriptor typedesc, Element type) throws CoreException { |
269 | NodeList methods = type.getElementsByTagName(IApiXmlConstants.ELEMENT_METHOD); |
270 | Element method = null; |
271 | IMethodDescriptor methoddesc = null; |
272 | String name, signature; |
273 | for(int i = 0; i < methods.getLength(); i++) { |
274 | method = (Element) methods.item(i); |
275 | name = method.getAttribute(IApiXmlConstants.ATTR_NAME); |
276 | if(name == null) { |
277 | abort(ScannerMessages.ComponentXMLScanner_2, null); |
278 | } |
279 | signature = method.getAttribute(IApiXmlConstants.ATTR_SIGNATURE); |
280 | if(signature == null) { |
281 | abort(ScannerMessages.ComponentXMLScanner_3, null); |
282 | } |
283 | methoddesc = typedesc.getMethod(name, signature); |
284 | annotateDescriptor(settings, methoddesc, method); |
285 | } |
286 | } |
287 | } |