How to Return Multiple Values From a Java Method

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 demonstrate how to use container classes for complex data, and learn how to create generic tuple classes.

Finally, we’ll illustrate 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 defined the coordinates array of type Number because it’s the common class between Integer and Double elements.

3. How to Return Two Arrays in a Method

At the outset, Java methods support only a single return value. However, we can use a class from the Collections Framework to return two, or more, values.

3.1. Returning Arrays of Same Type

The Collections framework supports creating collections to encapsulate a group of arrays as a single value. We can use generics to parameterize a Collections class when we want to return arrays of a specific type. Let’s demonstrate with an example returning two arrays of component type String. Accordingly, we can use an ArrayList<String[]> return type:

public ArrayList<String[]> getArrays() {
    ArrayList<String[]> arrays = new ArrayList<String[]>(2);

    String[] firstArray = {"first", "second", "third"};
    arrays.add(firstArray);

    String[] secondArray = {"one", "two", "three"};
    arrays.add(secondArray);
    return arrays;
}

In the example method above, we create an instance of type ArrayList<String[]> of capacity/size 2. Thereafter, we add two String arrays to the ArrayList and return it from the method.

We can retrieve the two arrays from the single value in the invocation context:

ArrayList<String[]> arrayList=getArrays();
String[] firstArray=arrayList.get(0);
String[] secondArray=arrayList.get(1);

Thereafter, let’s output the two arrays fetched:

System.out.println(Arrays.asList(firstArray));
System.out.println(Arrays.asList(secondArray));

We get, as output, the two arrays returned from the method call:

[first, second, third]
[one, two, three]

The method can return more than two arrays of component type String by modifying it slightly.

3.2. Returning Arrays of Different Type

The Collections doesn’t provide any ready-made type to group arrays of different component types. We can use the Object type to represent an array of any component type since all arrays are Java objects. Accordingly, we can parameterize ArrayList with Object using generics. Let’s demonstrate with an example to return two or more arrays of any component type:

public ArrayList<Object> getArrays() {
    ArrayList<Object> arrays = new ArrayList<Object>(2);

    String[] firstArray = {"first", "second", "third"};
    arrays.add(firstArray);

    int[] intArray = {1, 2, 3};
    arrays.add(intArray);
    return arrays;
}

In the example method above, we create an instance of a generic type ArrayList of capacity/size 2 that is parameterized over Object. Then, we add two arrays to the ArrayList. Furthermore, one of the arrays we add is of component type String, and the other is of component type int. As before, we return the ArrayList from the method. We can retrieve the two arrays in the invocation context:

ArrayList<Object> arrayList=getArrays();
String[] firstArray=(String[])(arrayList.get(0));
int[] secondArray=(int[])(arrayList.get(1));

Thereafter, let’s output the two arrays:

[first, second, third]
[1, 2, 3]

Furthermore, as the component type of an array may not be known when retrieving arrays, we can find it using getComponentType():

(arrayList.get(0)).getClass().getComponentType();
(arrayList.get(1)).getClass().getComponentType();

The output for the two example arrays lists the same types that we created:

class java.lang.String
int

Again, we can return more than two arrays of any similar component type.

4. 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.

4.1. Returning Values of Similar Type in a List

To start, 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.

4.2. Returning Named Values in a Map

If we want 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.

5. 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);
}

It’s recommended that we make data classes like Coordinates immutable. By doing so, we create simple, thread-safe, sharable objects.

6. Using Tuples

Like containers, tuples store fields of different types. However, they differ in that they aren’t application-specific.

They are specialized when we use them to describe which types we want them to handle, but can also act as a general-purpose container for a certain number of values. This means we don’t 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 we want to find the distance between a Coordinates point and all the other points inside a List<Coordinates>. Then we need to return the most distant Coordinate object, along with the distance.

Let’s first create a generic two-field 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 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.

7. 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’ve 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.

First, let’s add the commons-lang3 dependency in our pom.xml:

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

7.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();
}

7.2. ImmutableTriple From Apache Commons Lang

The ImmutableTriple is pretty similar to the ImmutablePair. The only difference is, as its name suggests, 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’ll 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 we can return the three values with a single method using the ImmutableTriple class:

ImmutableTriple<Double, Double, Double> getMinAvgMaxTriple(  
  List<Coordinates> coordinatesList, Coordinates target) {    
    <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);
}

8. Conclusion

In this article, we 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.

Conversely, 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 illustrated some examples from the Apache Commons Lang library.