Module mime
API
Declarations
![](https://bcentral-packageicons.azureedge.net/images/ballerina_mime_2.2.0.png)
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![](/images/permalink.svg)
base64Decode![](/images/permalink.svg)
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
string
if the given input is of type string, a decodedbyte[]
if the given input is of type byte[], a decodedio:ReadableByteChannel
if the given input is of type io:ReadableByteChannel or else amime:DecodeError
in case of errors
base64DecodeBlob![](/images/permalink.svg)
function base64DecodeBlob(byte[] valueToBeDecoded) returns byte[]|DecodeError
Decodes 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:DecodeError
record in case of errors
base64Encode![](/images/permalink.svg)
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
string
if the given input is of type string, an encodedbyte[]
if the given input is of type byte[], an encodedio:ReadableByteChannel
if the given input is of typeio:ReadableByteChannel
, or else amime:EncodeError
record in case of errors
base64EncodeBlob![](/images/permalink.svg)
function base64EncodeBlob(byte[] valueToBeEncoded) returns byte[]|EncodeError
Encodes 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:EncodeError
record in case of errors
getContentDispositionObject![](/images/permalink.svg)
function getContentDispositionObject(string contentDisposition) returns ContentDisposition
Given 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
ContentDisposition
object
getMediaType![](/images/permalink.svg)
function getMediaType(string contentType) returns MediaType|InvalidContentTypeError
Gets 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 -
MediaType
object or else amime:InvalidContentTypeError
in case of an invalid content-type
Classes![](/images/permalink.svg)
mime: ContentDisposition![](/images/permalink.svg)
Represents values in Content-Disposition
header.
toString![](/images/permalink.svg)
function toString() returns string
Converts 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
string
representation of theContentDisposition
object
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![](/images/permalink.svg)
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![](/images/permalink.svg)
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:InvalidContentTypeError
in case of invalid media-type
getContentType![](/images/permalink.svg)
function getContentType() returns string
Gets the content type of the entity.
string contentType = mimeEntity.getContentType();
Return Type
- string - Content type as a
string
setContentId![](/images/permalink.svg)
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![](/images/permalink.svg)
function getContentId() returns string
Gets the content ID of the entity.
string contentId = mimeEntity.getContentId();
Return Type
- string - Content ID as a
string
setContentLength![](/images/permalink.svg)
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![](/images/permalink.svg)
Gets the content length of the entity.
int|error contentLength = mimeEntity.getContentLength();
setContentDisposition![](/images/permalink.svg)
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![](/images/permalink.svg)
function getContentDisposition() returns ContentDisposition
Gets the content disposition of the entity.
mime:ContentDisposition contentDisposition = mimeEntity.getContentDisposition();
Return Type
- ContentDisposition - A
ContentDisposition
object
setBody![](/images/permalink.svg)
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![](/images/permalink.svg)
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![](/images/permalink.svg)
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![](/images/permalink.svg)
function getJson() returns json|ParserError
Extracts the JSON body from the entity.
json|mime:ParserError result = entity.getJson();
Return Type
- json|ParserError -
json
data extracted from the entity body or else anmime:ParserError
if the entity body is not a JSON
setXml![](/images/permalink.svg)
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![](/images/permalink.svg)
function getXml() returns xml|ParserError
Extracts the xml
body from the entity.
xml|mime:ParserError result = entity.getXml();
Return Type
- xml|ParserError -
xml
data extracted from the entity body or else anmime:ParserError
if the entity body is not an XML
setText![](/images/permalink.svg)
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![](/images/permalink.svg)
function getText() returns string|ParserError
Extracts 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 -
string
data extracted from the the entity body or else anmime:ParserError
if the entity body is not text compatible
setByteArray![](/images/permalink.svg)
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![](/images/permalink.svg)
function getByteArray() returns byte[]|ParserError
Gets 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:ParserError
in case of errors
setByteStream![](/images/permalink.svg)
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-stream
is the default value
getByteStream![](/images/permalink.svg)
function getByteStream(int arraySize) returns stream<byte[], Error?>|ParserError
Gets 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:ParserError
in case of errors
getBodyParts![](/images/permalink.svg)
function getBodyParts() returns Entity[]|ParserError
Gets 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:ParserError
if the entity body is not a set of the body parts
getBodyPartsAsStream![](/images/permalink.svg)
function getBodyPartsAsStream(int arraySize) returns stream<byte[], Error?>|ParserError
Gets 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![](/images/permalink.svg)
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![](/images/permalink.svg)
function getHeader(string headerName) returns string|HeaderNotFoundError
Gets 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. TheHeaderNotFoundError
is returned if the header is not found
getHeaders![](/images/permalink.svg)
function getHeaders(string headerName) returns string[]|HeaderNotFoundError
Gets 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 theHeaderNotFoundError
if the header is not found
getHeaderNames![](/images/permalink.svg)
function getHeaderNames() returns string[]
Gets all the header names.
string[] headerNames = mimeEntity.getHeaderNames();
Return Type
- string[] - All header names as a
string[]
addHeader![](/images/permalink.svg)
Adds the given header value against the given header. Panic if an illegal header is passed.
mimeEntity.addHeader("custom-header", "header-value");
setHeader![](/images/permalink.svg)
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![](/images/permalink.svg)
function removeHeader(string headerName)
Removes the given header from the entity.
mimeEntity.removeHeader("custom-header");
Parameters
- headerName string - Header name
removeAllHeaders![](/images/permalink.svg)
function removeAllHeaders()
Removes all headers associated with the entity.
mimeEntity.removeAllHeaders();
hasHeader![](/images/permalink.svg)
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 -
true
if the specified header key exists
mime: MediaType![](/images/permalink.svg)
Describes the nature of the data in the body of a MIME entity.
getBaseType![](/images/permalink.svg)
function getBaseType() returns string
Gets the “primaryType/subtype+suffix” combination in a string
format.
string baseType = mediaType.getBaseType();
Return Type
- string - Base type as a
string
from theMediaType
struct
toString![](/images/permalink.svg)
function toString() returns string
Converts 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![](/images/permalink.svg)
mime: APPLICATION_FORM_URLENCODED![](/images/permalink.svg)
Represents the application/x-www-form-urlencoded
media type.
mime: APPLICATION_JSON![](/images/permalink.svg)
Represents the application/json
media type.
mime: APPLICATION_OCTET_STREAM![](/images/permalink.svg)
Represents the application/octet-stream
media type.
mime: APPLICATION_PDF![](/images/permalink.svg)
Represents the application/pdf
media type.
mime: APPLICATION_SOAP_XML![](/images/permalink.svg)
Represents the application/soap+xml
media type.
mime: APPLICATION_SVG_XML![](/images/permalink.svg)
Represents the application/svg+xml
media type.
mime: APPLICATION_XHTML_XML![](/images/permalink.svg)
Represents the application/xhtml+xml
media type.
mime: APPLICATION_XML![](/images/permalink.svg)
Represents the application/xml
media type.
mime: BOUNDARY![](/images/permalink.svg)
Key name for boundary
parameter in MediaType. This is needed for composite type media types.
mime: CHARSET![](/images/permalink.svg)
Key name for charset
parameter in MediaType. This indicates the character set of the body text.
mime: CONTENT_DISPOSITION![](/images/permalink.svg)
Represents content-disposition
header name.
mime: CONTENT_ID![](/images/permalink.svg)
Represents content-id
header name.
mime: CONTENT_LENGTH![](/images/permalink.svg)
Represents content-length
header name.
mime: CONTENT_TYPE![](/images/permalink.svg)
Represents content-type
header name.
mime: DEFAULT_CHARSET![](/images/permalink.svg)
Default charset to be used with MIME encoding and decoding.
mime: IMAGE_GIF![](/images/permalink.svg)
Represents the image/gif
media type.
mime: IMAGE_JPEG![](/images/permalink.svg)
Represents the image/jpeg
media type.
mime: IMAGE_PNG![](/images/permalink.svg)
Represents the image/png
media type.
mime: MULTIPART_ALTERNATIVE![](/images/permalink.svg)
Represents the multipart/alternative
media type.
mime: MULTIPART_FORM_DATA![](/images/permalink.svg)
Represents the multipart/form-data
media type.
mime: MULTIPART_MIXED![](/images/permalink.svg)
Represents the multipart/mixed
media type.
mime: MULTIPART_PARALLEL![](/images/permalink.svg)
Represents the multipart/parallel
media type.
mime: MULTIPART_RELATED![](/images/permalink.svg)
Represents the multipart/related
media type.
mime: START![](/images/permalink.svg)
Key name for start
parameter in MediaType. This determines which part in the multipart message contains the
payload.
mime: TEXT_HTML![](/images/permalink.svg)
Represents the text/html
media type.
mime: TEXT_PLAIN![](/images/permalink.svg)
Represents the text/plain
media type.
mime: TEXT_XML![](/images/permalink.svg)
Represents the text/xml
media type.
mime: TYPE![](/images/permalink.svg)
Key name for type
parameter in MediaType. This indicates the MIME media type of the root
body part.
Errors![](/images/permalink.svg)
mime: DecodeError![](/images/permalink.svg)
Represents a DecodeError
with the message and the cause.
mime: EncodeError![](/images/permalink.svg)
Represents an EncodeError
with the message and the cause.
mime: Error![](/images/permalink.svg)
Defines the common error type for the module.
mime: GenericMimeError![](/images/permalink.svg)
Represents a GenericMimeError
with the message and the cause.
mime: HeaderNotFoundError![](/images/permalink.svg)
Represents a HeaderNotFoundError
error with the message and the cause.
mime: HeaderUnavailableError![](/images/permalink.svg)
Represents a HeaderUnavailableError
with the message and the cause.
mime: IdleTimeoutTriggeredError![](/images/permalink.svg)
Represents an IdleTimeoutTriggeredError
with the message and the cause.
mime: InvalidContentLengthError![](/images/permalink.svg)
Represents a InvalidContentLengthError
error with the message and the cause.
mime: InvalidContentTypeError![](/images/permalink.svg)
Represents an InvalidContentTypeError
with the message and the cause.
mime: InvalidHeaderOperationError![](/images/permalink.svg)
Represents a InvalidHeaderOperationError
error with the message and the cause.
mime: InvalidHeaderParamError![](/images/permalink.svg)
Represents a InvalidHeaderParamError
error with the message and the cause.
mime: InvalidHeaderValueError![](/images/permalink.svg)
Represents a InvalidHeaderValueError
error with the message and the cause.
mime: NoContentError![](/images/permalink.svg)
Represents a NoContentError
with the message and the cause.
mime: ParserError![](/images/permalink.svg)
Represents a ParserError
with the message and the cause.
mime: SerializationError![](/images/permalink.svg)
Represents a SerializationError
error with the message and the cause.
mime: SetHeaderError![](/images/permalink.svg)
Represents a SetHeaderError
with the message and the cause.
Import
import ballerina/mime;
Metadata
Released date: over 2 years ago
Version: 2.2.0
License: Apache-2.0
Compatibility
Platform: java11
Ballerina version: 2201.0.0
Pull count
Total: 474140
Current verison: 995
Weekly downloads
Keywords
mime
multipart
entity
Contributors
Dependencies