Package com.tccc.kos.commons.core.service.trouble

Class TroubleService

java.lang.Object
com.tccc.kos.commons.util.ready.ReadyBean
com.tccc.kos.commons.core.service.AbstractService
com.tccc.kos.commons.core.service.trouble.TroubleService
All Implemented Interfaces:
CtxEventListener, ContextHandleAware, HandleAware, Ready, ReadyListener
public final class TroubleService extends AbstractService
Service that manages troubles. Troubles are created by application code and added / removed from the service. While a trouble is registered with the service it is considered active. This service provides a number of ways for application to be notified when troubles are added / removed to facilitate actions based on the troubles.

Troubles do not persist across reboots. Generally speaking this tends not to be a problem but if persistence is required for specific troubles then application code can perform that function and simply recreate the troubles at startup.

This service implements TroubleSet which is essentially a container for troubles. This allows troubles to be added to either the service directly, or in specific use cases, added to another set and then merged into the service.

The equality of troubles is used to determine whether to add a trouble to the service. If a trouble is added but is equal to an existing trouble in the service, the new trouble will not be added. A vast majority of the time this greatly simplifies application code as it doesn't need to check if a trouble already exists before adding another instance. Care must be taken with the definition of equality when writing troubles to make sure that information in a new trouble is not lost because it is considered equal to an existing trouble without that information and thus the new trouble is discarded.

Usage

 
  public class MyClass {

      @Autowired
      private TroubleService troubleService;

      // . . .
  }
Since:
1.0
Version:
2023-03-06

  • Field Details

  • Method Details

    • getInfoFactory

      public TroubleInfoFactory getInfoFactory()
      Returns the TroubleInfoFactory . This can be used to add or remove TroubleInfo which decorates troubles.

    • log

      public void log(Trouble trouble)
      Logs a trouble. This does not add the trouble to the service, no listeners are notified and no references to the trouble are kept. This simply logs the trouble in the standard log stream. Useful for troubles that don't really do anything but are of interest from a data analytics perspective as it allows for consistent data in the stream.
      Parameters:
      trouble - the trouble to log

    • add

      public boolean add(Trouble trouble)
      Adds the specified trouble to the service. If an equal trouble exists then this trouble will not be added.
      Parameters:
      trouble - the trouble to add
      Returns:
      true if added

    • remove

      public void remove(Trouble trouble)
      Removes the specified trouble form the list.
      Parameters:
      trouble - the trouble to remove

    • removeImpacted

      public void removeImpacted(Object... objs)
      Removes all troubles where any of the specified objects are in the impact list of the trouble.
      Parameters:
      objs - the objects to match with impact lists

    • removeLinked

      public void removeLinked(Object... objs)
      Removes all troubles where any of the specified objects are in the linked list of the trouble.
      Parameters:
      objs - the objects to match with impact lists

    • removeTagged

      public void removeTagged(String tag)
      Removes all troubles that are tagged with the specified tag.
      Parameters:
      tag - the tag to check

    • resolve

      public FutureWork resolve(Trouble trouble)
      Resolves a trouble. A resolvable trouble can generally fix the underlying problem and this method is the way of triggering that action. This returns a future that needs to be started in order for the resolve process to run. If the future is successful then the trouble will automatically be removed, otherwise it will remain in the list of troubles.

      If the trouble is not resolvable this will throw NotResolvableTroubleException .

      Parameters:
      trouble - the trouble to resolve
      Returns:
      future to resolve the trouble
      Throws:
      TroubleException - if an error is detected

    • resolve

      public FutureWork resolve(Collection<Trouble> troubles)
      Resolves a list of troubles and wrap it all up in a single future. Any troubles that are not resolvable or are already in progress will be left out of the resulting future.

      Any troubles that are successful will be removed from the list while any troubles that don't resolve successfully will remain in the list.

      All troubles will be resolved in parallel and a failure of a single trouble will not impact the rest of the troubles being resolved.

      Parameters:
      troubles - the list of troubles to resolve
      Returns:
      parallel future for all the troubles

    • contains

      public boolean contains(TroubleMatcher matcher)
      Returns true if any troubles match the specified matcher.
      Parameters:
      matcher - the matcher to use
      Returns:
      true if any troubles match

    • getFirstTrouble

      public Trouble getFirstTrouble(TroubleMatcher matcher)
      Returns the first trouble that matches the matcher.
      Parameters:
      matcher - the matcher to use
      Returns:
      the first matching trouble or null

    • getTroubles

      public List<Trouble> getTroubles(TroubleMatcher matcher)
      Returns a list of troubles that match the specified matcher.
      Parameters:
      matcher - the matcher to use
      Returns:
      the list of matching troubles

    • removeTroubles

      public void removeTroubles(TroubleMatcher matcher)
      Removes all troubles that match the specified matcher.
      Parameters:
      matcher - the matcher to use

    • getTroubles

      public List<Trouble> getTroubles()
      Returns the list of all troubles. This is a copy of the active list of troubles.
      Returns:
      list of all troubles

    • contains

      public boolean contains(Trouble trouble)
      Returns true if the set contains the specified trouble.
      Parameters:
      trouble - the trouble to check
      Returns:
      true if the trouble is in the list

    • getTroubleById

      public Trouble getTroubleById(int id)
      Gets a trouble by ID.
      Parameters:
      id - the id of the trouble to return
      Returns:
      the trouble with the specified id or null

    • addListener

      public TroubleListener addListener(TroubleMatcher matcher, TroubleAware troubleAware)
      Add a TroubleAware as a listener with optional matcher. If the matcher is specified, only troubles that match will be passed to the listener. This will return a TroubleListener which combines the TroubleAware and TroubleMatcher . This listener can be used to remove the listener at a later time.
      Parameters:
      matcher - optional matcher to filter which troubles are passed
      troubleAware - receives the trouble events
      Returns:
      the constructed trouble listenser

    • addListener

      public void addListener(TroubleListener listener)
      Add a TroubleListener to the listener list. Listeners are a combination of TroubleAware and TroubleMatcher . It is typically more convenient to use an addListener() varient which handles the composition automatically.

    • removeListener

      public void removeListener(TroubleListener listener)
      Remove a TroubleListener from the listener list.

    • getListeners

      public ListenerList<TroubleListener> getListeners()