Imagine that you want to add new custom header to your SIP message in JAIN SIP. You look at javadoc and notice a interface called ExtensionHeader.

public interface ExtensionHeader extends Header

From javadoc:

This interface represents an Extension SIP header that was not defined at the baseline of this specification. Extension Headers can be added as required by extending this interface assuming other endpoints understand the Header. Any Header that extends this class must define a "NAME" String constant identifying the name of the extension Header. A server must ignore Headers that it does not understand. A proxy must not remove or modify Headers that it does not understand.

Cool, so it looks like you can add new SIP header just by extending this interface

public interface MySuperNewHeader extends ExtensionHeader {...}
public class MySuperNewHeaderImpl implements MySuperNewHeader {...}

and then just do

MySuperNewHeader mySuperNewheader = new MySuperNewheaderImpl(...);
request.addHeader(mySuperNewheader);

Guess what, it won’t work! You will get ClassCastException because all JAIN SIP implementations expect all headers to extend internal Header implementation. Read rest of javadoc and you can start thinking that this interface should ONLY be used by implementations of JAIN SIP.

Implementation note : The implementation of any new headers added since version 1.1 of this specification SHOULD implement ExtensionHeader for backwards compatibility (even if these headers are defined in the current version of this specification). Headers that are not part of the current version of this specification MUST implement ExtensionHeader.
Author:
BEA Systems, NIST

Standard body creating JAIN SIP spec didn’t think library users would want to easily add new headers. Only way to create custom header that you can add to SIP message is to create it with this function of HeaderFactory:

Header createHeader(java.lang.String name,
                    java.lang.String value)
                    throws java.text.ParseException

As you can see this function takes name and value parameters, both those two parameters can be taken from interface ExtensionHeader! So you can easily create usable header like this:

Header usableHeader = headerFactory.createHeader(mySuperNewheader.getName(), mySuperNewheader.getValue());

This way we can add our header to SIP message but we lose interface to our MySuperNewHeader :/

Only real solution would be to change specification to require implementations to allow adding ExtensionHeaders created by library user to SIP message. This could be easily achieved by adding some code to implementation of javax.sip.message.Message.addHeader(Header header) function.

void addHeader(Header header) {
	if(!(header instanceof InternalHeaderObject)
		&& header instanceof ExtensionHeader) {
			ExtensionHeader extensionHeader = (ExtensionHeader) header;
			header = headerFactory.createHeader(extensionHeader.getName(), extensionHeader.getValue());
		}
	...
}

Till then we need to work with createHeader(…) function as only way to add custom headers in JAIN SIP.