ScalarisVM
Date: 2016-02-29

de.zib.scalaris

## Class ScalarisVM

- java.lang.Object
- - de.zib.scalaris.ScalarisVM

-     public class ScalarisVM
      extends Object

  Provides methods to interact with a specific Scalaris (Erlang) VM.
  Since:
    3.6
  Version:
    3.10
  Author:
    Nico Kruber, kruber@zib.de

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ScalarisVM.AddNodesResult` Plain old data object for results of `addNodes(int)`.
    `static class` | `ScalarisVM.DeleteNodesByNameResult` Plain old data object for results of `shutdownNodes(int)`, `shutdownNodesByName(List)`, `killNodes(int)` and `killNodes(List)`.
    `static class` | `ScalarisVM.GetInfoResult` Plain old data object for results of `getInfo()`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ScalarisVM(PeerNode node)` Creates a connection to the erlang VM of the given Scalaris node.
    `ScalarisVM(String node)` Creates a connection to the erlang VM of the given Scalaris node.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ScalarisVM.AddNodesResult` | `addNodes(int number)` Adds the given number of nodes to the Scalaris VM of the current connection.
    `void` | `closeConnection()` Closes the transaction's connection to a scalaris node.
    `ScalarisVM.GetInfoResult` | `getInfo()` Gets some information about the VM and Scalaris.
    `List<ErlangValue>` | `getNodes()` Gets the names of the nodes in the Scalaris VM of the current connection.
    `int` | `getNumberOfNodes()` Gets the number of nodes in the Scalaris VM of the current connection.
    `List<String>` | `getOtherVMs(int max)` Retrieves additional nodes from the Scalaris VM of the current connection for use by `ConnectionFactory.addNode(String)`.
    `String` | `getVersion()` Gets the version of the Scalaris VM of the current connection.
    `boolean` | `killNode(ErlangValue name)` Kills the given node inside the Scalaris VM of the current connection.
    `List<ErlangValue>` | `killNodes(int number)` Kills the given number of nodes inside the Scalaris VM of the current connection.
    `ScalarisVM.DeleteNodesByNameResult` | `killNodes(List<ErlangValue> names)` Kills the given nodes inside the Scalaris VM of the current connection.
    `void` | `killVM()` Kills the Scalaris VM of the current connection.
    `boolean` | `shutdownNode(ErlangValue name)` Shuts down the given node (graceful leave) inside the Scalaris VM of the current connection.
    `List<ErlangValue>` | `shutdownNodes(int number)` Shuts down the given number of nodes (graceful leave) inside the Scalaris VM of the current connection.
    `ScalarisVM.DeleteNodesByNameResult` | `shutdownNodesByName(List<ErlangValue> names)` Shuts down the given nodes (graceful leave) inside the Scalaris VM of the current connection.
    `void` | `shutdownVM()` Tells the Scalaris VM of the current connection to shut down gracefully.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ScalarisVM

          public ScalarisVM(PeerNode node)
                     throws ConnectionException

      Creates a connection to the erlang VM of the given Scalaris node. Uses the connection policy of the global connection factory.
      Parameters:
        `node` - Scalaris node to connect with
      Throws:
        `ConnectionException` - if the connection fails or the connection policy is not cloneable

    - #### ScalarisVM

          public ScalarisVM(String node)
                     throws ConnectionException

      Creates a connection to the erlang VM of the given Scalaris node. Uses the connection policy of the global connection factory.
      Parameters:
        `node` - Scalaris node to connect with
      Throws:
        `ConnectionException` - if the connection fails or the connection policy is not cloneable

  - ### Method Detail

    - #### getVersion

          public String getVersion()
                            throws ConnectionException,
                                   UnknownException

      Gets the version of the Scalaris VM of the current connection.
      Returns:
        Scalaris version string
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### getInfo

          public ScalarisVM.GetInfoResult getInfo()
                                           throws ConnectionException,
                                                  UnknownException

      Gets some information about the VM and Scalaris.
      Returns:
        VM information
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### getNumberOfNodes

          public int getNumberOfNodes()
                               throws ConnectionException,
                                      UnknownException

      Gets the number of nodes in the Scalaris VM of the current connection.
      Returns:
        number of nodes
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### getNodes

          public List<ErlangValue> getNodes()
                                     throws ConnectionException,
                                            UnknownException

      Gets the names of the nodes in the Scalaris VM of the current connection.
      Returns:
        the names of the nodes (arbitrary type!)
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### addNodes

          public ScalarisVM.AddNodesResult addNodes(int number)
                                             throws ConnectionException,
                                                    UnknownException

      Adds the given number of nodes to the Scalaris VM of the current connection.
      Parameters:
        `number` - number of nodes to add
      Returns:
        result of the operation
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### shutdownNode

          public boolean shutdownNode(ErlangValue name)
                               throws ConnectionException,
                                      UnknownException

      Shuts down the given node (graceful leave) inside the Scalaris VM of the current connection.
      Parameters:
        `name` - the name of a node
      Returns:
        `true` if the node was shut down, `false` if the node was not found
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### killNode

          public boolean killNode(ErlangValue name)
                           throws ConnectionException,
                                  UnknownException

      Kills the given node inside the Scalaris VM of the current connection.
      Parameters:
        `name` - the name of a node
      Returns:
        `true` if the node was shut down, `false` if the node was not found
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### shutdownNodes

          public List<ErlangValue> shutdownNodes(int number)
                                          throws ConnectionException,
                                                 UnknownException

      Shuts down the given number of nodes (graceful leave) inside the Scalaris VM of the current connection.
      Parameters:
        `number` - number of nodes to shut down
      Returns:
        result of the operation
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### killNodes

          public List<ErlangValue> killNodes(int number)
                                      throws ConnectionException,
                                             UnknownException

      Kills the given number of nodes inside the Scalaris VM of the current connection.
      Parameters:
        `number` - number of nodes to kill
      Returns:
        result of the operation
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### shutdownNodesByName

          public ScalarisVM.DeleteNodesByNameResult shutdownNodesByName(List<ErlangValue> names)
                                                                 throws ConnectionException,
                                                                        UnknownException

      Shuts down the given nodes (graceful leave) inside the Scalaris VM of the current connection.
      Parameters:
        `names` - names of the nodes to shut down
      Returns:
        result of the operation
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### killNodes

          public ScalarisVM.DeleteNodesByNameResult killNodes(List<ErlangValue> names)
                                                       throws ConnectionException,
                                                              UnknownException

      Kills the given nodes inside the Scalaris VM of the current connection.
      Parameters:
        `names` - names of the nodes to kill
      Returns:
        result of the operation
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### getOtherVMs

          public List<String> getOtherVMs(int max)
                                   throws ConnectionException,
                                          UnknownException

      Retrieves additional nodes from the Scalaris VM of the current connection for use by `ConnectionFactory.addNode(String)`.
      Parameters:
        `max` - maximum number of nodes to return (> 0)
      Returns:
        a list of nodes (may be empty!)
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### shutdownVM

          public void shutdownVM()
                          throws ConnectionException

      Tells the Scalaris VM of the current connection to shut down gracefully.
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### killVM

          public void killVM()
                      throws ConnectionException

      Kills the Scalaris VM of the current connection.
      Throws:
        `ConnectionException` - if the connection is not active or a communication error occurs or an exit signal was received or the remote node sends a message containing an invalid cookie
        `UnknownException` - if any other error occurs

    - #### closeConnection

          public void closeConnection()

      Closes the transaction's connection to a scalaris node. Note: Subsequent calls to the other methods will throw `ConnectionException`s!