Java method parameter - get only Immutable List

I want to enforce immutability in one of my methods.

public record Student (String name, int rank, String school, String district){}

public String topRankingStudentName (List<Student> students) {
    // I want this incoming students to be Immutable List
    // How to enforce ?
}

Here I am getting the students as a List. I want to enforce to my callers that they pass only Immutable collection. I thought of getting ImmutableList, but that class is not accessible. Using JDK-17

How to do this ?

You can't. The List API does not have either a generally used accessible immutable subtype (nor could such a thing exist in java, at best, it could be a contract deal, with no compiler/runtime enforcement), nor does it have a method that tells you.

You have a few options, all of them bad.

use guava's ImmutableList

Use the ImmutableList class from the guava library. Note that this means an immutable non-guava list wouldn't be allowed either, e.g. List.of("a", "b") is immutable, but is not a com.google.common.collect.ImmutableList. Guava has terrible API design in regards to using guava types on the boundary between separate modules (due to them breaking backwards compatibility with abandon, which is fine, but guava not having a separate backwards locked variant with just the classes used in public APIs makes it terrible for this). I strongly recommend against doing it this way.

Write a method that checks at runtime

You can attempt to invoke .set(DUMMY_STUDENT) and then remove that student again (or set the same value), throwing an exception if this succeeds, and carrying on if you get an UnsupportedOperationException. This is a bit hacky (there is no spec guarantee that getting an UOEx necessarily means it's immutable). Use set and not add because Arrays.asList supports set and not add:

public String topRankingStudentName(List<? extends Student> students) {
  ensureImmutable(students);
  ....
}

/**
 * This method relies on the fact that the vast majority
 * of immutable list impls fail-fast when calling
 * mutable methods even if they would have no effect,
 * and that they fail-fast by throwing UnsupportedOperationException.
 */
public static <T> void ensureImmutable(List<T> list) {
  try {
    if (list.size() > 0) {
      list.set(0, list.get(0));
    } else {
      list.clear();
    }
  } catch (UnsupportedOperationException expected) {
    // This is good news - we want this to happen
    return;
  }
  throw new IllegalArgumentException("list should be immutable");
}

I wouldn't do this either; at some point you're better off putting in the documentation (the javadoc) what the inputs should be instead of checking everything; there are ways around this if someone is intentionally wanting to write broken code. And if someone is intentionally trying to mess it up, no amount of checks are going to stop them. Conclusion: Writing checks that go beyond trying to stop honest misuse of an API and try to stop intentional misuse of an API cannot possibly work, so don't try.

Just write it in the docs

Just put a note in the docs that the list must not be changed once passed, and recommending that callers use List.copyOf(someMutableList) if they can't make this guarantee.

Make a copy

You can always write:

public String topRankingStudentName(List<? extends Student> studentsIn) {
  List<? extends Student> students = List.copyOf(studentsIn);
 // Code here
}

There are situations where this code is 'smart' and doesn't actually make copies - specifically if studentsIn is e.g. made with List.of(), the above makes no copy (because the List API code knows there's no point to doing this). However, this doesn't do what you want (which is: Ensure callers only pass in immutable lists), it merely solves a different problem (which is: You don't want your code to do wonky things because the list is being changed halfway through running). Only you can determine if this alternate effect is good enough here.

Note that this also adds a requirement that the provided list contains no null values.

Hack in a different way

Given that List.copyOf is 'smart' and returns the argument directly if it is an immutable list from the core libraries (it wouldn't do that for various immutable lists, such as Arrays.asList(someZeroLenArray), or guava's ImmutableList instances) - you can use that:

public String topRankingStudentName(List<? extends Student> students) {
  /* Check immutable */ {
    List<? extends Students> s = List.copyOf(students);
    if (s != students) throw new IllegalArgumentException("students is not immutable");
  }

  // code here
}

Excluding various non-List.of-based immutable lists with this is not great, though.

Closing notes

Most of these hacks 'work' within the caveats they describe, but most aren't actually programming against spec, just against currently-known behaviour. I have no particular reason to believe these behaviours will ever change, but if they do, you can't file bugs with e.g. team OpenJDK that they changed how List.copyOf works.

For that and a few more reasons I strongly recommend going with either the 'make a copy' or 'just document it' options.

Also note that given the input is (supposed to be) immutable, List<? extends Student> is the right type, not List<Student>. The former lets folks pass List<SomeSpecificStudentSubC;ass> as well, and the only thing that a List<? extends Student> cannot do that a List<Student> can do, is 'add things to it' (doesn't mean the list is immutable, merely that your code cannot add anything except null, it can still remove things though), which, given that you want immutable input, you aren't interested in.