com.chain.api.Account Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of chain-sdk-java Show documentation
Show all versions of chain-sdk-java Show documentation
The Official Java SDK for Chain Core Developer Edition
The newest version!
package com.chain.api;
import com.chain.exception.*;
import com.chain.http.*;
import com.google.gson.annotations.SerializedName;
import java.util.*;
/**
* A single Account on the Chain Core, capable of spending or receiving assets in a transaction.
*/
public class Account {
/**
* Unique account identifier.
*/
public String id;
/**
* User specified, unique identifier.
*/
public String alias;
/**
* The list of keys used to create control programs under the account.
* Signatures from these keys are required for spending funds held in the account.
*/
public Key[] keys;
/**
* The number of keys required to sign transactions for the account.
*/
public int quorum;
/**
* User-specified tag structure for the account.
*/
public Map tags;
/**
* A class storing information about the keys associated with the account.
*/
public static class Key {
/**
* Hex-encoded representation of the root extended public key
*/
@SerializedName("root_xpub")
public String rootXpub;
/**
* The extended public key used to create control programs for the account.
*/
@SerializedName("account_xpub")
public String accountXpub;
/**
* The derivation path of the extended key.
*/
@SerializedName("account_derivation_path")
public String[] accountDerivationPath;
}
/**
* Creates a batch of account objects.
* Note: this method will not throw an exception APIException. Each builder's response object must be checked for error.
* @param client client object that makes requests to the core
* @param builders list of account builders
* @return a list of account and/or error objects
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public static BatchResponse createBatch(Client client, List builders)
throws ChainException {
for (Builder builder : builders) {
builder.clientToken = UUID.randomUUID().toString();
}
return client.batchRequest("create-account", builders, Account.class, APIException.class);
}
/**
* Updates tags for multiple accounts in a single API call.
* Note: this method will not throw an exception APIException. Each builder's response object must be checked for error.
* @param client client object that makes requests to the core
* @param builders list of tag update parameters, one per account
* @return a batch response containing success messages and/or error objects
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public static BatchResponse updateTagsBatch(
Client client, List builders) throws ChainException {
return client.batchRequest(
"update-account-tags", builders, SuccessMessage.class, APIException.class);
}
/**
* A paged collection of accounts returned from a query.
*/
public static class Items extends PagedItems {
/**
* Requests a page of accounts based on an underlying query.
* @return a page of accounts objects
* @throws APIException This exception is raised if the api returns errors while retrieving the accounts.
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public Items getPage() throws ChainException {
Items items = this.client.request("list-accounts", this.next, Items.class);
items.setClient(this.client);
return items;
}
}
/**
* Account.QueryBuilder utilizes the builder pattern to create {@link Account} queries.
* The possible parameters for each query can be found on the {@link BaseQueryBuilder} class.
* All parameters are optional, and should be set to filter the results accordingly.
*/
public static class QueryBuilder extends BaseQueryBuilder {
/**
* Executes a query on the core's accounts.
* @param client client object that makes requests to the core
* @return a collection of account objects
* @throws APIException This exception is raised if the api returns errors while retrieving the accounts.
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public Items execute(Client client) throws ChainException {
Items items = new Items();
items.setClient(client);
items.setNext(this.next);
return items.getPage();
}
}
/**
* Account.Builder utilizes the builder pattern to create {@link Account} objects.
* The following attributes are required to be set: {@link #rootXpubs}, {@link #quorum}.
*/
public static class Builder {
/**
* User specified, unique identifier.
*/
public String alias;
/**
* The number of keys required to sign transactions for the account.
* Must set with {@link #setQuorum(int)} before calling {@link #create(Client)}.
*/
public int quorum;
/**
* The list of keys used to create control programs under the account.
* Signatures from these keys are required for spending funds held in the account.
* Must set with {@link #addRootXpub(String)} or {@link #setRootXpubs(List)} before calling {@link #create(Client)}.
*/
@SerializedName("root_xpubs")
public List rootXpubs;
/**
* User-specified tag structure for the account.
*/
public Map tags;
/**
* Unique identifier used for request idempotence.
*/
@SerializedName("client_token")
private String clientToken;
/**
* Default constructor initializes the list of keys.
*/
public Builder() {
this.rootXpubs = new ArrayList<>();
}
/**
* Creates an account object.
* @param client client object that makes request to the core
* @return an account object
* @throws APIException This exception is raised if the api returns errors while creating the account.
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public Account create(Client client) throws ChainException {
return client.singletonBatchRequest(
"create-account", Arrays.asList(this), Account.class, APIException.class);
}
/**
* Sets the alias on the builder object.
* @param alias alias
* @return updated builder object
*/
public Builder setAlias(String alias) {
this.alias = alias;
return this;
}
/**
* Sets the quorum for control programs.
* Must be called before {@link #create(Client)}.
* @param quorum proposed quorum
* @return updated builder object
*/
public Builder setQuorum(int quorum) {
this.quorum = quorum;
return this;
}
/**
* Adds a key to the builder's list.
* Either this or {@link #setRootXpubs(List)} must be called before {@link #create(Client)}.
* @param xpub key
* @return updated builder object.
*/
public Builder addRootXpub(String xpub) {
this.rootXpubs.add(xpub);
return this;
}
/**
* Sets the builder's list of keys.
* Note: any existing keys will be replaced.
* Either this or {@link #addRootXpub(String)} must be called before {@link #create(Client)}.
* @param xpubs list of xpubs
* @return updated builder object
*/
public Builder setRootXpubs(List xpubs) {
this.rootXpubs = new ArrayList<>(xpubs);
return this;
}
/**
* Adds a field to the existing account tags object (initializing the object if it doesn't exist).
* @param key key of the tag
* @param value value of the tag
* @return updated builder object
*/
public Builder addTag(String key, Object value) {
if (this.tags == null) {
this.tags = new HashMap<>();
}
this.tags.put(key, value);
return this;
}
/**
* Sets the account tags object.
* Note: any existing account tag fields will be replaced.
* @param tags account tags object
* @return updated builder object
*/
public Builder setTags(Map tags) {
this.tags = tags;
return this;
}
}
/**
* Use this class to update an account's tags.
*/
public static class TagUpdateBuilder {
public String alias;
public String id;
public Map tags;
/**
* Specifies the account under which the receiver is created. You must use
* this method or @{link TagUpdateBuilder#forAlias}, but not both.
*
* @param id the unique ID of the account
* @return this TagUpdateBuilder object
*/
public TagUpdateBuilder forId(String id) {
this.id = id;
return this;
}
/**
* Specifies the account whose tags will be updated. You must use
* this method or @{link TagUpdateBuilder#forId}, but not both.
*
* @param alias the unique alias of the account
* @return this TagUpdateBuilder object
*/
public TagUpdateBuilder forAlias(String alias) {
this.alias = alias;
return this;
}
/**
* Specifies the new tags, which will replace the account's existing tags.
* @param tags account tags object
* @return updated builder object
*/
public TagUpdateBuilder setTags(Map tags) {
this.tags = tags;
return this;
}
/**
* Updates an account's tags.
* @param client client object that makes request to the core
* @throws APIException This exception is raised if the api returns errors while creating the account.
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public void update(Client client) throws ChainException {
client.singletonBatchRequest(
"update-account-tags", Arrays.asList(this), SuccessMessage.class, APIException.class);
}
}
/**
* Use this class to create a {@link Receiver} under an account.
*/
public static class ReceiverBuilder {
@SerializedName("account_alias")
public String accountAlias;
@SerializedName("account_id")
public String accountId;
@SerializedName("expires_at")
public Date expiresAt;
/**
* Specifies the account under which the receiver is created. You must use
* this method or @{link ReceiverBuilder#setAccountId}, but not both.
*
* @param alias the unique alias of the account
* @return this ReceiverBuilder object
*/
public ReceiverBuilder setAccountAlias(String alias) {
this.accountAlias = alias;
return this;
}
/**
* Specifies the account under which the receiver is created. You must use
* this method or @{link ReceiverBuilder#setAccountAlias}, but not both.
*
* @param id the unique ID of the account
* @return this ReceiverBuilder object
*/
public ReceiverBuilder setAccountId(String id) {
this.accountId = id;
return this;
}
/**
* Specifies when the receiver will expire. This defaults to 30 days in the
* future.
*
* Payments to expired receivers should not be considered valid, and may or
* may not be indexed by your Chain Core instance. In general, as long as
* the contents of receiver objects are not tampered with, the transaction
* builder will ensure that transactions that pay to expired receivers will
* be rejected by the blockchain.
*
* @param date the date when the receiver expires
* @return this ReceiverBuilder object
*/
public ReceiverBuilder setExpiresAt(Date date) {
this.expiresAt = date;
return this;
}
/**
* Creates a single Receiver object under an account.
*
* @param client the client object providing access to an instance of Chain Core
* @return a new Receiver object
* @throws APIException This exception is raised if the api returns errors while creating the control programs.
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public Receiver create(Client client) throws ChainException {
return client.singletonBatchRequest(
"create-account-receiver", Arrays.asList(this), Receiver.class, APIException.class);
}
}
/**
* Creates multiple Receiver objects under one or more accounts, as a batch.
*
* @param client the client object providing access to an instance of Chain Core
* @param builders a list of builder objects, one for each new Receiver to be created
* @return a list of new Receiver objects or error messages, as a {@link BatchResponse}
* @throws APIException This exception is raised if the api returns errors while creating the control programs.
* @throws BadURLException This exception wraps java.net.MalformedURLException.
* @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
* @throws HTTPException This exception is raised when errors occur making http requests.
* @throws JSONException This exception is raised due to malformed json requests or responses.
*/
public static BatchResponse createReceiverBatch(
Client client, List builders) throws ChainException {
return client.batchRequest(
"create-account-receiver", builders, Receiver.class, APIException.class);
}
}