When dealing with legacy APIs that do not use Optional but may return values or null, you can gracefully handle them in modern Java by using java.util.Optional to wrap and process the returned values. Here are some best practices for handling these scenarios:

---

1. Wrap the Legacy API Response Using Optional.ofNullable

Legacy APIs might return null, so it’s helpful to wrap the return value into Optional to make your code clearer and safer. Use Optional.ofNullable() for this purpose:

String result = legacyApiCall(); // Legacy call that might return null
Optional<String> optionalResult = Optional.ofNullable(result);

optionalResult.ifPresent(value -> {
    // Process the value if present
    System.out.println("Got a value: " + value);
});

---

2. Set Default Values Using orElse or orElseGet

If a legacy API might return null, you can use orElse or orElseGet to provide a default value:

String defaultValue = "default";
String result = Optional.ofNullable(legacyApiCall()).orElse(defaultValue);

The orElseGet is preferred when computing the default value is expensive, as it executes the supplier only when the Optional is empty:

String result = Optional.ofNullable(legacyApiCall())
                        .orElseGet(() -> computeDefault());

---

3. Use orElseThrow to Handle Missing Values

If having a null value from the legacy API is invalid, and you want to enforce that with an exception, use orElseThrow:

String result = Optional.ofNullable(legacyApiCall())
                        .orElseThrow(() -> new IllegalArgumentException("Value cannot be null"));

---

4. Transform Values with map

You can process or transform the value returned by the legacy API using the map function:

Optional<String> optionalResult = Optional.ofNullable(legacyApiCall());
Optional<Integer> length = optionalResult.map(String::length);

length.ifPresent(len -> System.out.println("String length: " + len));

If the legacy API returns an object, and you need to call a method on it safely, you can use this approach to avoid NullPointerException.

---

5. Apply Operations Conditionally Using filter

You can filter an optional value based on a condition. This is useful if not all non-null values are valid:

Optional<String> optionalResult = Optional.ofNullable(legacyApiCall())
                                          .filter(value -> value.startsWith("valid"));
optionalResult.ifPresent(System.out::println);

---

6. Combine Multiple Legacy Calls with flatMap

Use flatMap when dealing with multiple operations that can return Optional values:

Optional<String> result = Optional.ofNullable(legacyApiCall())
                                  .flatMap(value -> Optional.ofNullable(anotherLegacyCall(value)));
result.ifPresent(System.out::println);

---

7. Avoid Optional with Primitives Directly

Legacy APIs that return primitive wrapper types such as Integer, Double, etc., can use the Optional variants provided by Java (OptionalInt, OptionalDouble, OptionalLong):

Integer number = legacyApiCallReturningInteger();
OptionalInt optionalInt = Optional.ofNullable(number).mapToInt(Integer::intValue);
optionalInt.ifPresent(System.out::println);

---

8. Utility Method for Optional Wrapping

If you have multiple legacy APIs to handle, consider creating a utility method to simplify Optional wrapping:

public static <T> Optional<T> wrapLegacy(T value) {
    return Optional.ofNullable(value);
}

// Usage
Optional<String> result = wrapLegacy(legacyApiCall());
result.ifPresent(System.out::println);

---

9. Log Warnings for Unexpected Null Values

For better debugging and monitoring, log a warning when an unexpected null is converted into an empty Optional:

String result = legacyApiCall();
Optional<String> optionalResult = Optional.ofNullable(result);

if (!optionalResult.isPresent()) {
    System.err.println("Warning: API returned null!");
}

---

Example: Putting It All Together

Here’s a complete example of handling a legacy API gracefully:

package org.kodejava.util;

import java.util.Optional;

public class LegacyApiExample {

    public static void main(String[] args) {
        String result = legacyApiCall();

        Optional<String> optionalResult = Optional.ofNullable(result);

        // Handle the value or provide a default
        String processed = optionalResult.map(String::toUpperCase)
                .filter(value -> value.startsWith("HELLO"))
                .orElse("Default Value");

        System.out.println("Result: " + processed);
    }

    private static String legacyApiCall() {
        // Simulate a legacy API returning null
        return null;
    }
}

---

By wrapping legacy API responses in an Optional, you can achieve better null safety, reduce NullPointerException risks, and write clearer, more readable modern Java code.