You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Add missing @Deprecated(forRemoval = true) for deleted in 7.0Β #36591
There are a lot of classes/methods/constructors removed in 7.0 release. Many of these are missing @Deprecated(forRemoval=true) annotations (even just @Deprecated is missing) in the latest 6.2.17.
This may be critical as during migration you need to distinguish which deprecations are critical and which are not.
For a trivial microservice based on pure spring-boot this can be quite ok as it will simply lead to compilation failures highlighting all cases.
But for the huge codebases with hundreds of libraries this is quite challenging. For org.springframework.* libraries there is confidence (as we mostly take their versions from spring-boot-dependencies, others can be found on https://spring.io/projects/generations#mappings), but for own libraries based on spring as well as any third-party this can become an issue caught in the runtime.
E.g. within our organization we implemented arch-unit tests scanning project modules and all JAR dependencies on usages of classes/methods/constructors/fields marked as @Deprecated(forRemoval = true) to make the migration more safe.
The list of classes, methods, constructors and fields missing the proper annotation: β οΈ these are replaced with updated lists in the comments (as original lists had false positives)
I've added all lists that I planned (see issue description)
if the class is mentioned in the missing-deprecated-forRemoval-classes.txt, items from it are not listed for missing deprecations for constructors/methods/fields
I've separated protected and public members to different files
sorry if some of the lines are false positives (the list was so big, but the report was semi-automated so it's at least looks reasonable)
Thanks for your work @seregamorph .
I have processed the missing-deprecated-forRemoval-classes.txt and I think there are a lot of false positives. To me, the only invalid case would be deleting a class that was not marked previously @Deprecated(since="...", forRemoval = true).
Is there a bug in your archunit check maybe? I can continue processing the files you provided, but removing the false positives would help a lot. Maybe your tool considers that a type should be first @Deprecated and then @Deprecated(forRemoval = true) as a second step? In my opinion, deprecating for removal in one step is a valid use of the annotation and communicates the removal intent directly.
org.springframework.core.codec.Netty5BufferDecoder
org.springframework.core.codec.Netty5BufferEncoder
org.springframework.core.io.buffer.Netty5DataBuffer
org.springframework.core.io.buffer.Netty5DataBufferFactory
org.springframework.http.client.reactive.ReactorNetty2ClientHttpConnector
org.springframework.http.client.reactive.ReactorNetty2ResourceFactory
org.springframework.http.server.reactive.JettyHttpHandlerAdapter [see 3b65506c13f18535e2fb055fd790bf45efb13de5]
org.springframework.http.server.reactive.ReactorNetty2HttpHandlerAdapter
org.springframework.http.server.reactive.UndertowHttpHandlerAdapter
org.springframework.http.support.Netty5HeadersAdapter
org.springframework.messaging.tcp.reactor.ReactorNetty2TcpClient
org.springframework.messaging.tcp.reactor.ReactorNetty2TcpConnection
org.springframework.web.reactive.socket.adapter.Netty5WebSocketSessionSupport
org.springframework.web.reactive.socket.adapter.ReactorNetty2WebSocketSession
org.springframework.web.reactive.socket.adapter.UndertowWebSocketHandlerAdapter
org.springframework.web.reactive.socket.adapter.UndertowWebSocketSession
org.springframework.web.reactive.socket.client.ReactorNetty2WebSocketClient
org.springframework.web.reactive.socket.client.UndertowWebSocketClient
org.springframework.web.reactive.socket.server.upgrade.ReactorNetty2RequestUpgradeStrategy (see gh-33744)
org.springframework.web.reactive.socket.server.upgrade.TomcatRequestUpgradeStrategy (see gh-33744)
org.springframework.web.reactive.socket.server.upgrade.UndertowRequestUpgradeStrategy (see gh-33744)
org.springframework.web.servlet.view.document.AbstractPdfStamperView
org.springframework.web.servlet.view.document.AbstractPdfView
org.springframework.web.servlet.view.document.AbstractXlsView
org.springframework.web.servlet.view.document.AbstractXlsxStreamingView
org.springframework.web.servlet.view.document.AbstractXlsxView
org.springframework.web.servlet.view.feed.AbstractAtomFeedView
org.springframework.web.servlet.view.feed.AbstractFeedView
org.springframework.web.servlet.view.feed.AbstractRssFeedView
rg.springframework.web.socket.server.standard.AbstractStandardUpgradeStrategy (see gh-33744)
org.springframework.web.socket.server.standard.AbstractTyrusRequestUpgradeStrategy (see gh-33744)
org.springframework.web.socket.server.standard.GlassFishRequestUpgradeStrategy (see gh-33744)
org.springframework.web.socket.server.standard.TomcatRequestUpgradeStrategy (see gh-33744)
org.springframework.web.socket.server.standard.UndertowRequestUpgradeStrategy (see gh-33744)
org.springframework.web.socket.server.standard.WebLogicRequestUpgradeStrategy (see gh-33744)
org.springframework.web.socket.server.standard.WebSphereRequestUpgradeStrategy (see gh-33744)
org.springframework.web.socket.sockjs.client.UndertowXhrTransport
Hibernate 5
The org.springframework.orm.hibernate5 package is a special case, see #35111. The change was called out in our documentation, but I'm wondering if @Deprecate-ing those types now would have any net benefit. What do you think @jhoeller ?
I see what was my mistake (if the class is marked for deletion in spring-framework 7, but still present), that's indeed false positives. Will re-calculate the lists.
Sorry
I removed hibernate5 from this list. Also spring-jcl is not listed here (as it's not a valid case to mention it there). Note: as for now the lists of methods/constructors/fields are NOT yet updated
While re-calculating the list of missing deprecated annotations for methods, I've found one more interesting pitfall.
E.g. org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.isSingleton() looks like deleted, but actually it's now inherited via the super-interface default method :)
E.g. org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.isSingleton() looks like deleted, but actually it's now inherited via the super-interface default method :)
With major upgrades, we try to keep source compatibility as much as possible but we don't guarantee binary compatibility. We don't expect any application/library to be runtime compatible with both 6.2.x and 7.0.x.
I'm working on the updated list. Some of the reported types (like the Theme support) were deprecated in 6.0 but we didn't use the forRemoval flag back then. This means that since 6.0 developers need to suppress deprecation warnings to use these types. We are quite late in the 6.2.x line, so I don't think it's worth adding that removal flag now:
developers who added @SuppressWarnings("deprecation") will see a new compilation error and will need to update those to @SuppressWarnings("removal")
developers who are simply ignoring compilation warnings won't see any difference
We're now trying to consistently add forRemoval when we know the API will be removed in a future release. I guess that for those instances, it's not worth punishing developers during a maintenance upgrade. So I'll just go ahead and add @Deprecated on class/methods that were completely missing that information.
Another note on the WebSocket *UpgradeStrategy. As noted in gh-33744, it's really the Jakarta baseline upgrade that makes those immediately outdated. @Deprecate-ing those in 6.2.x has no meaning since Framework users might have no other choice if they're not using Jakarta WebSocket 2.1 already. I won't be deprecating those as a result.
Regarding methods this needs more complicated code analysis for reasons discussed before (consider inheritance), so I'll try to submit the updated list a bit later
I think all of those are already @Deprecated, admittedly without any since nor forRemoval information. Same reasoning: at this stage, adding forRemoval is just likely to annoy developers late in the 6.2.x generation since they already got the message.
List of constructors that seems to be missing @Deprecated(forRemoval = true):
Those could be deprecated, but they have no replacement we can point developers to. Typically unfortunate breaking changes that we couldn't avoid or methods that we think are not likely to be used by the community.
Regarding methods this needs more complicated code analysis for reasons discussed before (consider inheritance), so I'll try to submit the updated list a bit later
Thanks for your efforts here @seregamorph - maybe don't spend a lot of time on this. I guess you encountered concrete cases while upgrading and we'd rather target those as a priority.
So, what is the policy of deprecation in particular for the spring-framework project?
I see that there are many classes/methods/constructors that are removed and the replacement introduced in the same version update. This means that any project that intends to migrate from 6.2.x to 7.0.x will need not only to update dependencies, but also to address all these cases in the same commit. Shouldn't we have migration versions like we had spring-boot 2.7 or spring-security 5.8 providing both back and forward compatible code (say, for AutoConfiguration declarations)? I understand that for the group of Spring projects the policy can be different and things like breaking spring-boot-autoconfigure rearrangements cannot be accomplished this way. But Spring Framework is the core element of this family and can have more strict and seamless policies.
I really liked how the MockBean replacement was introduced, the only problem was that we had to temporarily disable -Werror sensitive kotlin failures as there were too many deprecation warnings (it was returned back within few days once we ensured the Spring update is okay).
Don't get me wrong, I really like how the project is evolving (and the diff between 6.x and 7.x is really significant). I just want to have an opportunity to move with updates in smaller steps (our main monolith application has 1000+ modules and 1000+ libraries, so I prefer smaller updates whenever possible with intermediate production releases to find root cause more easily in case of possible issues).
This problem is not only related to major version update. I had similar during spring-framework 6.1->6.2 (Spring Boot 3.4) migration. E.g. DefaultResponseErrorHandler.handleError(response, statusCode) was removed and a replacement was introduced in the same version update (with 4 arguments). Rechecking this, seems to be the only problem on minor updates, but still - this looks like a candidate for the automation to avoid such scenarios in general.
So, what is the policy of deprecation in particular for the spring-framework project?
We intend to keep binary compatibility for minor upgrades and source compatibility for major upgrades whenever possible. As we have seen, there are cases where we cannot keep that arrangement (like the Netty 5, Hibernate 5 integrations).
In the course of this conversation we did find a lot of false positives and fixed actual cases.
I see that there are many classes/methods/constructors that are removed and the replacement introduced in the same version update. This means that any project that intends to migrate from 6.2.x to 7.0.x will need not only to update dependencies, but also to address all these cases in the same commit.
Can you share examples for those? Did we miss other cases? Where should I look? I would really like to make progress here and focus on actionable items. Again, we have a mostly public, very large API surface so we tend to be more flexible when APIs aren't really user facing (as in the main programming model) and they target library integrations.
Shouldn't we have migration versions like we had spring-boot 2.7 or spring-security 5.8 providing both back and forward compatible code (say, for AutoConfiguration declarations)? I understand that for the group of Spring projects the policy can be different and things like breaking spring-boot-autoconfigure rearrangements cannot be accomplished this way. But Spring Framework is the core element of this family and can have more strict and seamless policies.
Spring Framework is indeed in a unique position. Almost our entire codebase has public visibility because it can be used by libraries and frameworks. We do have a strong culture of backwards compatibility but obviously sometimes we fail.
This problem is not only related to major version update. I had similar during spring-framework 6.1->6.2 (Spring Boot 3.4) migration. E.g. DefaultResponseErrorHandler.handleError(response, statusCode) was removed and a replacement was introduced in the same version update (with 4 arguments). Rechecking this, seems to be the only problem on minor updates, but still - this looks like a candidate for the automation to avoid such scenarios in general.
I would consider that a positive outcome. Out of a very large API surface we managed to ship lots of features and changes and only breaking once.
I agree that automating it would be a plus but as you've experienced it yourself it's not so easy and we are operating with limited resources. We had such an arrangement in the past and maintained API diffs reports for each release, but nobody really cared. I will look into this again.
org.springframework.web.util.ContentCachingRequestWrapper is removing constructor with a single parameter HttpServletRequest. There is a second constructor since 4.3.6
public ContentCachingRequestWrapper(HttpServletRequest request, int contentCacheLimit) {
but the problem here is that if you want to have an unbounded wrapper, you cannot use this constructor before Spring Framework 7 (it throws an exception if the contentCacheLimit==0 in Spring Framework 6, but is allowed in Spring Framework 7).
In other words, unbounded can be implemented only this way:
Spring Framework 6: new ContentCachingRequestWrapper(request)
Spring Framework 7: new ContentCachingRequestWrapper(request, 0)
HttpHeaders
HttpHeaders does not implement MultiValueMap since 7.0.
The problems are with calls inherited from Map. The replacement is provided only together with removing super interface headers.containsKey() -> headers.containsHeader
There is no containsHeader() in Spring Framework 6, and no containsKey() in Spring Framework 7
All other findings are mostly related to Kotlin nullability checks. That's out of scope for this issue, discussed here #36599 (BTW curious of your opinion as well)
The ContentCachingRequestWrapper part has been fixed in #36620, thanks for your feedback.
The HttpHeaders changes have been outlined in the upgrade guide and we carefully considered alternatives. It is unfortunate but we believe that applications must adapt to this breaking change in 7.0. Backporting a headers.containsHeader method now and deprecating the other would only break existing applications in a maintenance release and would not reflect the attention needed to this matter: HTTP headers should not be considered as a Map anymore.
Activity
seregamorph commentedon Apr 3, 2026
@bclozel few notes:
missing-deprecated-forRemoval-classes.txt, items from it are not listed for missing deprecations for constructors/methods/fieldsprotectedandpublicmembers to different filesbclozel commentedon Apr 3, 2026
Thanks for your work @seregamorph .
I have processed the
missing-deprecated-forRemoval-classes.txtand I think there are a lot of false positives. To me, the only invalid case would be deleting a class that was not marked previously@Deprecated(since="...", forRemoval = true).Is there a bug in your archunit check maybe? I can continue processing the files you provided, but removing the false positives would help a lot. Maybe your tool considers that a type should be first
@Deprecatedand then@Deprecated(forRemoval = true)as a second step? In my opinion, deprecating for removal in one step is a valid use of the annotation and communicates the removal intent directly.False positives
org.springframework.aot.agent.*@DeprecatedforRemovalorg.springframework.aot.hint.*@DeprecatedforRemovalorg.springframework.aot.hint.predicate.*@DeprecatedforRemovalorg.springframework.aot.test.agent.*@DeprecatedforRemovalorg.springframework.beans.factory.config.*@Deprecated@DeprecatedforRemovalorg.springframework.beans.support.*@DeprecatedforRemovalorg.springframework.core.io.*@DeprecatedforRemovalorg.springframework.dao.support.*@DeprecatedforRemovalorg.springframework.http.converter.*@DeprecatedforRemovalorg.springframework.jdbc.core.*@DeprecatedforRemovalorg.springframework.jms.*@DeprecatedforRemovalorg.springframework.test.http.*@DeprecatedforRemovalorg.springframework.web.reactive.result.method.annotation.*@DeprecatedforRemovalorg.springframework.web.servlet.handler.*@DeprecatedforRemovalorg.springframework.web.servlet.mvc.condition.*@DeprecatedforRemovalorg.springframework.web.servlet.mvc.method.annotation.*@DeprecatedforRemovalorg.springframework.web.servlet.view.json.*@DeprecatedforRemovalorg.springframework.web.servlet.view.xml.*@DeprecatedforRemovalorg.springframework.web.socket.sockjs.frame.*@DeprecatedforRemoval@DeprecatedwithoutforRemovaland removedRemoved with no prior warning:
Hibernate 5
The
org.springframework.orm.hibernate5package is a special case, see #35111. The change was called out in our documentation, but I'm wondering if@Deprecate-ing those types now would have any net benefit. What do you think @jhoeller ?seregamorph commentedon Apr 3, 2026
I see what was my mistake (if the class is marked for deletion in spring-framework 7, but still present), that's indeed false positives. Will re-calculate the lists.
Sorry
seregamorph commentedon Apr 3, 2026
Updated list of classes which are missing
@Deprecatedor@Deprecated(forRemoval = true):I removed hibernate5 from this list. Also
spring-jclis not listed here (as it's not a valid case to mention it there). Note: as for now the lists of methods/constructors/fields are NOT yet updatedseregamorph commentedon Apr 3, 2026
While re-calculating the list of missing deprecated annotations for methods, I've found one more interesting pitfall.
E.g.
org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.isSingleton()looks like deleted, but actually it's now inherited via the super-interfacedefaultmethod :)bclozel commentedon Apr 3, 2026
Thanks for the update @seregamorph .
With major upgrades, we try to keep source compatibility as much as possible but we don't guarantee binary compatibility. We don't expect any application/library to be runtime compatible with both 6.2.x and 7.0.x.
I'm working on the updated list. Some of the reported types (like the
Themesupport) were deprecated in 6.0 but we didn't use theforRemovalflag back then. This means that since 6.0 developers need to suppress deprecation warnings to use these types. We are quite late in the 6.2.x line, so I don't think it's worth adding that removal flag now:@SuppressWarnings("deprecation")will see a new compilation error and will need to update those to@SuppressWarnings("removal")We're now trying to consistently add
forRemovalwhen we know the API will be removed in a future release. I guess that for those instances, it's not worth punishing developers during a maintenance upgrade. So I'll just go ahead and add@Deprecatedon class/methods that were completely missing that information.bclozel commentedon Apr 3, 2026
Another note on the WebSocket
*UpgradeStrategy. As noted in gh-33744, it's really the Jakarta baseline upgrade that makes those immediately outdated.@Deprecate-ing those in 6.2.x has no meaning since Framework users might have no other choice if they're not using Jakarta WebSocket 2.1 already. I won't be deprecating those as a result.seregamorph commentedon Apr 3, 2026
WDYT regarding marking these static consts that are removed in 7.0?:
seregamorph commentedon Apr 3, 2026
List of constructors that seems to be missing
@Deprecated(forRemoval = true):Regarding methods this needs more complicated code analysis for reasons discussed before (consider inheritance), so I'll try to submit the updated list a bit later
bclozel commentedon Apr 3, 2026
I think all of those are already
@Deprecated, admittedly without anysincenorforRemovalinformation. Same reasoning: at this stage, addingforRemovalis just likely to annoy developers late in the 6.2.x generation since they already got the message.Those already had the
@Deprecatedannotation, so same reasoning.Those could be deprecated, but they have no replacement we can point developers to. Typically unfortunate breaking changes that we couldn't avoid or methods that we think are not likely to be used by the community.
I think the constructors were never meant to be public and there is no use for public instantiation of those types.
Was replaced by
public RestTemplate(Iterable<HttpMessageConverter<?>> messageConverters), a source compatible change.This one is indeed missing, I think it was missed during #33914 I'll fix that here.
bclozel commentedon Apr 3, 2026
Thanks for your efforts here @seregamorph - maybe don't spend a lot of time on this. I guess you encountered concrete cases while upgrading and we'd rather target those as a priority.
Deprecate types removed in 7.0
seregamorph commentedon Apr 5, 2026
So, what is the policy of deprecation in particular for the spring-framework project?
I see that there are many classes/methods/constructors that are removed and the replacement introduced in the same version update. This means that any project that intends to migrate from
6.2.xto7.0.xwill need not only to update dependencies, but also to address all these cases in the same commit. Shouldn't we have migration versions like we had spring-boot2.7or spring-security5.8providing both back and forward compatible code (say, for AutoConfiguration declarations)? I understand that for the group of Spring projects the policy can be different and things like breakingspring-boot-autoconfigurerearrangements cannot be accomplished this way. But Spring Framework is the core element of this family and can have more strict and seamless policies.I really liked how the MockBean replacement was introduced, the only problem was that we had to temporarily disable
-Werrorsensitive kotlin failures as there were too many deprecation warnings (it was returned back within few days once we ensured the Spring update is okay).Don't get me wrong, I really like how the project is evolving (and the diff between 6.x and 7.x is really significant). I just want to have an opportunity to move with updates in smaller steps (our main monolith application has 1000+ modules and 1000+ libraries, so I prefer smaller updates whenever possible with intermediate production releases to find root cause more easily in case of possible issues).
This problem is not only related to major version update. I had similar during spring-framework 6.1->6.2 (Spring Boot 3.4) migration. E.g.
DefaultResponseErrorHandler.handleError(response, statusCode)was removed and a replacement was introduced in the same version update (with 4 arguments). Rechecking this, seems to be the only problem on minor updates, but still - this looks like a candidate for the automation to avoid such scenarios in general.bclozel commentedon Apr 6, 2026
We intend to keep binary compatibility for minor upgrades and source compatibility for major upgrades whenever possible. As we have seen, there are cases where we cannot keep that arrangement (like the Netty 5, Hibernate 5 integrations).
In the course of this conversation we did find a lot of false positives and fixed actual cases.
Can you share examples for those? Did we miss other cases? Where should I look? I would really like to make progress here and focus on actionable items. Again, we have a mostly public, very large API surface so we tend to be more flexible when APIs aren't really user facing (as in the main programming model) and they target library integrations.
Spring Framework is indeed in a unique position. Almost our entire codebase has public visibility because it can be used by libraries and frameworks. We do have a strong culture of backwards compatibility but obviously sometimes we fail.
I would consider that a positive outcome. Out of a very large API surface we managed to ship lots of features and changes and only breaking once.
I agree that automating it would be a plus but as you've experienced it yourself it's not so easy and we are operating with limited resources. We had such an arrangement in the past and maintained API diffs reports for each release, but nobody really cared. I will look into this again.
seregamorph commentedon Apr 8, 2026
Actually only two of these.
ContentCachingRequestWrapper
org.springframework.web.util.ContentCachingRequestWrapperis removing constructor with a single parameterHttpServletRequest. There is a second constructor since4.3.6but the problem here is that if you want to have an unbounded wrapper, you cannot use this constructor before Spring Framework 7 (it throws an exception if the
contentCacheLimit==0in Spring Framework 6, but is allowed in Spring Framework 7).In other words, unbounded can be implemented only this way:
new ContentCachingRequestWrapper(request)new ContentCachingRequestWrapper(request, 0)HttpHeaders
HttpHeadersdoes not implementMultiValueMapsince 7.0.The problems are with calls inherited from
Map. The replacement is provided only together with removing super interfaceheaders.containsKey()->headers.containsHeaderThere is no
containsHeader()in Spring Framework 6, and nocontainsKey()in Spring Framework 7All other findings are mostly related to Kotlin nullability checks. That's out of scope for this issue, discussed here #36599 (BTW curious of your opinion as well)
bclozel commentedon Apr 8, 2026
The
ContentCachingRequestWrapperpart has been fixed in #36620, thanks for your feedback.The
HttpHeaderschanges have been outlined in the upgrade guide and we carefully considered alternatives. It is unfortunate but we believe that applications must adapt to this breaking change in 7.0. Backporting aheaders.containsHeadermethod now and deprecating the other would only break existing applications in a maintenance release and would not reflect the attention needed to this matter: HTTP headers should not be considered as a Map anymore.seregamorph commentedon Apr 8, 2026
Thank you very much for the clarifications and glad to hear one of the problems is addressed within
6.2.18bclozel commentedon Apr 10, 2026
I think this issue has run its course, I've opened #36640 to consider next steps.