Packages

  • package root
    Definition Classes
    root
  • package csw
    Definition Classes
    root
  • package services
    Definition Classes
    csw
  • package command

    This project defines the basic classes and traits for the Command Service.

    Command Service

    This project defines the basic classes and traits for the Command Service.

    Related projects are: - csw-messages:

    • This defines the types of command (Oneway/Submit etc.) and types of configurations (Setup/Observe/Wait etc.)
    • Complete usage of Messages is available at: https://tmtsoftware.github.io/csw-prod/services/messages.html

    - framework:

    • This defines the Hcd and Assembly handlers, lifecycle manager and supervisor for components.
    • Framework allows component writer to override onValidation, onSubmit and onOneway handlers. (Note it allows overriding other handlers as well.)
    • On every command received by component, onValidation handler gets invoked where received command gets validated and validation response is returned.
    • Based on validation response and command type, onSubmit/onOneway hooks gets invoked where command gets processed.
    • Complete details of handling commands can be found here : https://tmtsoftware.github.io/csw-prod/framework/handling-lifecycle.html#handling-commands

    Important classes in this project are:

    - csw.services.command.CommandResponseManager

    This class wraps CommandResponseManagerActor and provides helpers to interact with actor which is responsible for adding/updating/querying command result. Component writers will get handle to CommandResponseManager in their handlers.

    - csw.services.command.internal.CommandResponseManagerBehavior maintains two states:

    • csw.messages.commands.CommandResponseManagerState: It maintains csw.messages.params.models.Id of Commands and their corresponding csw.messages.commands.CommandState.
    • csw.messages.commands.CommandCorrelation : It maintains commands csw.messages.params.models.Id correlation between parent to child and child to parent.

    - csw.services.command.scaladsl.CommandService

    This class wraps the csw.messages.location.AkkaLocation and provides helpers to send commands to component actor extracted from provided location. Normal component writers workflow would be to first resolve component using location service and then create CommandService instance using resolved location.

    Using this instance, you can Submit Command/Commands to other component or query for command result or subscribe for long running command result.

    - csw.services.command.scaladsl.CommandDistributor

    When you have multiple commands targeted to multiple components then you can use ConfigDistributor. Using CommandDistributor utility you can send all these commands in one go and get aggregated response.

    Complete guide of usage of different API's provided by CommandService is available at: https://tmtsoftware.github.io/csw-prod/command.html

    Definition Classes
    services
  • package javadsl
  • package scaladsl
  • CommandResponseManager
  • package config
    Definition Classes
    services
  • package event

    This module implements an Event Service responsible for publishing an csw.messages.events.Event or subscribing to an csw.messages.events.Event.

    Event Service

    This module implements an Event Service responsible for publishing an csw.messages.events.Event or subscribing to an csw.messages.events.Event. An event is published on a csw.messages.events.EventKey. The event key is composed of a csw.messages.params.models.Prefix depicting the source and an csw.messages.events.EventName. The subscriber can subscribe to the csw.messages.events.EventKey to receive all events published on the Key.

    Example: Event Service
    val eventServiceFactory          = new EventServiceFactory()
    val eventService: EventService   = eventServiceFactory.make(locationService)

    Using above code, you can create instance of csw.services.event.api.scaladsl.EventService. EventService is the factory to create publishers and subscribers.

    You can choose to use defaultPublisher in case you want to share same connection for publishing different events.

    Example: Event Publisher

    Event Publisher provides asynchronous APIs to publish one or more Events

    val event = SystemEvent(prefix, EventName("filter_wheel"))
    
    val publisher    = eventService.defaultPublisher
    publisher.publish(event)
    Example: Event Subscriber (subscribe and get API)

    Event Subscriber provides asynchronous APIs to subscribe to one or more Event Keys. It also provides APIs to subscribe using a pattern. In addition, there are APIs to get latest events for one ore more Event Keys without making a subscription

    The EventSubscriber provides various API's to subscribe to csw.messages.events.EventKey. One of such a subscribe method takes an ActorRef of an arbitrary actor or a callback function to be called when an event matching the given csw.messages.events.EventKey is received. In the example below, we only provide the callback argument value. You could also provide an ActorRef of some actor that should receive the Event message.

     def callback(ev: Event): Unit = {
       // ...
     }
    
     async {
       val subscriber    = eventService.defaultSubscriber
       subscriber.subscribeCallback(Set(EventKey(prefix, EventName("filter_wheel"))), callback)
    
       val event = await(subscriber.get(event.eventKey))
    
       event match {
         case e: ObserveEvent => assert(e.prefix == expectedPrefix)
         case _               => fail("Expected ObserveEvent")
       }
    }

    csw-prod provides two implementations for Event Service which can be accessed through csw-event-client : 1. csw.services.event.internal.redis.RedisEventService - Redis as event store and publisher/subscriber functionality 2. csw.services.event.internal.kafka.KafkaEventService - Kafka as event store and publisher/subscriber functionality

    Complete guide of usage of different API's provided by EventService is available at: https://tmtsoftware.github.io/csw-prod/services/event.html

    Definition Classes
    services
  • package location

    The Location Service implemented in this project is based on CRDT (Conflict Free Replicated Data).

    Location Service

    The Location Service implemented in this project is based on CRDT (Conflict Free Replicated Data). The Location Service helps you resolve the hostname and port number for a service which can be used for further communication. In case of Akka connection, It helps you to resolve component reference with which you can send messages as well as other information for example, logAdminActorRef which is used to dynamically change the log level of component.

    Location Service supports three types of services as follows: Akka, Tcp and HTTP based services.

    Before calling LocationServiceFactory.make() to get an handle of LocationService, it is recommended to have below environment variables set to System global environments or system properties:

    • interfaceName (The network interface where akka cluster is formed.) Ex. interfaceName=eth0 if not set, first inet4 interface by priority will be picked
    • clusterSeeds (The host address and port of the seedNodes of the cluster) Ex. clusterSeeds="192.168.121.10:3552, 192.168.121.11:3552"
    • clusterPort (Specify port on which to start this service) Ex. clusterPort=3552 if this property is not set, service will start on random port.

    Location service make use of classes defined in csw-messages package, for example: - csw.messages.location.Location : When you resolve component location using csw.services.location.scaladsl.LocationService, you get back this location. There are three types of Locations:

    - csw.messages.location.Connection : Connection holds the identity of component which includes component name and csw.messages.location.ComponentType. Every component needs to register with location service using unique connection. There are three types of Connections:

    Another important actor from LocationService is DeathwatchActor csw.services.location.internal.DeathwatchActor which gets created with LocationService initialization. Job of this actor is to watch health of every component and on termination, unregister terminated component from LocationService.

    Complete guide of usage of different API's provided by LocationService is available at: https://tmtsoftware.github.io/csw-prod/services/location.html

    Definition Classes
    services
  • package logging

    This is a Actor based logging library which supports writing logs to File and StdOut Console.

    Logging Service

    This is a Actor based logging library which supports writing logs to File and StdOut Console.

    Features
    • Supports component specific log levels, ex. HCD1 can choose to log at info level and HCD2 can choose to log at debug level
    • Supports dynamically changing component log levels
    • Asynchronous thread safe logging
    • Structured logging
    • Supports overriding default logging properties per component viz
    • Intercepting logs from akka/slf4j
    • Supports JSON logging
    LogActor

    LogActor is the heart of logging library. It receives messages from following classes:

    • Slf4jAppender: Intercepts Slf4j logs and forwards it to LogActor via MessageHandler
    • AkkaLogger: Intercepts Akka logs and forwards it to LogActor via MessageHandler.
    • LoggerImpl: Provides csw logging API for component writer to log messages which gets forwarded to LogActor via MessageHandler
    Logging Appenders

    This library supports two types of csw.services.logging.appenders.LogAppender:

    You can specify the appender in application.conf file as shown below:

    csw-logging {
       appenders = ["csw.services.logging.appenders.StdOutAppender$", "csw.services.logging.appenders.FileAppender$"]
     }
    Component Specific Log Levels

    For each component, ComponentLoggingState instance gets created which maintains log levels which are enabled and disabled for this particular component. Every time message gets logged by component, LoggerImpl checks in corresponding componentLoggingState whether current log level enabled or not. If enabled, then only log message gets forwarded to LogActor via MessageHandler.

    You can specify the component specific log levels in application.conf file as shown below:

    component-log-levels {
       tromboneHcd = debug
       tromboneAssembly = error
    }

    ̄ Detailed documentation of Logging Service is available at: https://tmtsoftware.github.io/csw-prod/services/logging.html

    Definition Classes
    services
p

csw.services

command

package command

Command Service

This project defines the basic classes and traits for the Command Service.

Related projects are: - csw-messages:

  • This defines the types of command (Oneway/Submit etc.) and types of configurations (Setup/Observe/Wait etc.)
  • Complete usage of Messages is available at: https://tmtsoftware.github.io/csw-prod/services/messages.html

- framework:

  • This defines the Hcd and Assembly handlers, lifecycle manager and supervisor for components.
  • Framework allows component writer to override onValidation, onSubmit and onOneway handlers. (Note it allows overriding other handlers as well.)
  • On every command received by component, onValidation handler gets invoked where received command gets validated and validation response is returned.
  • Based on validation response and command type, onSubmit/onOneway hooks gets invoked where command gets processed.
  • Complete details of handling commands can be found here : https://tmtsoftware.github.io/csw-prod/framework/handling-lifecycle.html#handling-commands

Important classes in this project are:

- csw.services.command.CommandResponseManager

This class wraps CommandResponseManagerActor and provides helpers to interact with actor which is responsible for adding/updating/querying command result. Component writers will get handle to CommandResponseManager in their handlers.

- csw.services.command.internal.CommandResponseManagerBehavior maintains two states:

  • csw.messages.commands.CommandResponseManagerState: It maintains csw.messages.params.models.Id of Commands and their corresponding csw.messages.commands.CommandState.
  • csw.messages.commands.CommandCorrelation : It maintains commands csw.messages.params.models.Id correlation between parent to child and child to parent.

- csw.services.command.scaladsl.CommandService

This class wraps the csw.messages.location.AkkaLocation and provides helpers to send commands to component actor extracted from provided location. Normal component writers workflow would be to first resolve component using location service and then create CommandService instance using resolved location.

Using this instance, you can Submit Command/Commands to other component or query for command result or subscribe for long running command result.

- csw.services.command.scaladsl.CommandDistributor

When you have multiple commands targeted to multiple components then you can use ConfigDistributor. Using CommandDistributor utility you can send all these commands in one go and get aggregated response.

Complete guide of usage of different API's provided by CommandService is available at: https://tmtsoftware.github.io/csw-prod/command.html

Linear Supertypes

Type Members

  1. class CommandResponseManager extends AnyRef

    Wrapper API for interacting with Command Response Manager of a component

Inherited from AnyRef

Inherited from Any

Ungrouped