Overview
The LoopBack Android SDK provides classes that enable apps to upload, store and retrieve files from a LoopBack application using the LoopBack Storage service. See Storage service for information on how to create the corresponding LoopBack server application.
The relevant classes are:
ContainerRepository
provides methods for creating and querying containers.FileRepository
provides methods for querying existing files and uploading new files.Container
represents an instance of a server-side container and provides shortcuts for some of theFileRepository
methods.File
represents an instance of a server-side file, exposes additional metadata like the public URL and provides methods for downloading the file to the Android device.
Working with containers
Creating a new container
ContainerRepository containerRepo = adapter.createRepository(ContainerRepository.class); containerRepo.create("container-name", new ObjectCallback<Container>() { @Override public void onSuccess(Container container) { // container was created } @Override public void onError(Throwable error) { // request failed } });
Finding a container by name
containerRepo.get("container-name", new ObjectCallback<Container>() { @Override public void onSuccess(Container container) { // container was found } @Override public void onError(Throwable error) { // request failed } });
Listing all containers
containerRepo.getAll(new ListCallback<Container>() { @Override public void onSuccess(List<Container> containers) { // "containers" hold all items found } @Override public void onError(Throwable error) { // request failed } });
Working with files
All files live inside a container. The examples below assume you have a container
object acquired by one of the methods described in the previous section.
Listing existing files
// same as container.getFileRepository().getAll(callback) container.getAllFiles(new ListCallback<File>() { @Override public void onSuccess(List<File> files) { // process files } @Override public void onError(Throwable error) { // request failed } });
Finding a file by name
// same as container.getFileRepository.get("file-name", callback) container.getFile("file-name", new ObjectCallback<File>() { @Override public void onSuccess(File file) { // use the file } @Override public void onError(Throwable error) { // request failed } });
Uploading a local file
java.io.File localFile = new java.io.File("path/to/file.txt"); // same as container.getFileRepository.upload(localFile, callback) container.upload(localFile, new ObjectCallback<File>() { @Override public void onSuccess(File remoteFile) { // localFile was uploaded // call `remoteFile.getUrl()` to get its URL } @Override public void onError(Throwable error) { // upload failed } });
Uploading in-memory content
String fileName = "hello.txt"; byte[] content = "Hello world".getBytes("UTF-8"); String contentType = "text/plain"; // same as container.getFileRepository().upload(fileName,...); container.upload(fileName, content, contentType, new ObjectCallback<File>() { @Override public void onSuccess(File remoteFile) { // file was uploaded } @Override public void onError(Throwable error) { // upload failed } } );
Downloading to a local file
File remoteFile; // obtained by one of the methods shown above java.io.File localFile = new java.io.File("path/to/file.txt"); remoteFile.download(localFile, new VoidCallback() { @Override public void onSuccess() { // localFile contains the content } @Override public void onError(Throwable error) { // download failed } });
Downloading to memory
File remoteFile; // obtained by one of the methods shown above remoteFile.download(new File.DownloadCallback() { @Override public void onSuccess(byte[] content, String contentType) { // downloaded } @Override public void onError(Throwable error) { // download failed } });
Removing a remote file
File remoteFile; // obtained by one of the methods shown above remoteFile.delete(new Void() { @Override public void onSuccess() { // the file was deleted } @Override public void onError(Throwable error) { // request failed } });
Example
For example, consider an application for submitting insurance claims. To submit a claim, one has to attach documents proving the validity of the claim, such as pictures of the damaged property.
The LoopBack server will track claims using a Claim
model. Supporting documents will be stored in a storage service. There will be one container for every claim record. The Android application will enable users to view documents attached to a claim and to attach more documents.
See Storage service for information on setting up the server application that uses the LoopBack storage service.
Creating a new claim
To avoid extra checks further down the line, the app will create the container when the user enters a new claim in the system as shown below:
ContainerRepository containerRepo = adapter.createRepository(ContainerRepository.class); containerRepo.create(claim.getId().toString(), new ObjectCallback<Container>() { @Override public void onSuccess(Container container) { // container was created, save it activity.setContainer(container); // and continue to the next activity } @Override public void onError(Throwable error) { // request failed, report an error } });
Displaying documents
To display a list of documents that are already uploaded, we need to fetch all files in the container associated with the current claim as follows:
activity.getContainer().getAllFiles(new ListCallback<File>() { @Override public void onSuccess(List<File> remoteFiles) { // populate the UI with documents } @Override public void onError(Throwable error) { // request failed, report an error } }
To display the document, the app downloads its content and builds a Bitmap
object that it can display on the Android device:
void displayDocument(File remoteFile) { file.download(new File.DownloadCallback() { @Override public void onSuccess(byte[] content, String contentType) { Bitmap image = BitmapFactory.decodeByteArray(content, 0, content.length); // display the image in the GUI } @Override public void onError(Throwable error) { // download failed, report an error } }); }
Attaching a new document
To keep this example simple, we will skip details on how to take pictures in Android (for information on this, see the Android Camera docs). Once the picture is taken, the app uploads it to the storage service and updates the list of all documents:
camera.takePicture( null, /* shutter callback */ null, /* raw callback */ null, /* postview callback */ new Camera.PictureCallback() { /* jpeg callback */ @Override void onPictureTaken(byte[] data, Camera camera) { // A real app would probably ask the user to provide a file name String fileName = UUID.randomUUID().toString() + ".jpg"; activity.getContainer().upload(fileName, data, "image/jpeg", new ObjectCallback<File>() { @Override public void onSuccess(File remoteFile) { // Update GUI - add remoteFile to the list of documents } @Override public void onError(Throwable error) { // upload failed } } ); } } );