Package csw.location.api.javadsl

Interface ILocationService

  • public interface ILocationService
    A LocationService interface to manage connections and their registrations. All operations are non-blocking.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      csw.location.api.scaladsl.LocationService asScala()
      Returns the Scala API for this instance of location service
      <L extends Location>
      java.util.concurrent.CompletableFuture<java.util.Optional<L>>      		 find​(TypedConnection<L> connection)
      Resolve the location for a connection from the local cache
      java.util.concurrent.CompletableFuture<java.util.List<Location>> list()
      Lists all locations registered
      java.util.concurrent.CompletableFuture<java.util.List<Location>> list​(ComponentType componentType)
      Filters all locations registered based on a component type
      java.util.concurrent.CompletableFuture<java.util.List<Location>> list​(ConnectionType connectionType)
      Filters all locations registered based on a connection type
      java.util.concurrent.CompletableFuture<java.util.List<Location>> list​(java.lang.String hostname)
      Filters all locations registered based on a hostname
      java.util.concurrent.CompletableFuture<java.util.List<Location>> listByPrefix​(java.lang.String prefix)
      Filters all locations registered based on a prefix.
      java.util.concurrent.CompletableFuture<IRegistrationResult> register​(Registration registration)
      Registers a connection to location
      <L extends Location>
      java.util.concurrent.CompletableFuture<java.util.Optional<L>>      		 resolve​(TypedConnection<L> connection, java.time.Duration within)
      Resolves the location based on the given connection
      msocket.api.Subscription subscribe​(Connection connection, java.util.function.Consumer<TrackingEvent> consumer)
      Subscribe to tracking events for a connection by providing a consumer For each event accept method of consumer interface is invoked.
      akka.stream.javadsl.Source<TrackingEvent,​msocket.api.Subscription> track​(Connection connection)
      Tracks the connection and send events for modification or removal of its location
      java.util.concurrent.CompletableFuture<akka.Done> unregister​(Connection connection)
      Unregisters the connection
      java.util.concurrent.CompletableFuture<akka.Done> unregisterAll()
      Unregisters all connections registered

    • Method Detail

      • asScala

        csw.location.api.scaladsl.LocationService asScala()
        Returns the Scala API for this instance of location service
        Returns:
        (undocumented)

      • find

        <L extends Location> java.util.concurrent.CompletableFuture<java.util.Optional<L>> find​(TypedConnection<L> connection)
        Resolve the location for a connection from the local cache

        Parameters:
        connection - a connection to resolve to with its registered location
        Returns:
        a CompletableFuture which completes with the resolved location if found or Empty otherwise. It can fail with RegistrationListingFailed.

      • list

        java.util.concurrent.CompletableFuture<java.util.List<Location>> list()
        Lists all locations registered

        Returns:
        a CompletableFuture which completes with a List of all registered locations or can fail with RegistrationListingFailed

      • list

        java.util.concurrent.CompletableFuture<java.util.List<Location>> list​(ComponentType componentType)
        Filters all locations registered based on a component type

        Parameters:
        componentType - list components of this componentType
        Returns:
        a CompletableFuture which completes with filtered locations or can fail with RegistrationListingFailed

      • list

        java.util.concurrent.CompletableFuture<java.util.List<Location>> list​(java.lang.String hostname)
        Filters all locations registered based on a hostname

        Parameters:
        hostname - list components running on this hostname
        Returns:
        a CompletableFuture which completes with filtered locations or can fail with RegistrationListingFailed

      • list

        java.util.concurrent.CompletableFuture<java.util.List<Location>> list​(ConnectionType connectionType)
        Filters all locations registered based on a connection type

        Parameters:
        connectionType - list components of this connectionType
        Returns:
        a CompletableFuture which completes with filtered locations or can fail with RegistrationListingFailed

      • listByPrefix

        java.util.concurrent.CompletableFuture<java.util.List<Location>> listByPrefix​(java.lang.String prefix)
        Filters all locations registered based on a prefix.

        Note that all locations having subsystem prefix that starts with the given prefix value will be listed

        Parameters:
        prefix - list components by this prefix
        Returns:
        a CompletableFuture which completes with filtered locations or can fail with RegistrationListingFailed

      • register

        java.util.concurrent.CompletableFuture<IRegistrationResult> register​(Registration registration)
        Registers a connection to location

        Parameters:
        registration - the Registration holding connection and it's corresponding location to register with LocationService
        Returns:
        a CompletableFuture which completes with Registration result or can fail with RegistrationFailed or OtherLocationIsRegistered

      • resolve

        <L extends Location> java.util.concurrent.CompletableFuture<java.util.Optional<L>> resolve​(TypedConnection<L> connection,
                                                                                           java.time.Duration within)
        Resolves the location based on the given connection

        Parameters:
        connection - a connection to resolve to with its registered location
        within - the time for which a connection is looked-up within LocationService
        Returns:
        a CompletableFuture which completes with the resolved location if found or None otherwise. It can fail with RegistrationListingFailed.

      • subscribe

        msocket.api.Subscription subscribe​(Connection connection,
                                   java.util.function.Consumer<TrackingEvent> consumer)
        Subscribe to tracking events for a connection by providing a consumer For each event accept method of consumer interface is invoked. Use this method if you do not want to handle materialization and happy with a side-effecting callback instead

        Note that callbacks are not thread-safe on the JVM. If you are doing side effects/mutations inside the callback, you should ensure that it is done in a thread-safe way inside an actor.

        Parameters:
        connection - the connection that is to be tracked
        consumer - the Consumer function that consumes TrakingEvent
        Returns:
        a killswitch which can be shutdown to unsubscribe the consumer

      • track

        akka.stream.javadsl.Source<TrackingEvent,​msocket.api.Subscription> track​(Connection connection)
        Tracks the connection and send events for modification or removal of its location

        Parameters:
        connection - the connection that is to be tracked
        Returns:
        A stream that emits events related to the connection. It can be cancelled using KillSwitch. This will stop giving events for earlier tracked connection

      • unregister

        java.util.concurrent.CompletableFuture<akka.Done> unregister​(Connection connection)
        Unregisters the connection

        Note that this method is idempotent, which means multiple calls to unregister the same connection will be no-op once successfully unregistered from location service

        Parameters:
        connection - an already registered connection
        Returns:
        a CompletableFuture which completes after un-registration happens successfully and fails otherwise with UnregistrationFailed

      • unregisterAll

        java.util.concurrent.CompletableFuture<akka.Done> unregisterAll()
        Unregisters all connections registered

        Note that it is highly recommended to use this method for testing purpose only

        Returns:
        a CompletableFuture which completes after all connections are unregistered successfully or fails otherwise with RegistrationListingFailed