You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@commons.apache.org by "Gary D. Gregory (Jira)" <ji...@apache.org> on 2023/05/31 15:39:00 UTC

[jira] [Resolved] (IO-792) Add documentation how to migrate new BOMInputStream code

     [ 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)