Module mime
ballerina/mime Ballerina library
Overview
This module provides a set of APIs to work with messages, which follow the Multipurpose Internet Mail Extensions (MIME) specification as specified in the RFC 2045 standard.
Entity refers to the header fields and the content of a message or a part of the body in a multipart entity.
Supported multipart types
The module supports multipart/form-data, multipart/mixed, multipart/alternative, multipart/related, and
multipart/parallel as multipart content types.
Modify and retrieve the data in an entity
This module provides functions to set and get an entity body from different kinds of message types such as XML, text,
JSON, byte[], and body parts. Headers can be modified through functions such as addHeader(), setHeader(),
removeHeader(), etc.
Handling large files
The entity object method setFileAsEntityBody() can be used to set large files as the entity body and
is able to read it as a stream using the getByteStream() function.
Functions
base64Decode
function base64Decode((string|byte[]|ReadableByteChannel) contentToBeDecoded, string charset) returns (string|byte[]|ReadableByteChannel|DecodeError)Decodes a given input with MIME specific Base64 encoding scheme.
Parameters
- contentToBeDecoded (string|byte[]|ReadableByteChannel) - Content that needs to be decoded can be of type
string,byte[]orio:ReadableByteChannel
- charset string (default "utf-8") - Charset to be used. This is used only with the string input
Return Type
- (string|byte[]|ReadableByteChannel|DecodeError) - A decoded
stringif the given input is of type string, a decodedbyte[]if the given input is of type byte[], a decodedio:ReadableByteChannelif the given input is of type io:ReadableByteChannel or else amime:DecodeErrorin case of errors
base64DecodeBlob
function base64DecodeBlob(byte[] valueToBeDecoded) returns byte[]|DecodeErrorDecodes a given byte[] using the Base64 encoding scheme.
Parameters
- valueToBeDecoded byte[] - Content, which needs to be decoded
Return Type
- byte[]|DecodeError - A decoded
byte[]or else amime:DecodeErrorrecord in case of errors
base64Encode
function base64Encode((string|byte[]|ReadableByteChannel) contentToBeEncoded, string charset) returns (string|byte[]|ReadableByteChannel|EncodeError)Encodes a given input with MIME specific Base64 encoding scheme.
Parameters
- contentToBeEncoded (string|byte[]|ReadableByteChannel) - Content that needs to be encoded can be of type
string,byte[]orio:ReadableByteChannel
- charset string (default "utf-8") - Charset to be used. This is used only with the string input
Return Type
- (string|byte[]|ReadableByteChannel|EncodeError) - An encoded
stringif the given input is of type string, an encodedbyte[]if the given input is of type byte[], an encodedio:ReadableByteChannelif the given input is of typeio:ReadableByteChannel, or else amime:EncodeErrorrecord in case of errors
base64EncodeBlob
function base64EncodeBlob(byte[] valueToBeEncoded) returns byte[]|EncodeErrorEncodes a given byte[] using the Base64 encoding scheme.
Parameters
- valueToBeEncoded byte[] - Content, which needs to be encoded
Return Type
- byte[]|EncodeError - An encoded byte[] or else a
mime:EncodeErrorrecord in case of errors
getContentDispositionObject
function getContentDispositionObject(string contentDisposition) returns ContentDispositionGiven the Content-Disposition as a string, gets the ContentDisposition object with it.
mime:ContentDisposition cDisposition = getContentDispositionObject("form-data; name=filepart; filename=file-01.txt");
Parameters
- contentDisposition string - Content disposition string
Return Type
- ContentDisposition - A
ContentDispositionobject
getMediaType
function getMediaType(string contentType) returns MediaType|InvalidContentTypeErrorGets the MediaType object populated with it when the Content-Type is in string.
mime:MediaType|mime:InvalidContentTypeError returnVal = getMediaType("custom-header");
Parameters
- contentType string - Content-Type in string
Return Type
- MediaType|InvalidContentTypeError -
MediaTypeobject or else amime:InvalidContentTypeErrorin case of an invalid content-type
Classes
mime: ContentDisposition
Represents values in Content-Disposition header.
toString
function toString() returns stringConverts the ContentDisposition type to a string suitable to use as the value of a corresponding MIME header.
string contDisposition = contentDisposition.toString();
Return Type
- string - The
stringrepresentation of theContentDispositionobject
Fields
- fileName string(default "") - Default filename for storing the body part if the receiving agent wishes to store it in an external file
- disposition string(default "") - Indicates how the body part should be presented (
inline,attachment, or asform-data)
- name string(default "") - Represents the field name in case of
multipart/form-data
mime: Entity
Represents the headers and body of a message. This can be used to represent both the entity of a top level message and an entity(body part) inside of a multipart entity.
setContentType
function setContentType(string mediaType) returns InvalidContentTypeError?Sets the content-type to the entity.
mime:InvalidContentTypeError? contentType = mimeEntity.setContentType("application/json");
Parameters
- mediaType string - Content type, which needs to be set to the entity
Return Type
- InvalidContentTypeError? -
()if successful or else anmime:InvalidContentTypeErrorin case of invalid media-type
getContentType
function getContentType() returns stringGets the content type of the entity.
string contentType = mimeEntity.getContentType();
Return Type
- string - Content type as a
string
setContentId
function setContentId(string contentId)Sets the content ID of the entity.
mimeEntity.setContentId("test-id");
Parameters
- contentId string - Content ID, which needs to be set to the entity
getContentId
function getContentId() returns stringGets the content ID of the entity.
string contentId = mimeEntity.getContentId();
Return Type
- string - Content ID as a
string
setContentLength
function setContentLength(int contentLength)Sets the content length of the entity.
mimeEntity.setContentLength(45555);
Parameters
- contentLength int - Content length, which needs to be set to the entity
getContentLength
Gets the content length of the entity.
int|error contentLength = mimeEntity.getContentLength();
setContentDisposition
function setContentDisposition(ContentDisposition contentDisposition)Sets the content disposition of the entity.
mimeEntity.setContentDisposition(contentDisposition);
Parameters
- contentDisposition ContentDisposition - Content disposition, which needs to be set to the entity
getContentDisposition
function getContentDisposition() returns ContentDispositionGets the content disposition of the entity.
mime:ContentDisposition contentDisposition = mimeEntity.getContentDisposition();
Return Type
- ContentDisposition - A
ContentDispositionobject
setBody
Sets the body of the entity with the given content. Note that any string value is set as text/plain. To send a
JSON-compatible string, set the content-type header to application/json or use the setJsonPayload method instead.
mimeEntity.setBody("body string");
Parameters
setFileAsEntityBody
Sets the entity body with a given file. This method overrides any existing content-type headers
with the default content-type, which is application/octet-stream. This default value
can be overridden by passing the content type as an optional parameter.
mimeEntity.setFileAsEntityBody("<file path>");
Parameters
- filePath string - Path of the file
- contentType string (default "application/octet-stream") - Content type to be used with the payload. This is an optional parameter.
The default value is
application/octet-stream
setJson
function setJson(json jsonContent, string contentType)Sets the entity body with the given json content. This method overrides any existing content-type headers
with the default content-type, which is application/json. This default value can be overridden
by passing the content type as an optional parameter.
mimeEntity.setJson({ "Hello": "World" });
Parameters
- jsonContent json - JSON content, which needs to be set to the entity
- contentType string (default "application/json") - Content type to be used with the payload. This is an optional parameter.
The default value is
application/json
getJson
function getJson() returns json|ParserErrorExtracts the JSON body from the entity.
json|mime:ParserError result = entity.getJson();
Return Type
- json|ParserError -
jsondata extracted from the entity body or else anmime:ParserErrorif the entity body is not a JSON
setXml
Sets the entity body with the given XML content. This method overrides any existing content-type headers
with the default content-type, which is application/xml. This default value can be overridden
by passing the content-type as an optional parameter.
mimeEntity.setXml(xml `<hello> world </hello>`);
Parameters
- xmlContent xml - XML content, which needs to be set to the entity
- contentType string (default "application/xml") - Content type to be used with the payload. This is an optional parameter.
The default value is
application/xml
getXml
function getXml() returns xml|ParserErrorExtracts the xml body from the entity.
xml|mime:ParserError result = entity.getXml();
Return Type
- xml|ParserError -
xmldata extracted from the entity body or else anmime:ParserErrorif the entity body is not an XML
setText
Sets the entity body with the given text content. This method overrides any existing content-type headers
with the default content-type, which is text/plain. This default value can be overridden
by passing the content type as an optional parameter.
mimeEntity.setText("Hello World");
Parameters
- textContent string - Text content, which needs to be set to the entity
- contentType string (default "text/plain") - Content type to be used with the payload. This is an optional parameter.
The default value is
text/plain
getText
function getText() returns string|ParserErrorExtracts the text body from the entity. If the entity body is not text compatible, an error is returned.
string|mime:ParserError result = entity.getText();
Return Type
- string|ParserError -
stringdata extracted from the the entity body or else anmime:ParserErrorif the entity body is not text compatible
setByteArray
function setByteArray(byte[] blobContent, string contentType)Sets the entity body with the given byte[] content. This method overrides any existing content-type headers
with the default content-type, which is application/octet-stream. This default value
can be overridden by passing the content type as an optional parameter.
entity.setByteArray(content.toBytes());
Parameters
- blobContent byte[] -
byte[]content that needs to be set to the entity
- contentType string (default "application/octet-stream") - Content type to be used with the payload. This is an optional parameter.
The default value is
application/octet-stream
getByteArray
function getByteArray() returns byte[]|ParserErrorGets the entity body as a byte[] from a given entity. If the entity size is considerably large, consider
using the Entity.getByteStream() method instead.
byte[]|mime:ParserError result = entity.getByteArray();
Return Type
- byte[]|ParserError -
byte[]data extracted from the the entity body or else amime:ParserErrorin case of errors
setByteStream
Sets the entity body with the given byte stream content. This method overrides any existing content-type headers
with the default content-type, which is application/octet-stream. This default value
can be overridden by passing the content-type as an optional parameter.
entity.setByteStream(byteStream);
Parameters
- contentType string (default "application/octet-stream") - Content-type to be used with the payload. This is an optional parameter.
The
application/octet-streamis the default value
getByteStream
function getByteStream(int arraySize) returns stream<byte[], Error?>|ParserErrorGets the entity body as a stream of byte[] from a given entity.
stream<byte[], io:Error?>|mime:ParserError str = entity.getByteStream();
Parameters
- arraySize int (default 8192) - A defaultable parameter to state the size of the byte array. The default size is 8KB
Return Type
- stream<byte[], Error?>|ParserError - A byte stream from which the payload can be read or
mime:ParserErrorin case of errors
getBodyParts
function getBodyParts() returns Entity[]|ParserErrorGets the body parts from a given entity.
mime:Entity[]|mime:ParserError result = multipartEntity.getBodyParts();
Return Type
- Entity[]|ParserError - An array of body parts(
Entity[]) extracted from the entity body or else amime:ParserErrorif the entity body is not a set of the body parts
getBodyPartsAsStream
function getBodyPartsAsStream(int arraySize) returns stream<byte[], Error?>|ParserErrorGets the body parts as a byte stream from a given entity.
stream<byte[], io:Error?>|mime:ParserError str = multipartEntity.getBodyPartsAsStream();
Parameters
- arraySize int (default 8192) - A defaultable paramerter to state the size of the byte array. Default size is 8KB
Return Type
- stream<byte[], Error?>|ParserError - Body parts as a byte stream
setBodyParts
Sets the body parts to the entity. This method overrides any existing content-type headers
with the default multipart/form-data content-type. The default multipart/form-data value can be overridden
by passing the content type as an optional parameter.
multipartEntity.setBodyParts(bodyParts, contentType);
Parameters
- bodyParts Entity[] - Body parts, which need to be set to the entity
- contentType string (default "multipart/form-data") - Content-type to be used with the payload. This is an optional parameter.
The default value is
multipart/form-data.
getHeader
function getHeader(string headerName) returns string|HeaderNotFoundErrorGets the header value associated with the given header name.
string|mime:HeaderNotFoundError headerName = mimeEntity.getHeader(mime:CONTENT_LENGTH);
Parameters
- headerName string - Header name
Return Type
- string|HeaderNotFoundError - Header value associated with the given header name as a
string. If multiple header values are present, then the first value is returned. TheHeaderNotFoundErroris returned if the header is not found
getHeaders
function getHeaders(string headerName) returns string[]|HeaderNotFoundErrorGets all the header values associated with the given header name.
string[]|mime:HeaderNotFoundError headerNames = mimeEntity.getHeaders(mime:CONTENT_TYPE);
Parameters
- headerName string - Header name
Return Type
- string[]|HeaderNotFoundError - All the header values associated with the given header name as a
string[]or theHeaderNotFoundErrorif the header is not found
getHeaderNames
function getHeaderNames() returns string[]Gets all the header names.
string[] headerNames = mimeEntity.getHeaderNames();
Return Type
- string[] - All header names as a
string[]
addHeader
Adds the given header value against the given header. Panic if an illegal header is passed.
mimeEntity.addHeader("custom-header", "header-value");
setHeader
Sets the given header value against the existing header. If a header already exists, its value is replaced with the given header value. Panic if an illegal header is passed.
mimeEntity.setHeader("custom-header", "header-value");
removeHeader
function removeHeader(string headerName)Removes the given header from the entity.
mimeEntity.removeHeader("custom-header");
Parameters
- headerName string - Header name
removeAllHeaders
function removeAllHeaders()Removes all headers associated with the entity.
mimeEntity.removeAllHeaders();
hasHeader
Checks whether the requested header key exists in the header map.
boolean res = mimeEntity.hasHeader("custom-header");
Parameters
- headerName string - Header name
Return Type
- boolean -
trueif the specified header key exists
mime: MediaType
Describes the nature of the data in the body of a MIME entity.
getBaseType
function getBaseType() returns stringGets the “primaryType/subtype+suffix” combination in a string format.
string baseType = mediaType.getBaseType();
Return Type
- string - Base type as a
stringfrom theMediaTypestruct
toString
function toString() returns stringConverts the media type to a string, which is suitable to be used as the value of a corresponding HTTP header.
string mediaTypeString = mediaType.toString();
Return Type
- string - Content type with parameters as a
string
Fields
- primaryType string(default "") - Declares the general type of data
- subType string(default "") - A specific format of the primary-type data
- suffix string(default "") - Identifies the semantics of a specific media type
Constants
mime: APPLICATION_FORM_URLENCODED
Represents the application/x-www-form-urlencoded media type.
mime: APPLICATION_JSON
Represents the application/json media type.
mime: APPLICATION_OCTET_STREAM
Represents the application/octet-stream media type.
mime: APPLICATION_PDF
Represents the application/pdf media type.
mime: APPLICATION_SOAP_XML
Represents the application/soap+xml media type.
mime: APPLICATION_SVG_XML
Represents the application/svg+xml media type.
mime: APPLICATION_XHTML_XML
Represents the application/xhtml+xml media type.
mime: APPLICATION_XML
Represents the application/xml media type.
mime: BOUNDARY
Key name for boundary parameter in MediaType. This is needed for composite type media types.
mime: CHARSET
Key name for charset parameter in MediaType. This indicates the character set of the body text.
mime: CONTENT_DISPOSITION
Represents content-disposition header name.
mime: CONTENT_ID
Represents content-id header name.
mime: CONTENT_LENGTH
Represents content-length header name.
mime: CONTENT_TYPE
Represents content-type header name.
mime: DEFAULT_CHARSET
Default charset to be used with MIME encoding and decoding.
mime: IMAGE_GIF
Represents the image/gif media type.
mime: IMAGE_JPEG
Represents the image/jpeg media type.
mime: IMAGE_PNG
Represents the image/png media type.
mime: MULTIPART_ALTERNATIVE
Represents the multipart/alternative media type.
mime: MULTIPART_FORM_DATA
Represents the multipart/form-data media type.
mime: MULTIPART_MIXED
Represents the multipart/mixed media type.
mime: MULTIPART_PARALLEL
Represents the multipart/parallel media type.
mime: MULTIPART_RELATED
Represents the multipart/related media type.
mime: START
Key name for start parameter in MediaType. This determines which part in the multipart message contains the
payload.
mime: TEXT_HTML
Represents the text/html media type.
mime: TEXT_PLAIN
Represents the text/plain media type.
mime: TEXT_XML
Represents the text/xml media type.
mime: TYPE
Key name for type parameter in MediaType. This indicates the MIME media type of the root body part.
Errors
mime: DecodeError
Represents a DecodeError with the message and the cause.
mime: EncodeError
Represents an EncodeError with the message and the cause.
mime: Error
Defines the common error type for the module.
mime: GenericMimeError
Represents a GenericMimeError with the message and the cause.
mime: HeaderNotFoundError
Represents a HeaderNotFoundError error with the message and the cause.
mime: HeaderUnavailableError
Represents a HeaderUnavailableError with the message and the cause.
mime: IdleTimeoutTriggeredError
Represents an IdleTimeoutTriggeredError with the message and the cause.
mime: InvalidContentLengthError
Represents a InvalidContentLengthError error with the message and the cause.
mime: InvalidContentTypeError
Represents an InvalidContentTypeError with the message and the cause.
mime: InvalidHeaderOperationError
Represents a InvalidHeaderOperationError error with the message and the cause.
mime: InvalidHeaderParamError
Represents a InvalidHeaderParamError error with the message and the cause.
mime: InvalidHeaderValueError
Represents a InvalidHeaderValueError error with the message and the cause.
mime: NoContentError
Represents a NoContentError with the message and the cause.
mime: ParserError
Represents a ParserError with the message and the cause.
mime: SerializationError
Represents a SerializationError error with the message and the cause.
mime: SetHeaderError
Represents a SetHeaderError with the message and the cause.