Package com.kosdev.kos.core.service.assembly

Class Assembly

java.lang.Object
com.kosdev.kos.core.service.assembly.Assembly
All Implemented Interfaces:
HandleAware, JsonDescriptorAware, Loadable
public abstract class Assembly extends Object implements Loadable, HandleAware, JsonDescriptorAware
An assembly is used to describe a collection of hardware that can be added or removed as an atomic unit within KOS. This provides an atomic way to process hardware changes, which reduces race conditions and provides a pluggable system for adding new elements to an assembly.

Typically, an assembly includes all the hardware in a particular device and the system application adds the assembly as part of the startup process. This allows a single system app to define multiple supported device models by simply defining multiple assemblies and only installing the one that matches the actual hardware.

Assemblies are also intended for use in supporting optional expansion hardware. If a device supports another collection of hardware as an add-on or expansion kit, a corresponding assembly can be added for that expansion and removed if the kit is removed.

An assembly has a series of lifecycle callbacks that facilitate installation and removal of the assembly. The constructor is expected to create all the core objects in the assembly. When passed to AssemblyService to be installed, the handles for all objects in the context are set and any ConfigAware objects are configured before calling the assembly install() method. This allows the install() method to operate on all the objects that have already been autowired and configured.

Since:
1
Version:
9

  • Constructor Details

    • Assembly

      public Assembly(String name)
      Create a new assembly with the specified name, using the system app as the parent context.
      Parameters:
      name - name of the assembly
      Since:
      6

    • Assembly

      public Assembly(String name, Application<?> app)
      Create a new assembly with the specified name, using the specified app as the parent context.
      Parameters:
      name - name of the assembly
      Since:
      8

    • Assembly

      public Assembly(String name, BeanContext parentCtx)
      Create a new assembly with the specified name and parent context.
      Parameters:
      name - name of the assembly
      parentCtx - the parent context for the assembly
      Since:
      8

  • Method Details

    • setDescriptor

      public void setDescriptor(JsonDescriptor descriptor)
      Set an optional descriptor for the assembly. This allows meta data to be included with the assembly to provide additional application-specific data without needing to extend the Assembly class.
      Since:
      1

    • add

      public void add(Object obj)
      Add an object to the assembly. This is a generic add method that operates on any object. Subclasses of Assembly can override this (making sure to call super.add() and process objects that are of interest to the assembly. This allows certain core classes to take an assembly as a constructor argument and having the constructor call add() . This eliminates the need for users to know that they have to add objects to the assembly.

      The base Assembly class tracks Board objects and will connect them to the assembly context during the add operation.

      Parameters:
      obj - the object to add
      Since:
      9

    • addBoard

      @Deprecated public void addBoard(Board board)
      Deprecated.
      Add a board to the assembly. This exists for backward compatibility and simply calls add(board) . There is no need to manually add boards as the Board constructor takes an Assembly and adds the board automatically via add() .
      Since:
      1

    • getBoards

      public Collection<Board> getBoards()
      Return the boards in the assembly.
      Since:
      9

    • isCore

      public boolean isCore()
      Returns true if this is the core assembly.

    • getCtx

      public BeanContext getCtx()
      Returns the context for this assembly. This context will have the system application context as a parent.
      Since:
      1

    • addToCtx

      public void addToCtx(Object bean)
      Adds the given bean to the assembly context.
      Parameters:
      bean - the bean to add to the context
      Since:
      1

    • connect

      public void connect(Object bean)
      Autowires the given bean using the context, without actually adding it to the context. If this is called during load() then the connect will be deferred until start() is called. This ensures that all autowired dependencies are available before connecting.
      Parameters:
      bean - the bean to autowire
      Since:
      1

    • getBeans

      public <T> List<T> getBeans(Class<T> clazz)
      Returns a list of beans from the assembly context of the specified type. This only searches the assembly context. This allows quick access to beans in the assembly without having to track them as object properties.
      Since:
      1

    • whenInstalled

      public void whenInstalled(AssemblyInstallCallback callback)
      Call the specified callback when the assembly is fully installed. If already installed, this will be called immediately. This will only be called once.
      Parameters:
      callback - the callback to call when install is complete
      Since:
      9

    • load

      public abstract void load() throws Exception
      Callback to load the assembly.
      Specified by:
      load in interface Loadable
      Throws:
      Exception
      Since:
      1

    • start

      public abstract void start() throws Exception
      Callback during the installation phase. Any beans created during the load() callback are configured and have valid handles.
      Specified by:
      start in interface Loadable
      Throws:
      Exception

    • started

      public void started()
      Called after install completes and the assembly has been added to the device. Override as needed.
      Specified by:
      started in interface Loadable
      Since:
      1

    • stop

      public void stop() throws Exception
      Called when uninstalled from the device. Cleanup all the resources for the assembly. This will be called before any listener callbacks. Any resources that need to exist for these callbacks can be cleaned up in unload() .
      Specified by:
      stop in interface Loadable
      Throws:
      Exception
      Since:
      1

    • unload

      public void unload() throws Exception
      Release all resources from the assembly in preparation for garbage collection. Override as needed.
      Specified by:
      unload in interface Loadable
      Throws:
      Exception
      Since:
      1

    • getHandle

      public Handle getHandle()
      Description copied from interface: HandleAware
      Returns the handle for this bean. This is used by the context to compute the opaque handle for the object.
      Specified by:
      getHandle in interface HandleAware
      Returns:
      the handle node for the bean

    • isInstalling

      public boolean isInstalling()

    • isInstalled

      public boolean isInstalled()

    • getDescriptor

      public JsonDescriptor getDescriptor()
      Description copied from interface: JsonDescriptorAware
      Return the associated JsonDescriptor.
      Specified by:
      getDescriptor in interface JsonDescriptorAware