Coding App

This chapter will help guide you on how to develop and use Hive Java SDK (hereinafter referred to as SDK in this chapter) by realizing the most basic file data upload function, and shows the corresponding interface call and object maintenance in the application through key code segments.

Prepare DID

Developers should be aware that when saving Vault data to the backend, there will be four DIDs:

• Application DID

• Application Instance DID

• User DID

• Back-end Hive Node service DID

Among them, the application DID is generated by the developer in Essentials for the application, and the DID needs to be publicly put on the chain. Then, the application needs to be compiled to verify the compliance of its application when it's authorized to Essentials. The Application Instance DID represents a unique application instance that should be run on Android or iOS devices. It needs to be generated at one time when the developer installs it in the application, but doesn’t need to be publicly put on the chain. It can only be used when the application, as the user’s Agent, performs login verification when logging in to Hive Node service.

Each application has a unique DID identity, and users need to generate the DID in Essentials - at the same time, they need to disclose the co-chain. After that, it's kept in Essentials, and users are authorized to use it when logging in for subsequent applications. The backend Hive Node service DID, similar to the Application Instance DID, is also the only instance DID that represents the Hive service but needs to be exposed for the two-way authentication when the frontend applications interact.

The specified DID identity authorized in Essentials is used to login to the application. When requesting login from the backend Hive Node, you need to issue a credential requesting login to the application instance (instance DID) through the authorization of Essentials. Hive Node authorizes to issue an access token to the frontend application by verifying the authenticity of the login credentials, and subsequent applications use the access token to save and access the data in the Vault.

Create Vault

After the user creates the application framework through the Android Studio tool, the Vault object is instantiated through SDK, and the corresponding sub-service interface is obtained through the Vault object. When instantiating a Vault object, you need to prepare a certain program context environment. We need to use AppContext and Hive Node Provider URL address here. The Application Instance DID and User DID are used to create AppContext.

AppContext appContext = AppContext.build(new AppContextProvider() {
    @Override
    public String getLocalDataDir() {
        // return local location for storing data.
        return getLocalStorePath();
    }

    @Override
    public DIDDocument getAppInstanceDocument() {
        // return the application instance DID document.
        try {
            return appInstanceDid.getDocument();
        } catch (DIDException e) {
            e.printStackTrace();
        }
        return null;
    }

    @Override
    public CompletableFuture<String> getAuthorization(String jwtToken) {
        // return the authorization string for auth API.
        return CompletableFuture.supplyAsync(() -> {
            try {
                Claims claims = new JwtParserBuilder().build().parseClaimsJws(jwtToken).getBody();
                if (claims == null)
                    throw new HiveException("Invalid jwt token as authorization.");
                return appInstanceDid.createToken(appInstanceDid.createPresentation(
                        userDid.issueDiplomaFor(appInstanceDid),
                        claims.getIssuer(), (String) claims.get("nonce")), claims.getIssuer());
            } catch (Exception e) {
                throw new CompletionException(new HiveException(e.getMessage()));
            }
        });
    }
}, userDid.toString());

Meanwhile, the corresponding Hive Node address is filled as the Provider address parameter by selecting trusted Hive Node service nodes. With AppContext object and Provider address, you can instantiate the existing Vault service object:

Vault vault = new Vault(appContext, getVaultProviderAddress());

Get FilesService Interface

Because the example only involves the file upload function; you only need to get the FilesService interface - the specific call interface is as follows:

FilesService filesService = vault.getFilesService());

Upload File

Once the FilesService interface instance is obtained, the file data can be uploaded to the Vault service through here. When a file is uploading, the writer ought to be gotten firstly, and then the file content is written to complete the whole process of uploading the file data.

public CompletableFuture<Void> writeFileContent(Writer writer) {
    return CompletableFuture.runAsync(() -> {
        try {
            writer.write(REMOTE_FILE_CONTENT);
            writer.flush();
            writer.close();
        } catch (IOException e) {
            throw new CompletionException(e);
        }
    });
}

filesService.getUploadWriter(REMOTE_FILE_PATH)
    .thenCompose(this::writeFileContent)
    .thenAcceptAsync(result -> hideLoadingWithMessage(null))
    .exceptionally(ex -> {
        hideLoadingWithMessage(ex);
        return null;
    });