Java Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE

1. Overview

In this tutorial, we'll learn different ways to return multiple values from a Java method.

First, we'll return arrays and collections. Then, we'll show how to use container classes for complex data and learn how to create generic tuple classes.

Finally, we'll see examples of how to use third-party libraries to return multiple values.

2. Using Arrays

Arrays can be used to return both primitive and reference data types.

For example, the following getCoordinates method returns an array of two double values:

double[] getCoordinatesDoubleArray() {
  
    double[] coordinates = new double[2];

    coordinates[0] = 10;
    coordinates[1] = 12.5;
  
    return coordinates;
}

If we want to return an array of different reference types, we can use a common parent type as the array's type:

Number[] getCoordinatesNumberArray() {
  
    Number[] coordinates = new Number[2];

    coordinates[0] = 10;   // Integer
    coordinates[1] = 12.5; // Double
  
    return coordinates;
}

Here we've defined the coordinates array of type Number because it's the common class between Integer and Double elements.

3. Using Collections

With generic Java collections, we can return multiple values of a common type.

The collections framework has a wide spectrum of classes and interfaces. However, in this section, we'll limit our discussion to the List and Map interfaces.

3.1. Returning Values of Similar Type in a List

To start with, let's rewrite the previous array example using List<Number>:

List<Number> getCoordinatesList() {
  
    List<Number> coordinates = new ArrayList<>();
  
    coordinates.add(10);  // Integer
    coordinates.add(12.5);  // Double
  
    return coordinates;
}

Like Number[], the List<Number> collection holds a sequence of mixed-type elements all of the same common type.

3.2. Returning Named Values in a Map

If we'd like to name each entry in our collection, a Map can be used instead:

Map<String, Number> getCoordinatesMap() {
  
    Map<String, Number> coordinates = new HashMap<>();
  
    coordinates.put("longitude", 10);
    coordinates.put("latitude", 12.5);
  
    return coordinates;
}

Users of the getCoordinatesMap method can use the “longitude” or “latitude” keys with the Map#get method to retrieve the corresponding value.

4. Using Container Classes

Unlike arrays and collections, container classes (POJOs) can wrap multiple fields with different data types.

For instance, the following Coordinates class has two different data types, double and String:

public class Coordinates {
  
    private double longitude;
    private double latitude;
    private String placeName;
  
    public Coordinates(double longitude, double latitude, String placeName) {
  
        this.longitude = longitude;
        this.latitude = latitude;
        this.placeName = placeName;
    }
  
    // getters and setters
}

Using container classes like Coordinates enables us to model complex data types with meaningful names.

The next step is to instantiate and return an instance of Coordinates:

Coordinates getCoordinates() {
  
    double longitude = 10;
    double latitude = 12.5;
    String placeName = "home";
  
    return new Coordinates(longitude, latitude, placeName);
}

We should note that it's recommended that we make data classes like Coordinates immutable. By doing so, we create simple, thread-safe, sharable objects.

5. Using Tuples

Like containers, tuples store fields of different types. However, they differ in that they are not application-specific.

They are specialized when we use them to describe which types we want them to handle, but are general purpose container of a certain number of values. This means we do not need to write custom code to have them, and we can use a library, or create a common single implementation.

A tuple can be of any number of fields and is often called Tuplen, where n is the number of fields. For example, Tuple2 is a two-field tuple, Tuple3 is a three-field tuple, and so on.

To demonstrate the importance of tuples, let's consider the following example. Suppose that we want to find the distance between a Coordinates point and all other points inside a List<Coordinates>. Then, we need to return that most distant Coordinate object, along with the distance.

Let's first create a generic two-fields tuple:

public class Tuple2<K, V> {

    private K first;
    private V second;
  
    public Tuple2(K first, V second){
        this.first = first;
        this.second = second;
    }

    // getters and setters
}

Next, let's implement our logic and use a Tuple2<Coordinates, Double> instance to wrap the results:

Tuple2<Coordinates, Double> getMostDistantPoint(List<Coordinates> coordinatesList, 
                                                       Coordinates target) {

    return coordinatesList.stream()
      .map(coor -> new Tuple2<>(coor, coor.calculateDistance(target)))
      .max((d1, d2) -> Double.compare(d1.getSecond(), d2.getSecond())) // compare distances
      .get();
}

Using Tuple2<Coordinates, Double> in the previous example has saved us from creating a separate container class for one-time use with this particular method.

Like containers, tuples should be immutable. Additionally, due to their general-purpose nature, we should use tuples internally rather than as part of our public API.

6. Third-Party Libraries

Some third-party libraries have implemented an immutable Pair or Triple type. Apache Commons Lang and javatuples are prime examples. Once we have those libraries as dependencies in our application, we can directly use the Pair or Triple types provided by the libraries instead of creating them by ourselves.

Let's look at an example using Apache Commons Lang to return a Pair or a Triple object.

Before we step further, let's add the commons-lang3 dependency in our pom.xml:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.9</version>
</dependency>

6.1. ImmutablePair from Apache Commons Lang

The ImmutablePair type from Apache Commons Lang is exactly what we want: an immutable type whose usage is straightforward.

It contains two fields: left and right. Let's see how to make our getMostDistantPoint method return an object of the ImmutablePair type:

ImmutablePair<Coordinates, Double> getMostDistantPoint(
  List<Coordinates> coordinatesList, Coordinates target) {
    return coordinatesList.stream()
      .map(coordinates -> ImmutablePair.of(coordinates, coordinates.calculateDistance(target)))
      .max(Comparator.comparingDouble(Pair::getRight))
      .get();
}

6.2. ImmutableTriple from Apache Commons Lang

The ImmutableTriple is pretty similar to the ImmutablePair. The only difference is, as its name tells, an ImmutableTriple contains three fields: left, middle, and right.

Now, let's add a new method to our coordinates calculation to show how to use the ImmutableTriple type.

We're going to go through all points in a List<Coordinates> to find out the min, avg, and max distances to the given target point.

Let's see how can we return the three values with a single method using the ImmutableTriple class:

ImmutableTriple<Double, Double, Double> getMinAvgMaxTriple(
  List<Coordinates> coordinatesList, Coordinates target) {
    List<Double> distanceList = coordinatesList.stream()
      .map(coordinates -> coordinates.calculateDistance(target))
      .collect(Collectors.toList());
    Double minDistance = distanceList.stream().mapToDouble(Double::doubleValue).min().getAsDouble();
    Double avgDistance = distanceList.stream().mapToDouble(Double::doubleValue).average().orElse(0.0D);
    Double maxDistance = distanceList.stream().mapToDouble(Double::doubleValue).max().getAsDouble();

    return ImmutableTriple.of(minDistance, avgDistance, maxDistance);
}

7. Conclusion

In this article, we've learned how to use arrays, collections, containers, and tuples to return multiple values from a method. We can use arrays and collections in simple cases since they wrap a single data type.

On the other hand, containers and tuples are useful in creating complex types, with containers offering better readability.

We also learned that some third-party libraries have implemented pair and triple types and saw some examples from the Apache Commons Lang library.

As usual, the source code for this article is available over on GitHub.

Java bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE
6 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Pavlo Sidelov
5 months ago

Great article! Long term looking into this problem, thank you for the clarification!

Loredana Crusoveanu
5 months ago
Reply to  Pavlo Sidelov

Hi Pavlo,

Thanks for the feedback; happy to help.

Cheers.

Stephane D
Stephane D
5 months ago

Defined in Apache Commons:
– org.apache.commons.lang3.tuple.ImmutablePair
– org.apache.commons.lang3.tuple.ImmutableTriple

Loredana Crusoveanu
5 months ago
Reply to  Stephane D

Hi Stephane,

Thanks for the feedback! We plan to update the article with Apache Commons’ implementations.

Cheers.

Kweetal
Kweetal
5 months ago

Instead of having to come up with a new implementation each time one needs a Tuple2, why not use the Apache Commons class org.apache.commons.lang3.tuple.ImmutablePair.
Just use Pair tuple = ImmutablePair.of(leftValue, rightValue);

Loredana Crusoveanu
5 months ago
Reply to  Kweetal

Hi Kweetal,

Good point! We’ll update the article and mention Apache Commons’ implementations.

Cheers.

Comments are closed on this article!