1 | /******************************************************************************* |
2 | * Copyright (c) 2009 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.util.HashSet; |
14 | import java.util.Set; |
15 | import java.util.Stack; |
16 | |
17 | import org.eclipse.core.runtime.CoreException; |
18 | import org.eclipse.pde.api.tools.internal.provisional.ApiDescriptionVisitor; |
19 | import org.eclipse.pde.api.tools.internal.provisional.IApiAnnotations; |
20 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IElementDescriptor; |
21 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IFieldDescriptor; |
22 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IMethodDescriptor; |
23 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IPackageDescriptor; |
24 | import org.eclipse.pde.api.tools.internal.provisional.descriptors.IReferenceTypeDescriptor; |
25 | import org.eclipse.pde.api.tools.internal.provisional.model.IApiComponent; |
26 | import org.eclipse.pde.api.tools.internal.util.Signatures; |
27 | import org.eclipse.pde.api.tools.internal.util.Util; |
28 | import org.w3c.dom.Document; |
29 | import org.w3c.dom.Element; |
30 | |
31 | /** |
32 | * {@link IApiDescription} visitor that generates XML for the given {@link IApiComponent}. |
33 | * |
34 | * @since 1.0.0 |
35 | */ |
36 | public class ApiDescriptionXmlCreator extends ApiDescriptionVisitor { |
37 | |
38 | /** |
39 | * Component element |
40 | */ |
41 | private Element fComponent; |
42 | |
43 | /** |
44 | * XML doc being generated |
45 | */ |
46 | private Document fDoc; |
47 | |
48 | /** |
49 | * Current package node being created |
50 | */ |
51 | private Element fPackage; |
52 | |
53 | /** |
54 | * Visibility modifiers for package being visited |
55 | */ |
56 | private int fPackageVisibility; |
57 | |
58 | /** |
59 | * The stack of current type node being visited |
60 | */ |
61 | private Stack fTypeStack; |
62 | |
63 | /** |
64 | * Set of package names already visited (to avoid re-visiting same package) |
65 | */ |
66 | private Set fVisitedPackages; |
67 | |
68 | /** |
69 | * Constructs a new visitor for the given component. |
70 | * |
71 | * @param component API component |
72 | * @throws CoreException if unable to construct the visitor |
73 | */ |
74 | public ApiDescriptionXmlCreator(IApiComponent component) throws CoreException { |
75 | this(component.getName(), component.getId()); |
76 | } |
77 | |
78 | /** |
79 | * Constructs a new visitor for the given component. |
80 | * |
81 | * @param componentName the given component name |
82 | * @param componentId the given component id |
83 | * |
84 | * @throws CoreException if unable to construct the visitor |
85 | */ |
86 | public ApiDescriptionXmlCreator(String componentName, String componentId) throws CoreException { |
87 | fDoc = Util.newDocument(); |
88 | fComponent = fDoc.createElement(IApiXmlConstants.ELEMENT_COMPONENT); |
89 | fComponent.setAttribute(IApiXmlConstants.ATTR_NAME, componentName); |
90 | fComponent.setAttribute(IApiXmlConstants.ATTR_VERSION, IApiXmlConstants.API_DESCRIPTION_CURRENT_VERSION); |
91 | fDoc.appendChild(fComponent); |
92 | Element plugin = fDoc.createElement(IApiXmlConstants.ELEMENT_PLUGIN); |
93 | plugin.setAttribute(IApiXmlConstants.ATTR_ID, componentId); |
94 | fComponent.appendChild(plugin); |
95 | fVisitedPackages = new HashSet(); |
96 | fTypeStack = new Stack(); |
97 | } |
98 | |
99 | /** |
100 | * Annotates the attribute set of the specified {@link Element} |
101 | * |
102 | * @param componentContext component context to which the API applies, or <code>null</code> |
103 | * @param description the description to annotate from |
104 | * @param element the element to annotate |
105 | */ |
106 | private void annotateElementAttributes(IApiAnnotations description, Element element) { |
107 | element.setAttribute(IApiXmlConstants.ATTR_RESTRICTIONS, Integer.toString(description.getRestrictions())); |
108 | int visibility = description.getVisibility(); |
109 | if (visibility != fPackageVisibility) { |
110 | element.setAttribute(IApiXmlConstants.ATTR_VISIBILITY, Integer.toString(visibility)); |
111 | } |
112 | } |
113 | |
114 | /* (non-Javadoc) |
115 | * @see org.eclipse.pde.api.tools.internal.provisional.ApiDescriptionVisitor#endVisitElement(org.eclipse.pde.api.tools.internal.provisional.descriptors.IElementDescriptor, org.eclipse.pde.api.tools.internal.provisional.IApiAnnotations) |
116 | */ |
117 | public void endVisitElement(IElementDescriptor element, IApiAnnotations description) { |
118 | switch(element.getElementType()) { |
119 | case IElementDescriptor.PACKAGE: { |
120 | // A null package indicates there was an override for the package in a different context. |
121 | // Package rules are stored in the manifest, not the API description file. |
122 | // No need to add empty packages. |
123 | if (fPackage != null && fPackage.hasChildNodes()) { |
124 | fComponent.appendChild(fPackage); |
125 | } |
126 | fPackage = null; |
127 | break; |
128 | } |
129 | case IElementDescriptor.TYPE: { |
130 | fTypeStack.pop(); |
131 | break; |
132 | } |
133 | } |
134 | } |
135 | |
136 | /** |
137 | * Returns the settings as a UTF-8 string containing XML. |
138 | * |
139 | * @return XML |
140 | * @throws CoreException if something goes wrong |
141 | */ |
142 | public String getXML() throws CoreException { |
143 | return Util.serializeDocument(fDoc); |
144 | } |
145 | |
146 | /* (non-Javadoc) |
147 | * @see org.eclipse.pde.api.tools.model.component.ApiDescriptionVisitor#visitElement(org.eclipse.pde.api.tools.model.component.IElementDescriptor, java.lang.String, org.eclipse.pde.api.tools.model.IApiAnnotations) |
148 | */ |
149 | public boolean visitElement(IElementDescriptor element, IApiAnnotations description) { |
150 | switch(element.getElementType()) { |
151 | case IElementDescriptor.PACKAGE: { |
152 | IPackageDescriptor pkg = (IPackageDescriptor) element; |
153 | String pkgName = pkg.getName(); |
154 | if (fVisitedPackages.add(pkgName)) { |
155 | fPackage = fDoc.createElement(IApiXmlConstants.ELEMENT_PACKAGE); |
156 | fPackage.setAttribute(IApiXmlConstants.ATTR_NAME, pkgName); |
157 | // package visibility settings are stored in MANIFEST.MF, so omit them here. |
158 | // still keep track of the visibility to know if children should override |
159 | fPackageVisibility = description.getVisibility(); |
160 | fPackage.setAttribute(IApiXmlConstants.ATTR_VISIBILITY, Integer.toString(fPackageVisibility)); |
161 | fVisitedPackages.add(pkgName); |
162 | } |
163 | break; |
164 | } |
165 | case IElementDescriptor.TYPE: { |
166 | IReferenceTypeDescriptor typeDesc = (IReferenceTypeDescriptor) element; |
167 | fTypeStack.push(fDoc.createElement(IApiXmlConstants.ELEMENT_TYPE)); |
168 | Element type = (Element) fTypeStack.peek(); |
169 | annotateElementAttributes(description, type); |
170 | fPackage.appendChild(type); |
171 | type.setAttribute(IApiXmlConstants.ATTR_NAME, Signatures.getSimpleTypeName(typeDesc.getQualifiedName())); |
172 | break; |
173 | } |
174 | case IElementDescriptor.METHOD: { |
175 | IMethodDescriptor desc = (IMethodDescriptor) element; |
176 | Element method = fDoc.createElement(IApiXmlConstants.ELEMENT_METHOD); |
177 | Element type = (Element) fTypeStack.peek(); |
178 | //add standard attributes |
179 | annotateElementAttributes(description, method); |
180 | if (method.hasAttributes()) { |
181 | type.appendChild(method); |
182 | //add specific method attributes |
183 | method.setAttribute(IApiXmlConstants.ATTR_SIGNATURE, desc.getSignature()); |
184 | method.setAttribute(IApiXmlConstants.ATTR_NAME, desc.getName()); |
185 | } |
186 | break; |
187 | } |
188 | case IElementDescriptor.FIELD: { |
189 | IFieldDescriptor desc = (IFieldDescriptor) element; |
190 | Element field = fDoc.createElement(IApiXmlConstants.ELEMENT_FIELD); |
191 | Element type = (Element) fTypeStack.peek(); |
192 | annotateElementAttributes(description, field); |
193 | if (field.hasAttributes()) { |
194 | type.appendChild(field); |
195 | //add standard attributes |
196 | //add specific field attributes |
197 | field.setAttribute(IApiXmlConstants.ATTR_NAME, desc.getName()); |
198 | } |
199 | break; |
200 | } |
201 | } |
202 | return true; |
203 | } |
204 | } |