Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 370363

Summary:	Missing APIs in Juno
Product:	[WebTools] Dali JPA Tools	Reporter:	Kenneth Cheung <kennethc>
Component:	General	Assignee:	dali.general-inbox <dali.general-inbox>
Status:	RESOLVED WONTFIX	QA Contact:
Severity:	major
Priority:	P3	CC:	agueda, cbridgha, ccc, david_williams, deboer, jpitman, neil.hauge, thatnitind, theivend
Version:	unspecified
Target Milestone:	---
Hardware:	PC
OS:	Windows XP
Whiteboard:

Description Kenneth Cheung

2012-02-01 14:00:35 EST

Build Identifier: Version 4.2 Build id: I20120127-1145

Our adopting product supports Eclipse 3.6.2 and Eclipse 3.7.2 and above.  Our plugins fail to compile against Eclipse 4.2 because of missing APIs.

The following APIs are missing from Juno:
org.eclipse.jpt.jpa.core.context.PersistentType.allAttributes()
org.eclipse.jpt.jpa.core.context.QueryContainer.namedQueries()
org.eclipse.jpt.jpa.core.context.ReadOnlyJoinColumnRelationshipStrategy.specifiedJoinColumnsSize()
org.eclipse.jpt.jpa.core.context.java.JavaJoinColumnRelationshipStrategy.specifiedJoinColumns()
org.eclipse.jpt.jpa.core.context.java.JavaPersistentAttribute.getResourcePersistentAttribute()
org.eclipse.jpt.jpa.core.context.persistence.Persistence.persistenceUnits()
org.eclipse.jpt.jpa.core.context.persistence.PersistenceUnit.classRefs()
org.eclipse.jpt.jpa.core.context.persistence.PersistenceUnit.mappingFileRefs()

While for most of them the replacments are quite obvious, their removing is not conforming to http://wiki.eclipse.org/WTP_API_Policy

Provisional API may evolve during the first milestones but it must be frozen by the regular API freeze date of a release and will not change for the remainder of the release and the corresponding maintenance releases. Exceptions must be approved by the PMC. 

PMC is required for any changes after Indigo's M6... which was almost a year ago.

Reproducible: Always

Comment 1 Neil Hauge

2012-02-01 14:30:08 EST

I think you might be misinterpreting the API policy.  I think all of these referenced API changes occurred in Juno M1/M2.  Juno is not a maintenance release, and is not associated with the Indigo release in any way.  As a result, provisional API's can be changed with no expectation of compatibility with the previous release as per the policy.  That said, we do want to avoid unnecessary churn, and are hoping that much of our API can become public in the near future.

Let me know if I am incorrect about any of these changes occurring late in the Indigo release or in an Indigo maintenance release.  If they did, they should have corresponding PMC approval as you state.

Comment 2 Kenneth Cheung

2012-02-01 14:51:55 EST

Hi Neil,

You were correct that there were changes in those APIs during Juno.  However, the APIs already existed in Indigo GM.  The policy states any changes should be announced for discussion - and we can't find a bugzilla.

Comment 3 Neil Hauge

2012-02-01 16:41:14 EST

It has been our general policy to pre-announce any API changes after the M6 API freeze to help adopters who are building on the latest I-builds/milestones.  The API policy does recommend notification of changes to provisional API whenever they occur, and it sounds like this is what you are looking for.  If this is going to be helpful for you then I think we can make this happen.  My preference would be to do this on the mailing list or forum, as the bug database is not widely followed.

What I think would be the most helpful would be a good migration guide.  I think a real-time migration guide should be our main focus, and this bug is a good reminder to keep one up-to-date as we go, as opposed to building one at the end of the release.

Comment 4 Nitin Dahyabhai

2012-02-01 17:02:00 EST

http://wiki.eclipse.org/New_Help_for_Old_Friends_VII ?

Comment 5 Neil Hauge

2012-02-01 17:20:42 EST

(In reply to comment #4)
> http://wiki.eclipse.org/New_Help_for_Old_Friends_VII ?

Yes...that would be the document of choice to use.

Comment 6 Chuck Bridgham

2012-02-02 11:19:22 EST

I do think we need to revisit what it means to be a provisional api, as most of these classes have existed in this state for almost 4 years, and multiple releases.

Is it possible for the compatibility methods to be restored?  If they are going to be removed, then adding  @deprecated would help users stay away from these for now.

Comment 7 Neil Hauge

2012-02-02 13:57:26 EST

(In reply to comment #6)
> I do think we need to revisit what it means to be a provisional api, as most of
> these classes have existed in this state for almost 4 years, and multiple
> releases.

Actually, I don't think we have a single provisional API (except for maybe a couple of utility classes) that has not changed within the last year (for Indigo).  That doesn't sound great to some adopters, but does happen to be the case.  Our API has changed quite a bit over the last 3 years to reflect new spec levels (which change fundamental assumptions about the underlying technology) and to accommodate new technologies (JAXB), which was responsible for the most recent set of changes.  Our hope is that with our supported specifications reaching a more mature phase that we can finally move much of our provisional API to public.

This is quite different than many other WTP API's that have been in a stagnant provisional state for some time.

> 
> Is it possible for the compatibility methods to be restored?  If they are going
> to be removed, then adding  @deprecated would help users stay away from these
> for now.

The compatibility methods were added to our 3.1 release for adopters who were trying to remain binary compatible with Indigo (since that was the only available release train).  Since the upcoming 3.2 release is a Juno release, we do not intend to have compatibility methods for that release.  I should have marked those as deprecated for their short existence to make that more obvious.  See bug 319736 for information how to migrate to the API related to the compatibility methods.  This should be fairly trivial.  And as always, the Dali team is ready to help quickly with any migration issues that may arise.

Comment 8 Neil Hauge

2012-02-16 17:33:08 EST

Closing this as won't fix, but have opened bug 371824 to address the larger public API question.  We are also going to make a better effort at tracking provisional API changes on a milestone by milestone basis.