Module io.hotmoka.node.api

Package io.hotmoka.node.api

Interface Node

All Superinterfaces:

AutoCloseable, io.hotmoka.closeables.api.OnCloseHandlersContainer

public interface Node
extends AutoCloseable, io.hotmoka.closeables.api.OnCloseHandlersContainer

A node of the Hotmoka network, that provides the storage facilities for the execution of Takamaka code. Calls to code in the node can be added, run or posted. Posted calls are executed, eventually, and their value can be retrieved through the future returned by the calls. Added calls are shorthand for posting a call and waiting until the value of their future is available. Run calls are only available for view methods, without side-effects. They execute immediately and never modify the store of the node.

Method Summary

Modifier and Type	Method	Description
StorageReference	addConstructorCallTransaction(ConstructorCallTransactionRequest request)	Expands the store of this node with a transaction that runs a constructor of a class.
StorageReference	addGameteCreationTransaction(GameteCreationTransactionRequest request)	Expands the store of this node with a transaction that creates a gamete, that is, an externally owned contract with the given initial amount of coins, of class io.takamaka.code.lang.Gamete.
void	addInitializationTransaction(InitializationTransactionRequest request)	Expands the store of this node with a transaction that marks the node as initialized and installs its manifest.
Optional<StorageValue>	addInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request)	Expands the store of this node with a transaction that runs an instance method of an object already in this node's store.
TransactionReference	addJarStoreInitialTransaction(JarStoreInitialTransactionRequest request)	Expands the store of this node with a transaction that installs a jar in it.
TransactionReference	addJarStoreTransaction(JarStoreTransactionRequest request)	Expands the store of this node with a transaction that installs a jar in it.
Optional<StorageValue>	addStaticMethodCallTransaction(StaticMethodCallTransactionRequest request)	Expands the store of this node with a transaction that runs a static method of a class in this node.
void	close()	Closes the node.
ClassTag	getClassTag(StorageReference object)	Yields the class tag of the object with the given storage reference.
ConsensusConfig<?,?>	getConfig()	Yields the consensus configuration of this node.
Stream<TransactionReference>	getIndex(StorageReference object)	Yields information about the transactions that have affected the given object.
NodeInfo	getInfo()	Yields node-specific information about the node.
StorageReference	getManifest()	Yields the manifest installed in the store of the node, when the node was initialized.
TransactionResponse	getPolledResponse(TransactionReference reference)	Waits until a transaction has been committed, or until its delivering fails.
TransactionRequest<?>	getRequest(TransactionReference reference)	Yields the request that generated the transaction with the given reference.
TransactionResponse	getResponse(TransactionReference reference)	Yields the response generated for the request for the given transaction.
Stream<Update>	getState(StorageReference object)	Yields the current state of the object at the given storage reference.
TransactionReference	getTakamakaCode()	Yields the reference to the jar installed in the store of the node, when the node was initialized, containing the classes of the Takamaka runtime.
ConstructorFuture	postConstructorCallTransaction(ConstructorCallTransactionRequest request)	Posts a transaction that runs a constructor of a class in this node.
MethodFuture	postInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request)	Posts a transaction that runs an instance method of an object already in this node's store.
JarFuture	postJarStoreTransaction(JarStoreTransactionRequest request)	Posts a transaction that expands the store of this node with a transaction that installs a jar in it.
MethodFuture	postStaticMethodCallTransaction(StaticMethodCallTransactionRequest request)	Posts a request that runs a static method of a class in this node.
Optional<StorageValue>	runInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request)	Runs an instance @@View method of an object already in this node's store.
Optional<StorageValue>	runStaticMethodCallTransaction(StaticMethodCallTransactionRequest request)	Runs a static @@View method of a class in this node.
Subscription	subscribeToEvents(StorageReference creator, BiConsumer<StorageReference,StorageReference> handler)	Subscribes the given handler for events with the given creator.

Methods inherited from interface io.hotmoka.closeables.api.OnCloseHandlersContainer

addOnCloseHandler, removeOnCloseHandler

Method Details

getConfig

ConsensusConfig<?,?> getConfig()
                        throws ClosedNodeException,
TimeoutException,
InterruptedException

Yields the consensus configuration of this node.

Returns:

the consensus configuration of this node

Throws:

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getTakamakaCode

TransactionReference getTakamakaCode()
                              throws UninitializedNodeException,
ClosedNodeException,
TimeoutException,
InterruptedException

Yields the reference to the jar installed in the store of the node, when the node was initialized, containing the classes of the Takamaka runtime.

Returns:

the reference to the jar containing the classes of the Takamaka runtime

Throws:

ClosedNodeException - if the node is already closed

UninitializedNodeException - if the node has not been initialized yet

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getManifest

StorageReference getManifest()
                      throws UninitializedNodeException,
ClosedNodeException,
TimeoutException,
InterruptedException

Yields the manifest installed in the store of the node, when the node was initialized. The manifest is an object of type io.takamaka.code.system.Manifest that contains information about the node, useful for the users of the node.

Returns:

the reference to the manifest

Throws:

ClosedNodeException - if the node is already closed

UninitializedNodeException - if the node has not been initialized yet

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getInfo

NodeInfo getInfo()
          throws ClosedNodeException,
TimeoutException,
InterruptedException

Yields node-specific information about the node. This is likely different for each node of the network, hence this is not consensus information.

Returns:

the node-specific information about the node

Throws:

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getClassTag

ClassTag getClassTag(StorageReference object)
              throws UnknownReferenceException,
ClosedNodeException,
TimeoutException,
InterruptedException

Yields the class tag of the object with the given storage reference. If this method succeeds and this node has some form of commit, then the transaction of the storage reference has been definitely committed in this node. A node is allowed to keep in store all, some or none of the objects. Hence, this method might fail to find the class tag although the object previously existed in store.

Parameters:

object - the storage reference of the object

Returns:

the class tag

Throws:

UnknownReferenceException - if object cannot be found in this node

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getState

Stream<Update> getState(StorageReference object)
                 throws UnknownReferenceException,
ClosedNodeException,
TimeoutException,
InterruptedException

Yields the current state of the object at the given storage reference. If this method succeeds and this node has some form of commit, then the transaction of the storage reference has been definitely committed in this node. A node is allowed to keep in store all, some or none of the objects. Hence, this method might fail to find the state of the object although the object previously existed in store.

Parameters:

object - the storage reference of the object

Returns:

the last updates of all its instance fields; these updates include the class tag update for the object

Throws:

UnknownReferenceException - if object cannot be found in this node

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getIndex

Stream<TransactionReference> getIndex(StorageReference object)
                               throws UnknownReferenceException,
ClosedNodeException,
InterruptedException,
TimeoutException

Yields information about the transactions that have affected the given object. Nodes can reply with full, partial, or no information about it, depending for instance on the fact that they keep an index of the objects affected by each transaction, or that such index is full or that it keeps the latest transactions only.

Parameters:

object - the object whose affecting transactions are required

Returns:

the transactions that have affected object; this can be full, partial or no information

Throws:

UnknownReferenceException - if the given object is unknown to the index

ClosedNodeException - if the node is already closed

InterruptedException - if the current thread gets interrupted before completing the operation

TimeoutException - if no answer arrives before a time window

getRequest

TransactionRequest<?> getRequest(TransactionReference reference)
                          throws UnknownReferenceException,
ClosedNodeException,
TimeoutException,
InterruptedException

Yields the request that generated the transaction with the given reference. If this node has some form of commit, then this method can only succeed when the transaction has been definitely committed in this node. Nodes are allowed to keep in store all, some or none of the requests that they received during their lifetime.

Parameters:

reference - the reference of the transaction

Returns:

the request

Throws:

UnknownReferenceException - if the request of reference cannot be found in this node

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getResponse

TransactionResponse getResponse(TransactionReference reference)
                         throws UnknownReferenceException,
ClosedNodeException,
TimeoutException,
InterruptedException

Yields the response generated for the request for the given transaction. If this node has some form of commit, then this method can only succeed only when the transaction has been definitely committed in this node. Nodes are allowed to keep in store all, some or none of the responses that they computed during their lifetime.

Parameters:

reference - the reference of the transaction

Returns:

the response

Throws:

UnknownReferenceException - if the response of reference cannot be found in this node

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

getPolledResponse

TransactionResponse getPolledResponse(TransactionReference reference)
                               throws TransactionRejectedException,
ClosedNodeException,
TimeoutException,
InterruptedException

Waits until a transaction has been committed, or until its delivering fails. If this method succeeds and this node has some form of commit, then the transaction has been definitely committed. Nodes are allowed to keep in store all, some or none of the responses computed during their lifetime. Hence, this method might time out also when a response has been computed in the past for the transaction of reference, but it has not been kept in store.

Parameters:

reference - the reference of the transaction

Returns:

the response computed for request

Throws:

TransactionRejectedException - if the request failed to be committed

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread has been interrupted while waiting for the response

addJarStoreInitialTransaction

TransactionReference addJarStoreInitialTransaction(JarStoreInitialTransactionRequest request)
                                            throws TransactionRejectedException,
ClosedNodeException,
TimeoutException,
InterruptedException

Expands the store of this node with a transaction that installs a jar in it. It has no caller and requires no gas. The goal is to install, in the node, some basic jars that are likely needed as dependencies by future jars. For instance, the jar containing the basic Takamaka classes. This installation have special privileges, such as that of installing packages in io.takamaka.code.lang.*.

Parameters:

request - the transaction request

Returns:

the reference to the transaction, that can be used to refer to the jar in a class path or as future dependency of other jars

Throws:

TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread has been interrupted while waiting for the response

addGameteCreationTransaction

StorageReference addGameteCreationTransaction(GameteCreationTransactionRequest request)
                                       throws TransactionRejectedException,
ClosedNodeException,
TimeoutException,
InterruptedException

Expands the store of this node with a transaction that creates a gamete, that is, an externally owned contract with the given initial amount of coins, of class io.takamaka.code.lang.Gamete. This transaction has no caller and requires no gas.

Parameters:

request - the transaction request

Returns:

the reference to the freshly created gamete

Throws:

TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread has been interrupted while waiting for the response

addInitializationTransaction

void addInitializationTransaction(InitializationTransactionRequest request)
                           throws TransactionRejectedException,
ClosedNodeException,
TimeoutException,
InterruptedException

Expands the store of this node with a transaction that marks the node as initialized and installs its manifest. After this transaction, no more initial transactions can be executed on the node.

Parameters:

request - the transaction request

Throws:

TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread has been interrupted while waiting for the response

addJarStoreTransaction

TransactionReference addJarStoreTransaction(JarStoreTransactionRequest request)
                                     throws TransactionRejectedException,
TransactionException,
ClosedNodeException,
TimeoutException,
InterruptedException

Expands the store of this node with a transaction that installs a jar in it.

Parameters:

request - the transaction request

Returns:

the reference to the transaction, that can be used to refer to the jar in a class path or as future dependency of other jars

Throws:

TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

TransactionException - if the transaction could be executed and the store of the node has been expanded with a failed transaction

ClosedNodeException - if the node is not able to perform the operation

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

addConstructorCallTransaction

StorageReference addConstructorCallTransaction(ConstructorCallTransactionRequest request)
                                        throws TransactionRejectedException,
TransactionException,
CodeExecutionException,
ClosedNodeException,
TimeoutException,
InterruptedException

Expands the store of this node with a transaction that runs a constructor of a class.

Parameters:

request - the request of the transaction

Returns:

the created object, if the constructor was successfully executed, without exception

Throws:

TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

CodeExecutionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception in the user code, that is allowed to be thrown by the constructor

TransactionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception outside the user code in the node, or not allowed to be thrown by the constructor

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

addInstanceMethodCallTransaction

Optional<StorageValue> addInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request)
                                                 throws TransactionRejectedException,
TransactionException,
CodeExecutionException,
ClosedNodeException,
TimeoutException,
InterruptedException

Expands the store of this node with a transaction that runs an instance method of an object already in this node's store.

Parameters:

request - the transaction request

Returns:

the result of the call, if the method was successfully executed, without exception. This is empty if and only if the method is declared to return void

Throws:

TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

CodeExecutionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception in the user code, that is allowed to be thrown by the method

TransactionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception outside the user code in the node, or not allowed to be thrown by the method

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

addStaticMethodCallTransaction

Optional<StorageValue> addStaticMethodCallTransaction(StaticMethodCallTransactionRequest request)
                                               throws TransactionRejectedException,
TransactionException,
CodeExecutionException,
ClosedNodeException,
TimeoutException,
InterruptedException

Expands the store of this node with a transaction that runs a static method of a class in this node.

Parameters:

request - the transaction request

Returns:

the result of the call, if the method was successfully executed, without exception. This is empty if and only if the method is declared to return void

Throws:

TransactionRejectedException - if the transaction could not be executed and the store of the node remained unchanged

CodeExecutionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception in the user code, that is allowed to be thrown by the method

TransactionException - if the transaction could be executed and the node has been expanded with a failed transaction, because of an exception outside the user code, or not allowed to be thrown by the method

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

runInstanceMethodCallTransaction

Optional<StorageValue> runInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request)
                                                 throws TransactionRejectedException,
TransactionException,
CodeExecutionException,
ClosedNodeException,
TimeoutException,
InterruptedException

Runs an instance @@View method of an object already in this node's store. The node's store is not expanded, since the execution of the method has no side-effects.

Parameters:

request - the transaction request

Returns:

the result of the call, if the method was successfully executed, without exception. This is empty if and only if the method is declared to return void

Throws:

TransactionRejectedException - if the transaction could not be executed

CodeExecutionException - if the transaction could be executed but led to an exception in the user code, that is allowed to be thrown by the method

TransactionException - if the transaction could be executed but led to an exception outside the user code, or that is not allowed to be thrown by the method

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

runStaticMethodCallTransaction

Optional<StorageValue> runStaticMethodCallTransaction(StaticMethodCallTransactionRequest request)
                                               throws TransactionRejectedException,
TransactionException,
CodeExecutionException,
ClosedNodeException,
TimeoutException,
InterruptedException

Runs a static @@View method of a class in this node. The node's store is not expanded, since the execution of the method has no side-effects.

Parameters:

request - the transaction request

Returns:

the result of the call, if the method was successfully executed, without exception. This is empty if and only if the method is declared to return void

Throws:

TransactionRejectedException - if the transaction could not be executed

CodeExecutionException - if the transaction could be executed but led to an exception in the user code, that is allowed to be thrown by the method

TransactionException - if the transaction could be executed but led to an exception outside the user code, or that is not allowed to be thrown by the method

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

postJarStoreTransaction

JarFuture postJarStoreTransaction(JarStoreTransactionRequest request)
                           throws TransactionRejectedException,
ClosedNodeException,
InterruptedException,
TimeoutException

Posts a transaction that expands the store of this node with a transaction that installs a jar in it.

Parameters:

request - the transaction request

Returns:

the future holding the reference to the transaction where the jar has been installed

Throws:

TransactionRejectedException - if the transaction could not be posted

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

postConstructorCallTransaction

ConstructorFuture postConstructorCallTransaction(ConstructorCallTransactionRequest request)
                                          throws TransactionRejectedException,
ClosedNodeException,
InterruptedException,
TimeoutException

Posts a transaction that runs a constructor of a class in this node.

Parameters:

request - the request of the transaction

Returns:

the future holding the result of the computation

Throws:

TransactionRejectedException - if the transaction could not be posted

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

postInstanceMethodCallTransaction

MethodFuture postInstanceMethodCallTransaction(InstanceMethodCallTransactionRequest request)
                                        throws TransactionRejectedException,
ClosedNodeException,
InterruptedException,
TimeoutException

Posts a transaction that runs an instance method of an object already in this node's store.

Parameters:

request - the transaction request

Returns:

the future holding the result of the transaction

Throws:

TransactionRejectedException - if the transaction could not be posted

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

postStaticMethodCallTransaction

MethodFuture postStaticMethodCallTransaction(StaticMethodCallTransactionRequest request)
                                      throws TransactionRejectedException,
ClosedNodeException,
InterruptedException,
TimeoutException

Posts a request that runs a static method of a class in this node.

Parameters:

request - the transaction request

Returns:

the future holding the result of the transaction

Throws:

TransactionRejectedException - if the transaction could not be posted

ClosedNodeException - if the node is already closed

TimeoutException - if no answer arrives before a time window

InterruptedException - if the current thread is interrupted while waiting for an answer to arrive

subscribeToEvents

Subscription subscribeToEvents(StorageReference creator,
 BiConsumer<StorageReference,StorageReference> handler)
                        throws ClosedNodeException

Subscribes the given handler for events with the given creator.

Parameters:

creator - the creator of the events that will be forwarded to the handler; if this is null, all events will be forwarded to the handler

handler - a handler that gets executed when an event occurs; for each event, it receives the creator of the event and the event itself

Returns:

the subscription, that can be used later to stop event handling with handler

Throws:

ClosedNodeException - if the node is already closed

close

void close()

Closes the node.

Specified by:

close in interface AutoCloseable