Refactor Response handling by adding typed helper methods for responsePhrase

[frankgiordano]

Summary

This change introduces typed helper methods to the Response class to simplify consumption of the responsePhrase field and reduce repeated handling of raw Object values across the SDK.

Motivation

The current Response API exposes responsePhrase as Optional, which provides flexibility for different response types (e.g., JSON, text, binary). However, this design requires callers to repeatedly perform type conversion and null-safe handling, commonly using patterns such as:

        } catch (ZosmfRequestException e) {
            String errMsg = e.getMessage();
            if (e.getResponse() != null && e.getResponse().getResponsePhrase().isPresent()) {
                String response = e.getResponse().getResponsePhrase().get().toString();
                if (!response.isBlank() && !"{}".equals(response)) {
                    errMsg = response;
                }
            }
            throw new RuntimeException(errMsg, e);
        }

This results in:

• Repetitive boilerplate code across the codebase
• Reduced readability in error handling and response-processing logic
• Increased likelihood of inconsistent handling of response values

Changes

Added the following helper methods to Response:

• getResponsePhraseAsString() – retrieves the response phrase as a String
• getResponsePhraseAsBytes() – retrieves the response phrase as a byte[] when applicable
• hasResponsePhrase() – indicates whether a response phrase is present
• hasTextResponsePhrase() – indicates whether the response phrase is a non-blank String

These methods centralize type conversion logic within the SDK and improve overall ergonomics for consumers.

Benefits

• Improves readability of downstream code (especially exception handling paths)
• Eliminates repeated Object handling logic in callers
• Maintains backward compatibility (no changes to existing API methods)
• Aligns with existing use of Optional while making it easier to consume

Notes

• No breaking changes were introduced
• Existing methods and behavior remain unchanged
• All additions are additive and backward compatible

Example Improvement:

  } catch (ZosmfRequestException e) {
      String errMsg = e.getMessage();
  
      if (e.getResponse() != null && e.getResponse().hasTextResponsePhrase()) {
          errMsg = e.getResponse().getResponsePhraseAsString().get();
      }
  
      throw new RuntimeException(errMsg, e);
  }


  } catch (ZosmfRequestException e) {
      String errMsg = e.getMessage();
      if (e.getResponse() != null && e.getResponse().hasTextResponsePhrase()) {
          errMsg = e.getResponse().getResponsePhraseAsString().orElse(errMsg);
      }
      throw new RuntimeException(errMsg, e);
  }