Re: [pde-ui-dev] Finding API usage problems in batch mode

[Barys Dubauski <bdubausk@xxxxxxxxxx>]

Darin, what are the available report
forms that PDE API tooling currently supports? Is it possible to produce
report in form of an HTML file?

-Barys

IBM Rational SWG
EXT: 503-578-3521
TL: 775-3521

From:	Darin Wright <Darin_Wright@xxxxxxxxxx>
To:	pde-ui-dev@xxxxxxxxxxx
Date:	01/25/2008 11:16 AM
Subject:	[pde-ui-dev] Finding API usage problems in batch mode

---

For the interest of those wanting to
create "illegal API usage" reports during a batch build process,
it should be a little simpler now. We've refactored code such that a search
can be called from an integrated builder or batch process. See the new
class "ApiUseAnalyzer". It can be called to find illegal API
use in an entire profile, component, or specific scope within a component.
It returns the illegal usages as a collection of IReferences that can be
processed as desired. 

Darin Wright
 
----- Forwarded by Darin
Wright/Ottawa/IBM on 01/25/2008 01:09 PM -----

Darin Wright/Ottawa/IBM@IBMCA  
Sent by: pde-ui-dev-bounces@xxxxxxxxxxx

01/16/2008 12:06 PM

Please respond to
"Eclipse PDE UI developers list." <pde-ui-dev@xxxxxxxxxxx>

To	pde-ui-dev@xxxxxxxxxxx
cc
Subject	[pde-ui-dev] re: PDE API tooling questions

I'm posting this discussion on the mailing
list to benefit others interested leveraging API tooling features...


Hi Barys, 

API tooling is scheduled to have its
"graduation review" with the EMO on Jan 30th. You can see our
graduation review link off this page - http://www.eclipse.org/projects/whatsnew.php.
Assuming we pass the review, the code will be graduated to the Eclipse
SDK shortly after that (likely the week of Feb 11th). So, API tooling exists
as code in the CVS repository, but will not be available as a binary download
as part of the SDK until that time. 

There's nothing to stop you from experimenting
with the code right now - in fact, I encourage you to do so. My only disclaimer
is that the code is under development - APIs are not frozen. In fact, as
you will see in the slides, we are not planning to ship a public API in
the first release. So, you need to be willing to accept migration effort
as API tooling evolves. 

> I'd like to start with "API

> Usage Reporting" feature from
http://wiki.eclipse.org/index.
> php/PDE_UI_Incubator_ApiTools#API_Usage_Reporting_.28Batch_Mode.29.
> 
> 1) What is the current state of
this feature? 

Infrastructure to support API usage
analysis exists. There is *no* command line tool as of yet. We do intend
to produce rudimentary API usage reports with Eclipse builds (we will likey
write some Ant tasks to help with this). The support is designed to work
in "pure Java" mode (i.e. no OSGi or workspace required). So
you would need to write a Java program that calls our provisional APIs.
Below is a description of what you would need to do. Perhaps you could
review this, and provide some feedback on how we can make this more consumable
for you. 

For example, in the SDK, we analyze
a project for API usage problems when it is built. We do this by collecting
all of its prequisite bundles' API descriptions to create search criteria
for elements that have usage restrictions. We then search the project being
built. 

Steps: 

* Create an API profile (translates
to a product made up of binary bundles/plug-ins).

- use the Factory to do this (based
on a location, name, id, version, and execution environment description
file) 
* For each bundle in the product, create
and add the corresponding API component to the profile

- API components are created from the
profile, based on location 
* Use the API search engine to search
for specific API usage problems
- define the scope to search, and the
problems you are searching for 
- you could look at the APIToolBuilder
as an example that searches components for illegal API use

* Create a report with the search results
(references) 
- we do not currently create reports,
we create problem markers in the SDK 

Note: currently an API component initializes
its "API description" from the bundle's manifest.mf (i.e. defines
which packages are API), and from the .api_description file in the root
of the bundle (jar or folder). The .api_description file is the same format
as component.xml files - but also allows visibility and usage flags to
be set on members within types. This means you'd need to have some way
of injecting the api description files into the bundles. We plan to do
this with regular Eclipse builds. Here's an example file:


<?xml version="1.0" encoding="UTF-8"
standalone="no"?> 
<component name="Debug Core">

   <plugin id="org.eclipse.debug.core"/>

   <package name="org.eclipse.debug.core">

       <type
extend="false" name="DebugEvent"/>

       <type
extend="false" name="DebugException"/>

       <type
extend="false" instantiate="false" name="DebugPlugin"/>

       <type
implement="false" name="IBreakpointManager"/>

       <type
implement="false" name="IExpressionManager"/>

       <type
implement="false" name="ILaunchConfiguration">

           <field
name="ATTR_SOURCE_LOCATOR_ID" reference="false"/>

           <field
name="LAUNCH_CONFIGURATION_FILE_EXTENSION" reference="false"/>

           <method
name="getName" reference="false" signature="()Ljava/lang/String;"/>

       </type>

       <type
implement="false" name="ILaunchConfigurationType"/>

       <type
implement="false" name="ILaunchConfigurationWorkingCopy"/>

       <type
implement="false" name="ILaunchDelegate"/>

       <type
implement="false" name="ILaunchManager"/>

       <type
implement="false" name="ILaunchMode"/>

       <type
implement="false" name="IMemoryBlockManager"/>

   </package>

   <package name="org.eclipse.debug.core.model">

       <type
implement="false" name="IWatchExpression"/>

   </package>

   <package name="org.eclipse.debug.core.sourcelookup">

       <type
implement="false" name="ISourceContainerType"/>

       <type
implement="false" name="ISourcePathComputer"/>

   </package>

   <package name="org.eclipse.debug.core.sourcelookup.containers">

       <type
extend="false" name="ArchiveSourceContainer"/>

       <type
extend="false" instantiate="false" name="ContainerSourceContainer"/>

       <type
extend="false" name="DefaultSourceContainer"/>

       <type
extend="false" name="DirectorySourceContainer"/>

       <type
extend="false" name="ExternalArchiveSourceContainer"/>

       <type
extend="false" name="FolderSourceContainer"/>

       <type
extend="false" name="LocalFileStorage"/>

       <type
extend="false" name="ProjectSourceContainer"/>

       <type
extend="false" name="WorkspaceSourceContainer"/>

       <type
extend="false" name="ZipEntryStorage"/>

   </package>

</component>



> 2) Which version of PDE API tooling
should I pick up that has this 
> feature working? 

The code is all in HEAD. There are instructions
on how to get the code here: http://wiki.eclipse.org/PDE_UI_Incubator_ApiTools#Getting_the_Source_Code


> 3) What are the environment requirements
(Eclipse/JRE version, etc)? 

We require the latest I-build of Eclipse,
and a 1.4 JRE. Our test suite requires a 1.5 JRE.


> 4) Are there usage examples I can
follow? 

The test suite provides the best examples.
API usage problems are found by performing a search (search a scope for
specific types of problems). The SearchEngineTests might be a good place
to start. 

> 
> Any other pointers to speed up
the adoption of the tool? 

We have tried to write good javadoc
and keep it up to date. But, you will likely need to ask questions :-)


Darin _______________________________________________
pde-ui-dev mailing list
pde-ui-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/pde-ui-dev

_______________________________________________
pde-ui-dev mailing list
pde-ui-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/pde-ui-dev