com.atlassian.jira.mail.threading
Class EmailHeaderBuilders

java.lang.Object
  com.atlassian.jira.mail.threading.EmailHeaderBuilders

public class EmailHeaderBuilders
extends Object

Responsible for holding the builders used to create the headers inserted into JIRA's notification emails.

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:

JIRA.${issue-id}.${issue-created-date-millis}.${sequence}.${current-time-millis}@${host}

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" member of 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). The 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:

<JIRA.${issue-id}.${issue-created-date-millis}@${host}>

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 MessageIdBuilder and InReplyToHeaderBuilder is that MessageIdBuilder does 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.

Nested Class Summary

static class	EmailHeaderBuilders.InReplyToHeaderBuilder Responsible for building the string value for the In-Reply-To header included in JIRA's email notifications.
static class	EmailHeaderBuilders.MessageIdBuilder Responsible for building the Message-Id string values to be included in JIRA's issue email notifications.

Constructor Summary

EmailHeaderBuilders()

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EmailHeaderBuilders

public EmailHeaderBuilders()