From eeedfafddae996a2a98567ec38a473acfd0a7f64 Mon Sep 17 00:00:00 2001 From: Kenneth VanderLinde Date: Thu, 2 Nov 2023 15:17:55 -0700 Subject: [PATCH] Document ListSource.lightList regarding the serialization subtleties --- .../net/rptools/maptool/model/LightSource.java | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/main/java/net/rptools/maptool/model/LightSource.java b/src/main/java/net/rptools/maptool/model/LightSource.java index 88ba8eb722..0da670d38e 100644 --- a/src/main/java/net/rptools/maptool/model/LightSource.java +++ b/src/main/java/net/rptools/maptool/model/LightSource.java @@ -48,6 +48,20 @@ public enum Type { private final @Nullable GUID id; private final @Nonnull Type type; private final boolean scaleWithToken; + + /** + * This light segments that make up the light source. + * + *

In practice this will be an {@code ImmutableList} during runtime. However, previously + * serialized {@code LightSource} instances may have specified that it must be a {@code + * LinkedList} or other specific {@code List} implementation. So we need to keep this as a {@code + * List} in order to deserialize those. + * + *

There is also one case where it won't be an {@code ImmutableList}, and that is during + * serialization. At such a time, a temporary {@code LightSource} is created with an {@code + * ArrayList} instead. (see {@link #writeReplace()}) so that the XML does not depend on the use of + * {@code ImmutableList} or any other particular {@code List} implementation. + */ private final @Nonnull List lightList; // Lumens are now in the individual Lights. This field is only here for backwards compatibility