Package com.tccc.kos.ext.dispense.pipeline.beverage

Class BeveragePourEngine<T extends BeveragePourEngineConfig>

java.lang.Object
com.tccc.kos.ext.dispense.pipeline.beverage.BeveragePourEngine<T>
All Implemented Interfaces:
com.tccc.kos.commons.core.service.config.ConfigAware<T>, com.tccc.kos.commons.core.service.handle.HandleAware, IngredientChangeListener, InsertionListener, InsertionPumpListener, NozzleAvailabilityListener
public abstract class BeveragePourEngine<T extends BeveragePourEngineConfig> extends Object implements com.tccc.kos.commons.core.service.config.ConfigAware<T>, NozzleAvailabilityListener, IngredientChangeListener, InsertionPumpListener
Base class for an engine used by the pour pipeline to abstract a way to pour a beverage and handle the actual pour implementation.
Since:
1.0
Version:
2023-02-06

  • Constructor Details

    • BeveragePourEngine

      public BeveragePourEngine()

  • Method Details

    • getPipeline

      public BeverageNozzlePipeline getPipeline()
      The pipeline the engine is part of.

    • getNozzle

      public Nozzle getNozzle()
      The nozzle the engine is associated with.

    • start

      public abstract void start()
      Called once the pipeline is installed and the engine has been autowired. This can be used to setup the engine prior to use.

    • stop

      public abstract void stop()
      Called to shutdown the engine when it is about to be uninstalled.

    • getPourable

      public abstract Pourable getPourable(String definitionStr) throws Exception
      Given a definitionStr string, return a pourable. The definition is opaque to all parts of the system other than the pour engine. In general the engine will expose beverage data via availability and the definition will be sent from the ui back to the engine based on user selection. However, it is also possible for a ui to gather multiple inputs from the user to include in the definition which the pour engine then uses to construct a complex pour process.

      A Pourable is intended to be long living and survive graph rebuilds. It's typical to hold an instance of a pourble to represent the selected beverage and then clone it for actual use. Based on this, the pourable should not contain references to graph nodes which may change over time. For example, a pourable may hold a beverageId instead of a reference to a BeveageNode as the node can be looked up when it's time to perform the pour.

      The implementation can support different styles of pouring. The definitionStr passed to this method will never be used anywhere else and can represent complex data about the pour which is used by this method to construct one of potentially many types of Pourable or even custom built Pourable instances, such as if the definitionStr contains recipe data.

      Parameters:
      definitionStr - the string used to describe what to pour
      Throws:
      Exception

    • isPourable

      public abstract boolean isPourable(Pourable pourable)
      Return true if the specified pourable can currently be poured.
      Parameters:
      pourable - the pourable to check

    • rebuildGraph

      public abstract void rebuildGraph(BevGraphBuilder builder)
      Callback at key events that require the beverage graph to be rebuilt. Return the new graph and it will be installed automatically. The builder includes the list of pumps with ingredients assigned and the builder will already include pump nodes based on the pump paths.

      Most applications will also call builder.addIngredientNodes() to also create nodes for all the ingredients in the pumps which allows a graph to be constructed using ingredients, not pumps.

      Parameters:
      builder - the graph builder used to build the graph

    • onRebuildGraph

      public void onRebuildGraph(BevGraph graph)
      Called after rebuildGraph() returns so the engine can populate any state into the newly created graph. Pump and ingredient nodes will be updated with state before this is called. Override as needed.
      Parameters:
      graph - the graph to add state to

    • asyncRebuildGraph

      public void asyncRebuildGraph()
      Trigger an async rebuild of the graph.

    • notifyChanges

      public void notifyChanges()
      Indicate that any changes in availability / visibility have been completed and the changes should be processed.

    • getBeverageNode

      public BeverageNode getBeverageNode(String nodeId)
      Return the BeverageNode with the specified id.
      Parameters:
      nodeId - id of the node to return

    • getIngredientNode

      public IngredientNode getIngredientNode(String nodeId)
      Return the IngredientNode with the specified id.
      Parameters:
      nodeId - id of the node to return

    • isAvailable

      public boolean isAvailable(String nodeId)
      Return true if the specified graph node exists and is available. This tends to be an easy way to verify a beverage is pourable by passing in the beverageId.
      Parameters:
      nodeId - the beverage graph node id to check

    • isAvailable

      public boolean isAvailable(List<String> nodeIds)
      Return true if all the specified graph nodes exist and are available. This is a convenient way to check a list of nodes at the same time such as when verifying that a list of flavors for a beverage are available.
      Parameters:
      nodeIds - list of beveerage graph node ids to check

    • onAvailabilityChange

      public void onAvailabilityChange(List<Pump<?>> pumps)
      Called when pump availability changes on the nozzle. Any changes to pump availability will already be merged into the graph. Override this if application logic requires additional state changes as a side effect of pump availability changes.

      notifyChanges() will be called when this returns which will cause any beverage / brand / group changes to be sent to external listeners.

      Parameters:
      pumps - list of pumps that have changed availability

    • addOverride

      public void addOverride(NodeOverride override)
      Add an override callback to the associated node. Any time the node visibility / availability is recomputed the callback will be called and it will have the ability to override these values. This is useful for use cases such as external control of visibility of particular beverages. These callbacks will be automatically connected to the BevGraph each time it is rebuilt. This will cause the existing graph to update.
      Parameters:
      override - the override to attach to the node

    • addOverride

      public void addOverride(NodeOverride override, boolean update)
      Add an override callback to the associated node. Any time the node visibility / availability is recomputed the callback will be called and it will have the ability to override these values. This is useful for use cases such as external control of visibility of particular beverages. These callbacks will be automatically connected to the BevGraph each time it is rebuilt. The existing graph will only update based on the update flag.
      Parameters:
      override - the override to attach to the node
      update - if false, existing graph will not update

    • removeOverride

      public void removeOverride(NodeOverride override)
      Remove an override from the the engine.

    • removeOverride

      public void removeOverride(NodeOverride override, boolean update)
      Remove an override from the the engine with ability to control the graph update. In cases where overrides are being removed as part of constructing a new graph, there is no need to update the existing graph so update can be set to false.
      Parameters:
      override - the override to remove
      update - if false, existing graph will not update

    • getNodeProperties

      public Map<String,Object> getNodeProperties(String nodeId)
      Return properties for the specified node.
      Parameters:
      nodeId - id of the node to return properties for

    • clearNodeProperties

      public void clearNodeProperties(String nodeId)
      Clear all the properties for the specified node.
      Parameters:
      nodeId - id of the node clear

    • setNodeProperty

      public void setNodeProperty(String nodeId, String name, Object val)
      Set a property on a node. This will be visible via the beverage graph data and will trigger an update to the UI. Setting a property with a null value removes the property.
      Parameters:
      nodeId - id of the node the property is for
      name - name of the property
      val - value of the property

    • removeNodeProperty

      public void removeNodeProperty(String nodeId, String name)
      Remove a property from a node.
      Parameters:
      nodeId - id of the node containing the property
      name - name of the property to remove

    • startPump

      public void startPump(Pump<?> pump, Pourable pourable)
      Generate pump lifecycle events for a beverage pour. This indicates that the specified pump is about to start. The first time this method is called for a given pump during a beverage pour, it will first generate a lock lifecycle event followed by a start lifecycle event. Subsequent calls to this method will generate no events unless stopPump() has been called first. All locked pumps associated with the pour will be unlocked at the end of the pour.

      It is critical that startPump() or startPumps() be called for every pump involved in a beverage pour in order to ensure that standard pump lifecycle events are generated within KOS.

      It is possible that a pump start/stops multiple times during a beverage pour. The startPump() and stopPump() methods can be called multiple times during a pour to generate granular lifecycle events if needed. Pump lock and unlock events will only occur once during a pour.

      This does not actually start the physical pump. This simply generates the callbacks indicating that the pump has started (or is about to start).

      Parameters:
      pump - the pump to mark started
      pourable - the pourable being poured

    • startPumps

      public void startPumps(Collection<? extends Pump<?>> pumps, Pourable pourable)
      Collection version of startPump() allowing multiple pumps to be started in a single call. See startPump() for details.

    • stopPump

      public void stopPump(Pump<?> pump)
      Generate a stop lifecycle event for a pump. All pumps passed to startPump() will automatically generate stop events at the end of the pour. However, if there is a need for more granular control over start/stop events, these methods can be called manually and multiple times during a beverage pour.

      This does not actually stop the physical pump. This simply generates the callbacks indicating that the pump has topped (or is about to stop).

      Parameters:
      pump - the pump that has stopped

    • stopPumps

      public void stopPumps(Collection<? extends Pump<?>> pumps)
      Collection version of stopPump() allowing multiple pumps to be stopped in a single call. See stopPump() for details.

    • onNozzleAvailabilityChange

      public final void onNozzleAvailabilityChange(Nozzle nozzle, List<Pump<?>> pumps)
      Description copied from interface: NozzleAvailabilityListener
      Called when there are changes to pump availability. This will include the nozzle that changed and a list of pumps that changed availability. The ingredientPour and beveragePour flags in the pump indicate whether the pump can be used for ingredient / beverage pouring. If not available, the unavailableReasons provides information about the limitation which can be useful for debugging.
      Specified by:
      onNozzleAvailabilityChange in interface NozzleAvailabilityListener
      Parameters:
      nozzle - the nozzle the changed
      pumps - the pumps that changed availability

    • onIngredientChange

      public void onIngredientChange(IngredientService svc, String name, IngredientSource source)
      Description copied from interface: IngredientChangeListener
      Called when a new IngredientSource is installed into IngredientService . This can mean that any existing ingredients may now be unknown. It may also mean that previously unknown ingredients are now known.
      Specified by:
      onIngredientChange in interface IngredientChangeListener
      Parameters:
      svc - the ingredient service
      name - id of the source
      source - the IngrediengSource that was added or changed, null for removed

    • onContainerInserted

      public void onContainerInserted(Container container, Pump<?> pump)
      Description copied from interface: InsertionPumpListener
      Called when a container is inserted all the way to a pump. At this point the pump inserted flag is set the and pump can be used normally.
      Specified by:
      onContainerInserted in interface InsertionPumpListener
      Parameters:
      container - the container that was inserted
      pump - the pump inserted into

    • onContainerRemoved

      public void onContainerRemoved(Container container, Pump<?> pump)
      Description copied from interface: InsertionPumpListener
      Called when a container is removed. This callback will be called prior to the holder remove callback.
      Specified by:
      onContainerRemoved in interface InsertionPumpListener
      Parameters:
      container - the container that was removed
      pump - the associated pump

    • onConfigChanged

      public void onConfigChanged(com.tccc.kos.commons.core.service.config.BeanChanges changes)
      Specified by:
      onConfigChanged in interface com.tccc.kos.commons.core.service.config.ConfigAware<T extends BeveragePourEngineConfig>

    • getIngredientService

      public IngredientService getIngredientService()

    • getHandle

      public com.tccc.kos.commons.core.service.handle.Handle getHandle()
      Specified by:
      getHandle in interface com.tccc.kos.commons.core.service.handle.HandleAware

    • getGraph

      public BevGraph getGraph()

    • getConfig

      public T getConfig()
      Specified by:
      getConfig in interface com.tccc.kos.commons.core.service.config.ConfigAware<T extends BeveragePourEngineConfig>

    • setConfig

      public void setConfig(T config)
      Specified by:
      setConfig in interface com.tccc.kos.commons.core.service.config.ConfigAware<T extends BeveragePourEngineConfig>