Package io.atomix.cluster

Class AtomixClusterBuilder

java.lang.Object
io.atomix.cluster.AtomixClusterBuilder
All Implemented Interfaces:
io.atomix.utils.Builder<AtomixCluster>
public class AtomixClusterBuilder
extends Object
implements io.atomix.utils.Builder<AtomixCluster>
Builder for an AtomixCluster instance.

This builder is used to configure an AtomixCluster instance programmatically. To create a new builder, use one of the AtomixCluster.builder() static methods. 

   
   AtomixClusterBuilder builder = AtomixCluster.builder();
The instance is configured by calling the with* methods on this builder. Once the instance has been configured, call build() to build the instance: 
   
   AtomixCluster cluster = AtomixCluster.builder()
     .withMemberId("member-1")
     .withAddress("localhost", 5000)
     .build();
Backing the builder is an ClusterConfig which is loaded when the builder is initially constructed. To load a configuration from a file, use AtomixCluster.builder(String).

  • Method Details

    • withClusterId

      public AtomixClusterBuilder withClusterId​(String clusterId)
      Sets the cluster identifier.

      The cluster identifier is used to verify intra-cluster communication is taking place between nodes that are intended to be part of the same cluster, e.g. if multicast discovery is used. It only needs to be configured if multiple Atomix clusters are running within the same network.

      Parameters:
      clusterId - the cluster identifier
      Returns:
      the cluster builder

    • withMemberId

      public AtomixClusterBuilder withMemberId​(String localMemberId)
      Sets the local member identifier.

      The member identifier is an optional attribute that can be used to identify and send messages directly to this node. If no member identifier is provided, a UUID based identifier will be generated.

      Parameters:
      localMemberId - the local member identifier
      Returns:
      the cluster builder

    • withMemberId

      public AtomixClusterBuilder withMemberId​(MemberId localMemberId)
      Sets the local member identifier.

      The member identifier is an optional attribute that can be used to identify and send messages directly to this node. If no member identifier is provided, a UUID based identifier will be generated.

      Parameters:
      localMemberId - the local member identifier
      Returns:
      the cluster builder

    • withHost

      public AtomixClusterBuilder withHost​(String host)
      Sets the member host.
      Parameters:
      host - the member host
      Returns:
      the cluster builder

    • withPort

      public AtomixClusterBuilder withPort​(int port)
      Sets the member port.
      Parameters:
      port - the member port
      Returns:
      the cluster builder

    • withAddress

      @Deprecated public AtomixClusterBuilder withAddress​(String address)
      Deprecated.
      since 3.1. Use withHost(String) and/or withPort(int) instead
      Sets the member address.

      The constructed AtomixCluster will bind to the given address for intra-cluster communication. The format of the address can be host:port or just host.

      Parameters:
      address - a host:port tuple
      Returns:
      the cluster builder
      Throws:
      io.atomix.utils.net.MalformedAddressException - if a valid Address cannot be constructed from the arguments

    • withAddress

      @Deprecated public AtomixClusterBuilder withAddress​(String host, int port)
      Deprecated.
      since 3.1. Use withHost(String) and withPort(int) instead
      Sets the member host/port.

      The constructed AtomixCluster will bind to the given host/port for intra-cluster communication. The provided host should be visible to other nodes in the cluster.

      Parameters:
      host - the host name
      port - the port number
      Returns:
      the cluster builder
      Throws:
      io.atomix.utils.net.MalformedAddressException - if a valid Address cannot be constructed from the arguments

    • withAddress

      @Deprecated public AtomixClusterBuilder withAddress​(int port)
      Deprecated.
      since 3.1. Use withPort(int) instead
      Sets the member address using local host.

      The constructed AtomixCluster will bind to the given port for intra-cluster communication.

      Parameters:
      port - the port number
      Returns:
      the cluster builder
      Throws:
      io.atomix.utils.net.MalformedAddressException - if a valid Address cannot be constructed from the arguments

    • withAddress

      public AtomixClusterBuilder withAddress​(io.atomix.utils.net.Address address)
      Sets the member address.

      The constructed AtomixCluster will bind to the given address for intra-cluster communication. The provided address should be visible to other nodes in the cluster.

      Parameters:
      address - the member address
      Returns:
      the cluster builder

    • withZoneId

      public AtomixClusterBuilder withZoneId​(String zoneId)
      Sets the zone to which the member belongs.

      The zone attribute can be used to enable zone-awareness in replication for certain primitive protocols. It is an arbitrary string that should be used to group multiple nodes together by their physical location.

      Parameters:
      zoneId - the zone to which the member belongs
      Returns:
      the cluster builder

    • withZone

      @Deprecated public AtomixClusterBuilder withZone​(String zone)
      Deprecated.
      since 3.1. Use withZoneId(String) instead
      Sets the zone to which the member belongs.

      The zone attribute can be used to enable zone-awareness in replication for certain primitive protocols. It is an arbitrary string that should be used to group multiple nodes together by their physical location.

      Parameters:
      zone - the zone to which the member belongs
      Returns:
      the cluster builder

    • withRackId

      public AtomixClusterBuilder withRackId​(String rackId)
      Sets the rack to which the member belongs.

      The rack attribute can be used to enable rack-awareness in replication for certain primitive protocols. It is an arbitrary string that should be used to group multiple nodes together by their physical location.

      Parameters:
      rackId - the rack to which the member belongs
      Returns:
      the cluster builder

    • withRack

      @Deprecated public AtomixClusterBuilder withRack​(String rack)
      Deprecated.
      since 3.1. Use withRackId(String) instead
      Sets the rack to which the member belongs.

      The rack attribute can be used to enable rack-awareness in replication for certain primitive protocols. It is an arbitrary string that should be used to group multiple nodes together by their physical location.

      Parameters:
      rack - the rack to which the member belongs
      Returns:
      the cluster builder

    • withHostId

      public AtomixClusterBuilder withHostId​(String hostId)
      Sets the host to which the member belongs.

      The host attribute can be used to enable host-awareness in replication for certain primitive protocols. It is an arbitrary string that should be used to group multiple nodes together by their physical location. Typically this attribute only applies to containerized clusters.

      Parameters:
      hostId - the host to which the member belongs
      Returns:
      the cluster builder

    • withProperties

      public AtomixClusterBuilder withProperties​(Properties properties)
      Sets the member properties.

      The properties are arbitrary settings that will be replicated along with this node's member information. Properties can be used to enable other nodes to determine metadata about this node.

      Parameters:
      properties - the member properties
      Returns:
      the cluster builder
      Throws:
      NullPointerException - if the properties are null

    • withProperty

      public AtomixClusterBuilder withProperty​(String key, String value)
      Sets a property of the member.

      The properties are arbitrary settings that will be replicated along with this node's member information. Properties can be used to enable other nodes to determine metadata about this node.

      Parameters:
      key - the property key to set
      value - the property value to set
      Returns:
      the cluster builder
      Throws:
      NullPointerException - if the property is null

    • withMessagingInterface

      public AtomixClusterBuilder withMessagingInterface​(String iface)
      Sets the interface to which to bind the instance.
      Parameters:
      iface - the interface to which to bind the instance
      Returns:
      the cluster builder

    • withMessagingInterfaces

      public AtomixClusterBuilder withMessagingInterfaces​(String... ifaces)
      Sets the interface(s) to which to bind the instance.
      Parameters:
      ifaces - the interface(s) to which to bind the instance
      Returns:
      the cluster builder

    • withMessagingInterfaces

      public AtomixClusterBuilder withMessagingInterfaces​(Collection<String> ifaces)
      Sets the interface(s) to which to bind the instance.
      Parameters:
      ifaces - the interface(s) to which to bind the instance
      Returns:
      the cluster builder

    • withMessagingPort

      public AtomixClusterBuilder withMessagingPort​(int bindPort)
      Sets the local port to which to bind the node.
      Parameters:
      bindPort - the local port to which to bind the node
      Returns:
      the cluster builder

    • withConnectionPoolSize

      public AtomixClusterBuilder withConnectionPoolSize​(int connectionPoolSize)
      Sets the messaging connection pool size.

      The node will create connectionPoolSize connections to each peer with which it regularly communicates over TCP. Periodic heartbeats from cluster membership protocols will not consume pool connections. Thus, if a node does not communicate with one of its peers for replication or application communication, the pool for that peer should remain empty.

      Parameters:
      connectionPoolSize - the connection pool size
      Returns:
      the cluster builder

    • withMulticastEnabled

      public AtomixClusterBuilder withMulticastEnabled()
      Enables multicast communication.

      Multicast is disabled by default. This method must be called to enable it. Enabling multicast enables the use of the BroadcastService.

      Returns:
      the cluster builder
      See Also:
      withMulticastAddress(Address)

    • withMulticastEnabled

      public AtomixClusterBuilder withMulticastEnabled​(boolean multicastEnabled)
      Sets whether multicast communication is enabled.

      Multicast is disabled by default. This method must be called to enable it. Enabling multicast enables the use of the BroadcastService.

      Parameters:
      multicastEnabled - whether to enable multicast
      Returns:
      the cluster builder
      See Also:
      withMulticastAddress(Address)

    • withMulticastAddress

      public AtomixClusterBuilder withMulticastAddress​(io.atomix.utils.net.Address address)
      Sets the multicast address.

      Multicast is disabled by default. To enable multicast, first use withMulticastEnabled().

      Parameters:
      address - the multicast address
      Returns:
      the cluster builder

    • setBroadcastInterval

      @Deprecated public AtomixClusterBuilder setBroadcastInterval​(java.time.Duration interval)
      Deprecated.
      since 3.0.2
      Sets the reachability broadcast interval.

      The broadcast interval is the interval at which heartbeats are sent to peers in the cluster.

      Parameters:
      interval - the reachability broadcast interval
      Returns:
      the cluster builder

    • withBroadcastInterval

      @Deprecated public AtomixClusterBuilder withBroadcastInterval​(java.time.Duration interval)
      Deprecated.
      Sets the reachability broadcast interval.

      The broadcast interval is the interval at which heartbeats are sent to peers in the cluster.

      Parameters:
      interval - the reachability broadcast interval
      Returns:
      the cluster builder

    • setReachabilityThreshold

      @Deprecated public AtomixClusterBuilder setReachabilityThreshold​(int threshold)
      Deprecated.
      since 3.0.2
      Sets the reachability failure detection threshold.

      Reachability of cluster members is determined using a phi-accrual failure detector. The reachability threshold is the phi threshold after which a peer will be determined to be unreachable.

      Parameters:
      threshold - the reachability failure detection threshold
      Returns:
      the cluster builder

    • withReachabilityThreshold

      @Deprecated public AtomixClusterBuilder withReachabilityThreshold​(int threshold)
      Deprecated.
      Sets the reachability failure detection threshold.

      Reachability of cluster members is determined using a phi-accrual failure detector. The reachability threshold is the phi threshold after which a peer will be determined to be unreachable.

      Parameters:
      threshold - the reachability failure detection threshold
      Returns:
      the cluster builder

    • withReachabilityTimeout

      @Deprecated public AtomixClusterBuilder withReachabilityTimeout​(java.time.Duration timeout)
      Deprecated.
      Sets the reachability failure timeout.

      The reachability timeout determines the maximum time after which a member will be marked unreachable if heartbeats have failed.

      Parameters:
      timeout - the reachability failure timeout
      Returns:
      the cluster builder

    • withMembershipProtocol

      public AtomixClusterBuilder withMembershipProtocol​(GroupMembershipProtocol protocol)
      Sets the cluster membership protocol.

      The membership protocol is responsible for determining the active set of members in the cluster, replicating member metadata, and detecting failures. The default is HeartbeatMembershipProtocol.

      Parameters:
      protocol - the cluster membership protocol
      Returns:
      the cluster builder
      See Also:
      HeartbeatMembershipProtocol, SwimMembershipProtocol

    • withMembershipProvider

      public AtomixClusterBuilder withMembershipProvider​(NodeDiscoveryProvider locationProvider)
      Sets the cluster membership provider.

      The membership provider determines how peers are located and the cluster is bootstrapped.

      Parameters:
      locationProvider - the membership provider
      Returns:
      the cluster builder
      See Also:
      BootstrapDiscoveryProvider, MulticastDiscoveryProvider

    • withTlsEnabled

      public AtomixClusterBuilder withTlsEnabled()
      Enables TLS for the Atomix messaging service.

      The messaging service is the service through which all Atomix protocols communicate with their peers. Enabling TLS for the messaging service enables TLS for all internal Atomix communication. When TLS is enabled, Atomix will look for an atomix.jks file in the /conf directory unless a keystore/truststore is provided.

      Returns:
      the cluster builder
      See Also:
      withKeyStore(String), withTrustStore(String)

    • withTlsEnabled

      public AtomixClusterBuilder withTlsEnabled​(boolean tlsEnabled)
      Sets whether TLS is enabled for the Atomix messaging service.

      The messaging service is the service through which all Atomix protocols communicate with their peers. Enabling TLS for the messaging service enables TLS for all internal Atomix communication. When TLS is enabled, Atomix will look for an atomix.jks file in the /conf directory unless a keystore/truststore is provided.

      Returns:
      the cluster builder
      See Also:
      withKeyStore(String), withTrustStore(String)

    • withKeyStore

      public AtomixClusterBuilder withKeyStore​(String keyStore)
      Sets the key store to use for TLS in the Atomix messaging service.
      Parameters:
      keyStore - the key store path
      Returns:
      the cluster builder

    • withKeyStorePassword

      public AtomixClusterBuilder withKeyStorePassword​(String keyStorePassword)
      Sets the key store password for the Atomix messaging service.
      Parameters:
      keyStorePassword - the key store password
      Returns:
      the cluster builder

    • withTrustStore

      public AtomixClusterBuilder withTrustStore​(String trustStore)
      Sets the trust store to use for TLS in the Atomix messaging service.
      Parameters:
      trustStore - the trust store path
      Returns:
      the cluster builder

    • withTrustStorePassword

      public AtomixClusterBuilder withTrustStorePassword​(String trustStorePassword)
      Sets the trust store password for the Atomix messaging service.
      Parameters:
      trustStorePassword - the trust store password
      Returns:
      the cluster builder

    • build

      public AtomixCluster build()
      Specified by:
      build in interface io.atomix.utils.Builder<AtomixCluster>