[
https://issues.apache.org/jira/browse/IO-792?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17724158#comment-17724158
]
Vladimir Sitnikov commented on IO-792:
--------------------------------------
The current state of deprecation in Java seems as follows:
1) {{@InlineMe}} annotation appears in javadoc, and it appears in quick info at
the call site, so I believe it is helpful for the users
2) {{-Xlint:deprecation}} wins over Errorprone processing. That is unfortunate.
If a method is deprecated and has InlineMe at the same time, then compilation
fails as follows:
{noformat}
FileServer.java:428: warning: [deprecation] BOMInputStream2(InputStream) in
BOMInputStream2 has been deprecated
BOMInputStream2 is = new
BOMInputStream2(Files.newInputStream(Paths.get("hello")));
^
{noformat}
If I remove "lint:deprecation", then the failure becomes
{noformat}
FileServer.java:428: warning: [InlineMeInliner] Migrate (via inlining) away
from deprecated `BOMInputStream2.<init>()`.
BOMInputStream2 is = new
BOMInputStream2(Files.newInputStream(Paths.get("hello")));
^
(see https://errorprone.info/bugpattern/InlineMeInliner)
Did you mean 'BOMInputStream2 is =
BOMInputStream.builder().setInputStream(Files.newInputStream(Paths.get("hello"))).get();'?
{noformat}
3) IDEA does not yet support the automatic handling of {{{}@InlineMe{}}}, see
[https://youtrack.jetbrains.com/issue/IDEA-275990/Quickfix-using-InlineMe-annotation-from-Errorprone]
4) Errorprone has [https://errorprone.info/bugpattern/InlineMeSuggester] that
can report "did you mean..."
5) IDEA understands the following pattern in javadoc: {{@deprecated use \{@link
#of()\} instead}}. However, it does not support suggestions for constructors.
See
[https://github.com/JetBrains/intellij-community/blob/24e147cc018ff9ad646d0497eb4e65ef890ca5f0/java/java-analysis-impl/src/com/intellij/codeInspection/deprecation/DeprecationInspectionBase.java#L169],
Sample class for testing purposes:
{code:java}
public class BOMInputStream2 {
/**
* test.
* @param delegate
* @deprecated use {@link #of(InputStream)} instead
*/
@Deprecated
@InlineMe(replacement =
"BOMInputStream.builder().setInputStream(delegate).get()", imports =
{"org.apache.commons.io.input.BOMInputStream"})
public BOMInputStream2(final InputStream delegate) {
}
public static BOMInputStream2 of(InputStream delegate) {
return null;
}
/**
* test.
* @param delegate
* @deprecated use {@link #of()} instead
*/
@Deprecated
public static BOMInputStream2 TEST = new BOMInputStream2(null);
public static BOMInputStream2 of() {
return null;
}
}
{code}
> Add documentation how to migrate new BOMInputStream code
> --------------------------------------------------------
>
> Key: IO-792
> URL: https://issues.apache.org/jira/browse/IO-792
> Project: Commons IO
> Issue Type: Improvement
> Components: Streams/Writers
> Affects Versions: 2.12.0
> Reporter: Vladimir Sitnikov
> Priority: Major
>
> Recently, all the constructors of {{BOMInputStream}} got deprecated.
> It causes build failures when project lint for deprecation usages.
> See build failure in https://github.com/apache/jmeter/pull/5924
> The are three problems:
> P1) Unfortunately, in the case of {{new BOMInputStream}}, the API is obscure.
> The documentation merely says {{Deprecated Use builder()}}, and it is hard to
> understand what is the right way to migrate old code.
> Imagine the build fails at the following line:
> {code:java}BOMInputStream fis = new
> BOMInputStream(Files.newInputStream(fileEntry.file.toPath()));{code}
> What is the intended replacement?
> P2) {{BOMInputStream(final InputStream delegate, final boolean include, final
> ByteOrderMark... boms)}} constructor is both deprecated and used in builder
> internally.
> Is there a true reason for deprecating the method? Does it miss a vital
> parameter?
> P3) Javadoc above {{class BOMInputStream}} still promotes {{new
> BOMInputStream}} which is, well, deprecated.
> I would suggest:
> 1) Document deprecation reasons, and provide migration code.
> For instance, for constructors you could provide exact call to the builder
> API instead of the current "use builder()"
> 2) Fix javadocs above {{BOMInputStream}}
> 3) Consider using ErrorProne annotations for automatic migration to the new
> APIs: {{@InlineMe(replacement = "...")}}. It appears in javadocs, and it
> makes it easier for the users to migrate (IDEs can migrate automatically):
> https://javadoc.io/static/io.grpc/grpc-api/1.47.0/io/grpc/NameResolver.Listener2.html#onAddresses-java.util.List-io.grpc.Attributes-
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
