[
https://issues.apache.org/jira/browse/IO-792?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17724030#comment-17724030
]
Gary D. Gregory commented on IO-792:
------------------------------------
{quote}If the deprecated constructor `BOMInputStream(File file)` had something
like `100% identical to BOMInputStream.builder().newFileOrigin(file)`, then it
would be awesome.
{quote}
That won't even compile ;)
See the Javadoc, reproduced here:
{code:java}
org.apache.commons.io.input.BOMInputStream
This class is used to wrap a stream that includes an encoded ByteOrderMark as
its first bytes.
This class detects these bytes and, if required, can automatically skip them
and return the subsequent byte as thefirst byte in the stream.
The ByteOrderMark implementation has the following predefined BOMs:
•UTF-8 - ByteOrderMark.UTF_8
•UTF-16BE - ByteOrderMark.UTF_16LE
•UTF-16LE - ByteOrderMark.UTF_16BE
•UTF-32BE - ByteOrderMark.UTF_32LE
•UTF-32LE - ByteOrderMark.UTF_32BE
To build an instance, see Builder.
Example 1 - Detecting and excluding a UTF-8 BOM
BOMInputStream bomIn = BOMInputStream.builder().setInputStream(in).get();
if (bomIn.hasBOM()) {
// has a UTF-8 BOM
}
Example 2 - Detecting a UTF-8 BOM without excluding it
boolean include = true;
BOMInputStream bomIn = BOMInputStream.builder()
.setInputStream(in)
.setInclude(include)
.get();
if (bomIn.hasBOM()) {
// has a UTF-8 BOM
}
Example 3 - Detecting Multiple BOMs
BOMInputStream bomIn = BOMInputStream.builder()
.setInputStream(in)
.setByteOrderMarks(ByteOrderMark.UTF_16LE, ByteOrderMark.UTF_16BE,
ByteOrderMark.UTF_32LE, ByteOrderMark.UTF_32BE)
.get();
if (bomIn.hasBOM() == false) {
// No BOM found
} else if (bomIn.hasBOM(ByteOrderMark.UTF_16LE)) {
// has a UTF-16LE BOM
} else if (bomIn.hasBOM(ByteOrderMark.UTF_16BE)) {
// has a UTF-16BE BOM
} else if (bomIn.hasBOM(ByteOrderMark.UTF_32LE)) {
// has a UTF-32LE BOM
} else if (bomIn.hasBOM(ByteOrderMark.UTF_32BE)) {
// has a UTF-32BE BOM
}
Since:2.0See Also:org.apache.commons.io.ByteOrderMarkWikipedia - Byte Order Mark
{code}
and:
{code:java}
org.apache.commons.io.input.BOMInputStream.Builder
Builds a new BOMInputStream instance.
Using NIO
BOMInputStream s = BOMInputStream.builder()
.setPath(Paths.get("MyFile.xml"))
.setByteOrderMarks(ByteOrderMark.UTF_8)
.setInclude(false)
.get()
Using IO
BOMInputStream s = BOMInputStream.builder()
.setFile(new File("MyFile.xml"))
.setByteOrderMarks(ByteOrderMark.UTF_8)
.setInclude(false)
.get()
Since:2.12.0
{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)
