Module : mime
Module Overview
This module provides functions to encapsulate multiple body parts, such as attachments in a single message. The communication of such messages follow the MIME (Multipurpose Internet Mail Extensions) 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.
Modify and retrieve the data in an entity
The module provides functions to set and get an entity body from different kinds of message types, such as XML, text, JSON, blob, and body parts. Headers can be modified through functions such as addHeader()
, setHeader()
, removeHeader()
, etc.
Samples
Handle multipart request
The sample service given below handles a multipart request. It extracts the body content from each part, converts it to a string
, and sends a response.
import ballerina/http;
import ballerina/log;
import ballerina/mime;
@http:ServiceConfig {
basePath: "/test"
}
service test on new http:Listener(9090) {
@http:ResourceConfig {
methods: ["POST"],
path: "/multipleparts"
}
// The resource that handles multipart requests.
resource function multipartResource(http:Caller caller, http:Request request) {
http:Response response = new;
// Get the body parts from the request.
var bodyParts = request.getBodyParts();
if (bodyParts is mime:Entity[]) {
string content = "";
// Iterate through each body part and handle the content.
foreach var part in bodyParts {
content = content + " -- " + handleContent(part);
}
response.setPayload(<@untainted> content);
} else {
// If there is an error while getting the body parts, set the
// response code as 500 and set the error message as the
// response message.
response.statusCode = 500;
response.setPayload(<@untainted> bodyParts.reason());
}
var result = caller->respond(response);
if (result is error) {
log:printError("Error in responding", err = result);
}
}
}
// The function that handles the content based on the body part type.
function handleContent(mime:Entity bodyPart) returns @tainted string {
var mediaType = mime:getMediaType(bodyPart.getContentType());
if (mediaType is mime:MediaType) {
// Get the base type of the specific body part.
string baseType = mediaType.getBaseType();
// If the base type is ‘application/xml’ or ‘text/xml’, get the XML
// content from body part.
if (mime:APPLICATION_XML == baseType || mime:TEXT_XML == baseType) {
var payload = bodyPart.getXml();
if (payload is xml) {
return payload.getTextValue();
} else {
return "Error in parsing xml payload";
}
} else if (mime:APPLICATION_JSON == baseType) {
// If the base type is ‘application/json’, get the JSON content
// from body part.
var payload = bodyPart.getJson();
if (payload is json) {
return payload.toJsonString();
} else {
return "Error in parsing json payload";
}
}
} else {
return mediaType.reason();
}
return "";
}
The sample request that is sent to the above service is shown below.
curl -v -F "request={\"param1\": \"value1\"};type=application/json" -F "language=ballerina;type=text/plain" -F "upload=@/home/path-to-file/encode.txt;type=application/octet-stream" http://localhost:9090/test/multipleparts -H "Expect:"
Create a multipart request
Following code snippet creates a multipart request. It includes two body parts with application/json
and application/xml
content type.
// Create a JSON body part.
mime:Entity bodyPart1 = new;
// Set the JSON content.
bodyPart1.setJson({"bodyPart": "jsonPart"});
// Create another body part using an XML file.
mime:Entity bodyPart2 = new;
bodyPart2.setFileAsEntityBody("ballerina/mime/file.xml", contentType = mime:APPLICATION_XML);
//Create an array to hold all the body parts.
mime:Entity[] bodyParts = [bodyPart1, bodyPart2];
// Set the body parts to the outbound response.
http:Request outRequest = new;
// Set the content type as ‘multipart/mixed’ and set the body parts.
outRequest.setBodyParts(bodyParts, contentType = mime:MULTIPART_MIXED);
Detail | Holds the details of entity header and body related errors. |
ContentDisposition | Represents values in |
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. |
MediaType | Describes the nature of the data in the body of a MIME entity. |
base64Decode | Deprecated API. Decodes a given input with MIME specific Base64 encoding scheme. |
base64DecodeBlob | Deprecated API. Decodes a given byte[] with Base64 encoding scheme. |
base64Encode | Deprecated API. Encodes a given input with MIME specific Base64 encoding scheme. |
base64EncodeBlob | Deprecated API. Encodes a given byte[] with Base64 encoding scheme. |
getContentDispositionObject | Given the Content-Disposition as a string, gets the ContentDisposition object with it. |
getMediaType | Given the Content-Type in string, gets the MediaType object populated with it. |
prepareDecodingErrorWithDetail | Constructs a |
prepareEncodingErrorWithDetail | Constructs an |
LEADING | Header is placed before the payload of the request/response. |
TRAILING | Header is placed after the payload of the request/response. |
APPLICATION_OCTET_STREAM | Represent |
APPLICATION_JSON | Represent |
APPLICATION_XML | Represent |
APPLICATION_SVG_XML | Represent |
APPLICATION_XHTML_XML | Represent |
APPLICATION_SOAP_XML | Represent |
APPLICATION_FORM_URLENCODED | Represent |
APPLICATION_PDF | Represent |
IMAGE_JPEG | Represent |
IMAGE_GIF | Represent |
IMAGE_PNG | Represent |
MULTIPART_FORM_DATA | Represent |
MULTIPART_MIXED | Represent |
MULTIPART_ALTERNATIVE | Represent |
MULTIPART_RELATED | Represent |
MULTIPART_PARALLEL | Represent |
TEXT_PLAIN | Represent |
TEXT_HTML | Represent |
TEXT_XML | Represent |
ENCODE_ERROR | Identifies encoding errors. |
DECODE_ERROR | Identifies decoding errors. |
GENERIC_MIME_ERROR | Identifies generic errors related to MIME. |
SET_HEADER_FAILED | Identifies set header failures. |
READING_HEADER_FAILED | Identifies header parsing errors. |
PARSER_ERROR | Identifies entity body parsing errors. |
INVALID_CONTENT_TYPE | Identifies errors related to content-type header. |
HEADER_UNAVAILABLE | Identifies errors related to header unavailability. |
IDLE_TIMEOUT_TRIGGERED | Identifies errors related to read/write timeouts. |
NO_CONTENT_ERROR_CODE | |
BOUNDARY | Key name for |
START | Key name for |
TYPE | Key name for |
CHARSET | Key name for |
DEFAULT_CHARSET | Default charset to be used with MIME encoding and decoding. |
CONTENT_ID | Represents |
CONTENT_LENGTH | Represents |
CONTENT_TYPE | Represents |
CONTENT_DISPOSITION | Represents |
Error | Represents MIME related errors. |
HeaderPosition | Defines the position of the headers in the request/response.
|
DecodeError | Represents a |
EncodeError | Represents an |
GenericMimeError | Represents a |
HeaderUnavailableError | Represents a |
IdleTimeoutTriggeredError | Represents a |
InvalidContentTypeError | Represents an |
NoContentError | Represents a |
ParserError | Represents a |
ReadingHeaderFailed | Represents a |
SetHeaderError | Represents a |