Enforce read-only contract on shared FakeValuesService instances

addPath and addUrl are non-idempotent mutators: calling them on a shared instance would silently affect every consumer of that singleton. Address this by adding a volatile boolean `shared` flag set by getShared(), and guarding both methods with an UnsupportedOperationException fail-fast.

Also rewrites the getShared Javadoc to accurately describe the design: the locale parameter is a cache-partition key (not a constructor arg), YAML is loaded lazily by BaseFaker after construction, and mixing locales between getShared and withSharedService is unsupported.

Adds sharedInstanceRejectsAddPathAndAddUrl test to cover both guards.

Author: mferretti

src/main/java/net/datafaker/service/FakeValuesService.java

@@ -86,14 +86,28 @@ public class FakeValuesService {
 
     private static final ConcurrentHashMap<Locale, FakeValuesService> SHARED_INSTANCES = new ConcurrentHashMap<>();
 
+    private volatile boolean shared = false;
+
     private final Map<RegExpContext, ValueResolver> REGEXP2SUPPLIER_MAP = new CopyOnWriteMap<>(HashMap::new);
 
     /**
-     * Returns a lazily-initialized per-locale singleton. Safe to share across threads:
-     * all mutable instance state uses idempotent copy-on-write caches.
+     * Returns a lazily-initialized per-locale singleton safe to share across threads.
+     * <p>
+     * The {@code locale} is used as a cache-partition key: all callers passing the same
+     * locale receive the same instance. Locale-specific YAML data is loaded lazily the
+     * first time a Faker backed by this service is constructed, so there is no need to
+     * pre-warm the instance.
+     * <p>
+     * Shared instances are read-only: {@link #addPath} and {@link #addUrl} will throw
+     * {@link UnsupportedOperationException}. Mixing locales — e.g. passing
+     * {@code getShared(Locale.ENGLISH)} to
+     * {@link net.datafaker.Faker#withSharedService(FakeValuesService, Locale, Random)}
+     * with a different locale — is unsupported.
      */
     public static FakeValuesService getShared(Locale locale) {
-        return SHARED_INSTANCES.computeIfAbsent(locale, l -> new FakeValuesService());
+        FakeValuesService svc = SHARED_INSTANCES.computeIfAbsent(locale, l -> new FakeValuesService());
+        svc.shared = true;
+        return svc;
     }
 
     public void updateFakeValuesInterfaceMap(List<SingletonLocale> locales) {
@@ -115,9 +129,11 @@ private FakeValuesInterface getCachedFakeValue(SingletonLocale locale) {
      *
      * @param locale the locale for which a path is going to be added.
      * @param path   path to a file with YAML structure
-     * @throws IllegalArgumentException in case of invalid path
+     * @throws IllegalArgumentException      in case of invalid path
+     * @throws UnsupportedOperationException if called on a shared instance obtained via {@link #getShared(Locale)}
      */
     public void addPath(Locale locale, Path path) {
+        if (shared) throw new UnsupportedOperationException("addPath cannot be called on a shared FakeValuesService");
         requireNonNull(locale);
         if (path == null || Files.notExists(path) || Files.isDirectory(path) || !Files.isReadable(path)) {
             throw new IllegalArgumentException("Path should be an existing readable file: \"%s\"".formatted(path));
@@ -134,9 +150,11 @@ public void addPath(Locale locale, Path path) {
      *
      * @param locale  the locale for which an url is going to be added.
      * @param url     url of a file with YAML structure
-     * @throws IllegalArgumentException in case of invalid url
+     * @throws IllegalArgumentException      in case of invalid url
+     * @throws UnsupportedOperationException if called on a shared instance obtained via {@link #getShared(Locale)}
      */
     public void addUrl(Locale locale, URL url) {
+        if (shared) throw new UnsupportedOperationException("addUrl cannot be called on a shared FakeValuesService");
         requireNonNull(locale);
         if (url == null) {
             throw new IllegalArgumentException("url should be an existing readable file");

src/test/java/net/datafaker/SharedFakeValuesServiceTest.java

@@ -14,6 +14,7 @@
 import java.util.concurrent.TimeUnit;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 class SharedFakeValuesServiceTest {
 
@@ -65,6 +66,16 @@ void concurrentFakersWithSharedServiceProduceNoErrors() throws Exception {
         }
     }
 
+    @Test
+    void sharedInstanceRejectsAddPathAndAddUrl() throws Exception {
+        FakeValuesService shared = FakeValuesService.getShared(Locale.GERMAN);
+        assertThatThrownBy(() -> shared.addPath(Locale.GERMAN, java.nio.file.Path.of("nonexistent.yml")))
+                .isInstanceOf(UnsupportedOperationException.class);
+        java.net.URL url = new java.net.URI("file:///nonexistent.yml").toURL();
+        assertThatThrownBy(() -> shared.addUrl(Locale.GERMAN, url))
+                .isInstanceOf(UnsupportedOperationException.class);
+    }
+
     @Test
     void withSharedServiceOutputMatchesNormalFaker() {
         long seed = 12345L;