Method signature mismatched with javadoc and implementation

[robobario]

The javadoc of ManagedDependentResourceContext#put describe it as returning Optional. The implementation returns an Optional but casts it to T, so it is currently a compile error to write:

Optional<String> result = new ManagedDependentResourceContext().put("key", "value");

Using the method as declared results in a ClassCastException:

DefaultManagedDependentResourceContext context = new DefaultManagedDependentResourceContext();
context.put("key", "value");
String actual = context.put("key", "valueB");

fails with:

java.lang.ClassCastException: class java.util.Optional cannot be cast to class java.lang.String (java.util.Optional and java.lang.String are in module java.base of loader 'bootstrap')

The user can cast to get at the Optional like Optional<String> actual = (Optional<String>) (Object) context.put("key", "value");

So this PR updated the javadoc and implementation to match the method declaration and return the object-or-null rather than an Optional.

[metacosm]

This should target the next branch because this would be a breaking API change. Alternatively, we would need to deprecate the existing methods and provide new implementations but this cannot go as-is in main.

[robobario]

pushed up creating a new method and deprecating the old, a bit clunky since put is a nicer name than the new one.

[metacosm]

Upon further review, looking at the history of the modifications, I believe that this API got broken at some point in the past and we should probably conform to the Map-like API and change the documentation accordingly instead of returning Optional. I have made the required changes but I cannot push to your branch, @robobario.

[metacosm]

@robobario see #2595 for the changes that I think should be included as part of this work.

[robobario]

great, thanks @metacosm . Have updated and cleaned up the git history (and renamed a test method)

[csviri]

LGTM

[robobario]

thank you!

[metacosm]

Thank you for your work!