mn create-app example.micronaut.micronautguide \
--features=yaml,object-storage-oracle-cloud,graalvm \
--build=maven \
--lang=java \
--test=junit
Use the Micronaut Object Storage API to store files in Oracle Cloud Infrastructure (OCI) Object Storage
Learn how to upload and retrieve files from Oracle Cloud Infrastructure (OCI) Object Storage using the Micronaut Object Storage API
Authors: Álvaro Sánchez-Mariscal
Micronaut Version: 4.6.1
1. Getting Started
In this guide, we will create a Micronaut application written in Java.
It will be a microservice to store, retrieve and delete profile pictures for users.
2. What you will need
To complete this guide, you will need the following:
-
Some time on your hands
-
A decent text editor or IDE (e.g. IntelliJ IDEA)
-
JDK 17 or greater installed with
JAVA_HOME
configured appropriately
-
An Oracle Cloud account (create a free trial account at signup.oraclecloud.com)
-
Oracle Cloud CLI installed with local access to Oracle Cloud configured by running
oci setup config
Some of the following commands use jq
jq is a lightweight and flexible command-line JSON processor
3. Solution
We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.
-
Download and unzip the source
4. Writing the Application
Create an application using the Micronaut Command Line Interface or with Micronaut Launch.
If you don’t specify the --build argument, Gradle is used as the build tool. If you don’t specify the --lang argument, Java is used as the language.If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.
|
The previous command creates a Micronaut application with the default package example.micronaut
in a directory named micronautguide
.
If you use Micronaut Launch, select Micronaut Application as application type and add yaml
, object-storage-oracle-cloud
, and graalvm
features.
If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features and apply those changes to your application. |
5. Create a bucket
5.1. Compartment OCID
Find the OCID of the compartment where we’ll be deploying. Run this to list all the compartments in your root compartment:
oci iam compartment list
and find the compartment by the name or description in the JSON output. It should look like this:
{
"compartment-id": "ocid1.tenancy.oc1..aaaaaaaaud4g4e5ovjaw...",
"defined-tags": {},
"description": "Micronaut guides",
"freeform-tags": {},
"id": "ocid1.compartment.oc1..aaaaaaaarkh3s2wcxbbm...",
"inactive-status": null,
"is-accessible": null,
"lifecycle-state": "ACTIVE",
"name": "micronaut-guides",
"time-created": "2021-05-02T23:54:28.392000+00:00"
}
Use the OCID from the id
property; the compartment-id
property is the parent compartment.
For convenience, save the compartment OCID as an environment variable. For Linux or Mac, run
export C=ocid1.compartment.oc1..aaaaaaaarkh3s2wcxbbm...
or for Windows, if using cmd
run
set C=ocid1.compartment.oc1..aaaaaaaarkh3s2wcxbbm...
and if using PowerShell run
$C = "ocid1.compartment.oc1..aaaaaaaarkh3s2wcxbbm..."
In the examples below we use Linux/Mac syntax for environment variables, e.g. -c $C . If you use Windows cmd , change those to -c %C% (but no change needed if using PowerShell)
|
5.2. Use the CLI to create the bucket
oci os bucket create --compartment-id $C --name micronaut-guide-object-storage
We can also use the CLI to get the Object Storage namespace:
export OCI_NS=$(oci os ns get | jq -r '.data')
Then, configure the bucket name and namespace in application.yml
:
micronaut:
object-storage:
oracle-cloud:
default:
bucket: micronaut-guide-object-storage
namespace: ${OCI_NS}
6. Controller API
Let’s define an interface with the endpoints of the profile pictures microservice:
public interface ProfilePicturesApi {
@Post(uri = "/{userId}", consumes = MediaType.MULTIPART_FORM_DATA) (1)
HttpResponse upload(CompletedFileUpload fileUpload, String userId, HttpRequest<?> request);
@Get("/{userId}") (2)
Optional<HttpResponse<StreamedFile>> download(String userId);
@Status(HttpStatus.NO_CONTENT) (3)
@Delete("/{userId}") (4)
void delete(String userId);
}
1 | The @Post annotation maps the method to an HTTP POST request. |
2 | The @Get annotation maps the method to an HTTP GET request. |
3 | You can return void in your controller’s method and specify the HTTP status code via the @Status annotation. |
4 | The @Delete annotation maps the delete method to an HTTP Delete request on /{userId} . |
And then, an implementation with the required dependencies:
@Controller(ProfilePicturesController.PREFIX) (1)
@ExecuteOn(TaskExecutors.BLOCKING) (2)
public class ProfilePicturesController implements ProfilePicturesApi {
static final String PREFIX = "/pictures";
private final OracleCloudStorageOperations objectStorage; (3)
private final HttpHostResolver httpHostResolver; (4)
public ProfilePicturesController(OracleCloudStorageOperations objectStorage, HttpHostResolver httpHostResolver) {
this.objectStorage = objectStorage;
this.httpHostResolver = httpHostResolver;
}
}
1 | The class is defined as a controller with the @Controller annotation mapped to the path /pictures . |
2 | It is critical that any blocking I/O operations (such as fetching the data from the database) are offloaded to a separate thread pool that does not block the Event loop. |
3 | OracleCloudStorageOperations is the cloud-specific interface for using object storage. |
4 | HttpHostResolver allows you to resolve the host for an HTTP |
6.1. Upload endpoint
Implement the upload endpoint by receiving the file from the HTTP client via CompletedFileUpload
, and the userId
path
parameter. Upload it to Oracle Cloud using
OracleCloudStorageOperations,
and then return its ETag
in an HTTP response header to the client:
@Override
public HttpResponse<?> upload(CompletedFileUpload fileUpload, String userId, HttpRequest<?> request) {
String key = buildKey(userId); (1)
UploadRequest objectStorageUpload = UploadRequest.fromCompletedFileUpload(fileUpload, key); (2)
UploadResponse<PutObjectResponse> response = objectStorage.upload(objectStorageUpload); (3)
return HttpResponse
.created(location(request, userId)) (4)
.header(HttpHeaders.ETAG, response.getETag()); (5)
}
private static String buildKey(String userId) {
return userId + ".jpg";
}
private URI location(HttpRequest<?> request, String userId) {
return UriBuilder.of(httpHostResolver.resolve(request))
.path(PREFIX)
.path(userId)
.build();
}
1 | The key represents the path under which the file will be stored. |
2 | You can use any of the UploadRequest static methods to build an upload request. |
3 | The upload operation returns an UploadResponse , which wraps the cloud-specific SDK response |
4 | We return the absolute URL of the resource in the Location header. |
5 | The response object contains some common properties for all cloud vendors, such as the ETag , that is sent in a header to the client. |
6.2. Download endpoint
For the download endpoint, simply retrieve the entry from the expected key, and transform it into an StreamedFile
:
@Override
public Optional<HttpResponse<StreamedFile>> download(String userId) {
String key = buildKey(userId);
return objectStorage.retrieve(key) (1)
.map(ProfilePicturesController::buildStreamedFile); (2)
}
private static HttpResponse<StreamedFile> buildStreamedFile(OracleCloudStorageEntry entry) {
GetObjectResponse nativeEntry = entry.getNativeEntry();
MediaType mediaType = MediaType.of(nativeEntry.getContentType());
StreamedFile file = new StreamedFile(entry.getInputStream(), mediaType).attach(entry.getKey());
MutableHttpResponse<Object> httpResponse = HttpResponse.ok()
.header(HttpHeaders.ETAG, nativeEntry.getETag()); (3)
file.process(httpResponse);
return httpResponse.body(file);
}
1 | The retrieve operation returns an ObjectStorageEntry , in this case an
OracleCloudStorageEntry,
which allows accessing the Oracle Cloud-specific
GetObjectResponse |
2 | We transform the OracleCloudStorageEntry into an HttpResponse<StreamedFile> . |
3 | The response contains not only the file, but also an ETag header. |
The HTTP client could have used the ETag from the upload operation and send it in a If-None-Match header in the
download request to implement caching,
which then would have been to be implemented in the download endpoint. But this is beyond the scope of this guide.
|
6.3. Delete endpoint
For the delete endpoint, all we have to do is invoke the delete
method with the expected key:
@Override
public void delete(String userId) {
String key = buildKey(userId);
objectStorage.delete(key);
}
7. Running the Application
To run the application, use the ./mvnw mn:run
command, which starts the application on port 8080.
8. Generate a Micronaut Application Native Executable with GraalVM
We will use GraalVM, the polyglot embeddable virtual machine, to generate a native executable of our Micronaut application.
Compiling native executables ahead of time with GraalVM improves startup time and reduces the memory footprint of JVM-based applications.
Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.
|
8.1. GraalVM installation
sdk install java 17.0.8-graal
sdk use java 17.0.8-graal
For installation on Windows, or for manual installation on Linux or Mac, see the GraalVM Getting Started documentation.
The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.
Alternatively, you can use the GraalVM Community Edition:
sdk install java 17.0.8-graalce
sdk use java 17.0.8-graalce
8.2. Native executable generation
To generate a native executable using Maven, run:
./mvnw package -Dpackaging=native-image
The native executable is created in the target
directory and can be run with target/micronautguide
.
9. Testing
Test the application from the command line.
9.1. Uploading a profile picture
If you want to upload a file larger than 1MB, you need to configure: src/main/resources/application.yml
|
Assuming you have locally a profile picture in a profile.jpg
file, you can send it to your application with:
$ curl -i -F 'fileUpload=@profile.jpg' http://localhost:8080/pictures/alvaro
HTTP/1.1 201 Created
location: http://localhost:8080/pictures/alvaro
ETag: "617cb82e296e153c29b34cccf7af0908"
date: Wed, 14 Sep 2022 12:50:30 GMT
connection: keep-alive
transfer-encoding: chunked
Note the Location
and ETag
headers.
Use the oci
CLI to verify that the file has been uploaded to an Oracle Cloud bucket:
oci os object list --bucket-name micronaut-guide-object-storage
9.2. Download a profile picture
curl http://localhost:8080/pictures/alvaro -O -J
The file will be saved as alvaro.jpg
since our download endpoint includes a Content-Disposition: attachment
header.
Open it to check that it is actually the same image as profile.jpg
.
9.3. Delete a profile picture
curl -X DELETE http://localhost:8080/pictures/alvaro
Then, check that the file has actually been deleted:
oci os object list --bucket-name micronaut-guide-object-storage
9.4. Cleanup
Remove the bucket from Oracle Cloud to not leave stale resources:
oci os bucket delete --bucket-name micronaut-guide-object-storage
10. Next Steps
-
Read more about Micronaut Object Storage.
11. License
All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…). |