Re: Can we deprecate Path.endsWith(String)?

[Pavel Rappo]

Apologies if this is painfully obvious to everyone in this thread, but
I want to explicitly draw attention to what Anthony is saying. Among
other things, he is saying that Path.endsWith(String, String...) is
NOT equivalent to Path.endsWith(Path.of(String, String...)), which
people will be tempted to use without reading the javadoc or IDE
hand-holding.

The reason it's not equivalent is that two paths -- the receiver and
the argument -- might be incompatible. That is, they might be produced
by two different file systems. If paths in Path.endsWith(Path) are
from different file systems, it's extremely likely to be a bug. And
the way to maximise the odds of this bug is to construct the argument
as Path.of(String, String...).

Knowing the main author of this API a bit, this String-taking method
wasn't introduced willy-nilly. It was likely introduced specifically
to eliminate the described hazard. However, it looks like the method
backfired in a really unexpected way. I guess no amount of thinking,
even by a very smart person, can foresee all real-life issues.

-Pavel

On Wed, Jan 14, 2026 at 10:01 AM Anthony Vanelverdinghe
 wrote:
>
> On 1/14/2026 8:15 AM, Alan Bateman wrote:
> > On 13/01/2026 20:13, Anthony Vanelverdinghe wrote:
> >> There are 3 questions:
> >>
> >> (1) should we deprecate `Path::startsWith(String)`?
> >> (2) should we deprecate `Path::endsWith(String)`?
> >> (3) should we add a file extension API?
> >>
> > The "plan" is to deprecate startsWith(String) and endsWith(String),
> > and to reboot the effort to add the file extension API.
> >
> > -Alan
>
>
> Just for the record, emptying my bag of arguments:
>
> Google's Error Prone has a whole catalog of bug patterns, including
> confusing Java SE APIs. Shall we deprecate all of those as well then?
> And note that it does *not* have a bug pattern for
> `Path::{starts,ends}With`. So nobody at Google ever bothered to add it.
> And nobody outside Google ever bothered to file an issue to add it.
> (Same for SonarQube, SpotBugs, or FindBugs: no pattern for this.)
>
> Virtually every Java developer has made the mistake of using
> `Thread.sleep(5)` to mean "sleep 5 seconds" (which is the behavior in
> pretty much every shell). So why are we not deprecating that method then?
>
> Even `String::endsWith(String)` itself is confusing, since some people
> assume its argument is a regex (as with some other String methods like
> `matches`) [1]. So why not e.g., replace `String::matches(String)` with
> `String::matches(Pattern)`?
>
> [1]
> https://stackoverflow.com/questions/9943609/checking-if-string-ends-with-something-with-java-regex
>
> Anthony
>

Re: [External] : Re: Can we deprecate Path.endsWith(String)?

[Anthony Vanelverdinghe]

Thank you for taking the time to clarify the trade-offs, especially 
highlighting the importance of code readers and readability.


Please bear with me and allow me to express my point of view in terms of 
code authors and code readers.


Regarding code authors, I hold that when they are misled, they were 
looking for a file extension API in virtually all cases. So I see a 
dependency here in that adding a file extension API would reduce the 
number of misleads to a negligible frequency, no larger than the 
frequency with other Java SE APIs. For example, being misled to write 
`Duration.from(aPeriod)`.
By deprecating these methods, I believe code authors will be misled to 
simply write `path.endsWith(Path.of("foo"))`, without considering 
alternative file systems (AFSs). Even code authors that actually know 
about AFSs, as it's a subtle consideration that is easily overlooked. 
And this will in turn impact code readers as well, as they'll wonder 
whether it is acceptable to ignore AFSs (unless the code author 
documented why it is). With `path.endsWith("foo")`, authors don't have 
to document anything and readers don't have to wonder: it just works.


Regarding code readers, I hold that it is rare to be misled and that the 
code author is best placed to judge whether `path.endsWith("foo")` is 
misleading. For example, code readers would readily see that 
`Files.isDirectory(path) && path.endsWith(".git")` looks for Git 
repositories. And in cases where the code author considers 
`path.endsWith("foo")` to be misleading, they'd simply introduce a 
variable to eliminate any confusion, e.g., `var filename = "foo"; 
path.endsWith(filename)`.
By deprecating these methods, code authors have one less tool for 
writing readable code. Since something like 
`path.endsWith(path.getFileSystem().getPath("foo"))` can hardly be 
considered readable, either code authors have to constrain their code to 
the default file system, or they have to introduce a new local variable 
for the argument to `endsWith`. In case of the former, code readers may 
be left to wonder whether it is acceptable to ignore AFSs (as explained 
above). In case of the latter, code readers might be misled to simplify 
`var foo = path.getFileSystem().getPath("foo")` to `var foo = 
Path.of("foo")`, thinking these are equivalent.


Thanks again for reading. I don't mean to drag on the discussion, so if 
there's nothing in here that you hadn't already considered, we can leave 
it at this.


Kind regards, Anthony

On 1/14/2026 7:20 PM, Stuart Marks wrote:


You're making this too complicated.

On their face, startsWith/endsWith(String) are misleading to both code 
authors and code readers, and that justifies their deprecation. It 
will help code authors avoid making new mistakes. Readers of code that 
uses these APIs -- even correctly -- can easily misinterpret the code 
as if it performed string-based testing and thus be misled about what 
the code is actually doing. In both cases, the code is better replaced 
with more explicit, if more verbose, alternatives that already exist.


Certainly a file extension API would facilitate use cases that involve 
file extensions, such as inspecting a file's extension to determine 
how to process the file. I'm in favor of adding such an API. But 
that's a different topic from this one, and it should be handled 
independently.


I did read all of your message but I'm not responding to most of it, 
because it doesn't establish a dependency between these two topics.


s'marks

On 1/13/26 12:13 PM, Anthony Vanelverdinghe wrote:


There are 3 questions:

(1) should we deprecate `Path::startsWith(String)`?
(2) should we deprecate `Path::endsWith(String)`?
(3) should we add a file extension API?

And the TL;DR: no, no, yes.

Let's first establish why `startsWith/endsWith` add tangible value:
because `path.startsWith("foo")` is not equivalent to 
`path.startsWith(Path.of("foo"))`
and is much more readable than 
`path.startsWith(getFileSystem().getPath("foo"))`.


Next, let's consider why people might want to use String-based 
`startsWith/endsWith` testing on Path instances:


* testing file extensions = 99.% of the times: covered by 
`FileSystem::getPathMatcher`

* testing name elements = 0.999% of the times: covered by `Path`
* any other use cases = ~0% of the times: covered by 
`FileSystem::getPathMatcher`


So it is always possible to do without String conversion.
In fact, it is arguably always a bad idea to do String-based testing,
because `path.toString().endsWith(".java")` will also match a file 
named ".java",
which on Linux-like OSes would be considered a hidden file named 
"java" that has no file extension.
So using a dedicated `PathMatcher` for testing file extensions is 
more robust and elegant.


However, when testing file extensions we inevitably start by typing 
`path.`

(assuming we don't just use a third-party library),
first notice there's no method `getFileExtension` or such,
and then notice `endsWith(

Re: [External] : Re: Can we deprecate Path.endsWith(String)?

[Stuart Marks]

You're making this too complicated.

On their face, startsWith/endsWith(String) are misleading to both code authors and 
code readers, and that justifies their deprecation. It will help code authors avoid 
making new mistakes. Readers of code that uses these APIs -- even correctly -- can 
easily misinterpret the code as if it performed string-based testing and thus be 
misled about what the code is actually doing. In both cases, the code is better 
replaced with more explicit, if more verbose, alternatives that already exist.


Certainly a file extension API would facilitate use cases that involve file 
extensions, such as inspecting a file's extension to determine how to process the 
file. I'm in favor of adding such an API. But that's a different topic from this 
one, and it should be handled independently.


I did read all of your message but I'm not responding to most of it, because it 
doesn't establish a dependency between these two topics.


s'marks

On 1/13/26 12:13 PM, Anthony Vanelverdinghe wrote:


There are 3 questions:

(1) should we deprecate `Path::startsWith(String)`?
(2) should we deprecate `Path::endsWith(String)`?
(3) should we add a file extension API?

And the TL;DR: no, no, yes.

Let's first establish why `startsWith/endsWith` add tangible value:
because `path.startsWith("foo")` is not equivalent to 
`path.startsWith(Path.of("foo"))`

and is much more readable than 
`path.startsWith(getFileSystem().getPath("foo"))`.

Next, let's consider why people might want to use String-based 
`startsWith/endsWith` testing on Path instances:


* testing file extensions = 99.% of the times: covered by 
`FileSystem::getPathMatcher`

* testing name elements = 0.999% of the times: covered by `Path`
* any other use cases = ~0% of the times: covered by 
`FileSystem::getPathMatcher`

So it is always possible to do without String conversion.
In fact, it is arguably always a bad idea to do String-based testing,
because `path.toString().endsWith(".java")` will also match a file named 
".java",
which on Linux-like OSes would be considered a hidden file named "java" that has 
no file extension.
So using a dedicated `PathMatcher` for testing file extensions is more robust and 
elegant.


However, when testing file extensions we inevitably start by typing `path.`
(assuming we don't just use a third-party library),
first notice there's no method `getFileExtension` or such,
and then notice `endsWith(String)`
(and maybe we've also noticed `getFileName` and already have 
`path.getFileName().`).
At this point it's pure psychology:
we're looking for a method that behaves like String's `endsWith(String)`,
we're looking at a method with the same method signature,
and we can't imagine that the Path class does *not* have a method to test the 
filename extension,

so surely this must be it.
And obviously we ignore any hints at the contrary
(like our IDE proposing both `endsWith(Path)` and `endsWith(String)` for 
autocompletion).
And we don't bother to read the Javadoc, because in cases like this we can easily 
verify our assumptions with JShell

and equally quickly realize our assumptions are wrong.

So yes, this is a common mistake. But this is actually an argument for *not* 
deprecating it.
Many developers have bumped into this, but as far as I can tell the mailing list 
thread in September was the first in the existence of the API.

And I'm unable to find any previous bug reports either.
And here's why: when we realized our assumptions were wrong, we read the Javadoc, 
realized our mistake, learned from it, and moved on.
The Javadoc is crystal-clear, the method overloads another method with the same 
behavior, it clearly adds value over the other method.

In other words: we conclude "makes sense" and don't see any reason to complain.

To turn this common mistake into a rare-if-ever mistake, I see two (combinable) 
options:


* introduce a file extension API
* replace `startsWith/endsWith` with methods `startsWithNames/endsWithNames`

I don't consider deprecating `startsWith/endsWith` without replacement an option 
because:


* these methods add value (as was also argued by Rob Spoor), so it's a net loss 
for the Java SE APIs.
And all the people that are happily using these methods today and are unaware of 
this mailing list thread will be unpleasantly surprised to see it deprecated
* this means breaking compilation for everyone that builds with "-Werror" and "no 
usage of deprecated APIs" is a very common policy.
So people will end up adding a duplicate of the deprecated methods in their own 
utility libraries
* this trades one trap for another, much more subtle trap, since people will 
blindly replace `"foo"` with `Path.of("foo")`.

(We're having this very discussion because people don't read Javadoc.
So surely we're not expecting people to read the deprecation text and follow the 
recommendations, are we?)
Eventually they'll notice there's a bug, add `IO.println(foo)` and 
`IO.println(Path.of("foo"))`, notice

Re: Can we deprecate Path.endsWith(String)?

[Anthony Vanelverdinghe]

On 1/14/2026 8:15 AM, Alan Bateman wrote:

On 13/01/2026 20:13, Anthony Vanelverdinghe wrote:

There are 3 questions:

(1) should we deprecate `Path::startsWith(String)`?
(2) should we deprecate `Path::endsWith(String)`?
(3) should we add a file extension API?

The "plan" is to deprecate startsWith(String) and endsWith(String), 
and to reboot the effort to add the file extension API.


-Alan



Just for the record, emptying my bag of arguments:

Google's Error Prone has a whole catalog of bug patterns, including 
confusing Java SE APIs. Shall we deprecate all of those as well then? 
And note that it does *not* have a bug pattern for 
`Path::{starts,ends}With`. So nobody at Google ever bothered to add it. 
And nobody outside Google ever bothered to file an issue to add it. 
(Same for SonarQube, SpotBugs, or FindBugs: no pattern for this.)


Virtually every Java developer has made the mistake of using 
`Thread.sleep(5)` to mean "sleep 5 seconds" (which is the behavior in 
pretty much every shell). So why are we not deprecating that method then?


Even `String::endsWith(String)` itself is confusing, since some people 
assume its argument is a regex (as with some other String methods like 
`matches`) [1]. So why not e.g., replace `String::matches(String)` with 
`String::matches(Pattern)`?


[1] 
https://stackoverflow.com/questions/9943609/checking-if-string-ends-with-something-with-java-regex


Anthony

Re: Can we deprecate Path.endsWith(String)?

[Alan Bateman]

On 13/01/2026 20:13, Anthony Vanelverdinghe wrote:


There are 3 questions:

(1) should we deprecate `Path::startsWith(String)`?
(2) should we deprecate `Path::endsWith(String)`?
(3) should we add a file extension API?

The "plan" is to deprecate startsWith(String) and endsWith(String), and 
to reboot the effort to add the file extension API.


-Alan

Re: Can we deprecate Path.endsWith(String)?

[Anthony Vanelverdinghe]

There are 3 questions:

(1) should we deprecate `Path::startsWith(String)`?
(2) should we deprecate `Path::endsWith(String)`?
(3) should we add a file extension API?

And the TL;DR: no, no, yes.

Let's first establish why `startsWith/endsWith` add tangible value:
because `path.startsWith("foo")` is not equivalent to 
`path.startsWith(Path.of("foo"))`
and is much more readable than 
`path.startsWith(getFileSystem().getPath("foo"))`.


Next, let's consider why people might want to use String-based 
`startsWith/endsWith` testing on Path instances:


* testing file extensions = 99.% of the times: covered by 
`FileSystem::getPathMatcher`

* testing name elements = 0.999% of the times: covered by `Path`
* any other use cases = ~0% of the times: covered by 
`FileSystem::getPathMatcher`


So it is always possible to do without String conversion.
In fact, it is arguably always a bad idea to do String-based testing,
because `path.toString().endsWith(".java")` will also match a file named 
".java",
which on Linux-like OSes would be considered a hidden file named "java" 
that has no file extension.
So using a dedicated `PathMatcher` for testing file extensions is more 
robust and elegant.


However, when testing file extensions we inevitably start by typing `path.`
(assuming we don't just use a third-party library),
first notice there's no method `getFileExtension` or such,
and then notice `endsWith(String)`
(and maybe we've also noticed `getFileName` and already have 
`path.getFileName().`).

At this point it's pure psychology:
we're looking for a method that behaves like String's `endsWith(String)`,
we're looking at a method with the same method signature,
and we can't imagine that the Path class does *not* have a method to 
test the filename extension,

so surely this must be it.
And obviously we ignore any hints at the contrary
(like our IDE proposing both `endsWith(Path)` and `endsWith(String)` for 
autocompletion).
And we don't bother to read the Javadoc, because in cases like this we 
can easily verify our assumptions with JShell

and equally quickly realize our assumptions are wrong.

So yes, this is a common mistake. But this is actually an argument for 
*not* deprecating it.
Many developers have bumped into this, but as far as I can tell the 
mailing list thread in September was the first in the existence of the API.

And I'm unable to find any previous bug reports either.
And here's why: when we realized our assumptions were wrong, we read the 
Javadoc, realized our mistake, learned from it, and moved on.
The Javadoc is crystal-clear, the method overloads another method with 
the same behavior, it clearly adds value over the other method.
In other words: we conclude "makes sense" and don't see any reason to 
complain.


To turn this common mistake into a rare-if-ever mistake, I see two 
(combinable) options:


* introduce a file extension API
* replace `startsWith/endsWith` with methods `startsWithNames/endsWithNames`

I don't consider deprecating `startsWith/endsWith` without replacement 
an option because:


* these methods add value (as was also argued by Rob Spoor), so it's a 
net loss for the Java SE APIs.
And all the people that are happily using these methods today and are 
unaware of this mailing list thread will be unpleasantly surprised to 
see it deprecated
* this means breaking compilation for everyone that builds with 
"-Werror" and "no usage of deprecated APIs" is a very common policy.
So people will end up adding a duplicate of the deprecated methods in 
their own utility libraries
* this trades one trap for another, much more subtle trap, since people 
will blindly replace `"foo"` with `Path.of("foo")`.

(We're having this very discussion because people don't read Javadoc.
So surely we're not expecting people to read the deprecation text and 
follow the recommendations, are we?)
Eventually they'll notice there's a bug, add `IO.println(foo)` and 
`IO.println(Path.of("foo"))`, notice these both print "foo",
but somehow `foo.endsWith(Path.of("foo"))` results in `false`, 
eventually find the culprit ... and then notice the deprecated 
`endsWith` method did exactly

what they wanted all along
* what would the rationale for the deprecation be? How would you 
document this in the Javadoc?
Now you might still say: "People who were looking for a file extension 
API regularly ended up here. If you're one of them, use Path::toString 
instead."
But once a file extension API will be available, it'll be extremely hard 
to come up with a reasonable justification for the deprecation.
And as argued above, simple String-based comparisons are rarely, if 
ever, the most robust solution
* for `startsWith` in particular: the only argument to deprecate it 
seems to be "for the sake of symmetry"


Anthony

On 1/12/2026 8:36 PM, Stuart Marks wrote:


Let's not tie these two issues together.

The discussion clearly shows that the startsWith/endsWith(String) APIs 
are a trap that several people have fallen in

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Deal.

I can't make JBS Submissions, but if someone gets me a bug number, I can do
it.

On Mon, Jan 12, 2026, 2:36 PM Stuart Marks  wrote:

> Let's not tie these two issues together.
>
> The discussion clearly shows that the startsWith/endsWith(String) APIs are
> a trap that several people have fallen into. On that basis it should be
> deprecated. (Ordinarily, so as to emit a warning, and not for removal, so
> there won't be any compatibility issue.)
>
> There is also no requirement that a new API be introduced to replace any
> deprecated API. As the earlier discussion in the thread shows, both the
> path-based and the string-based use cases can be written using existing
> APIs, somewhat less conveniently and more verbosely; but these constructs
> are much more explicit and so are preferable to the APIs to be deprecated.
> The deprecation text should steer people toward the preferred constructs.
>
> It would indeed be nice to have a file extension API, but this has been
> discussed several times and has run aground each time for a variety of
> reasons. Tying these together will hold up the deprecation for no good
> reason.
>
> Let's proceed with just the deprecation first and work on the file
> extension API separately.
>
> s'marks
> On 1/11/26 12:45 PM, David Alayachew wrote:
>
> Thanks for the response Anthony. Messages have been arriving out-of-order
> for me, so I didn't see yours at the time of me writing that message.
>
> I think introducing the file extension API first, then gauging the need
> for a deprecation before doing it is fine. Sounds like then that we are
> universally agreed on the first step being to add the file extension API,
> yes?
>
> On Sun, Jan 11, 2026 at 2:06 PM Anthony Vanelverdinghe <
> anthonyv...@outlook.com> wrote:
>
>> I dissent. (Apparently my previous message wasn't clear.)
>>
>> The right order of things is to first introduce a file extension API.
>> Then see if there's still complaints about `Path::endsWith(String)`. And
>> only then, if there are, consider taking action.
>>
>> In my previous message I've already explained how these methods add real,
>> tangible value and actually are intuitive.
>> (Again, ask developers to guess how `A::foo(B)` behaves, given that both
>> `A::foo(A)` and `B::foo(B)` exist, and a large majority of them will
>> intuitively guess it converts its `b` argument to an instance of `A` and
>> passes it on to `A::foo(A)`. And their intuition would be correct in the
>> case of `Path::endsWith(String)`. That being said, I'll be the first to
>> admit that I've also made the mistake of attempting to use
>> `Path::endsWith(String)` to test the file extension.)
>>
>> In hindsight, maybe `endsWithNames(String)` would've been a better
>> choice, but hindsight is 20/20.
>>
>> Deprecating these methods now is premature. And deprecating them without
>> replacement methods would result in way more complaints than there have
>> ever been about `endsWith(String)`.
>>
>> Anthony
>> On 1/11/2026 12:19 AM, David Alayachew wrote:
>>
>> Of course.
>>
>> I see lots of approvals and not really any dissenters. Are we waiting for
>> more responses? Or is there anything we can do to kick start this?
>>
>> On Fri, Jan 9, 2026, 10:22 PM Brian Burkhalter <
>> brian.burkhal...@oracle.com> wrote:
>>
>>> Thanks for the corroboration.
>>>
>>> On Jan 8, 2026, at 1:50 PM, David Alayachew 
>>> wrote:
>>>
>>> Thanks for reviving this.
>>>
>>> I am perfectly happy with the idea of deprecating the
>>> Path.{start,ends}With(String), and then only add the file extension method.
>>> Originally, I didn't know that new method was on the table, so I suggested
>>> a rename. But the file extension api feels like the superior solution.
>>>
>>> 10 times out of 10, if I am calling endsWith, the only time I am not
>>> looking for "whole" path elements is when I am looking for a file
>>> extension. In every other instance, the api does exactly what I expect and
>>> want. And plus, something like looking for a file extension is better off
>>> being explicit.
>>>
>>>

Re: Can we deprecate Path.endsWith(String)?

[Stuart Marks]

Let's not tie these two issues together.

The discussion clearly shows that the startsWith/endsWith(String) APIs are a trap 
that several people have fallen into. On that basis it should be deprecated. 
(Ordinarily, so as to emit a warning, and not for removal, so there won't be any 
compatibility issue.)


There is also no requirement that a new API be introduced to replace any deprecated 
API. As the earlier discussion in the thread shows, both the path-based and the 
string-based use cases can be written using existing APIs, somewhat less 
conveniently and more verbosely; but these constructs are much more explicit and so 
are preferable to the APIs to be deprecated. The deprecation text should steer 
people toward the preferred constructs.


It would indeed be nice to have a file extension API, but this has been discussed 
several times and has run aground each time for a variety of reasons. Tying these 
together will hold up the deprecation for no good reason.


Let's proceed with just the deprecation first and work on the file extension API 
separately.


s'marks

On 1/11/26 12:45 PM, David Alayachew wrote:
Thanks for the response Anthony. Messages have been arriving out-of-order for me, 
so I didn't see yours at the time of me writing that message.


I think introducing the file extension API first, then gauging the need for a 
deprecation before doing it is fine. Sounds like then that we are universally 
agreed on the first step being to add the file extension API, yes?


On Sun, Jan 11, 2026 at 2:06 PM Anthony Vanelverdinghe  
wrote:


I dissent. (Apparently my previous message wasn't clear.)

The right order of things is to first introduce a file extension API. Then 
see
if there's still complaints about `Path::endsWith(String)`. And only then, 
if
there are, consider taking action.

In my previous message I've already explained how these methods add real,
tangible value and actually are intuitive.
(Again, ask developers to guess how `A::foo(B)` behaves, given that both
`A::foo(A)` and `B::foo(B)` exist, and a large majority of them will
intuitively guess it converts its `b` argument to an instance of `A` and
passes it on to `A::foo(A)`. And their intuition would be correct in the 
case
of `Path::endsWith(String)`. That being said, I'll be the first to admit 
that
I've also made the mistake of attempting to use `Path::endsWith(String)` to
test the file extension.)

In hindsight, maybe `endsWithNames(String)` would've been a better choice, 
but
hindsight is 20/20.

Deprecating these methods now is premature. And deprecating them without
replacement methods would result in way more complaints than there have ever
been about `endsWith(String)`.

Anthony

On 1/11/2026 12:19 AM, David Alayachew wrote:

Of course.

I see lots of approvals and not really any dissenters. Are we waiting for
more responses? Or is there anything we can do to kick start this?

On Fri, Jan 9, 2026, 10:22 PM Brian Burkhalter 
wrote:

Thanks for the corroboration.


On Jan 8, 2026, at 1:50 PM, David Alayachew 
wrote:

Thanks for reviving this.

I am perfectly happy with the idea of deprecating the
Path.{start,ends}With(String), and then only add the file extension
method. Originally, I didn't know that new method was on the table, so I
suggested a rename. But the file extension api feels like the superior
solution.

10 times out of 10, if I am calling endsWith, the only time I am not
looking for "whole" path elements is when I am looking for a file
extension. In every other instance, the api does exactly what I expect
and want. And plus, something like looking for a file extension is
better off being explicit.

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Thanks for the response Anthony. Messages have been arriving out-of-order
for me, so I didn't see yours at the time of me writing that message.

I think introducing the file extension API first, then gauging the need for
a deprecation before doing it is fine. Sounds like then that we are
universally agreed on the first step being to add the file extension API,
yes?

On Sun, Jan 11, 2026 at 2:06 PM Anthony Vanelverdinghe <
anthonyv...@outlook.com> wrote:

> I dissent. (Apparently my previous message wasn't clear.)
>
> The right order of things is to first introduce a file extension API. Then
> see if there's still complaints about `Path::endsWith(String)`. And only
> then, if there are, consider taking action.
>
> In my previous message I've already explained how these methods add real,
> tangible value and actually are intuitive.
> (Again, ask developers to guess how `A::foo(B)` behaves, given that both
> `A::foo(A)` and `B::foo(B)` exist, and a large majority of them will
> intuitively guess it converts its `b` argument to an instance of `A` and
> passes it on to `A::foo(A)`. And their intuition would be correct in the
> case of `Path::endsWith(String)`. That being said, I'll be the first to
> admit that I've also made the mistake of attempting to use
> `Path::endsWith(String)` to test the file extension.)
>
> In hindsight, maybe `endsWithNames(String)` would've been a better choice,
> but hindsight is 20/20.
>
> Deprecating these methods now is premature. And deprecating them without
> replacement methods would result in way more complaints than there have
> ever been about `endsWith(String)`.
>
> Anthony
> On 1/11/2026 12:19 AM, David Alayachew wrote:
>
> Of course.
>
> I see lots of approvals and not really any dissenters. Are we waiting for
> more responses? Or is there anything we can do to kick start this?
>
> On Fri, Jan 9, 2026, 10:22 PM Brian Burkhalter <
> brian.burkhal...@oracle.com> wrote:
>
>> Thanks for the corroboration.
>>
>> On Jan 8, 2026, at 1:50 PM, David Alayachew 
>> wrote:
>>
>> Thanks for reviving this.
>>
>> I am perfectly happy with the idea of deprecating the
>> Path.{start,ends}With(String), and then only add the file extension method.
>> Originally, I didn't know that new method was on the table, so I suggested
>> a rename. But the file extension api feels like the superior solution.
>>
>> 10 times out of 10, if I am calling endsWith, the only time I am not
>> looking for "whole" path elements is when I am looking for a file
>> extension. In every other instance, the api does exactly what I expect and
>> want. And plus, something like looking for a file extension is better off
>> being explicit.
>>
>>

Re: Can we deprecate Path.endsWith(String)?

[Anthony Vanelverdinghe]

I dissent. (Apparently my previous message wasn't clear.)

The right order of things is to first introduce a file extension API. 
Then see if there's still complaints about `Path::endsWith(String)`. And 
only then, if there are, consider taking action.


In my previous message I've already explained how these methods add 
real, tangible value and actually are intuitive.
(Again, ask developers to guess how `A::foo(B)` behaves, given that both 
`A::foo(A)` and `B::foo(B)` exist, and a large majority of them will 
intuitively guess it converts its `b` argument to an instance of `A` and 
passes it on to `A::foo(A)`. And their intuition would be correct in the 
case of `Path::endsWith(String)`. That being said, I'll be the first to 
admit that I've also made the mistake of attempting to use 
`Path::endsWith(String)` to test the file extension.)


In hindsight, maybe `endsWithNames(String)` would've been a better 
choice, but hindsight is 20/20.


Deprecating these methods now is premature. And deprecating them without 
replacement methods would result in way more complaints than there have 
ever been about `endsWith(String)`.


Anthony

On 1/11/2026 12:19 AM, David Alayachew wrote:

Of course.

I see lots of approvals and not really any dissenters. Are we waiting 
for more responses? Or is there anything we can do to kick start this?


On Fri, Jan 9, 2026, 10:22 PM Brian Burkhalter 
 wrote:


Thanks for the corroboration.


On Jan 8, 2026, at 1:50 PM, David Alayachew
 wrote:

Thanks for reviving this.

I am perfectly happy with the idea of deprecating the
Path.{start,ends}With(String), and then only add the file
extension method. Originally, I didn't know that new method was
on the table, so I suggested a rename. But the file extension api
feels like the superior solution.

10 times out of 10, if I am calling endsWith, the only time I am
not looking for "whole" path elements is when I am looking for a
file extension. In every other instance, the api does exactly
what I expect and want. And plus, something like looking for a
file extension is better off being explicit.

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Of course.

I see lots of approvals and not really any dissenters. Are we waiting for
more responses? Or is there anything we can do to kick start this?

On Fri, Jan 9, 2026, 10:22 PM Brian Burkhalter 
wrote:

> Thanks for the corroboration.
>
> On Jan 8, 2026, at 1:50 PM, David Alayachew 
> wrote:
>
> Thanks for reviving this.
>
> I am perfectly happy with the idea of deprecating the
> Path.{start,ends}With(String), and then only add the file extension method.
> Originally, I didn't know that new method was on the table, so I suggested
> a rename. But the file extension api feels like the superior solution.
>
> 10 times out of 10, if I am calling endsWith, the only time I am not
> looking for "whole" path elements is when I am looking for a file
> extension. In every other instance, the api does exactly what I expect and
> want. And plus, something like looking for a file extension is better off
> being explicit.
>
>

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

Thanks for the corroboration.

On Jan 8, 2026, at 1:50 PM, David Alayachew  wrote:

Thanks for reviving this.

I am perfectly happy with the idea of deprecating the 
Path.{start,ends}With(String), and then only add the file extension method. 
Originally, I didn't know that new method was on the table, so I suggested a 
rename. But the file extension api feels like the superior solution.

10 times out of 10, if I am calling endsWith, the only time I am not looking 
for "whole" path elements is when I am looking for a file extension. In every 
other instance, the api does exactly what I expect and want. And plus, 
something like looking for a file extension is better off being explicit.

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Thanks for reviving this.

I am perfectly happy with the idea of deprecating the
Path.{start,ends}With(String), and then only add the file extension method.
Originally, I didn't know that new method was on the table, so I suggested
a rename. But the file extension api feels like the superior solution.

10 times out of 10, if I am calling endsWith, the only time I am not
looking for "whole" path elements is when I am looking for a file
extension. In every other instance, the api does exactly what I expect and
want. And plus, something like looking for a file extension is better off
being explicit.

On Thu, Jan 8, 2026, 5:50 AM Anthony Vanelverdinghe 
wrote:

> On 1/8/2026 10:39 AM, Alan Bateman wrote:
> > On 08/01/2026 01:02, Brian Burkhalter wrote:
> >> We have had a bit of a race condition in this discussion, but at
> >> least there appears to be some agreement that deprecation alone (with
> >> some javadoc enhancement) is a good way to go.
> > It would be also be good to try again to get a handle on the use-cases
> > around the convention that we know as the "file extension". We've had
> > several failed attempts on this but I think you make good progress on
> > defining it at the last iteration. That is, I assume some temptation
> > to use endsWith(String) is just wanting to test if the string
> > representation has an interesting suffix.
> >
> > -Alan
> Alan is spot on here, and I'm wholeheartedly in favor of leaving the API
> untouched.
>
> What I believe is needed, is simply to:
> * add a method to get the file extension from a Path (people want to get
> the file extension from a Path, notice there's no method to do so,
> notice `endsWith(String)`, use that, eventually find out it doesn't work
> as they expected, and then blame `endsWith(String)`)
> * point out that the current APIs actually are intuitive (when a method
> is overloaded, I intuitively expect all overloads to behave in the same
> manner, except for a trivial conversion of their arguments to some
> canonical form. This is exactly the case here)
> * remind people to read the Javadoc (the Javadoc of these methods is
> crystal clear on their behavior)
>
> The existing methods are useful (fwiw, in my codebases all uses of
> `Path::endsWith` invoke the `String` overload) and have many uses in
> existing codebases (as they've existed for nearly 15 years). And again,
> the actual issue is people expecting methods to behave as needed in the
> context of their actual use case (here, in 99% of the cases: testing the
> file extension), without verifying their expectations by reading the
> Javadoc.
>
> Deprecating these methods is also a sure-fire way to have people
> introduce subtle bugs in their codebases, as they'd likely "fix" the
> deprecations by replacing `path.endsWith("other")` with
> `path.endsWith(Path.of("other"))`.
>
> Adding `Path.pathString{ends,starts}With(String)` would be a mistake, I
> believe. One of the things that makes `Path` such a fine API, is that it
> cleanly abstracts the OS-specific file separator. These methods would
> break that abstraction and you'd end up with things like
> `Path.of("foo\bar").pathStringStartsWith("foo/bar")` and either way
> you'd have people complaining that its behavior is unintuitive (i.e.,
> some people would expect this to return `true`, others `false`).
>
> Anthony
>

Re: Can we deprecate Path.endsWith(String)?

[Anthony Vanelverdinghe]

On 1/8/2026 10:39 AM, Alan Bateman wrote:

On 08/01/2026 01:02, Brian Burkhalter wrote:
We have had a bit of a race condition in this discussion, but at 
least there appears to be some agreement that deprecation alone (with 
some javadoc enhancement) is a good way to go.
It would be also be good to try again to get a handle on the use-cases 
around the convention that we know as the "file extension". We've had 
several failed attempts on this but I think you make good progress on 
defining it at the last iteration. That is, I assume some temptation 
to use endsWith(String) is just wanting to test if the string 
representation has an interesting suffix.


-Alan 
Alan is spot on here, and I'm wholeheartedly in favor of leaving the API 
untouched.


What I believe is needed, is simply to:
* add a method to get the file extension from a Path (people want to get 
the file extension from a Path, notice there's no method to do so, 
notice `endsWith(String)`, use that, eventually find out it doesn't work 
as they expected, and then blame `endsWith(String)`)
* point out that the current APIs actually are intuitive (when a method 
is overloaded, I intuitively expect all overloads to behave in the same 
manner, except for a trivial conversion of their arguments to some 
canonical form. This is exactly the case here)
* remind people to read the Javadoc (the Javadoc of these methods is 
crystal clear on their behavior)


The existing methods are useful (fwiw, in my codebases all uses of 
`Path::endsWith` invoke the `String` overload) and have many uses in 
existing codebases (as they've existed for nearly 15 years). And again, 
the actual issue is people expecting methods to behave as needed in the 
context of their actual use case (here, in 99% of the cases: testing the 
file extension), without verifying their expectations by reading the 
Javadoc.


Deprecating these methods is also a sure-fire way to have people 
introduce subtle bugs in their codebases, as they'd likely "fix" the 
deprecations by replacing `path.endsWith("other")` with 
`path.endsWith(Path.of("other"))`.


Adding `Path.pathString{ends,starts}With(String)` would be a mistake, I 
believe. One of the things that makes `Path` such a fine API, is that it 
cleanly abstracts the OS-specific file separator. These methods would 
break that abstraction and you'd end up with things like 
`Path.of("foo\bar").pathStringStartsWith("foo/bar")` and either way 
you'd have people complaining that its behavior is unintuitive (i.e., 
some people would expect this to return `true`, others `false`).


Anthony

Re: Can we deprecate Path.endsWith(String)?

[Alan Bateman]

On 08/01/2026 01:02, Brian Burkhalter wrote:


We have had a bit of a race condition in this discussion, but at least 
there appears to be some agreement that deprecation alone (with some 
javadoc enhancement) is a good way to go.


It would be also be good to try again to get a handle on the use-cases 
around the convention that we know as the "file extension". We've had 
several failed attempts on this but I think you make good progress on 
defining it at the last iteration. That is, I assume some temptation to 
use endsWith(String) is just wanting to test if the string 
representation has an interesting suffix.


-Alan

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

Thanks for the useful comments.

On Jan 7, 2026, at 4:32 PM, John Rose  wrote:

Maybe that is the way to go: just deprecating Path.{ends,starts}With(String) 
and nothing else.

$0.01 more – I’m OK with that, as long as the javadoc teaches
the toString technique in some discoverable manner.  And not just
via the deprecated methods…?

On Jan 7, 2026, at 4:36 PM, Stuart Marks  wrote:

So, maybe do (1) and (2) but omit (3). This boils down to just deprecating 
endsWith(String) and startsWith(String).

We have had a bit of a race condition in this discussion, but at least there 
appears to be some agreement that deprecation alone (with some javadoc 
enhancement) is a good way to go.

Re: Can we deprecate Path.endsWith(String)?

[Stuart Marks]

On 1/7/26 12:34 PM, Brian Burkhalter wrote:

Resuscitating  this discussion thread from last year ...

To summarize my rereading of the thread, there is good agreement that 
Path.{ends,starts}With(String) should be deprecated and replaced with something 
else, perhaps Path.{ends,starts}WithString(String). There was also a parallel 
suggestion that Path.{ends,starts}With(Path) be deprecated in favor of 
Path.{ends,starts}WithPath(Path). Thus:


* Path.{ends,starts}With(String) -> Path.{ends,starts}WithString(String)
* Path.{ends,starts}With(Path) -> Path.{ends,starts}WithPath(Path)


My experience is that deprecation for the purposes of renaming doesn't work very 
well. I don't think we're intending to remove the old APIs, so they'd remain, so 
"renaming" would merely be the addition of new APIs with similar names. This would 
just make things more confusing.


The main problem is that Path.{ends,starts}With(String) is confusing and misleading, 
so let's focus on that.



Among doubtlessly many others, one alternative is

1. Leave Path.{ends,starts}With(Path) unchanged


This makes sense. I haven't seen any evidence that this is a problem if one is 
already working in the Path domain.



2. Deprecate Path.{ends,starts}With(String)


This is the confusing one, so yes, deprecate this (not for removal). It's an open 
question regarding what the deprecation text should recommend be used instead. 
Perhaps some of the discussion below will resolve this.



3. Add Path.pathString{ends,starts}With(String)

where "pathstring" in effect implies the value of Path.toString().


Before we start adding new APIs, I think we should consider which use cases we think 
we want to support. The methods take a string argument, and the two cases are 
whether the operation is performed on Paths and Path segments or whether the 
operation is performed in terms of Strings.


For brevity I'll just use "EW" to represent the "endsWith" operation in either 
domain, but the analysis applies equally to the "startsWith" operation.


Suppose we start off with

var path = Path.of("/one/two/three");

The cases are:

a) Path domain. The code path.EW(string) is equivalent to

path.endsWith(path.getFileSystem().getPath(string))
    // note, this is Path.endsWith(Path)

and thus we have

    path.EW("/two/three") ==> false
    path.EW("two/three") ==> true

b) String domain. The code path.EW(string) is equivalent to

    path.toString().endsWith(string)
    // note, this is String.endsWith(String)

and thus we have

    path.EW("/two/three") ==> true
    path.EW("two/three") ==> true

=

I'm not convinced we need any new APIs at all. It seems likely that many people want 
to perform the string-based endsWith() operation, in which case maybe it's best to 
be explicit and convert the path to a string using toString() before doing that. 
Adding a deprecation for Path.endsWith(String) should warn people not to use this 
method for the string-domain case.


If you want to perform this operation in the Path domain, maybe it's best to be 
explicit about it. If you're writing library code that wants to be very general, 
then you probably have the relevant FileSystem in a local variable already, and you 
might construct Path objects explicitly before invoking the endsWith(Path) 
operation. Using string literals directly, and having them implicitly be converted 
to Path objects, seems like it easily leads to subtle problems (such as the 
difference in behavior between my "/two/three" and "two/three" examples above.) So, 
maybe being explicit is better, even if it is more verbose and less convenient.


If you're writing an application that uses the default FileSystem everywhere, and 
you really want to perform a Path-based operation, you can just slap Path.of() 
around your string literal and move on. I don't think we need another method to 
handle this case.


So, maybe do (1) and (2) but omit (3). This boils down to just deprecating 
endsWith(String) and startsWith(String).


s'marks



Comments?

Brian


On Nov 2, 2025, at 3:35 PM, David Alayachew  wrote:

As for deprecations, I still think all 4 methods should be deprecated. This path 
variants are kind of ok, but the String variants are just too deceptively named.


I think Rob Spoor hit it on the head with this quote.

> Perhaps both can be added?
>
> Path.{start,end}sWithString would default to calling
> toString().{start,end}sWith(arg) and
> Path.{start,end}sWithPath would default to calling
> {start,end}sWith(arg). The latter could default to
> calling {start,end}sWith(getFileSystem().getPath(arg))
> but then custom implementations that do something else
> (in addition) may not work as expected.

Doing it this way, we can have (start|end)sWithPath() have both String and Path 
overloads with no ambiguity.

Re: Can we deprecate Path.endsWith(String)?

[John Rose]

On 7 Jan 2026, at 16:25, Brian Burkhalter wrote:

> …So, as I think, unless there is a substantial optimization to offer from 
> merging this two operations, i would prefer just suggesting to use 
> toString().{starts,ends}With directly
>
> Maybe that is the way to go: just deprecating Path.{ends,starts}With(String) 
> and nothing else.

$0.01 more – I’m OK with that, as long as the javadoc teaches
the toString technique in some discoverable manner.  And not just
via the deprecated methods…?

Re: Can we deprecate Path.endsWith(String)?

[John Rose]

On 7 Jan 2026, at 12:34, Brian Burkhalter wrote:

> Resuscitating  this discussion thread from last year ...
>
> To summarize my rereading of the thread, there is good agreement that 
> Path.{ends,starts}With(String) should be deprecated and replaced with 
> something else, perhaps Path.{ends,starts}WithString(String). There was also 
> a parallel suggestion that Path.{ends,starts}With(Path) be deprecated in 
> favor of Path.{ends,starts}WithPath(Path). Thus:
>
> * Path.{ends,starts}With(String) -> Path.{ends,starts}WithString(String)
> * Path.{ends,starts}With(Path) -> Path.{ends,starts}WithPath(Path)
>
> Among doubtlessly many others, one alternative is
>
> 1. Leave Path.{ends,starts}With(Path) unchanged
> 2. Deprecate Path.{ends,starts}With(String)
> 3. Add Path.pathString{ends,starts}With(String)
>
> where "pathstring" in effect implies the value of Path.toString().
>
> Comments?

$0.02 – I like it.  I think David and Pavel have pointed out
a legitimately significant "sharp edge" in the API, where it is
too easy to read /foo.startsWith("bar")/ and read that as a string
operation.  But it isn’t.

(Any other string-like methods out there?  Any other /foo/ that
responds to /.startsWith("bar")/ but does something different
from /foo.toString()/?)

Olexandr’s observation about factoring the string ops via
Path::toString is also spot-on.  However, it’s not a cure-all,
especially given the "false friend" methods already in Path.

I would suggest that, if we add new "true friend" methods in
Path, that they should say something like "this is the same as
calling /toString().startWith(x)/ but may be more efficient".

Javadoc does (at least) two useful things at the same time:
It A. makes it easier to discover useful API points, and B. teaches
you how to use both those API points and related ones.  The very
presence of Path::endsWithString (or whatever) makes the
useful API point (A) discoverable, but then it can also suggest,
(B) "hey, did you consider calling toString first?".

— John

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

Thanks for helping to continue to the discussion.

On Jan 7, 2026, at 4:13 PM, Olexandr Rotan  wrote:

I am not sure if thoughts similar to mine were already present in the thread, 
but I am not sure there is any particular value in adding any replacement 
methods for deprecated ones.

Nor am I.

To me it seems like path.toString.{starts,ends}With provides endlessly more 
clarity on what is going on, besides maybe  pathString{ends,starts}With, but 
this name seems clumsy, in some way resembling some denormalized column name in 
db in a way that it traverses multiple mental indirections to explain clearly 
enough what it does

Indeed the name is clumsy.

So, as I think, unless there is a substantial optimization to offer from 
merging this two operations, i would prefer just suggesting to use 
toString().{starts,ends}With directly

Maybe that is the way to go: just deprecating Path.{ends,starts}With(String) 
and nothing else.

Brian

Re: Can we deprecate Path.endsWith(String)?

[Olexandr Rotan]

I am not sure if thoughts similar to mine were already present in the
thread, but I am not sure there is any particular value in adding any
replacement methods for deprecated ones.

To me it seems like path.toString.{starts,ends}With provides endlessly more
clarity on what is going on, besides maybe  pathString{ends,starts}With,
but this name seems clumsy, in some way resembling some denormalized column
name in db in a way that it traverses multiple mental indirections to
explain clearly enough what it does

So, as I think, unless there is a substantial optimization to offer from
merging this two operations, i would prefer just suggesting to use
toString().{starts,ends}With directly

Best regards

On Wed, Jan 7, 2026 at 11:45 PM Brian Burkhalter <
brian.burkhal...@oracle.com> wrote:

> In the list below I omitted adding Path.{ends,starts}WithString(String)
> which is different from item 3 in the list.
>
> Brian
>
> On Jan 7, 2026, at 12:34 PM, Brian Burkhalter 
> wrote:
>
> Among doubtlessly many others, one alternative is
>
> 1. Leave Path.{ends,starts}With(Path) unchanged
> 2. Deprecate Path.{ends,starts}With(String)
> 3. Add Path.pathString{ends,starts}With(String)
>
> where "pathstring" in effect implies the value of Path.toString().
>
>
>

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

In the list below I omitted adding Path.{ends,starts}WithString(String) which 
is different from item 3 in the list.

Brian

On Jan 7, 2026, at 12:34 PM, Brian Burkhalter  
wrote:

Among doubtlessly many others, one alternative is

1. Leave Path.{ends,starts}With(Path) unchanged
2. Deprecate Path.{ends,starts}With(String)
3. Add Path.pathString{ends,starts}With(String)

where "pathstring" in effect implies the value of Path.toString().

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

Resuscitating  this discussion thread from last year ...

To summarize my rereading of the thread, there is good agreement that 
Path.{ends,starts}With(String) should be deprecated and replaced with something 
else, perhaps Path.{ends,starts}WithString(String). There was also a parallel 
suggestion that Path.{ends,starts}With(Path) be deprecated in favor of 
Path.{ends,starts}WithPath(Path). Thus:

* Path.{ends,starts}With(String) -> Path.{ends,starts}WithString(String)
* Path.{ends,starts}With(Path) -> Path.{ends,starts}WithPath(Path)

Among doubtlessly many others, one alternative is

1. Leave Path.{ends,starts}With(Path) unchanged
2. Deprecate Path.{ends,starts}With(String)
3. Add Path.pathString{ends,starts}With(String)

where "pathstring" in effect implies the value of Path.toString().

Comments?

Brian

On Nov 2, 2025, at 3:35 PM, David Alayachew  wrote:

As for deprecations, I still think all 4 methods should be deprecated. This 
path variants are kind of ok, but the String variants are just too deceptively 
named.

I think Rob Spoor hit it on the head with this quote.

> Perhaps both can be added?
>
> Path.{start,end}sWithString would default to calling
> toString().{start,end}sWith(arg) and
> Path.{start,end}sWithPath would default to calling
> {start,end}sWith(arg). The latter could default to
> calling {start,end}sWith(getFileSystem().getPath(arg))
> but then custom implementations that do something else
> (in addition) may not work as expected.

Doing it this way, we can have (start|end)sWithPath() have both String and Path 
overloads with no ambiguity.

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Ty vm. Looks great. Hope to see that change come back soon!

If there is anything I can do to help it come out faster, please let me
know! I am perfectly happy to write the implementation. And since we have
the Bug Number, couldn't I just submit my PR under that? Lmk, I could do it
right now!

I'm excited since this is an implementation that I could actually do by
myself.

One thing that stood out to me is that, in the unit test, I saw that "." is
considered as no extension, but ".." is considered to be an empty
extension. Wouldn't that break Path's that are built out of ".." and "."?
For example, if I submit a Path as Path.of(".."), then by definition, that
is a directory, and thus, should be considered no extension.

I propose that "." and ".." be considered no extension.

On Sun, Nov 2, 2025 at 7:03 PM Pavel Rappo  wrote:

> On Sun, Nov 2, 2025 at 11:36 PM David Alayachew
>  wrote:
> >
> > 
> >
> > I only see the commit hash, I don't know how to look that up.
> >
>
> Each commit (but a few initial) in openjdk/jdk has a commit message.
> That message starts with an issue number. That number can be used to
> look up the issue in JBS: https://bugs.openjdk.org/. The issue has a
> summary, comments, and links to GitHub's commit and PR pages.
>
> Here are the links for 10356e767a44632c5de142d4666bd85d4618bf71
>
>  - https://bugs.openjdk.org/browse/JDK-8298303
>  -
> https://github.com/openjdk/jdk/commit/10356e767a44632c5de142d4666bd85d4618bf71
>  - https://github.com/openjdk/jdk/pull/11566
>
> -Pavel
>

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

{
  "emoji": "❤️",
  "version": 1
}

Re: Can we deprecate Path.endsWith(String)?

[Pavel Rappo]

On Sun, Nov 2, 2025 at 11:36 PM David Alayachew
 wrote:
>
> 
>
> I only see the commit hash, I don't know how to look that up.
>

Each commit (but a few initial) in openjdk/jdk has a commit message.
That message starts with an issue number. That number can be used to
look up the issue in JBS: https://bugs.openjdk.org/. The issue has a
summary, comments, and links to GitHub's commit and PR pages.

Here are the links for 10356e767a44632c5de142d4666bd85d4618bf71

 - https://bugs.openjdk.org/browse/JDK-8298303
 - 
https://github.com/openjdk/jdk/commit/10356e767a44632c5de142d4666bd85d4618bf71
 - https://github.com/openjdk/jdk/pull/11566

-Pavel

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Sorry to revive this thread after all this time. Missed the emails somehow.

A file extension method would be ideal. Didn't know that was on the table.

As for deprecations, I still think all 4 methods should be deprecated. This
path variants are kind of ok, but the String variants are just too
deceptively named.

I think Rob Spoor hit it on the head with this quote.

> Perhaps both can be added?
>
> Path.{start,end}sWithString would default to calling
> toString().{start,end}sWith(arg) and
> Path.{start,end}sWithPath would default to calling
> {start,end}sWith(arg). The latter could default to
> calling {start,end}sWith(getFileSystem().getPath(arg))
> but then custom implementations that do something else
> (in addition) may not work as expected.

Doing it this way, we can have (start|end)sWithPath() have both String and
Path overloads with no ambiguity.

And (start|end)sWithString() doesn't obviate the need for a file extension
method/API. It would just be a good enough stop gap in the meantime.

Out of curiosity, why was the old commit for file extension pulled out? I
only see the commit hash, I don't know how to look that up.

Thank you all again for your time and consideration.
David Alayachew

On Thu, Sep 18, 2025 at 5:12 PM Pavel Rappo  wrote:

> On Thu, Sep 18, 2025 at 7:08 PM Brian Burkhalter
>  wrote:
>
> 
>
> > I have filed an issue to improve the specification of this method
> somehow:
> >
> > https://bugs.openjdk.org/browse/JDK-8368007
> >
>
> Personally, a better spec wouldn't have helped me avoid the trap. The
> spec is already clear. I think it's the combination of the method's
> name and the argument type that is misleading.
>
> I think I learned about this method by scrolling autocompletion
> suggestions in my IDE. The method seemed to fit my need exactly. Of
> course, I quickly learned that I was wrong, but somehow kept falling
> into the same trap. Not sure how representative my experience in this
> case is, though.
>
> Deprecation would flag the method in the IDE and help avoid the trap.
> But eventually, it would be good to also have the file extension
> functionality.
>

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

Hello David,

Redirecting to nio-dev.

On Sep 10, 2025, at 12:01 PM, David Alayachew  wrote:

One would expect only fileZ.html to be printed out, but nothing does. The 
reason why is because path.endsWith(String) is effectively an alias for 
path.endsWith(Path.of(String)). The confusion being that Path.of(someString) is 
looking for a file or a directory. Thus, since there is neither a file nor a 
folder called "html", the stream prints out nothing.

The specification looks like it is pretty clear about the behavior, especially 
the implementation note in 
Path.endsWith(String):

"The default implementation is equivalent for this path to:

endsWith(getFileSystem().getPath(other));"

What you were expecting sounds like what would be given by

.filter(path -> path.toString().endsWith("html”))

or better

.filter(path -> path.getFileName().toString().endsWith("html”))

Is that correct?

If we could eventually agree on how to handle file extensions, that would help 
here.

Brian

Re: Can we deprecate Path.endsWith(String)?

[Pavel Rappo]

On Thu, Sep 18, 2025 at 7:08 PM Brian Burkhalter
 wrote:



> I have filed an issue to improve the specification of this method somehow:
>
> https://bugs.openjdk.org/browse/JDK-8368007
>

Personally, a better spec wouldn't have helped me avoid the trap. The
spec is already clear. I think it's the combination of the method's
name and the argument type that is misleading.

I think I learned about this method by scrolling autocompletion
suggestions in my IDE. The method seemed to fit my need exactly. Of
course, I quickly learned that I was wrong, but somehow kept falling
into the same trap. Not sure how representative my experience in this
case is, though.

Deprecation would flag the method in the IDE and help avoid the trap.
But eventually, it would be good to also have the file extension
functionality.

Re: Can we deprecate Path.endsWith(String)?

[Rob Spoor]

If I saw a method called endsWithString, I'd be inclined to call 
path.endsWithString(".html"), which is what started this entire thread.


Perhaps both can be added? Path.{start,end}sWithString would default to 
calling toString().{start,end}sWith(arg) and Path.{start,end}sWithPath 
would default to calling {start,end}sWith(arg). The latter could default 
to calling {start,end}sWith(getFileSystem().getPath(arg)) but then 
custom implementations that do something else (in addition) may not work 
as expected.



On 18/09/2025 20:38, Brian Burkhalter wrote:

If Path.endsWith(String) and possibly Path.startsWith(String) were to be 
deprecated, then perhaps something like Path.{start,end}sWIthString(String) 
could be replacements?

Brian

On Sep 18, 2025, at 11:19 AM, Rob Spoor  wrote:

If Path.endsWith(String) and possibly Path.startsWith(String) are deprecated, 
can we then get Path.endsWithPath(String) and Path.startsWithPath(String) as 
replacements? Because having to type 
path.endsWith(path.getFileSystem().getPath(other)) is not only a lot more 
verbose but my IDE also complains that I don't close the result of calling 
path.getFileSystem() (which of course I shouldn't), so I have to suppress the 
warning.

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

If Path.endsWith(String) and possibly Path.startsWith(String) were to be 
deprecated, then perhaps something like Path.{start,end}sWIthString(String) 
could be replacements?

Brian

On Sep 18, 2025, at 11:19 AM, Rob Spoor  wrote:

If Path.endsWith(String) and possibly Path.startsWith(String) are deprecated, 
can we then get Path.endsWithPath(String) and Path.startsWithPath(String) as 
replacements? Because having to type 
path.endsWith(path.getFileSystem().getPath(other)) is not only a lot more 
verbose but my IDE also complains that I don't close the result of calling 
path.getFileSystem() (which of course I shouldn't), so I have to suppress the 
warning.

Re: Can we deprecate Path.endsWith(String)?

[Rob Spoor]

If Path.endsWith(String) and possibly Path.startsWith(String) are 
deprecated, can we then get Path.endsWithPath(String) and 
Path.startsWithPath(String) as replacements? Because having to type 
path.endsWith(path.getFileSystem().getPath(other)) is not only a lot 
more verbose but my IDE also complains that I don't close the result of 
calling path.getFileSystem() (which of course I shouldn't), so I have to 
suppress the warning.



On 18/09/2025 20:08, Brian Burkhalter wrote:


On Sep 17, 2025, at 8:24 AM, Pavel Rappo  wrote:

FWIW, I too have fallen into this trap, and I did that even more than
once. When my brain sees Path.endsWith(String), it somehow silently
assumes that its semantic is that of String.endsWith(String).

Of course, it isn't. What's worse, I learn about my mistake at
runtime. But not because of an exception, no; I learn about it by
getting unexpected results.

I have filed an issue to improve the specification of this method somehow:

https://bugs.openjdk.org/browse/JDK-8368007

There used to be a method that implemented the file extension thingy,
but the commit was backed out. If it makes its way back in one form or
another, it might help to avoid the trap:

One day I might evenutally attempt to push that boulder up the mountain again. 
Today is not that day.

Brian

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

On Sep 17, 2025, at 8:24 AM, Pavel Rappo  wrote:

FWIW, I too have fallen into this trap, and I did that even more than
once. When my brain sees Path.endsWith(String), it somehow silently
assumes that its semantic is that of String.endsWith(String).

Of course, it isn't. What's worse, I learn about my mistake at
runtime. But not because of an exception, no; I learn about it by
getting unexpected results.

I have filed an issue to improve the specification of this method somehow:

https://bugs.openjdk.org/browse/JDK-8368007

There used to be a method that implemented the file extension thingy,
but the commit was backed out. If it makes its way back in one form or
another, it might help to avoid the trap:

One day I might evenutally attempt to push that boulder up the mountain again. 
Today is not that day.

Brian

Re: Can we deprecate Path.endsWith(String)?

[Pavel Rappo]

FWIW, I too have fallen into this trap, and I did that even more than
once. When my brain sees Path.endsWith(String), it somehow silently
assumes that its semantic is that of String.endsWith(String).

Of course, it isn't. What's worse, I learn about my mistake at
runtime. But not because of an exception, no; I learn about it by
getting unexpected results.

There used to be a method that implemented the file extension thingy,
but the commit was backed out. If it makes its way back in one form or
another, it might help to avoid the trap:

commit 10356e767a44632c5de142d4666bd85d4618bf71
Author: Brian Burkhalter 
Date:   Wed Dec 7 18:54:18 2022 +

8298303: (fs) temporarily remove Path.getExtension

Reviewed-by: smarks, alanb

commit 50d91a31d495adf8e189d0188918f4ff22f93876
Author: Brian Burkhalter 
Date:   Tue Nov 1 21:35:54 2022 +

8057113: (fs) Path should have a method to obtain the filename extension

Reviewed-by: rriggs, lancea, mr, alanb

On Wed, Sep 10, 2025 at 8:01 PM David Alayachew
 wrote:
>
> Hello @core-libs-dev,
>
> I have frequently run into the following pothole.
>
> Imagine the following directory setup.
>
> root/folderA/fileX.java
> root/folderB/fileY.js
> root/folderC/fileZ.html
>
> In this directory, let's say that we run the following code.
>
> Files
> .walk(Path.of("root"))
> .filter(path -> path.endsWith("html"))
> .forEach(System.out::println)
> ;
>
> One would expect only fileZ.html to be printed out, but nothing does. The 
> reason why is because path.endsWith(String) is effectively an alias for 
> path.endsWith(Path.of(String)). The confusion being that Path.of(someString) 
> is looking for a file or a directory. Thus, since there is neither a file nor 
> a folder called "html", the stream prints out nothing.
>
> This a very easy pothole to fall into, as the method name endsWith is the 
> same as the one for String, thus, people will easily mix it up. And worse 
> yet, depending on what they test with, they can easily confuse themselves 
> into thinking they are good. For example, if I had done "fileZ.html" as my 
> endsWith, I would have returned exactly what was expected, causing me to be 
> misled.
>
> And as a cherry on the top, the syntactic benefit of this method is very 
> little. Wrapping your string in a Path.of() means that you fall under the 
> Path.endsWith(Path) overload, which is more explicit what it does. And at the 
> very least, should give pause to the developer thinking it is doing String 
> comparison, as they have to wrap their String in a Path, causing a moment to 
> think.
>
> So, since this is a low value method and it causes high confusion, I vote 
> that we deprecate it.
>
> Thoughts?
>
> Thank you for your time.
> David Alayachew

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Oh yes, agreed -- if we were going to do this, can't just be this method.
So there is the startsWith method, for example.

If we are going down the documentation route, then I'd like a simple
example added to the javadocs for both startsWith and endsWith that show
what this would and would not match. Not only will this clear up my
ambiguity, but there might be a few corners of this api worth showing by
example.

For example, I had a root path specified by Path.of("."), and when I tried
to use the string overload of starts with (the way it was intended to be
used), it actually failed because I failed to add the ./ at the front.

If we don't want to add this stuff, that's fine. The dev will figure it out
eventually. I just keep falling into this hole, so I figured this would
make a useful experience report. And if nothing else, then this will help
for designing future api's.

Thanks for the help.
David Alayachew

On Wed, Sep 10, 2025, 4:39 PM Brian Burkhalter 
wrote:

> Hello David,
>
> On Sep 10, 2025, at 1:28 PM, David Alayachew 
> wrote:
>
> Yes exactly.
>
> And I'm not trying to say that the method is underspecified -- the javadoc
> is fairly clear.
>
> I'm merely saying that this overload adds little value, while being a
> tripping hazard for those thinking the name describes the obvious.
>
> So, I'd like to deprecate the overload. Those who want the overload, just
> use the suggestion in the javadocs.
>
>
> There are a number of methods in Path which are the same except for
> String- vs. Path-valued parameters. I’m not sure we’d want to deprecate
> just this one although I do see your point. Perhaps some additional
> disambiguating verbiage in the endsWith(String) specification would help?
>
> Brian
>

Re: Can we deprecate Path.endsWith(String)?

[Brian Burkhalter]

Hello David,

On Sep 10, 2025, at 1:28 PM, David Alayachew  wrote:

Yes exactly.

And I'm not trying to say that the method is underspecified -- the javadoc is 
fairly clear.

I'm merely saying that this overload adds little value, while being a tripping 
hazard for those thinking the name describes the obvious.

So, I'd like to deprecate the overload. Those who want the overload, just use 
the suggestion in the javadocs.

There are a number of methods in Path which are the same except for String- vs. 
Path-valued parameters. I’m not sure we’d want to deprecate just this one 
although I do see your point. Perhaps some additional disambiguating verbiage 
in the endsWith(String) specification would help?

Brian

Re: Can we deprecate Path.endsWith(String)?

[David Alayachew]

Hello @brian.burkhal...@oracle.com ,

Yes exactly.

And I'm not trying to say that the method is underspecified -- the javadoc
is fairly clear.

I'm merely saying that this overload adds little value, while being a
tripping hazard for those thinking the name describes the obvious.

So, I'd like to deprecate the overload. Those who want the overload, just
use the suggestion in the javadocs.

On Wed, Sep 10, 2025, 4:07 PM Brian Burkhalter 
wrote:

> Hello David,
>
> Redirecting to nio-dev.
>
> On Sep 10, 2025, at 12:01 PM, David Alayachew 
> wrote:
>
> One would expect only fileZ.html to be printed out, but nothing does. The
> reason why is because path.endsWith(String) is effectively an alias for
> path.endsWith(Path.of(String)). The confusion being that
> Path.of(someString) is looking for a file or a directory. Thus, since there
> is neither a file nor a folder called "html", the stream prints out nothing.
>
>
> The specification looks like it is pretty clear about the behavior,
> especially the implementation note in Path.endsWith(String)
> 
> :
>
> "The default implementation is equivalent for this path to:
>
> endsWith(getFileSystem().getPath(other));"
>
> What you were expecting sounds like what would be given by
>
> .filter(path -> path.toString().endsWith("html”))
>
> or better
>
> .filter(path -> path.getFileName().toString().endsWith("html”))
>
> Is that correct?
>
> If we could eventually agree on how to handle file extensions, that would 
> help here.
>
> Brian
>
>