Package com.tccc.kos.core.service.app

Class Application<T extends BaseAppConfig>

java.lang.Object
com.tccc.kos.core.service.app.Application<T>
All Implemented Interfaces:
ConfigAware<T>, ContextHandleAware, HandleAware, JsonDescriptorAware, Loadable
Direct Known Subclasses:
SystemApplication
public abstract class Application<T extends BaseAppConfig> extends Object implements Loadable, ContextHandleAware, JsonDescriptorAware, ConfigAware<T>
Base class for all kOS applications.
Since:
1.0
Version:
2023-05-22

  • Constructor Details

    • Application

      public Application()

  • Method Details

    • getHandlePrefix

      public String getHandlePrefix()
      Description copied from interface: ContextHandleAware
      Returns the prefix for the object to be used when the handle is allocated by the context. The prefix typically reflects the type of the object, such that two objects with the same name but different types are uniquely identified. This value should be the name of the getter if this object was to be fetched from a parent object. For example, if class was Pump there may be two instances: water and carb. The prefix for the water pump may be "water" while the prefix for carb may be "carb", as this distinguishes them. In cases where there is a single getter, it's not uncommon for the prefix to be the type of the object or null. The default implementation returns null.
      Specified by:
      getHandlePrefix in interface ContextHandleAware

    • getConfig

      public T getConfig()
      Retrieves the configuration bean.
      Specified by:
      getConfig in interface ConfigAware<T extends BaseAppConfig>
      Returns:
      the config bean

    • setConfig

      public void setConfig(T config)
      Sets the configuration bean.
      Specified by:
      setConfig in interface ConfigAware<T extends BaseAppConfig>

    • getLoader

      public AppLoader getLoader()
      Return the loader that loaded the application.

    • getCtx

      public BeanContext getCtx()
      Returns this applicaton's bean context.

      If this is the system app, then this context's parent is the kOS core context, and is the parent of all other applications. This allows the system app to easily expose resources to all other apps.

      If this is not the system app, then this context is private to the application, and the parent context is the system app context. This allows resources to be exposed to various parts of the app using autowiring.

    • addToCtx

      public void addToCtx(Object bean)
      Add a bean to the application context.
      Parameters:
      bean - the bean to add

    • getDescriptor

      public JsonDescriptor getDescriptor()
      Returns the descriptor from this application's KAB file (descriptor.json). This provides easy access to the KAB file contents, allowing dotted notation access to individual fields or bean deserialization.
      Specified by:
      getDescriptor in interface JsonDescriptorAware

    • getVfs

      public VFS getVfs()
      Returns the root VFS (virtual file system) for this application. The VFS controls which content is visible via the webserver, and each application is provided a base directory in the global VFS, which is /app/{appId}.

      The system app has a base direrctory of /system. There are many VFS components that can be used to export content to this path in the webserver. For more information check documentation for VFS.

    • getAppId

      public String getAppId()
      Returns the ID of this application, which comes from the kos.app.appId field of the descriptor.json file.

    • getAppDir

      public File getAppDir()
      Returns the base directory of the application. This is a read-only image of the application KAB contents mapped into the native filesystem. Contents of the KAB can be access directly from the KAB using getKab() , or directly from the filesystem. Since the KAB contents are visible in the native filesystem, it is possible to package native binaries in a KAB and run them from the mounted filesystem.

    • getAppFile

      public File getAppFile(String path)
      Adds the specified path to the base application directory and returns it as a File. This is a convenience method to convert relative paths to files within the application space.
      Parameters:
      path - the relative path

    • getDataDir

      public File getDataDir()
      Returns the base directory of the application's local storage area. This area is used by the application for any local storage needs, and is isolated from other applications.

      Application data is inherently nodeType specific and switching the nodeType of a board will cause it to use a new data directory. This is generally the preferred area to store data. In the event a board is removed from one device and used as a different nodeType in a different device, data from the original node type generally causes issues. Anything stored in the application data dir will not spill over across node types.

      If there is a need to store data that spans node types on a given board, use getCoreDir() as this data area will remain the same regardless of nodeType of the board. This should only be used in very limited and special cases related to board reuse.

    • getDataFile

      public File getDataFile(String path)
      Adds the specified path to the base application data directory and returns it as a File. This is a convenience method that converts relative paths to files within the application space.
      Parameters:
      path - the relative path

    • getCoreDir

      public File getCoreDir()
      Returns the base directory of the application's core storage area. Core storage remains the same regardless of the nodeType of the board. This storage area should only be used for very limited use cases, such as storing a device birth cert that should be used the entire life of the board even if it's moved from device to device. Do not use this a the primary storage area for your application data.

    • getCoreFile

      public File getCoreFile(String path)
      Adds the specified path to the base application core directory and returns it as a File. This is a convenience method that converts relative paths to files within the application core space.

      Please see notes for getCoreDir() regarding the use of core space vs data space. In most cases data space should be used to store application data.

      Parameters:
      path - the relative path

    • getKab

      public KabFile getKab()
      Returns the KabFile for the application KAB. This allows direct access to the contents of the KAB, including its header information.

    • getSection

      public ResolvedManifestSection getSection()
      Returns the ResolvedManifestSection associated with the application. This is the manifest section that is provided when the application is loaded. If no section was specified, then this is null.

      This provides access to related KAB files for the application to operate on, and provides a mechanism to enumerate and search the section for other related KABs.

    • getSection

      public ResolvedManifestSection getSection(String name)
      Returns the ResolvedManifestSection with the specified name. This provides access to KAB files in the section.

    • getSectionsByNamePrefix

      public Collection<ResolvedManifestSection> getSectionsByNamePrefix(String prefix)
      Return all ResolvedManifestSection with the specified name prefix.

    • getNodeManifest

      public ResolvedNodeManifest getNodeManifest()
      Return the currently active node manifest for this node.

    • getLocalization

      public LocalizationContext getLocalization()
      Return localization context for the app.

    • addLocalization

      public void addLocalization(ResolvedManifestSection section)
      Add all kabs in the section with a type of kos.localization to the associated localization context.
      Parameters:
      section - the section to examine

    • getKeyVal

      public KeyValNameSpace getKeyVal()
      Return the KeyValNameSpace associated with the application. This provides simple key/val storage that is backed by the core KeyValService within kos. The application KeyValNameSpace will be namespaced to the app id. The KeyValNameSpace is also part of the application context so it can be autowired into anything that has access to the application context.

    • openDatabase

      public Jdbi openDatabase(String name, DatabaseMigrator migrator)
      Opens or creates a database with the specified name in the local storage area of the application. The supplied migrator is used to create and/or migrate the database to the latest schema before the Jdbi wrapper is returned.

      If a single DAO is used, it can implement DatabaseMigrator and rely on the Jdbi instance injected after migration is complete. If multiple DAO's exist for the database, then the returned Jdbi instance can be used to create the various DAO's.

      The DatabaseMigrator controls much of the database policy such as forward migration, how to handle rollback to a previous schema, and how many previous schema revisions to maintain. Check the DatabaseMigrator documentation for more information.

      Parameters:
      migrator - used to migrate the database
      name - the name of the database
      Returns:
      the resulting Jdbi instance

    • resolveAppBrowserIntent

      public BrowserNav resolveAppBrowserIntent(BrowserIntent intent)
      Override to process BrowserIntent objects directed at this application. This allows applications to process intents without the need to implement BrowserIntentResolver and filter out intents specific to this application.

      To generate an intent for an application, use AppBrowserIntent()). param intent the intent to resolve

    • load

      public void load() throws Exception
      Called from AppLoader when the application is first loaded. This should be used for application initialization, however the application should not begin operation until start() is called.

      When this method returns, the application context is updated, which triggers any pending autowiring. Any configurable objects added to the context are also configured. This allows these objects to be used in start() , knowing they are autowired and configured.

      Specified by:
      load in interface Loadable
      Throws:
      Exception

    • start

      public void start() throws Exception
      Called from AppLoader.start() to notify the application is is being started. Any objects added to the context during load() will be autowired and configured before this is called. Once this returns, the application is considered to be running. Until an application is started, any associated endpoints are not accessible. This prevents the application from being used when it is not running.

      Once started, an application may be unloaded by calling AppLoader.unload() .

      Specified by:
      start in interface Loadable
      Throws:
      Exception

    • started

      public void started() throws Exception
      Called after start() returns. When this is called, all application vfs and endpoints are available for use. It is now safe to notify other systems that the application endpoints and content can be used.

      Override as needed.

      Specified by:
      started in interface Loadable
      Throws:
      Exception

    • stop

      public void stop() throws Exception
      Called before the application is unloaded. When this is called, endpoints and vfs content has been disabled, but not yet unmounted.

      Override as needed.

      Specified by:
      stop in interface Loadable
      Throws:
      Exception

    • unload

      public void unload() throws Exception
      Called when the application is being unloaded as a result of calling AppLoader.unload() . This must clean up all resources and references to allow the app class loader to be garbage collected.

      Override as needed.

      Specified by:
      unload in interface Loadable
      Throws:
      Exception

    • hasProfile

      public boolean hasProfile(String profile)
      Profiles are constants that are defined by command-line arguments to the JVM. This provides access to the list of profiles provided at startup, and returns true if the named profile is in the profile list. This is used to change behavior of an application based on a command-line argument.
      Parameters:
      profile - the profile to check

    • isStarted

      public boolean isStarted()
      Return true if the app has been started. This will become true just before the application started() callback is called. After started() returns, postStarted will be true.

    • isPostStarted

      public boolean isPostStarted()
      Return true if the started() has returned. This indicates the app is completely functional.

    • isStopped

      public boolean isStopped()
      Return true if the app has been stopped.

    • 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