[
https://issues.apache.org/jira/browse/IO-792?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17723926#comment-17723926
]
Vladimir Sitnikov edited comment on IO-792 at 5/18/23 2:40 PM:
---------------------------------------------------------------
Thanks for the clarifications, and I understand the reasons you do not want to
add parameters to constructors. Fully agree that adding more constructors there
would make it even more complicated for maintaining and using points of view.
I do not suggest un-deprecating constructors (however, it would probably make
sense to un-deprecate the one which Builder uses internally). I mean it would
be great if you could add documentation on the migration path as the migration
path is obscure for someone who did not create the builder in the first place.
I did try using the builder, and I did try using
{{Builder.newFileOrigin(file)}}, however, I was not sure if it would
automatically create an InputStream or if it would use the file name for error
reporting purposes only. So I thought "I would just add suppress deprecation
warning" instead of migrating the code to the new API.
---
The documentation for the class itself still references deprecated
constructors:
https://commons.apache.org/proper/commons-io/apidocs/org/apache/commons/io/input/BOMInputStream.html
was (Author: vladimirsitnikov):
Thanks for the clarifications, and I understand the reasons you do not want to
add parameters to constructors. Fully agree that adding more constructors there
would make it even more complicated for maintaining and using points of view.
I do not suggest un-deprecating constructors (however, it would probably make
sense to un-deprecate the one which Builder uses internally). I mean it would
be great if you could add documentation on the migration path as the migration
path is obscure for someone who did not create the builder in the first place.
I did try using the builder, and I did try using
{{Builder.newFileOrigin(file)}}, however, I was not sure if it would
automatically create an InputStream or if it would use the file name for error
reporting purposes only. So I thought "I would just add suppress deprecation
warning" instead of migrating the code to the new API.
---
However, as someone who runs into "you can no longer use
{{BOMInputStream(Files.newInputStream(fileEntry.file.toPath()))}}", it is
problematic to find the replacement, and BOMInputStream.Builder.html does not
make it easier.
I think it would be great if similar examples were added right to the
deprecated constructors.
The documentation for the class itself still references deprecated
constructors:
https://commons.apache.org/proper/commons-io/apidocs/org/apache/commons/io/input/BOMInputStream.html
> 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)
