[
https://issues.apache.org/jira/browse/IO-792?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17723921#comment-17723921
]
Gary D. Gregory commented on IO-792:
------------------------------------
Hello [~vladimirsitnikov]
Please the Javadoc here
[https://commons.apache.org/proper/commons-io/apidocs/org/apache/commons/io/input/BOMInputStream.Builder.html]
The idea behind deprecating constructors for builders is that with every
release we usually add constructors here and there and we end up with some
classes with ten constructors (for one of many examples, see
[XmlStreamReader|https://commons.apache.org/proper/commons-io/apidocs/org/apache/commons/io/input/XmlStreamReader.html]).
Instead, using a builder, keeps the constructor count to one (or two) and we
can just grow setter methods on builders.
> 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)
