[
https://issues.apache.org/jira/browse/IO-792?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Gary D. Gregory resolved IO-792.
--------------------------------
Fix Version/s: 2.13.0
Resolution: Fixed
I've updated the Javadoc throughout with examples.
> 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
> Fix For: 2.13.0
>
>
> 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)
