Class ExtensionId<T extends Extension>

  • Type Parameters:
    T - The concrete extension type
    Direct Known Subclasses:
    ActorFlightRecorder$, ActorRefResolver$, Cluster$, ClusterSharding$, ClusterSingleton$, DistributedData$, DistributedData$, EventStreamExtension$, Receptionist$, ReplicatedShardingExtension$, ShardedDaemonProcess$

    public abstract class ExtensionId<T extends Extension>
    extends java.lang.Object
    Identifier and factory for an extension. Is used to look up an extension from the ActorSystem, and possibly create an instance if no instance was already registered. The extension can also be listed in the actor system configuration to have it eagerly loaded and registered on actor system startup.

    *Scala API*

    The ExtensionId for an extension written in Scala is best done by letting it be the companion object of the extension. If the extension will be used from Java special care needs to be taken to provide a get method with the concrete extension type as return (as this will not be inferred correctly by the Java compiler with the default implementation)

    Example:

    
     object MyExt extends ExtensionId[Ext] {
    
       override def createExtension(system: ActorSystem[_]): MyExt = new MyExt(system)
    
       // Java API: retrieve the extension instance for the given system.
       def get(system: ActorSystem[_]): MyExt = apply(system)
     }
    
     class MyExt(system: ActorSystem[_]) extends Extension {
       ...
     }
    
     // can be loaded eagerly on system startup through configuration
     // note that the name is the JVM/Java class name, with a dollar sign in the end
     // and not the Scala object name
     pekko.actor.typed.extensions = ["com.example.MyExt$"]
    
     // Allows access like this from Scala
     MyExt().someMethodOnTheExtension()
     // and from Java
     MyExt.get(system).someMethodOnTheExtension()
     

    *Java API*

    To implement an extension in Java you should first create an ExtensionId singleton by implementing a static method called getInstance, this is needed to be able to list the extension among the pekko.actor.typed.extensions in the configuration and have it loaded when the actor system starts up.

    
    
     public class MyExt extends AbstractExtensionId<MyExtImpl> {
       // single instance of the identifier
       private final static MyExt instance = new MyExt();
    
       // protect against other instances than the singleton
       private MyExt() {}
    
       // This static method singleton accessor is needed to be able to enable the extension through config when
       // implementing extensions in Java.
       public static MyExt getInstance() {
         return instance;
       }
    
       public MyExtImpl createExtension(ActorSystem<?> system) {
         return new MyExtImpl();
       }
    
       // convenience accessor
       public static MyExtImpl get(ActorSystem<?> system) {
          return instance.apply(system);
       }
     }
    
     public class MyExtImpl implements Extension {
        ...
     }
    
     // can be loaded eagerly on system startup through configuration
     pekko.actor.typed.extensions = ["com.example.MyExt"]
    
     // Allows access like this from Scala
     MyExt.someMethodOnTheExtension()
     // and from Java
     MyExt.get(system).someMethodOnTheExtension()
     

    For testing purposes extensions typically provide a concrete ExtensionSetup that can be used in pekko.actor.setup.ActorSystemSetup when starting the ActorSystem to replace the default implementation of the extension.

    See Also:
    ExtensionSetup
    • Constructor Summary

      Constructors 
      Constructor Description
      ExtensionId()  
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      T apply​(ActorSystem<?> system)
      Lookup or create an instance of the extension identified by this id.
      abstract T createExtension​(ActorSystem<?> system)
      Create the extension, will be invoked at most one time per actor system where the extension is registered.
      boolean equals​(java.lang.Object other)  
      int hashCode()  
      ExtensionId<T> id()
      Java API: The identifier of the extension
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ExtensionId

        public ExtensionId()
    • Method Detail

      • apply

        public final T apply​(ActorSystem<?> system)
        Lookup or create an instance of the extension identified by this id.
      • createExtension

        public abstract T createExtension​(ActorSystem<?> system)
        Create the extension, will be invoked at most one time per actor system where the extension is registered.
      • equals

        public final boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • id

        public ExtensionId<T> id()
        Java API: The identifier of the extension