Serialization overhaul: improved support and explicit legacy failures

[bbottema]

Problem

Email implements Serializable, but its current serialized form deliberately omits three pieces of state that are needed to use the restored email:

• attachment, embedded-image and decrypted-attachment DataSource content;
• the forwarded MimeMessage;
• SmimeSigningConfig.

The result is a partial read-back. Attachment metadata may still be present, but content access or sending eventually fails because the nested data source is gone. The website documents this as a list of transient fields, including one field that no longer exists, rather than defining what serialization is useful for.

Chosen behavior for v9.2.0

Treat Java serialization as a send-ready email snapshot:

1. Materialize every attachment-like data source while the email is serialized.
2. Store its bytes, name, MIME type and Jakarta Mail EncodingAware hint.
3. Restore a private, read-only, byte-backed data source.
4. Store a forwarded message as RFC822/MIME bytes and reconstruct it with a neutral Session.
5. Serialize S/MIME signing configuration, including its PKCS12 data and key settings.

This preserves the email state needed to copy, govern, validate, convert and send it later. It does not preserve the original runtime object graph.

A custom DataSource is always materialized, even when that implementation also implements Serializable. After deserialization, its concrete type, lazy IMAP/URL access, caching, write behavior and implementation-specific methods are not restored. A lazy source is therefore fetched at serialization time.

Legacy streams

Simple Java Mail releases before 9.2.0 never wrote attachment bytes into the stream, so those bytes cannot be recovered later.

A pre-9.2 email should continue to deserialize for archival and metadata inspection. Its legacy attachment receives an unavailable-data placeholder. Reading or writing its content—and therefore attempting to send it—must fail with a clear exception explaining that the legacy stream contains no attachment data, instead of failing with a null pointer.

Forwarded MIME content and S/MIME signing configuration omitted by an old stream remain null; there is no data from which to reconstruct them.

Historical lineage

• Enhancement: make Email serializable #218 introduced native Email serialization for queueing and later processing, while explicitly recognizing that arbitrary attachment data sources could not simply be serialized.
• URLDataSource uses source data name #47 / PR New NamedDataSource #50 established that an attachment wrapper must preserve the caller-facing name while delegating source behavior.
• NamedDataSource should implement EncodingAware #131 preserved EncodingAware because it can prevent repeated remote reads.
• outlookMsgToEmail loses nested msg attachments #298 and Attachments of nested Outlook messages (being attachments themselves) missing #314 exposed nested attachment loss and temporarily used a specialized serialized .sjm representation; Generating an EML from an Email object with nested attachments, when created from an Outlook MSG file #315 later replaced that path with ordinary EML attachments.
• Parse MimeMessage without reading all attachments #345 / PR Add option to parse MimeMessage without fetching attachment data from server #346 established deliberate lazy attachment loading for IMAP-backed messages. Serialization now becomes the explicit boundary at which such a source is materialized.

Acceptance criteria

• New serialized emails restore attachment, embedded-image and decrypted-attachment bytes and MIME metadata.
• Serializable custom data sources are still restored as internal read-only snapshots, never as their original implementation.
• Lazy sources are read exactly once during serialization and their streams are closed.
• Forwarded MIME messages survive with their headers, body structure and attachments.
• S/MIME signing configuration survives, including PKCS12 bytes and algorithm.
• Restored emails can be copied, governed, validated, converted and sent.
• Pre-9.2 attachment-bearing fixtures still deserialize, but content access and sending fail with a clear legacy-data exception.
• Serialization failures do not produce a usable partial snapshot.
• Website, Javadocs, v9.2 migration notes and Unreleased release notes describe the new contract and its security implications.
• Focused tests and the complete Java 8 build pass.

[bbottema]

Implemented for v9.2.0:

• Native Java serialization now creates a send-ready content snapshot.
• Attachment, embedded-image, and decrypted-attachment bytes and MIME metadata are restored through repeatable, read-only data sources.
• Forwarded MIME content and S/MIME signing configuration, including PKCS12 material, are retained.
• Custom DataSource implementations are materialized; their concrete type and runtime behavior are not reconstructed.
• Pre-9.2.0 streams remain inspectable, and attachment bytes those versions never stored now fail with an explicit legacy-format message when used.
• Javadocs, feature documentation, migration notes, and release notes describe the behavior and sensitive-data boundary.

The older custom-DataSource discussions have also been updated with this direction.

[bbottema]

This issue's change is now available in Simple Java Mail 9.2.0 and from Maven Central.