Module mime
API
Declarations
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.
Handle 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
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
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
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
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
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
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
mime: ContentDisposition
Represents values in Content-Disposition
header.
toString
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
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:InvalidContentTypeError
in case of invalid media-type
getContentType
function getContentType() returns string
Gets 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 string
Gets 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 ContentDisposition
Gets the content disposition of the entity.
mime:ContentDisposition contentDisposition = mimeEntity.getContentDisposition();
Return Type
- ContentDisposition - A
ContentDisposition
object
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|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
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|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
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|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
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[]|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
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
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
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
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
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|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
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
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 -
true
if the specified header key exists
mime: MediaType
Describes the nature of the data in the body of a MIME entity.
getBaseType
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
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
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_EVENT_STREAM
Represents the text/event-stream
media type.
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.
Import
import ballerina/mime;
Metadata
Released date: 3 months ago
Version: 2.10.0
License: Apache-2.0
Compatibility
Platform: java17
Ballerina version: 2201.10.0
GraalVM compatible: Yes
Pull count
Total: 501011
Current verison: 4670
Weekly downloads
Keywords
mime
multipart
entity
Contributors
Dependencies