Package io.atomix.primitive

Interface PrimitiveFactory

public interface PrimitiveFactory
Manages the creation of distributed primitive instances.

The primitives service provides various methods for constructing core and custom distributed primitives. The service provides various methods for creating and operating on distributed primitives. Generally, the primitive methods are separated into two types. Primitive getters return multiton instances of a primitive. Primitives created via getters must be pre-configured in the Atomix instance configuration. Alternatively, primitive builders can be used to create and configure primitives in code: 

   
   AtomicMap<String, String> map = atomix.mapBuilder("my-map")
     .withProtocol(MultiRaftProtocol.builder("raft")
       .withReadConsistency(ReadConsistency.SEQUENTIAL)
       .build())
     .build();
Custom primitives can be constructed by providing a custom PrimitiveType and using the primitiveBuilder(String, PrimitiveType) method: 
   
   MyPrimitive myPrimitive = atomix.primitiveBuilder("my-primitive, MyPrimitiveType.instance())
     .withProtocol(MultiRaftProtocol.builder("raft")
       .withReadConsistency(ReadConsistency.SEQUENTIAL)
       .build())
     .build();

  • Method Details

    • getPrimitiveType

      PrimitiveType getPrimitiveType​(String typeName)
      Returns a primitive type by name.
      Parameters:
      typeName - the primitive type name
      Returns:
      the primitive type

    • getPrimitive

      default <P extends SyncPrimitive> P getPrimitive​(String name, PrimitiveType<?,​?,​P> primitiveType)
      Gets or creates a distributed primitive.

      A new primitive of the given primitiveType will be created if no primitive instance with the given name exists on this node, otherwise the existing instance will be returned. The name is used to reference a distinct instance of the primitive within the cluster. The returned primitive will share the same state with primitives of the same name on other nodes.

      When the instance is initially constructed, it will be configured with any pre-existing primitive configuration defined in atomix.conf.

      To get an asynchronous instance of the primitive, use the SyncPrimitive.async() method: 

         
   AsyncPrimitive async = atomix.getPrimitive("my-primitive").async();
      Type Parameters:
      P - the primitive type
      Parameters:
      name - the primitive name
      primitiveType - the primitive type
      Returns:
      the primitive instance

    • getPrimitive

      default <C extends PrimitiveConfig<C>,​ P extends SyncPrimitive> P getPrimitive​(String name, PrimitiveType<?,​C,​P> primitiveType, C primitiveConfig)
      Gets or creates a distributed primitive.

      A new primitive of the given primitiveType will be created if no primitive instance with the given name exists on this node, otherwise the existing instance will be returned. The name is used to reference a distinct instance of the primitive within the cluster. The returned primitive will share the same state with primitives of the same name on other nodes.

      When the instance is initially constructed, it will be configured with any pre-existing primitive configuration defined in atomix.conf.

      To get an asynchronous instance of the primitive, use the SyncPrimitive.async() method: 

         
   AsyncPrimitive async = atomix.getPrimitive("my-primitive").async();
      Type Parameters:
      C - the primitive configuration type
      P - the primitive type
      Parameters:
      name - the primitive name
      primitiveType - the primitive type
      primitiveConfig - the primitive configuration
      Returns:
      the primitive instance

    • getPrimitiveAsync

      <P extends SyncPrimitive> CompletableFuture<P> getPrimitiveAsync​(String name, PrimitiveType<?,​?,​P> primitiveType)
      Gets or creates a distributed primitive asynchronously.

      A new primitive of the given primitiveType will be created if no primitive instance with the given name exists on this node, otherwise the existing instance will be returned. The name is used to reference a distinct instance of the primitive within the cluster. The returned primitive will share the same state with primitives of the same name on other nodes.

      When the instance is initially constructed, it will be configured with any pre-existing primitive configuration defined in atomix.conf.

      Type Parameters:
      P - the primitive type
      Parameters:
      name - the primitive name
      primitiveType - the primitive type
      Returns:
      the primitive instance

    • getPrimitiveAsync

      <C extends PrimitiveConfig<C>,​ P extends SyncPrimitive> CompletableFuture<P> getPrimitiveAsync​(String name, PrimitiveType<?,​C,​P> primitiveType, C primitiveConfig)
      Gets or creates a distributed primitive asynchronously.

      A new primitive of the given primitiveType will be created if no primitive instance with the given name exists on this node, otherwise the existing instance will be returned. The name is used to reference a distinct instance of the primitive within the cluster. The returned primitive will share the same state with primitives of the same name on other nodes.

      When the instance is initially constructed, it will be configured with any pre-existing primitive configuration defined in atomix.conf.

      Type Parameters:
      C - the primitive configuration type
      P - the primitive type
      Parameters:
      name - the primitive name
      primitiveType - the primitive type
      primitiveConfig - the primitive configuration
      Returns:
      a future to be completed with the primitive instance

    • primitiveBuilder

      <B extends PrimitiveBuilder<B,​ C,​ P>,​ C extends PrimitiveConfig<C>,​ P extends SyncPrimitive> B primitiveBuilder​(String name, PrimitiveType<B,​C,​P> primitiveType)
      Creates a new named primitive builder of the given primitiveType.

      The primitive name must be provided when constructing the builder. The name is used to reference a distinct instance of the primitive within the cluster. Multiple instances of the primitive with the same name will share the same state. However, the instance of the primitive constructed by the returned builder will be distinct and will not share local memory (e.g. cache) with any other instance on this node.

      To get an asynchronous instance of the primitive, use the SyncPrimitive.async() method: 

         
   AsyncPrimitive async = atomix.primitiveBuilder("my-primitive", MyPrimitiveType.instance()).build().async();
      Type Parameters:
      B - the primitive builder type
      P - the primitive type
      Parameters:
      name - the primitive name
      primitiveType - the primitive type
      Returns:
      the primitive builder

    • getPrimitives

      Collection<PrimitiveInfo> getPrimitives()
      Returns a collection of open primitives.
      Returns:
      a collection of open primitives

    • getPrimitives

      Collection<PrimitiveInfo> getPrimitives​(PrimitiveType primitiveType)
      Returns a collection of open primitives of the given type.
      Parameters:
      primitiveType - the primitive type
      Returns:
      a collection of open primitives of the given type