A Shared Singleton JAX-RS Resource and a Mapper That Never Runs

406 Not Acceptable - the client's Accept cannot be satisfied. Content negotiation runs before the method body: the runtime intersects the media types the client will accept with the @Produces set on the matched method (or class) and picks the best match by specificity and q-value. Adding application/vnd.acme.v2+json does not widen the set for a client that sends only Accept: application/json - that type is still declared, so 406 is not automatic here. The realistic causes are: (a) the method (or class) now declares only the vendor type in a different revision, (b) the client sends Accept: application/json;q=0, or (c) a MessageBodyWriter for the selected type is absent. Diagnose by logging the resolved @Produces: 406 always means "the server had no representation the client declared it would accept".

Fixes: keep application/json in @Produces alongside the vendor type, or set qs to express preference (@Produces({"application/vnd.acme.v2+json;qs=0.9","application/json;qs=0.5"})), or have the mobile client send the vendor type. Note that Content-Type is irrelevant to a GET's negotiation - that is the usual confusion on this kind of question.

415 Unsupported Media Type - the server cannot read what the client sent. For a POST, the runtime matches the request's Content-Type against @Consumes; with no match it returns 415 before invoking the method. It is the mirror image of 406.

Do not "accept anything". Declaring @Consumes(MediaType.WILDCARD) pushes the problem into the body reader: an unmatched type still needs a MessageBodyReader, and you lose the contract. Better: declare exactly the supported types (application/json, application/xml) and document the 415, or add a custom MessageBodyReader<Charge> for text/plain if the partner is genuinely sending CSV-like text.

Default lifecycle. A JAX-RS root resource class is, by specification, instantiated per request (and with CDI, the default scope is @RequestScoped). That means ordinary instance fields are effectively request-local and need no synchronization - which is exactly why the class worked before. Annotating the class @Singleton changes it into one shared instance for the application's lifetime: instance fields become global mutable state, visible to every concurrent request.

What breaks.

• SimpleDateFormat is not thread-safe. Its internal Calendar is mutated by both format and parse; concurrent use produces garbled output, wrong dates (the partner's "malformed dates"), or NumberFormatException/ArrayIndexOutOfBoundsException surfacing as 500s. This is the exact symptom described, and it is intermittent because it depends on timing.
• The ArrayList cache is a second hazard: concurrent add can corrupt the internal array or lose elements, and iteration during a resize can throw ConcurrentModificationException.

Fixes.

1. Remove @Singleton. The per-request instance has no shared state and the JVM allocation is trivial compared with the request cost.
2. Replace SimpleDateFormat with java.time.format.DateTimeFormatter (immutable and thread-safe) and use it as a static final constant.
3. If the cache genuinely must be shared, make it an @ApplicationScoped CDI bean holding a ConcurrentHashMap, injected into the resource - separation of concerns, and a clear concurrency contract.
4. If you keep a shared formatter in legacy code, wrap it in a ThreadLocal or synchronize, but that is a workaround, not a design.

Remember that sub-resource locators return objects whose lifecycle is also per-request unless annotated; a @Singleton returned from a locator is invalid in JAX-RS 2.0 and the runtime will report an error.

Root cause: scanning is disabled. When an Application subclass overrides getClasses() and returns a non-empty set, the JAX-RS runtime uses exactly that set and does not perform class-path scanning for @Provider classes. If getClasses() returns an empty set, the implementation falls back to scanning. Because RestApplication returns only AccountResource.class, the mapper is never registered - it is not a mapper, it is just an unregistered class. This is the single most common cause of "my @Provider is ignored".

Fixes.

1. Return the providers too: getClasses() returns AccountResource.class and ErrorEnvelopeMapper.class (and any MessageBodyReader/Writer, ContainerRequestFilter, Feature).
2. Or return Collections.emptySet() from getClasses() and let the container scan, keeping @ApplicationPath for the base URI.
3. Or register in web.xml via the Jersey servlet's jersey.config.server.provider.classnames init-param.

Once it runs, mind these traps.

• A mapper for Throwable or Exception also catches WebApplicationException in most implementations. If you return a generic 500 envelope, a legitimate 404 or 401 becomes a 500. Preserve the status: if (e instanceof WebApplicationException) { status = ((WebApplicationException) e).getResponse().getStatus(); }.
• Precedence is by nearest superclass: a BankRejectionException will be handled by ExceptionMapper<BankRejectionException> if present, else ExceptionMapper<Exception>, else Throwable.
• Never leak stack traces or SQL into the envelope; log with a correlation id and return that id.
• Mappers cannot be used to alter responses produced before JAX-RS is reached (container-level 404 for an unmapped URL, or errors from an authentication constraint), which are still rendered by the servlet container's error pages; configure <error-page> separately for those.