public final class MessageProtocol extends Object
This describes the negotiated protocol being used for a message. It has three elements, a content type, a charset, and a version.
The contentType may be registered mime type such as application/json, or it
could be an application specific content type, such as application/vnd.myservice+json.
It could also contain protocol versioning information, such as
application/vnd.github.v3+json. During the protocol negotiation process, the content
type may be transformed, for example, if the content type contains a version, the configured
HeaderFilter will be expected to extract that version out into the version,
leaving a contentType that will be understood by the message serializer.
The charset applies to text messages, if the message is not in a text format, then no charset should be specified. This is not only used in setting of content negotiation headers, it's also used as a hint to the framework of when it can treat a message as text. For example, if the charset is set, then when a message gets sent via WebSockets, it will be sent as a text message, otherwise it will be sent as a binary message.
The version is used to describe the version of the protocol being used. Lagom does not, out of the box, prescribe any semantics around the version, from Lagom's perspective, two message protocols with different versions are two different protocols. The version is however treated as a separate piece of information so that generic parsers, such as json/xml, can make sensible use of the content type passed to them. The version could come from a media type header, but it does not necessarily have to come from there, it could come from the URI or any other header.
MessageProtocol instances can also be used in content negotiation, an empty value means that any value is accepted.
| Constructor and Description |
|---|
MessageProtocol()
Create a message protocol that doesn't specify any content type, charset or version.
|
MessageProtocol(Optional<String> contentType,
Optional<String> charset,
Optional<String> version)
Create a message protocol with the given content type, charset and version.
|
| Modifier and Type | Method and Description |
|---|---|
Optional<String> |
charset()
The charset of the protocol.
|
Optional<String> |
contentType()
The content type of the protocol.
|
boolean |
equals(Object o) |
static MessageProtocol |
fromContentTypeHeader(Optional<String> contentType)
Parse a message protocol from a content type header, if defined.
|
int |
hashCode() |
boolean |
isText()
Whether this message protocol is a text based protocol.
|
boolean |
isUtf8()
Whether the protocol uses UTF-8.
|
Optional<String> |
toContentTypeHeader()
Convert this message protocol to a content type header, if the content type is defined.
|
String |
toString() |
Optional<String> |
version()
The version of the protocol.
|
MessageProtocol |
withCharset(String charset)
Return a copy of this message protocol with the charset set to the given charset.
|
MessageProtocol |
withContentType(String contentType)
Return a copy of this message protocol with the content type set to the given content type.
|
MessageProtocol |
withVersion(String version)
Return a copy of this message protocol with the version set to the given version.
|
public MessageProtocol(Optional<String> contentType, Optional<String> charset, Optional<String> version)
contentType - The content type.charset - The charset.version - The version.public MessageProtocol()
public Optional<String> contentType()
public MessageProtocol withContentType(String contentType)
contentType - The content type to set.public MessageProtocol withCharset(String charset)
charset - The charset to set.public MessageProtocol withVersion(String version)
version - The version to set.public boolean isText()
This is determined by whether the charset is defined.
public boolean isUtf8()
public Optional<String> toContentTypeHeader()
public static MessageProtocol fromContentTypeHeader(Optional<String> contentType)
contentType - The content type header to parse.