Package com.tccc.kos.ext.dispense

Class Container

java.lang.Object
com.tccc.kos.ext.dispense.Container
Direct Known Subclasses:
IntrinsicContainer, LockedContainer
public class Container extends Object
Abstraction of a something that holds one or more an ingredient such as a cartridge or box of BiB ingredient.

While most containers are simply cardboard boxes with plastic liners, some containers have attributes such as codes printed on them or even RFID tags that provide a great deal of information about the contents. In some cases, a single container may even contain multiple ingredients, such as a Freestyle double cartridge. Ingredients are abstracted within a container using ContainerSlice objects, where each slice defines an associated ingredient.

A container includes a unique ID. This is used to detect container changes even when the ingredient hasn't changed and allows business logic to be triggered on these changes. In cases where the physical container has a unique ID, such as an RFID tag, this also allows for detection of swapped ingredients while the system is powered down.

Features of kOS are free to use the ID to persist meta-data about the container, such as fuelGauge data or other information. For this reason it's important that IDs are consistent across reboots (where applicable). In some cases, such as when using AssignmentService, the service will manage the persistence of IDs across reboots, but any custom logic must be aware of the requirement to avoid triggering business logic when not applicable.

This service also supports mark-and-sweep functionality for containers. By setting the source and mark properties of a container, it is possible at a later point to sweep (remove) all containers with the specified source and a mark other than the one specified. This can be particularly useful for containers that self-identify, such as using rfid tags, where the container was removed while the device was turned off. By inserting with a unique mark on each power cycle, all active containers will have the new mark, while all removed containers will have an old mark. These can then be removed by sweeping them.

Since:
1.0
Version:
2023-01-16

  • Constructor Details

    • Container

      public Container(String id, ContainerSlice slice)
      Creates a new container with the specified ID and single slice.
      Parameters:
      id - ID of the container
      slice - slice in the container

    • Container

      public Container(String id, ContainerSlice[] slices)
      Creates a new container with the specified ID and slices.
      Parameters:
      id - ID of the container
      slices - array of slices in left to right order

  • Method Details

    • getId

      public String getId()
      Returns an optional unique ID for this container. Not all containers support this, but some, like RFID tag-based containers, do. This is used by the mapping layer to streamline some insertion logic, but is otherwise not required.
      Returns:
      the unique ID for this container

    • setId

      public void setId(String id)
      Sets the ID of the container, if available.
      Parameters:
      id - the new container ID to use

    • getIngredientIds

      public String[] getIngredientIds()
      Returns the list of ingredient IDs in the container in the same order as the associated slices.
      Returns:
      the ingredient IDs in the container

    • getFirstIngredientId

      public String getFirstIngredientId()
      Returns the first ingredient ID.
      Returns:
      the first ingredientId in the container

    • getSlices

      public ContainerSlice[] getSlices()
      Returns the array of slices in the container.
      Returns:
      the array of slices in the container

    • getSlice

      public ContainerSlice getSlice(int idx)
      Returns the specified slice.
      Parameters:
      idx - the index of the slice
      Returns:
      the slice

    • isIntrinsic

      public boolean isIntrinsic()
      Returns true if this container is an intrinsic ingredient such as plain or carbonated water. This bypasses all filter checks in the insertion service. This should only be used for water/carb, which are unconditionally assigned to holders/pumps at startup by the assembly. Other ingredients that seem intrinsic, such as HFCS or NNS, should typically still use regular container so that the first insertion can trigger filter-based business logic, such as requiring the pump to be primed.

    • isLocked

      public boolean isLocked()
      Returns true if this container cannot be removed once inserted. This is commonly used in conjunction with intrinsic containers.

    • getInsertTime

      public long getInsertTime()
      Return the time when the container was first inserted. This will not change across reboots, but will reset if the container is removed and inserted again. Returns zero if not currently fully inserted.

    • getSource

      public String getSource()
      Return the source of the cartridge.

    • setSource

      public void setSource(String source)
      Set the source of the cartridge. This exists to support mark-and-sweep functionality for cartridges that self-identify (such as with RFID tags). This is rarely needed in most applications and can be left unset. When used, this is typically set to an unchanging value relative to where the container was detected. For example, when using RFID, this might be the id of the antenna that detected the tag.

    • getMark

      public String getMark()
      Return the source of the cartridge.

    • setMark

      public void setMark(String mark)
      Set the mark of the cartridge. This exists to support mark-and-sweep functionality for cartridges that self-identify (such as with RFID tags). This is rarely needed in most applications and can be left unset. When used, this is used to mark cartridges that still exist from the source. For example, on each reboot a new mark is selected and all cartridges for a given source are re-inserted using the current mark. Once complete, a mark-and-sweep cycle can be performed using the source and current mark, which will remove any containers with the source and a mark other than the current mark.

    • isSoldOut

      public boolean isSoldOut()
      Return true if the container is sold out.