Blame - releng.wtpbuilder/tools/apitools/api-usage-checking-design.html - webtools/webtools.releng

format is XML-based; the DTD follows (complete <a href="http://dev.eclipse.org/viewcvs/index.cgi/working/apitools/component.xsd?cvsroot=WebTools_Project">XML

67

scheme</a>):

68

<!ATTLIST component

name CDATA #REQUIRED

></pre>

The <component> element provides information about a component.

73

Attributes:

74

<ul>

75

<li>name - the component name; "Eclipse Platform Generic

76

Workbench"; note that this name is used to refer to the component and

77

distinguish it from other components (but otherwise has no official status

78

in Eclipse ontology)</li>

79

</ul>

80

Child elements or the <component> element describe the set of plug-ins

81

and fragments making up the component, provide information about the Java

82

packages and types in the component's code, and include a list of other

83

components on which this component may depend.

84

Each <plugin> element must identify a distinct plug-in or fragment. The

85

list of plug-ins must be complete; that is, a component contains a plug-in (or

86

fragment) if and only if a <plugin> element occurs as a child of the

<component> element.

<!ATTLIST plugin

id CDATA #REQUIRED

fragment ("true" | "false") "false"

92

></pre>

93

The <plugin> element identifies a plug-in or plug-in fragment that is part

94

of the component. Attributes:

95

<ul>

96

<li>id - the plug-in id or plug-in fragment id; e.g., "org.eclipse.core.resources";

97

note that in the case of a fragment, this is the id of fragment itself</li>

98

<li>fragment - whether this is a plug-in fragment as opposed to a

99

plug-in (default: plug-in)</li>

100

</ul>

101

Each <plugin> element must identify a distinct plug-in or fragment. The

102

list of plug-ins must be complete; that is, a component contains a plug-in (or

103

fragment) if and only if a <plugin> element occurs as a child of the

<component> element.

<!ATTLIST package

name CDATA #REQUIRED

exclusive ("true" | "false") "true"

109

api ("true" | "false") "true"

110

></pre>

111

The <package> element provides information about a package as used by the

112

component. Attributes:

113

<ul>

114

<li>name - Java package name; e.g., "javax.swing", "org.eclipse.ui"</li>

115

<li>api - whether top-level types in this package are API types by

116

default (default: true). It's good practice for all public classes API

117

top-level types in a package to be considered API. Specify "false"

118

in order to explicitly list API types found in the package.</li>

119

<li>exclusive - whether this package is reserved for exclusive use by

120

this component (default: true); specify "false" in (rare) cases

121

where a multiple components declared types in the same package. Package

122

sharing is only by mutual consent; all components involved must explicitly

123

declare the package as exclusive="false" (even if it has no API

124

types).</li>

125

</ul>

126

Each <package> element must identify a distinct package relative to

127

that component. If the unusual case where a package is shared with other

128

components, the <package> element is understood to apply only to the types

129

the component actually declares, and has no bearing on the types declared in the

130

same package in any other component. The list of packages may be incomplete; if

131

the component contains code in a package not mentioned in the list, the package

132

is considered to be internal (equivalent to being explicitly described as

133

<package name="..." api="false" />). The children of

134

the <package> element provide information about specific types in the

package.

<!ATTLIST type

name CDATA #REQUIRED

reference ("true" | "false") "true"

140

implement ("true" | "false") "true"

141

subclass ("true" | "false") "true"

142

instantiate ("true" | "false") "true"

143

></pre>

144

The <type> element provides information about a top-level type in a

145

package. Attributes:

146

<ul>

147

<li>name - simple name of a top-level Java class, interface,

148

enumeration, or annotation type; e.g., "String", "IResource"</li>

149

<li>reference - whether other components are expected to reference this

150

type by name (default: true); specify "false" to indicate that the

151

type is internal</li>

152

<li>implement - whether other components are expected to declare a

153

class that implements this interface (default: true); specify

154

"false" for an interface that other components are not supposed to

155

implement directly; this attribute is ignored for classes, enumerations, and

156

annotation types, none of which can be meaningfully implemented</li>

157

<li>subclass - whether other components are expected to declare a class

158

that directly subclasses this class (default: true); specify

159

"false" for a class that other components are not supposed to

160

subclass directly; this attribute is ignored for interfaces, enumerations,

161

and annotation types, none of which can be meaningfully subclassed</li>

162

<li>instantiate - whether other components are expected to create

163

instances of this class or annotation type (default: true); specify

164

"false" for a type that other components are not supposed to

165

instantiate directly; this attribute is ignored for interfaces and

166

enumerations, neither of which can be meaningfully instantiated; this

167

attribute is moot for classes that are declared final (or ones with no

168

generally accessible constructors), since the Java compiler and JRE will

169

block outside attempts to instantiate</li>

170

</ul>

171

(Note: We could extend the schema in the future to allow <type>

172

elements to provide analogous information about their members. We could also

173

extend the <component> element to allow aspects other than code API to be

174

described.)

175

176

<!ATTLIST component-depends

177

unrestricted ("true" | "false") "false"

178

>

179

<!ELEMENT component-ref EMPTY>

180

<!ATTLIST component-ref

181

name CDATA #REQUIRED

182

></pre>

183

The <component-depends> element identifies other components on which this

184

component is allowed to depend. Attributes:

185

<ul>

186

<li>unrestricted - whether this component is allowed to depend on

187

arbitrary other components, or just the ones explicitly named by the

188

<component-ref> children</li>

189

</ul>

190

If a component specifies <component-depends

191

unrestricted="true">, then it is allowed to depend on any component

192

(and the children, if any, are ignored). Otherwise, the <component-ref>

193

elements give the names of the component on which this component may depend. The

194

<component-ref> element identifies a component by name. Attributes:

195

<ul>

196

<li>name - the name of the referenced component; e.g., "Eclipse

197

Platform Generic Workbench"</li>

198

</ul>

199

<h3>Example</h3>

200

A component description of one of the Eclipse Platform components:

</package>

</package>

</package>

</package>

<component-depends>

<component-ref name="Eclipse Platform Core Resources" />

246

<component-ref name="J2SE" />

247

</component-depends>

248

</component></pre>

249

<h2>How component descriptions are used</h2>

250

<ul>

251

<li>Component package/type map - Given the code for a component and its

252

component description, you can generate a fleshed-out list of the API types

253

declared by the component. (It's considerably harder to properly describe

254

the set of API members, since this involves building the supertype chain and

255

performing inheritance. Since the supertype chain need not be confined to a

256

single component, you also need the code for required plug-ins, etc.)</li>

257

<li>Inter-component reference map - Given the code for a component, its

258

component description, and the component descriptions for all other

259

components to which the given component may contain references, you can

260

generate the list of external references from the component to types in some

261

other component (possibly unknown, possibly ambiguous). In particular, you

262

can do this without needing to consult the code for the other components (or

263

even needing the code to be available).</li>

264

<li>Fragile usage map - You can go further and classify inter-component

265

usage as fragile. This requires the code for a component, its component

266

description, and the component descriptions for all other components to

267

which the given component may contain references. In the limited case of

268

shared packages between components, the code for these components may be

269

needed to disambiguate external references to types in the shared package. A

270

fragile external reference is any of:

271

<ul>

272

<li>A reference to an internal type in another (possibly unknown)

273

component.</li>

274

<li>A declaration of a subclass of a class C in another component where C

275

is described as subclass="false".</li>

276

<li>A declaration of a class implementing an interface I in another

277

component where I is described as implement="false".</li>

278

<li>An invocation of a constructor of a class C in another component where

279

C is described as instantiate="false".</li>

280

<li>A declaration of a type in a package P that another component

281

describes as exclusive="true".</li>

</ul>

</li>

</ul>

<h2>Change history</h2>

286

<ul>

287

<li>Dec. 23, 2004 - Initial version</li>

288

<li>Jan. 14, 2005

289

<ul>

290

<li>Added <component-depends> element to allow each component to

291

explicitly specify which other component it may depend on.</li>

292

<li>Added clarification to "api" attribute of <package>

293

element re: this is in line with good practice of making all top-types

294

public types in an API package being considered API.</li>

</ul>

</li>

</ul>

</body>

</html>