Multipart File Upload Endpoint Generation

As of version 1.5, the Framework now allows Multipart endpoints for file upload to be generated using RAML in a similar way to the other endpoint generation.

The endpoint is specified in RAML and the framework will use that RAML to generate the multipart endpoint. When a request reaches that endpoint, the generated code will save the file into the database using the File-Service. The generated code will create a JsonEnvelope containing the newly stored file's id with the property name of the file part specified in RAML, and any rest path parameters.

Then a handler with an annotation matching the command name is invoked, passing it the new JsonEnvelope.

The Raml

/cases/{caseId}/casedocuments:
post:
  description: |
    Upload Case Documents
    ...
    (mapping):
      requestType: multipart/form-data
      name: staging.command.upload-case-documents
    ...
  body:
    multipart/form-data:
      formParameters:
        # This name is the name of the file part and, once the file is stored and 
        # we have an id for the file, will be used as the name of the field 
        # containing the file id in your JsonEnvelope
        caseFileId:  
          description: The id of the newly stored case document
          type: file # this is mandatory and must always be set to 'file'
  responses:
    202:
      description: Request accepted
    400:
      description: Bad Request
    500:
      description: Internal Server Error

This pretty much matches the RAML for other endpoint generation. It starts with the URL path (with any path parameters) and contains the mapping to your command name: in this case staging.command.upload-case-documents.

The requestType must always be multipart/form-data

Next is the body. This too must be multipart/form-data. Then the form parameters which must contain one form parameter who's name is the name used for the file part/field name in the JsonEnvelope. In this case the name is set to caseFileId

The type of the form parameter must be set to file. This is required by RAML to let it know we are dealing with a multipart endpoint here

filePartName/fieldName

The endpoint generation needs to link the file part name in the multipart request with a name for the fileId field in the resulting JsonEnvelope. It is very important therefore, to ensure that the form parameter name in the RAML and the filePart name in your rest client match. Failure to ensure they match will result in a BadRequestException and a HTTP 400 as a response.

Handler Class

In a similar way to the other endpoints, a handler class needs to be created:

@ServiceComponent(COMMAND_API)
public class CaseDocumentUploadCommandHandler {

    @Inject
    Sender sender;

    @Inject
    Enveloper enveloper;

    @Handles("staging.command.upload-case-documents")
    public void uploadFile(final JsonEnvelope command)  {
        
        // the JsonEnvelope will contain both path parameters and the id of the new file
        final JsonObject payload = command.payloadAsJsonObject();

        // path parameter from the url
        final String caseId = payload.getString("caseId");

        // the id of the newly stored file. The field name is specified in the RAML
        // and is the name of the file part
        final String caseFileId = payload.getString("caseFileId");

       // do any required logic...

       sender.send(jsonEnvelope);
    }
}