Add utilities to detect and replace broken links.

[barsh404error]

Thanks alot to @christolis for helping me out on making this pull request.
Added two utulity methods isLinkBroken and replaceDeadLinks

-isLinkBroken(String url) checks the link availability using a HEAD request
I used HEAD request instead of GET request to check link availability without downloading the response body, reducing bandwidth and improving the performance.

-replaceDeadLinks (String text, String replacement) replaces unreachable/broken links asynchronously.

This change does not have any behavior changes to the existing code.

Part of #1276, implements the mentioned utility but doesnt apply it.

[CLAassistant]

All committers have signed the CLA.

[barsh404error]

@tj-wazei I've added your request and fixed them
I’ve updated the implementation to avoid mutating shared state in async callbacks and now collect the results before doing replacements sequentially.
I also reuse a single HttpClient and added a GET fallback when HEAD is not supported.
Let me know if anything else should be adjusted ^^

[Zabuzard]

The added methods are utility methods and for those it is crucial that they have a proper Javadoc explaining what they do and give examples.

The isLinkBroken method needs to explain what it means for a link to be broken and how it behaves in edge case, for example if the given text isnt a url and so on.

The other method needs to explain in more detail what the two parameters are and how they work, maybe giving a concrete example in the javadoc.

[barsh404error]

The added methods are utility methods and for those it is crucial that they have a proper Javadoc explaining what they do and give examples.

The isLinkBroken method needs to explain what it means for a link to be broken and how it behaves in edge case, for example if the given text isnt a url and so on.

The other method needs to explain in more detail what the two parameters are and how they work, maybe giving a concrete example in the javadoc.

Yes, i got that solved made javadoc for isLinkBroken and replaceDeadLinks.
i explained what does it do step by step altho idk if i wrote to long

[tj-wazei]

LGTM

[Zabuzard]

better: instead of map(foo -> ...thenApply(...)), use .map(foo -> ...).filter(...) then you also dont have all these null items in ur list, polluting it

[Zabuzard]

not done yet

[Zabuzard]

not done yet

[Zabuzard]

not done yet

[barsh404error]

I focused primarily on improving the Javadocs as requested @Zabuzard
While doing so, I slightly refactored the internal stream to use Optional instead of null to better match the documented behavior and avoid null handling
No external behavior was changed.

[barsh404error]

Thanks for the detailed review @Zabuzard I went through the comments one by one and addressed them explicitly:

Javadoc & behavior clarification

Expanded Javadoc for isLinkBroken to clearly define what “broken” means:

HTTP request failure

HTTP status codes outside the 200–399 range

Clarified that:

Status 200 is considered valid even with an empty body

Response body content is not inspected

Invalid URL formats result in an IllegalArgumentException

HEAD / GET request logic

HEAD is used as an initial, cheaper check

If HEAD indicates failure, a GET request is used as a fallback to handle servers that don’t implement HEAD correctly

Any exception during either request is treated as a broken link

Naming improvements

Renamed request variables to describe intent rather than HTTP mechanics (e.g. link status validation rather than fallback flow)

Asynchronous behavior

replaceDeadLinks performs all link checks asynchronously

CompletableFuture.allOf(...) is used only as a synchronization point; no blocking is introduced

thenApply(_ -> …) is intentionally used to ignore the unused result and avoid misleading variable names

replaceDeadLinks behavior

Added a concrete usage example to the Javadoc showing input → output transformation

Only links detected as broken are replaced

Working links and non-URL content remain unchanged

Duplicate links are checked once and replaced consistently

Edge cases

Empty input or no detected links returns the original text

Empty response bodies are not treated as broken

Exceptions during HTTP checks are handled defensively and result in “broken”

sorry for stopping to answer those comments one by one it was annoying and frustrating lol

[Zabuzard]

not done yet

[barsh404error]

hello, @Zabuzard in this commit i focused mostly on the javadocs and updated isLinkBroken() to only treat 4xx/5xx status codes as broken.
let me know if the javadocs makes sense or not, also with any few changes if your request :]

[Zabuzard]

still one open comment from my side (and the CI/CD is red)