Package com.kosdev.kos.core.service.app

Class Application<T extends BaseAppConfig>

java.lang.Object
com.kosdev.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
Version:
9

  • 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
      Since:
      1

    • setConfig

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

    • getLoader

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

    • 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.

      Since:
      1

    • addToCtx

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

    • 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
      Since:
      1

    • 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.

      Since:
      1

    • getAppId

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

    • 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.
      Since:
      1

    • 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
      Since:
      1

    • 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.

      Since:
      1

    • 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
      Since:
      1

    • 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.
      Since:
      1

    • 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
      Since:
      1

    • 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.
      Since:
      1

    • getKabByType

      public KabFile getKabByType(String type)
      Returns the first KabFile of the specified type from the section the application loaded from.
      Parameters:
      type - the type of KAB to return
      Since:
      1

    • getKabByType

      public KabFile getKabByType(String sectionName, String type)
      Returns the first KabFile of the specified type from the section with the specified name. Returns null if the section doesn't exist or no KAB of the specified type exists in the section.
      Parameters:
      sectionName - name of the section, null for section the app loaded from
      type - the type of KAB to return
      Since:
      1

    • getSectionName

      public String getSectionName()
      Return the name of the section the application is located in.
      Since:
      1

    • 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.

      Since:
      1

    • getSection

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

    • getSectionsByNamePrefix

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

    • getNodeManifest

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

    • getLocalization

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

    • 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
      Since:
      1

    • addUiPlugin

      public void addUiPlugin(KabFile kab)
      Add the kab as a UI plugin. This will also add the KAB to the localization context of the application, ensuring that any localization data for the UI plugin is also available without a need to manually add it to the localization context. This can be called multiple times with the same KAB and will ignore KAB's that don't contain ui plugin data or localization data in the KAB descriptor.
      Parameters:
      kab - the kab to add
      Since:
      9

    • addUiPlugins

      public void addUiPlugins(ResolvedManifestSection section)
      Add all kabs in the section as UI plugins. This is equivalent to calling addUiPlugin(com.kosdev.kos.commons.kab.KabFile) for each KAB in the section. Any KAB's with ui plugin data in the descriptor will be added to the UiPluginContext and any localization data will be added to the LocalizationContext .
      Parameters:
      section - the section to examine
      Since:
      9

    • getParentAppId

      public String getParentAppId()
      Return the application id of the parent application. This is the id of the application that loaded this application. Applications inherit context from parent applications, but a parent application is optional so this may return null.
      Returns:
      application id of the parent application
      Since:
      1

    • 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.
      Since:
      1

    • getBroker

      public MessageBroker getBroker()
      Return the MessageBroker scoped to this application. This prefixes all topics with an application-specific prefix of /app/{appId}/} which ensures that topics between applications never conflict.

      Any subscriptions performed using this broker will automatically be unsubscribed when the application unloads.

      Since:
      1

    • 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
      Since:
      1

    • 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

      Since:
      1

    • 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
      Since:
      1

    • 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
      Since:
      1

    • 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
      Since:
      1

    • 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
      Since:
      1

    • 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
      Since:
      1

    • 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.
      Since:
      1

    • isPostStarted

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

    • isStopped

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

    • whenStarted

      public void whenStarted(AppStartedCallback callback)
      Call the specified callback when this app is started. If already started, the callback will be called immediately.
      Parameters:
      callback - the callback to call when started
      Since:
      9

    • whenAppStarted

      public void whenAppStarted(String appId, AppStartedCallback callback)
      Call the specified callback when the requested appId is started. If already started, this will be called immediately. This will only be called once. If the application unloads and reloads it will not be called again. This is a convenience method which is a simple alternative to implementing AppListener .
      Parameters:
      appId - the id of the app to monitor
      callback - the callback to call
      Since:
      6

    • whenAppStarted

      public <T> void whenAppStarted(String appId, GenericAppStartedCallback<T> callback, Class<T> clazz)
      Call the specified callback when the requested appId is started. If already started, this will be called immediately. This will only be called once. If the application unloads and reloads it will not be called again. This is a convenience method which is a simple alternative to implementing AppListener .

      This will cast the Application to the specified class in the callback. This is a convenience method as in most cases the application is cast to a well defined interface in order to interact with the application.

      Parameters:
      appId - the id of the app to monitor
      callback - the callback to call
      clazz - the class to cast the application to
      Since:
      9

    • isAppInstalled

      public boolean isAppInstalled(String appId)
      Return true if the specified appId is installed as part of the running manifest.
      Parameters:
      appId - the id of the app to check
      Since:
      9

    • isAppAutostart

      public boolean isAppAutostart(String appId)
      Return true if the specified appId is in an autostart section.
      Parameters:
      appId - the id of the app to check
      Since:
      9

    • getApiVersion

      public int getApiVersion()
      Return the api version for the app.
      Since:
      9

    • getSdkList

      public List<SdkInfo> getSdkList()
      Return information about the sdk's that are packaged with this app. This can be used to determine which version of which sdk the app was built against. This can be used to investigate compatibility issues with actually installed applications.
      Since:
      9

    • 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