COSMOS API Cleanup

COSMOS API Cleanup - Housecleaning

This wiki page was constructed in response to https://bugs.eclipse.org/bugs/show_bug.cgi?id=218558. In preparation for releasing COSMOS 1.0, committers are required to ensure API guidelines are met. In COSMOS there are three types of APIs:

1. Internal - Indicated by having a package name that contains the keyword 'internal' (e.g. org.eclipse.cosmos.dc.cmdbf.services.internal)
2. Provisional - Indicated by having a package name that contains the keyword 'provisional' (e.g. org.eclipse.cosmos.dc.cmdbf.services.provisional.metadata.transform)
3. Public - Any API that does not fall under (1) or (2)

Please see COSMOS API Contract for more details. COSMOS 1.0 does not plan to release any public APIs. All classes are expected to fall under (1) or (2). Provisional classes MUST be thoroughly commented. A recent (April 17, 2008) manual code scan revealed the following plug-ins to be in violation of the guideline. Package/classes expected to be provisional are indicated by orange and expected internal APIs are indicated by red. The final verdict of what should be internal or provisional is made by the component owner.

Archiving unused code

In i11, there will be a new module added to COSMOS' CVS called ('archive') that will contain all plug-ins that are no longer needed.

Data Collection

Violating Plug-ins	Packages/Classes	Assignee	Complete
org.eclipse.cosmos.aperi.mdr.ws	org.eclipse.cosmos.aperi.mdr.ws org.eclipse.cosmos.aperi.mdr.ws.db	Bill Muldoon	No
org.eclipse.cosmos.common	org.eclipse.cosmos.common org.eclipse.cosmos.common.exceptions	Bill Muldoon	No
org.eclipse.cosmos.dc.broker.core	org.eclipse.cosmos.dc.broker.ws org.eclipse.cosmos.dc.broker.ws.persistence org.eclipse.cosmos.dc.broker.ws.client org.eclipse.cosmos.dc.broker.ws.datamodel	Hubert Leung	No
org.eclipse.cosmos.dc.cmdbf.services	org.eclipse.cosmos.dc.cmdbf.services.cmdbfservice org.eclipse.cosmos.dc.cmdbf.services.common org.eclipse.cosmos.dc.cmdbf.services.transform org.eclipse.cosmos.dc.cmdbf.services.transform.artifacts org.eclipse.cosmos.dc.cmdbf.services.metadata.transform org.eclipse.cosmos.dc.cmdbf.services.metadata.transform.input.artifacts org.eclipse.cosmos.dc.cmdbf.services.query.transform org.eclipse.cosmos.dc.cmdbf.services.query.transform.artifacts org.eclipse.cosmos.dc.cmdbf.services.query.transform.input.artifacts org.eclipse.cosmos.dc.cmdbf.services.query.transform.response.artifacts org.eclipse.cosmos.dc.cmdbf.services.query.service org.eclipse.cosmos.dc.cmdbf.services.query.service.impl org.eclipse.cosmos.dc.cmdbf.services.deregistration.transform org.eclipse.cosmos.dc.cmdbf.services.deregistration.transform.input.artifacts org.eclipse.cosmos.dc.cmdbf.services.deregistration.transform.output.artifacts org.eclipse.cosmos.dc.cmdbf.services.registration.transform org.eclipse.cosmos.dc.cmdbf.services.registration.transform.input.artifacts org.eclipse.cosmos.dc.cmdbf.services.registration.transform.output.artifacts org.eclipse.cosmos.dc.cmdbf.services.common org.eclipse.cosmos.dc.cmdbf.services.deregistration.service org.eclipse.cosmos.dc.cmdbf.services.deregistration.service.impl org.eclipse.cosmos.dc.cmdbf.services.registration.service org.eclipse.cosmos.dc.cmdbf.services.registration.service.impl	Ali Mehregani	No
org.eclipse.cosmos.dc.cmdbf.ws	org.eclipse.cosmos.dc.cmdbf.exception org.eclipse.cosmos.dc.cmdbf.query.client org.eclipse.cosmos.dc.cmdbf.query.ws org.eclipse.cosmos.dc.cmdbf.receiver org.eclipse.cosmos.dc.cmdbf.registration.client org.eclipse.cosmos.dc.cmdbf.registration.ws	Hubert Leung	No
org.eclipse.cosmos.dc.datamanager.ws	org.eclipse.cosmos.dc.datamanager.ws	Hubert Leung	No
org.eclipse.cosmos.dc.logging.datamgr.ws	org.eclipse.cosmos.dc.logging.datamgr.axis	John Todd	No
org.eclipse.cosmos.dc.logging.datamgr.ws.client	org.eclipse.cosmos.dc.logging.datamgr.ws.client	John Todd	No
org.eclipse.cosmos.dc.service.finder	org.eclipse.cosmos.dc.service.finder org.eclipse.cosmos.dc.service.finder.datamodel org.eclipse.cosmos.dc.service.finder.client	Hubert Leung	No
org.eclipse.cosmos.dc.stat.datamgr.ws	org.eclipse.cosmos.dc.stat.datamgr.axis	John Todd	No
org.eclipse.cosmos.dc.stat.datamgr.ws.client	org.eclipse.cosmos.dc.stat.datamgr.ws.client	John Todd	No
org.eclipse.cosmos.dc.stat.datamgr.ws.common	org.eclipse.cosmos.dc.stat.datamgr.ws.common	John Todd	No

Archived Bundles

The following plug-ins will be archived:

1. org.eclipse.cosmos.dc.birt.helper
2. org.eclipse.cosmos.dc.broker
3. org.eclipse.cosmos.dc.broker.client
4. org.eclipse.cosmos.dc.common
5. org.eclipse.cosmos.dc.dataManager
6. org.eclipse.cosmos.dc.dataManager.client
7. org.eclipse.cosmos.dc.dataManager.common
8. org.eclipse.cosmos.dc.local.domain
9. org.eclipse.cosmos.dc.local.registry
10. org.eclipse.cosmos.dc.logging.datamgr
11. org.eclipse.cosmos.dc.logging.datamgr.client
12. org.eclipse.cosmos.dc.logging.datamgr.common
13. org.eclipse.cosmos.dc.logging.datamgr.web
14. org.eclipse.cosmos.dc.management.domain
15. org.eclipse.cosmos.dc.management.domain.client
16. org.eclipse.cosmos.dc.mdr
17. org.eclipse.cosmos.dc.mdr.client
18. org.eclipse.cosmos.dc.mdr.common
19. org.eclipse.cosmos.dc.mdr.registration
20. org.eclipse.cosmos.dc.mdr.registration.client
21. org.eclipse.cosmos.dc.mdr.registration.common
22. org.eclipse.cosmos.dc.remote.wsdm
23. org.eclipse.cosmos.dc.sample.components
24. org.eclipse.cosmos.dc.sample.configurations
25. org.eclipse.cosmos.dc.sample.jpa
26. org.eclipse.cosmos.dc.spec
27. org.eclipse.cosmos.dc.stat.datamgr
28. org.eclipse.cosmos.dc.stat.datamgr.client
29. org.eclipse.cosmos.dc.stat.datamgr.common
30. org.eclipse.cosmos.dc.stat.datamgr.web
31. org.eclipse.cosmos.dc.tptp.agentcontroller
32. org.eclipse.cosmos.dc.tptp.gla.components
33. org.eclipse.cosmos.example.mdr.web
34. org.eclipse.cosmos.management.common
35. org.eclipse.cosmos.management.wsdm
36. org.eclipse.cosmos.tptp.dependencies

Re-structuring

Plug-ins	Description	Assignee	Complete
org.eclipse.cosmos.dc.stat.datamgr.ws org.eclipse.cosmos.dc.stat.datamgr.ws.client org.eclipse.cosmos.dc.stat.datamgr.ws.common	Merge 3 plug-ins into one	John Todd	No
org.eclipse.cosmos.dc.logging.datamgr.ws org.eclipse.cosmos.dc.logging.datamgr.ws.client	Merge 2 plug-ins into one	John Todd	No

Data Visualization

Violating Plug-ins	Packages/Classes	Assignee	Complete
org.eclipse.cosmos.dr.web.ui.viewer	org.eclipse.cosmos.dr.web.ui.viewer	Sheldon Lee-Loy	No

Archived Bundles

The following plug-ins will be archived:

1. org.eclipse.cosmos.dr.build
2. org.eclipse.cosmos.dr.drs.service.handler.php
3. org.eclipse.cosmos.dr.gvs.report.viewer
4. org.eclipse.cosmos.examples.e2e.dr.gvs.report.viewer

Restructuring

The DV bundles are split between the data reporting and the examples/end2end directories. Sheldon has agreed to move all core components from the example module (if any) to the data-reporting module.

Management Enablement

Violating Plug-ins	Packages/Classes	Assignee	Complete
org.eclipse.cosmos.me.dmtoolkit.common	org.eclipse.cosmos.me.dmtoolkit.common	David Whiteman	No
org.eclipse.cosmos.me.dmtoolkit.j2ee	org.eclipse.cosmos.me.dmtoolkit.j2ee org.eclipse.cosmos.me.dmtoolkit.j2ee.delegates org.eclipse.cosmos.me.dmtoolkit.j2ee.factory org.eclipse.cosmos.me.dmtoolkit.j2ee.ui org.eclipse.cosmos.me.dmtoolkit.j2ee.util	David Whiteman	No
org.eclipse.cosmos.me.management.common	org.eclipse.cosmos.me.management.annotations org.eclipse.cosmos.me.management.api org.eclipse.cosmos.me.management.binding org.eclipse.cosmos.me.management.common org.eclipse.cosmos.me.management.common.info org.eclipse.cosmos.me.management.common.util org.eclipse.cosmos.me.management.osgi org.eclipse.cosmos.me.management.web	Joel Hawkins	No
org.eclipse.cosmos.me.management.wsdm	org.eclipse.cosmos.me.management.provisional.wsdm org.eclipse.cosmos.me.management.provisional.wsdm.annotations org.eclipse.cosmos.me.management.provisional.wsdm.capabilities org.eclipse.cosmos.me.management.provisional.wsdm.capabilities.impl org.eclipse.cosmos.me.management.provisional.wsdm.faults org.eclipse.cosmos.me.management.provisional.wsdm.impl org.eclipse.cosmos.me.management.provisional.wsdm.impl.info org.eclipse.cosmos.me.management.provisional.wsdm.persistence org.eclipse.cosmos.me.management.provisional.wsdm.util org.eclipse.cosmos.me.management.provisional.wsrf.capabilities org.eclipse.cosmos.me.management.provisional.wsrf.capabilities.impl org.eclipse.cosmos.me.management.provisional.wsrf.faults org.eclipse.cosmos.me.management.wsdm.osgi org.eclipse.cosmos.me.management.wsdm.web	Joel Hawkins	No

Re-structuring

The toolkit plug-ins can reside under one plug-in: This will reduce 2 plug-ins into one.

org.eclipse.cosmos.me.dmtoolkit
  |__ org.eclipse.cosmos.me.dmtoolkit.common
  |__ org.eclipse.cosmos.me.dmtoolkit.j2ee

Resource Modeling

Violating Plug-ins	Packages/Classes	Assignee	Complete
org.eclipse.cosmos.rm.repository	org.eclipse.cosmos.rm.repository.core org.eclipse.cosmos.rm.repository.exception org.eclipse.cosmos.rm.repository.operations org.eclipse.cosmos.rm.repository.operations.cmdbf org.eclipse.cosmos.rm.repository.resource	Ali Mehregani	No
org.eclipse.cosmos.rm.sml.mdr.ws	org.eclipse.cosmos.rm.sml.mdr.ws	Hubert Leung	No

Archived Bundles

The following plug-ins will be archived:

1. org.eclipse.cosmos.rm.sml.mdr
2. org.eclipse.cosmos.rm.sml.mdr.web

Defects

The following defects have been opened to handle the work required for this effort:

Bug	Owner
229959	Ali Mehregani
229962	David Whiteman
229958	Hubert Leung
229964	Joel Hawkins
229961	Sheldon Lee-Loy
229960	John Todd
229957	Bill Muldoon

Open Questions/Concerns

Harm Sluiman:

It seems the package provisional idea is being skipped and that is the most common form of provisional in Eclipse. Note TPTP introduced the concept of javadoc provisional only as a transient state where api was stable but behavior was not and testing or documentation was not complete. If you only have one provisional state, I strongly suggest you use the package variant.

COSMOS decided to indicate provisional APIs by including the 'provisional' keyword in the package name

Ruth Lee

1. Ali, can we look into Bill's bugzilla for this as well? He talks about deprecating any bundles and code that are no longer used, so we should identify those and delete them rather than comment them. 220776
2. Question: Looks like COSMOS does not use experimental APIs in COSMOS. What are the COSMOS guidelines for using provisional vs experimental? Eclipse Quality Guidelines

Regarding bug 220776:
>1. Deprecate any bundles and code that are no longer used.
> a. DC assemblies
> b. the "old" annotations
Addressed

>2. Re-organize the directory structure to group logically related bundles together
> a. The Example MDR bundle for OSGI is in the Examples directory but the Example MDR for the web is in the DC directory. They should reside together.
Addressed

> b. All data managers should be grouped into a single directory.
Addressed

> c. The BIRT helper bundle belongs in the data reporting (not in DC)
Addressed

> d. All the CMDBf components (CMDBf services, tooling, registration example, and the MDRs) belong in the same directory
Addressed

> e. The DV bundles are split between the data reporting and the examples/end2end directories
Addressed

> f. We have a common tests directory with subdirectories for each subproject. Should we move each of these subdirectories into a tests directory under their respective subprojects?
Community collectively decided to keep the current structure

Second question has already been raised by Harm and will be discussed during the next architecture call