Skip to content

FalconDB API¶

API¶

Base URL depends on the version of FalconDB:

FalconDB - Onteon: http://localhost:8021/_by_name/falcon-db-core-microservice/v1
FalconDB - standalone: http://localhost:${PORT}, where ${PORT} is defined in falcondb/envs file in -Dhttp-port system properties (by default http://localhost:7000/v1)

NOTE

In the following Swagger API http://localhost:8021/_by_name/falcon-db-core-microservice/v1 is set as base URL.

Examples¶

Dependencies used in the following Java examples

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.15.2</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>
<!-- Apache HttpComponents examples -->
<dependency>
    <groupId>org.apache.httpcomponents.client5</groupId>
    <artifactId>httpclient5</artifactId>
    <version>5.2.1</version>
</dependency>

Save file to FalconDB via stream¶

Using java.net.HttpURLConnection¶

public void saveFileAsStream(
        String falconDbUri,
        String fileKey,
        String fileName,
        String inputFilePath,
        String boundary) throws Exception {

    FileInputStream fileInputStream = null;
    OutputStream outputStream = null;
    HttpURLConnection httpURLConnection = null;

    try {
        URL url = new URL(falconDbUri + "/v1/saveBinaryFile");

        httpURLConnection = (HttpURLConnection) url.openConnection();
        httpURLConnection.setDoOutput(true);
        httpURLConnection.setRequestMethod("POST");
        httpURLConnection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
        httpURLConnection.setRequestProperty("key", fileKey);
        httpURLConnection.setRequestProperty("fileName", fileName);

        outputStream = httpURLConnection.getOutputStream();
        fileInputStream = new FileInputStream(inputFilePath);

        outputStream.write(("--" + boundary + "\n").getBytes());
        outputStream.write(("Content-Disposition: form-data; name=\"file\"; filename=\"file\"\n").getBytes());
        outputStream.write(("Content-Type: application/octet-stream\n\n").getBytes());

        byte[] buffer = new byte[8192];
        int bytesRead;
        while ((bytesRead = fileInputStream.read(buffer)) != -1) {
            outputStream.write(buffer, 0, bytesRead);
        }

        outputStream.write(("\n--" + boundary + "--\n").getBytes());
        outputStream.flush();
    } catch (Throwable th) {
        throw new Exception("error, while saving file as stream to FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(httpURLConnection)) {
            httpURLConnection.disconnect();
        }

        if (Objects.nonNull(fileInputStream)) {
            fileInputStream.close();
        }

        if (Objects.nonNull(outputStream)) {
            outputStream.close();
        }
    }
}

Using Apache HttpComponents¶

public void saveFileAsStream(
        String falconDbUri,
        String fileKey,
        String fileName,
        String inputFilePath) throws Exception {
    String url = falconDbUri + "/v1/saveBinaryFile";

    MultipartEntityBuilder multipartEntityBuilder = MultipartEntityBuilder.create();

    HttpPost httpPost = new HttpPost(url);
    httpPost.addHeader("key", fileKey);
    httpPost.addHeader("fileName", fileName);

    CloseableHttpClient client = null;
    FileInputStream fileInputStream = null;
    HttpEntity multipartHttpEntity = null;
    CloseableHttpResponse httpResponse = null;

    try {
        client = HttpClients.createDefault();
        fileInputStream = new FileInputStream(inputFilePath);

        multipartEntityBuilder.addBinaryBody("file", fileInputStream, ContentType.DEFAULT_BINARY, fileName);

        multipartHttpEntity = multipartEntityBuilder.build();
        httpPost.setEntity(multipartHttpEntity);

        httpResponse = client.execute(httpPost);
    } catch (Throwable th) {
        throw new Exception("error, while saving file as stream to FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(client)) {
            try {
                client.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(fileInputStream)) {
            try {
                fileInputStream.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(multipartHttpEntity)) {
            try {
                multipartHttpEntity.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(httpResponse)) {
            try {
                httpResponse.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }
    }
}

V2¶

public void saveFileAsStreamV2(
        String falconDbUri,
        String fileKey,
        String fileName,
        String inputFilePath) throws Exception {
    FileInputStream fileInputStream = null;
    OutputStream outputStream = null;
    InputStreamReader inputStreamReader = null;
    BufferedReader bufferedReader = null;

    try {

        URL url = new URL(falconDbUri + "/v2/saveBinaryFile");

        HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
        httpURLConnection.setDoOutput(true);
        httpURLConnection.setRequestMethod("POST");
        httpURLConnection.setRequestProperty("Content-Type", "application/octet-stream");
        httpURLConnection.setRequestProperty("key", fileKey);
        httpURLConnection.setRequestProperty("fileName", fileName);

        outputStream = httpURLConnection.getOutputStream();
        fileInputStream = new FileInputStream(inputFilePath);

        byte[] buffer = new byte[8192];
        int bytesRead;
        while ((bytesRead = fileInputStream.read(buffer)) != -1) {
            outputStream.write(buffer, 0, bytesRead);
        }
        outputStream.flush();

        String operationCode = httpURLConnection.getHeaderField("operation-code");
        inputStreamReader = new InputStreamReader(httpURLConnection.getInputStream());
        bufferedReader = new BufferedReader(inputStreamReader);
        String line;
        while ((line = bufferedReader.readLine()) != null) {
            System.out.println(line);
        }

    } catch (Throwable th) {
        throw new Exception("error, while saving file as stream to FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(fileInputStream)) {
            fileInputStream.close();
        }

        if (Objects.nonNull(outputStream)) {
            outputStream.close();
        }

        if (Objects.nonNull(inputStreamReader)) {
            inputStreamReader.close();
        }

        if (Objects.nonNull(bufferedReader)) {
            bufferedReader.close();
        }
    }
}

cURL¶

curl --location 'http://localhost:8020/_by_name/falcon-db-core-microservice/v1/saveBinaryFile' \
--header 'key: file-key' \
--header 'fileName: file' \
--form 'file=@"/path/to/file"'

Get file as stream¶

Using java.net.HttpURLConnection¶

public void getFileAsStream(
        String falconDbUri,
        String fileKey,
        String fileName,
        int chunkSize,
        String outputFilePath) throws Exception {
    URL url = new URL(falconDbUri
            + "/v1/getBinaryFile"
            + "?key=" + fileKey
            + "&file-name=" + fileName
            + "&chunk-size=" + chunkSize);

    HttpURLConnection httpURLConnection = null;
    InputStream inputStream = null;
    FileOutputStream fileOutputStream = null;

    try {
        fileOutputStream = new FileOutputStream(outputFilePath);

        httpURLConnection = (HttpURLConnection) url.openConnection();
        httpURLConnection.setDoOutput(true);
        httpURLConnection.setRequestMethod("GET");

        inputStream = httpURLConnection.getInputStream();
        byte[] chunk = new byte[chunkSize];
        int bytesRead;

        while ((bytesRead = inputStream.read(chunk)) != -1) {
            fileOutputStream.write(chunk, 0, bytesRead);
        }
    } catch (Throwable th) {
        throw new Exception("error, while getting file as stream from FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(inputStream)) {
            inputStream.close();
        }

        if (Objects.nonNull(httpURLConnection)) {
            httpURLConnection.disconnect();
        }

        if (Objects.nonNull(fileOutputStream)) {
            fileOutputStream.close();
        }
    }
}

Using Apache HttpComponents¶

public void getFileAsStream(
        String falconDbUri,
        String fileKey,
        String fileName,
        int chunkSize,
        String outputFilePath) throws Exception {
    String url = falconDbUri
            + "/v1/getBinaryFile"
            + "?key=" + fileKey
            + "&file-name=" + fileName
            + "&chunk-size=" + chunkSize;

    HttpGet httpGet = new HttpGet(url);
    File outputFile = new File(outputFilePath);

    CloseableHttpClient client = null;
    InputStream inputStream = null;
    FileOutputStream fileOutputStream = null;
    CloseableHttpResponse httpResponse = null;
    HttpEntity httpEntity = null;

    try {
        client = HttpClients.createDefault();
        httpResponse = client.execute(httpGet);
        httpEntity = httpResponse.getEntity();

        if (Objects.nonNull(httpEntity)) {
            inputStream = httpEntity.getContent();
            fileOutputStream = new FileOutputStream(outputFile);
            byte[] chunk = new byte[chunkSize];
            int bytesRead;

            while ((bytesRead = inputStream.read(chunk)) != -1) {
                fileOutputStream.write(chunk, 0, bytesRead);
            }
        } else {
            throw new Exception("http entity is null, while getting file as stream from FalconDB");
        }
    } catch (Throwable th) {
        throw new Exception("error, while getting file as stream from FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(client)) {
            try {
                client.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(fileOutputStream)) {
            try {
                fileOutputStream.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(inputStream)) {
            try {
                inputStream.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(httpEntity)) {
            try {
                httpEntity.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(httpResponse)) {
            try {
                httpResponse.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }
    }
}

cURL¶

curl -X GET 'http://localhost:7000/v1/getBinaryFile?file-name=test-file&key=file-key&chunk-size=16' -o output_file.txt

Save file to FalconDB as base64 chunks¶

Using java.net.HttpURLConnection¶

public void saveFileAsChunks(
        String falconDbUri,
        String fileKey,
        String fileName,
        int chunkSize,
        String inputFilePath,
        ObjectMapper objectMapper) throws Exception {

    HttpURLConnection httpURLConnection = null;
    OutputStream outputStream = null;
    FileInputStream fileInputStream = null;

    try {
        FileDTO fileDTO = new FileDTO();
        fileDTO.setFileName(fileName);
        fileDTO.setKey(fileKey);
        URL url = new URL(falconDbUri + "/v1/saveOrAppendFile");

        fileInputStream = new FileInputStream(inputFilePath);

        byte[] chunk = new byte[chunkSize];
        int bytesRead;

        while ((bytesRead = fileInputStream.read(chunk)) != -1) {
            String base64Encoded;
            if (bytesRead == chunkSize) {
                base64Encoded = Base64.getEncoder().encodeToString(chunk);
            } else {
                base64Encoded = Base64.getEncoder().encodeToString(Arrays.copyOf(chunk, bytesRead));
            }
            fileDTO.setBase64FileContent(base64Encoded);
            String fileDTOAsJson = objectMapper.writeValueAsString(fileDTO);
            byte[] fileDTOJsonAsBytes = fileDTOAsJson.getBytes();

            // send request
            httpURLConnection = (HttpURLConnection) url.openConnection();
            httpURLConnection.setDoOutput(true);
            httpURLConnection.setRequestMethod("PUT");
            httpURLConnection.setRequestProperty("Content-Type", "application/json");
            outputStream = httpURLConnection.getOutputStream();
            outputStream.write(fileDTOJsonAsBytes, 0, fileDTOJsonAsBytes.length);
            outputStream.flush();

            outputStream.close();
            httpURLConnection.disconnect();
        }

    } catch (Throwable th) {
        throw new Exception("error, while saving file as chunks to FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(httpURLConnection)) {
            httpURLConnection.disconnect();
        }

        if (Objects.nonNull(fileInputStream)) {
            fileInputStream.close();
        }

        if (Objects.nonNull(outputStream)) {
            outputStream.close();
        }
    }
}

Using Apache HttpComponents¶

public void saveFileAsChunks(
        String falconDbUri,
        String fileKey,
        String fileName,
        int chunkSize,
        String inputFilePath,
        ObjectMapper objectMapper) throws Exception {
    String url = falconDbUri + "/v1/saveOrAppendFile";

    HttpPut httpPut = new HttpPut(url);
    FileDTO fileDTO = new FileDTO();
    fileDTO.setFileName(fileName);
    fileDTO.setKey(fileKey);

    CloseableHttpClient client = null;
    FileInputStream fileInputStream = null;
    CloseableHttpResponse httpResponse = null;
    EntityBuilder entityBuilder = EntityBuilder.create();

    try {
        fileInputStream = new FileInputStream(inputFilePath);
        byte[] chunk = new byte[chunkSize];
        int bytesRead;

        while ((bytesRead = fileInputStream.read(chunk)) != -1) {
            String base64Encoded;
            if (bytesRead == chunkSize) {
                base64Encoded = Base64.getEncoder().encodeToString(chunk);
            } else {
                base64Encoded = Base64.getEncoder().encodeToString(Arrays.copyOf(chunk, bytesRead));
            }
            fileDTO.setBase64FileContent(base64Encoded);
            String fileDTOAsJson = objectMapper.writeValueAsString(fileDTO);

            client = HttpClients.createDefault();
            entityBuilder.setText(fileDTOAsJson);
            httpPut.setEntity(entityBuilder.build());
            httpResponse = client.execute(httpPut);
        }
    } catch (Throwable th) {
        throw new Exception("error, while saving file as chunks to FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(client)) {
            try {
                client.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(fileInputStream)) {
            try {
                fileInputStream.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(httpResponse)) {
            try {
                httpResponse.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }
    }
}

Get file in base64 chunks¶

Using java.net.HttpURLConnection¶

public void getFileAsChunks(
        String falconDbUri,
        String fileKey,
        String fileName,
        int chunkSize,
        String outputFilePath,
        ObjectMapper objectMapper) throws Exception {

    HttpURLConnection httpURLConnection = null;
    InputStream inputStream = null;
    FileOutputStream fileOutputStream = null;

    try {
        String getFileChunkUrl = falconDbUri
                + "/v1/getFileChunk"
                + "?key=" + fileKey
                + "&file-name=" + fileName
                + "&chunk-size=" + chunkSize;
        URL url;

        boolean isEOF = false;
        int chunkNumber = 0;
        FileChunkOutputDTO fileChunkOutputDTO;

        fileOutputStream = new FileOutputStream(outputFilePath);

        while (!isEOF) {
            url = new URL(getFileChunkUrl + "&chunk-number=" + chunkNumber);
            httpURLConnection = (HttpURLConnection) url.openConnection();
            httpURLConnection.setDoOutput(true);
            httpURLConnection.setRequestMethod("GET");

            inputStream = httpURLConnection.getInputStream();

            fileChunkOutputDTO = objectMapper.readValue(inputStream, FileChunkOutputDTO.class);

            inputStream.close();
            httpURLConnection.disconnect();

            isEOF = fileChunkOutputDTO.isEOF();
            byte[] bytes = Base64.getDecoder().decode(fileChunkOutputDTO.getBase64FileContent());
            if (fileChunkOutputDTO.getReadBytesSize() != chunkSize) {
                bytes = Arrays.copyOf(bytes, fileChunkOutputDTO.getReadBytesSize());
            }
            fileOutputStream.write(bytes);
            chunkNumber++;
        }
    } catch (Throwable th) {
        throw new Exception("error, while getting file as chunks from FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(httpURLConnection)) {
            httpURLConnection.disconnect();
        }

        if (Objects.nonNull(inputStream)) {
            inputStream.close();
        }

        if (Objects.nonNull(fileOutputStream)) {
            fileOutputStream.close();
        }
    }
}

Using Apache HttpComponents¶

public void getFileAsChunks(
        String falconDbUri,
        String fileKey,
        String fileName,
        int chunkSize,
        String outputFilePath,
        ObjectMapper objectMapper) throws Exception {
    String url = falconDbUri
            + "/v1/getFileChunk"
            + "?key=" + fileKey
            + "&file-name=" + fileName
            + "&chunk-size=" + chunkSize;

    int chunkNumber = 0;

    HttpGet httpGet = new HttpGet("");
    File outputFile = new File(outputFilePath);
    FileChunkOutputDTO fileChunkOutputDTO;
    boolean isEOF = false;

    CloseableHttpClient client = null;
    CloseableHttpResponse httpResponse = null;
    InputStream inputStream = null;
    HttpEntity httpEntity = null;
    FileOutputStream fileOutputStream = null;

    try {
        client = HttpClients.createDefault();
        fileOutputStream = new FileOutputStream(outputFile);

        while (!isEOF) {
            httpGet.setUri(URI.create(url + "&chunk-number=" + chunkNumber));
            httpResponse = client.execute(httpGet);
            httpEntity = httpResponse.getEntity();
            inputStream = httpEntity.getContent();
            fileChunkOutputDTO = objectMapper.readValue(inputStream, FileChunkOutputDTO.class);
            isEOF = fileChunkOutputDTO.isEOF();
            byte[] bytes = Base64.getDecoder().decode(fileChunkOutputDTO.getBase64FileContent());
            if (fileChunkOutputDTO.getReadBytesSize() != chunkSize) {
                bytes = Arrays.copyOf(bytes, fileChunkOutputDTO.getReadBytesSize());
            }
            fileOutputStream.write(bytes);
            chunkNumber++;
        }
    } catch (Throwable th) {
        throw new Exception("error, while getting file as chunks from FalconDB, caused by: ", th);
    } finally {
        if (Objects.nonNull(client)) {
            try {
                client.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(httpResponse)) {
            try {
                httpResponse.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(inputStream)) {
            try {
                inputStream.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(httpEntity)) {
            try {
                httpEntity.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }

        if (Objects.nonNull(fileOutputStream)) {
            try {
                fileOutputStream.close();
            } catch (Throwable th) {
                throw new Exception(th);
            }
        }
    }
}