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.