public class EmailHeaderBuilders extends Object
The RFCs for email specify that headers for any messages must contain a globally unique identifier (the Message-ID) that allows the email recipient to distinguish between new emails and emails they have already received. When JIRA sends an email about an issue, the Message-ID header field is set to:
In JIRA, Message-ID uniqueness is achieved by using the current time in milliseconds
as part of the Message-ID. However, more that one email may be sent in the same millisecond by JIRA, and so in order
to preserve global uniqueness an atomic counter is also used as part of the Message-ID, such that
no two emails sent in the same millisecond can have the same value provided by this atomic counter (the "sequence"
MessageIdBuilder below corresponds to this counter: the thread-safety of "sequence" is not the
responsibility of this class, and is assumed to be taken care of by the caller).
MessageIdBuilder class below encapsulates the Message-ID generation logic in JIRA.
The "InReplyTo" header field in the email is used to keep track of what previous email a new email is replying to. This is used by email clients to facilitate conversation threading. Typically, the InReplyTo field will contain the Message-ID of the email that is being replied to. JIRA's use of this field is atypical in this sense. When JIRA sends an email about an issue, the InReplyTo header field is set to:
This causes the recipient of the email to group this email with other emails with the same InReplyTo header, so that hopefully emails from the same host regarding the same issue are considered part of the same thread. How email threading works is specific to the email client, and it will not always be the case that the InReplyTo header value will be used for this purpose, however this header value can be re-used in other header values such as the "References" header value (i.e. Outlook), in order to increase the likeliness that email threading will be triggered appropriately in the client. The reason that JIRA does not simply use previous Message-IDs for the InReplyTo header value is that multiple users may all be sent emails regarding an issue, and each will have a different Message-ID. It is impractical for JIRA to keep track of all the previous emails sent to different users, as this requires vast database resources.
An important difference between the
InReplyToHeaderBuilder is that
not wrap the generated string with angle brackets, but
InReplyToHeaderBuilder does. Both the Message-ID and
InReplyTo header fields are wrapped with angle brackets, but the
MessageIdBuilder assumes that this is
done after it has transferred control back to the caller, and
InReplyToHeaderBuilder encapsulates this behaviour
as part of its functionality. This is simply the result of catering for the existing callers.
|Modifier and Type||Class and Description|
Responsible for building the string value for the In-Reply-To header included in JIRA's email notifications.
Responsible for building the Message-Id string values to be included in JIRA's issue email notifications.
|Constructor and Description|
Copyright © 2002-2019 Atlassian. All Rights Reserved.