Package com.microsoft.azure.eventprocessorhost

Class EventProcessorHost

  • public final class EventProcessorHost
extends Object
    The main class of event processor host.

    • Method Detail

      • createHostName

        public static String createHostName​(String prefix)
        Convenience method for generating unique host names, safe to pass to the EventProcessorHost constructors that take a hostName argument.

        If a prefix is supplied, the constructed name begins with that string. If the prefix argument is null or an empty string, the constructed name begins with "javahost". Then a dash '-' and a UUID are appended to create a unique name.

        Parameters:
        prefix - String to use as the beginning of the name. If null or empty, a default is used.
        Returns:
        A unique host name to pass to EventProcessorHost constructors.

      • safeCreateUUID

        public static String safeCreateUUID()
        Synchronized string UUID generation convenience method.

        We saw null and empty strings returned from UUID.randomUUID().toString() when used from multiple threads and there is no clear answer on the net about whether it is really thread-safe or not.

        One of the major users of UUIDs is the built-in lease and checkpoint manager, which can be replaced by user implementations. This UUID generation method is public so user implementations can use it as well and avoid the problems.

        Returns:
        A string UUID with dashes but no curly brackets.

      • getHostName

        public String getHostName()
        The processor host name is supplied by the user at constructor time, but being able to get it is useful because it means not having to carry both the host object and the name around. As long as you have the host object, you can get the name back, such as for logging.
        Returns:
        The processor host name

      • getPartitionManagerOptions

        public PartitionManagerOptions getPartitionManagerOptions()
        Returns the existing partition manager options object. Unless you are providing implementations of ILeaseManager and ICheckpointMananger, to change partition manager options, call this method to get the existing object and call setters on it to adjust the values.
        Returns:
        the internally-created PartitionManangerObjects object or any replacement object set with setPartitionManangerOptions

      • setPartitionManagerOptions

        public void setPartitionManagerOptions​(PartitionManagerOptions options)
        Set the partition manager options all at once. Normally this method is used only when providing user implementations of ILeaseManager and ICheckpointManager, because it allows passing an object of a class derived from PartitionManagerOptions, which could contain options specific to the user-implemented ILeaseManager or ICheckpointMananger. When using the default, Azure Storage-based implementation, the recommendation is to call getPartitionManangerOptions to return the existing options object, then call setters on that object to adjust the values.
        Parameters:
        options - - a PartitionManangerOptions object (or derived object) representing the desired options

      • registerEventProcessor

        public <T extends IEventProcessor> CompletableFuture<Void> registerEventProcessor​(Class<T> eventProcessorType)
        Register class for event processor and start processing.

        This overload uses the default event processor factory, which simply creates new instances of the registered event processor class, and uses all the default options.

        The returned CompletableFuture completes when host initialization is finished. Initialization failures are reported by completing the future with an exception, so it is important to call get() on the future and handle any exceptions thrown. 

         class MyEventProcessor implements IEventProcessor { ... }
 EventProcessorHost host = new EventProcessorHost(...);
 CompletableFuture<Void> foo = host.registerEventProcessor(MyEventProcessor.class);
 foo.get();
        Type Parameters:
        T - Not actually a parameter. Represents the type of your class that implements IEventProcessor.
        Parameters:
        eventProcessorType - Class that implements IEventProcessor.
        Returns:
        Future that completes when initialization is finished.

      • registerEventProcessor

        public <T extends IEventProcessor> CompletableFuture<Void> registerEventProcessor​(Class<T> eventProcessorType,
                                                                                  EventProcessorOptions processorOptions)
        Register class for event processor and start processing.

        This overload uses the default event processor factory, which simply creates new instances of the registered event processor class, but takes user-specified options.

        The returned CompletableFuture completes when host initialization is finished. Initialization failures are reported by completing the future with an exception, so it is important to call get() on the future and handle any exceptions thrown.

        Type Parameters:
        T - Not actually a parameter. Represents the type of your class that implements IEventProcessor.
        Parameters:
        eventProcessorType - Class that implements IEventProcessor.
        processorOptions - Options for the processor host and event processor(s).
        Returns:
        Future that completes when initialization is finished.

      • registerEventProcessorFactory

        public CompletableFuture<Void> registerEventProcessorFactory​(IEventProcessorFactory<?> factory)
        Register a user-supplied event processor factory and start processing.

        If creating a new event processor requires more work than just new'ing an objects, the user must create an object that implements IEventProcessorFactory and pass it to this method, instead of calling registerEventProcessor.

        This overload uses default options for the processor host and event processor(s).

        The returned CompletableFuture completes when host initialization is finished. Initialization failures are reported by completing the future with an exception, so it is important to call get() on the future and handle any exceptions thrown.

        Parameters:
        factory - User-supplied event processor factory object.
        Returns:
        Future that completes when initialization is finished.

      • registerEventProcessorFactory

        public CompletableFuture<Void> registerEventProcessorFactory​(IEventProcessorFactory<?> factory,
                                                             EventProcessorOptions processorOptions)
        Register user-supplied event processor factory and start processing.

        This overload takes user-specified options.

        The returned CompletableFuture completes when host initialization is finished. Initialization failures are reported by completing the future with an exception, so it is important to call get() on the future and handle any exceptions thrown.

        Parameters:
        factory - User-supplied event processor factory object.
        processorOptions - Options for the processor host and event processor(s).
        Returns:
        Future that completes when initialization is finished.

      • unregisterEventProcessor

        public CompletableFuture<Void> unregisterEventProcessor()
        Stop processing events and shut down this host instance.
        Returns:
        A CompletableFuture that completes when shutdown is finished.