Interface IAppSessionGyro

All Superinterfaces:
ILocaleString, IMessageBox, IPrivateStorage, IRuntimeImageCache, IToaster
All Known Implementing Classes:
AppSessionGyro

public interface IAppSessionGyro extends ILocaleString, IMessageBox, IToaster, IRuntimeImageCache, IPrivateStorage
The interface used to access the Application Session Gyro.
Author:
Christopher Mindus
  • Field Details

    • STORAGE_NAME

      static final String STORAGE_NAME
      Local storage name in SessionInfo.
  • Method Details

    • getSessionInstance

      static IAppSessionGyro getSessionInstance()
      Gets the runtime application instance for the current thread in a client session.
      Returns:
      The RuntimeApp instance when called from a thread of the client session, null otherwise.
    • getSessionInstance

      static IAppSessionGyro getSessionInstance(SessionInfo sessionInfo)
      Gets the runtime application instance for the current thread in a client session.
      Parameters:
      sessionInfo - A session information instance, or null for none.
      Returns:
      The RuntimeApp instance when called from a thread of the client session, null otherwise.
    • addDisposeListener

      boolean addDisposeListener(IAppSessionDisposeListener listener)
      Adds a dispose listener for the application session. Calling this method multiple times with the same listener will have no effect (but to return false).
      Parameters:
      listener - The listener to add.
      Returns:
      true if the listener was added, false otherwise.
      Throws:
      NullPointerException - If the listener is null.
    • removeDisposeListener

      boolean removeDisposeListener(IAppSessionDisposeListener listener)
      Removes a dispose listener for the application session.
      Parameters:
      listener - The listener to remove.
      Returns:
      true if listener is successfully removed, false otherwise.
    • addClientConnectionListener

      boolean addClientConnectionListener(IClientSessionConnectionListener listener)
      Adds a client connection listener for the application session. Calling this method multiple times with the same listener will have no effect (but to return false).
      Parameters:
      listener - The listener to add.
      Returns:
      true if the listener was added, false otherwise.
      Throws:
      NullPointerException - If the listener is null.
    • removeClientConnectionListener

      boolean removeClientConnectionListener(IClientSessionConnectionListener listener)
      Removes a client connection listener for the application session.
      Parameters:
      listener - The listener to remove.
      Returns:
      true if listener is successfully removed, false otherwise.
    • dispose

      boolean dispose()
      Disposes of the Application session gyro, and effectively closes all the client sessions and end point connections.
      Returns:
      true for dispose success, false if already disposed of.
    • isDisposed

      boolean isDisposed()
      Checks if the application session Gyro is disposed of.
      Returns:
      true if the user's app-session is disposed of along with all client sessions, false otherwise.
    • getTransactionCoordinator

      ITXPCoordinator getTransactionCoordinator()
      Gets the transaction coordinator of the session.
      Returns:
      The TXP coordinator, or null for none.
    • getAppWorker

      Worker getAppWorker()
      Gets the Worker for the Application.
      Returns:
      The Application Worker.
    • post

      default void post(Runnable runnable)
      Helper method to post a runnable for execution. The runnable is executed in the application session's worker thread and is typically used to ensure that execution takes place in the correct application session thread when performing inter-session calls.
      Parameters:
      runnable - The runnable.
    • getAppThreadGroup

      ThreadGroup getAppThreadGroup()
      Gets the AppSessionGyro's Thread Group.
      Returns:
      The Thread Group.
    • getApplicationTimerEngine

      ITimerEngine getApplicationTimerEngine()
      Gets the application timer engine. All timer tasks as disposed of automatically when the application session exits.
      Returns:
      The application session implementation of the timeout engine.
    • getAppID

      String getAppID()
      Gets the application ID.
      Returns:
      The AppID is an upper case string.
    • getEnvironment

      EnvProps getEnvironment()
      Gets the original environment properties for Selector's or Value's.

      This is NOT the same instance as the one available from the IClientSessionGyro.getEnvironment().

      Returns:
      The original environment properties for selectors, null if never initialized.
    • getAppSessionInfo

      SessionInfo getAppSessionInfo()
      Gets the application session info.
      Returns:
      The original session information that initiated the application session.
    • getCreationTime

      long getCreationTime()
      Gets the creation time in milliseconds.
      Returns:
      Milliseconds since the epoch.
    • getSessionUserIdentifier

      SessionUserIdentifier getSessionUserIdentifier()
      Gets the SessionUserIdentifier.
      Returns:
      The user identifier of the session.
    • getCustomAppValue

      String getCustomAppValue(String key)
      Gets a value for a key in the custom app properties.
      Parameters:
      key - The key or name of the property to retrieve.
      Returns:
      The value, or null if no value is defined for the key, or the custom map is not defined.
    • getAppKStringInfoProvider

      IKStringInfoProvider getAppKStringInfoProvider()
      Retrieves the KStringInfoProvider for the application session.

      Note: it is recommended to use the IClientSessionGyro.getKStringInfoProvider() when available as it has more precise information available for the client session.

      Returns:
      The KString information provider instance, or null if not possible.
    • getKStringInfoProvider

      IKStringInfoProvider getKStringInfoProvider()
      Retrieves the KStringInfoProvider for the application session.

      Note: it is recommended to use the IClientSessionGyro.getKStringInfoProvider() when available as it has more precise information available for the client session.

      Specified by:
      getKStringInfoProvider in interface ILocaleString
      Returns:
      The KString information provider instance, or null if not possible. This method returns the same value as getAppKStringInfoProvider().
    • getLanguageCode

      String getLanguageCode()
      Gets the language code of the application session. This language may very well not be the one requested by the end user device, but rather one of the languages the application supports.
      Returns:
      The language code.
    • getPrettyLocaledTexts

      PrettyLocaledTexts getPrettyLocaledTexts()
      Gets the locale'd texts instance for the sessions language and text tables.
      Returns:
      The instance used to create locale'd strings for e.g. duration and distances.
    • getRuntimePropFromReference

      GProp<?> getRuntimePropFromReference(String reference)
      Gets a reference for runtime use to get the reference of an item. The reference must be fully qualified such as "*ALIAS:/type/path" or "MODULE:/type/path" and cannot be relative.

      Note: The reference can be to the static or virtualized properties, but if a property type is virtualized and the property is not found, a fall-back to search the application for the static non-virtualized property IS NOT PERFORMED.

      Calling this method is the same as calling getRuntimePropFromReference(reference, false)}.

      Parameters:
      reference - The reference to look-up.
      Returns:
      The property found, or null for reference not found.
    • getRuntimePropFromReference

      GProp<?> getRuntimePropFromReference(String reference, boolean fallBackToNonVirtualized)
      Gets a reference for runtime use to get the reference of an item. The reference must be fully qualified such as "*ALIAS:/type/path" or "MODULE:/type/path" and cannot be relative.

      If the flag fallBackToNonVirtualized is false, the search will not fallback to searching for the non-virtualized property in the runtime app. The result will only returned virtualized properties, i.e. for a reference as e.g. "module:/vs/someVS", and depending on where this method is called (the client session), also includes other virtualized properties such as panels as e.g. "module:/panel/somePanel".

      To always fallback to also searching the runtime app, specify fallBackToNonVirtualized to true.

      Parameters:
      reference - The reference to look-up.
      fallBackToNonVirtualized - Flag indicating a fallback to non-virtualized properties.
      Returns:
      The property found, or null for reference not found.
    • getRootFromName

      PropCnr getRootFromName(GProp<?> requestor, String module)
      Gets the module root for a name. In the Editor, the module is the project, and that root container is returned. In the Server, the module doesn't matter, so the real root returns itself.

      When running with assertions, this call throws an assertion error by default, showing that the call is directed to a non-root property container.

      Parameters:
      requestor - The requestor property.
      module - The module name (without colon), i.e. the project name in the Designer.
      Returns:
      The root property container, or null if this container is not the root, or if the module name is not found. The default implementation returns null.
    • getClientSessionsCount

      int getClientSessionsCount()
      Gets the count of client sessions.
    • getClientSessionGyros

      IClientSessionGyro[] getClientSessionGyros()
      Gets the active client session Gyro's for this application session Gyro.
      Returns:
      The array of active client session Gyro's.
    • requestUILock

      ILockState requestUILock()
      Requests a UI lock state. The object returned can be used to set a message below the lock spinner. It can also be used to set a progress indicator, also below the spinner. A progress indicator can also be handled using the lock object.

      Note: You MUST call the objects {link @ILockState#release()} method to release the lock state.

      Returns:
      The lock state object.
    • isUILocked

      boolean isUILocked()
      Get the current UI lock state.

      You may also query the incremental lock state using getLockCount().

      Returns:
      true if busy state is on, false otherwise.
    • lockUI

      boolean lockUI(KString waitMsg, ProgressIndicatorDelay delay)
      Locks the UI with a message and a delay.

      Consider using the method requestUILock() to handle UI locking along with optional message, wait delay and progress indicator.

      This call will not change the potential wait message or wait message delay if the method is not successful.

      Also consider using the method decrementUILock() in case multiple operations and threads can toggle the lock state.

      Parameters:
      waitMsg - The wait message, null for none.
      delay - Delay before the message is shown in the Client.
      Returns:
      Busy change flag, true if busy state changed, false otherwise. The return value may be false because the lock count is non-zero.
    • lockUI

      boolean lockUI(KString waitMsg, int delay)
      Locks the UI with a message and a delay.

      Consider using the method requestUILock() to handle UI locking along with optional message, wait delay and progress indicator.

      This call will not change the potential wait message or wait message delay if the method is not successful.

      Also consider using the method decrementUILock() in case multiple operations and threads can toggle the lock state.

      Parameters:
      waitMsg - The wait message, null for none.
      delay - Delay of lock spinner: -2 for default (1.5 second), -1 disabled, 0=no delay, >0 wait time in milliseconds (1-20000, i.e. 20 seconds).
      Returns:
      Busy change flag, true if busy state changed, false otherwise. The return value may be false because the lock count is non-zero.
      Throws:
      IllegalArgumentException - If the delay value is not -1 to 20000 (20 seconds).
    • unlockUI

      boolean unlockUI()
      Unlocks the UI.

      Consider using the method requestUILock() to handle UI locking along with optional message, wait delay and progress indicator.

      This call will not change the potential wait message or wait message delay if the method is not successful.

      Also consider using the method decrementUILock() in case multiple operations and threads can toggle the lock state.

      Returns:
      Busy change flag, true if busy state changed, false otherwise. The return value may be false because the lock count is non-zero.
    • getLockCount

      int getLockCount()
      Returns the incremental lock count that governs the UI locking state. Note that the lock state may be in effect even if the lock count is zero.
      Returns:
      The lock count, zero or positive value.
    • incrementUILock

      int incrementUILock()
      Increases the incremental lock state. If it was zero, it will UI lock the session. Each call to this method must match a call to decrementUILock().

      Consider using the method requestUILock() to handle UI locking along with optional message, wait delay and progress indicator.

      Returns:
      The lock count, i.e. the number of calls that has been made to this method minus the number of calls to decrementUILock(), after the call to this method.
    • decrementUILock

      int decrementUILock()
      Decreases the incremental lock state. If it becomes zero, it will UI unlock the session. Each call to this method must match a call to incrementUILock().

      If this method is called and the lock count is zero, nothing will happen, but a warning event with a call stack will be logged.

      Returns:
      The lock count, i.e. the number of calls that has been made to incrementUILock() minus the number of calls to this method.
    • setLockMessage

      boolean setLockMessage(KString msg)
      Sets the message to display for the lock state, above the indicator.
      Parameters:
      msg - The message to display, or null to remove it.
      Returns:
      true for changed, or false if busy state is not present or no change of message.
    • setLockMessage

      boolean setLockMessage(KString msg, int progress)
      Sets the message to display for the lock state, above the indicator, along with a progress value.
      Parameters:
      msg - The message to display, or null to remove it.
      progress - The progress value between 0 and 100, or -1 to remove it.
      Returns:
      true for changed, or false if busy state is not present or no change of values.
      Throws:
      IllegalArgumentException - If the progress value is not -1 or 0 to 100.
    • setLockMessage

      boolean setLockMessage(KString msg, int delay, int progress)
      Sets the message to display for the lock state, above the indicator, along with a progress value.
      Parameters:
      msg - The message to display, or null to remove it.
      delay - Delay of lock spinner: -2 for default (1.5 second), -1 disabled, 0=no delay, >0 wait time in milliseconds (1-20000, i.e. 20 seconds).
      progress - The progress value between 0 and 100, or -1 to remove it.
      Returns:
      true for changed, or false if busy state is not present or no change of values.
      Throws:
      IllegalArgumentException - If progress value is not -1 or 0 to 100, or delay is smaller than -2 or larger than 20000.
    • setLockProgress

      boolean setLockProgress(int progress)
      Sets the current progress bar value. This method will not do anything if the lock state is not present.
      Parameters:
      progress - The progress value between 0 and 100, or -1 to remove it.
      Returns:
      true for changes, false for no change or no lock state.
      Throws:
      IllegalArgumentException - If the progress value is not -1 or 0 to 100.
    • getFocusEngine

      IFocusEngine getFocusEngine(IFocusComp comp)
      Returns the focus engine instance for the specified component.
      Parameters:
      comp - The component requesting the focus engine. For the AppSessionGyro, the focus engine returns an instance of the VirtualSpace focus engine if the component instance is a VSComponent (VSTable, VSField, etc) or a VirtualSpace, for now.
      Returns:
      The focus engine instance, or null if not found.
    • isVirtualized

      boolean isVirtualized(VirtualSpace virtualSpace)
      Returns if a VirtualSpace already is virtualized for the application.
      Parameters:
      virtualSpace - The VirtualSpace.
      Returns:
      true if vitualSpace already is virtualized or a virtualized instance is present, false otherwise.
    • getVirtualizedVSComponent

      IVSComponent getVirtualizedVSComponent(IVSComponent component)
      Gets the virtualized VSComponent counterpart from a non-virtualized VSComponent. If the component's VirtualSpace is not virtualized, it will be done. If the component parameter already is virtualized, that instance is returned. This method can also process a VirtualSpace instance as it is implementing the IVSComponent interface.
      Parameters:
      component - A VS component.
      Returns:
      A virtualized component for the component parameter, or the component parameter instance if it was virtualized. null is returned if the VirtualSpace is virtualized and the VSComponent counterpart doesn't exist or the class instance is not the same as the original component, or if the component parameter is null.
    • getVirtualizedVirtualSpace

      VirtualSpace getVirtualizedVirtualSpace(VirtualSpace virtualSpace, boolean doVirtualize)
      Gets the virtualized counterpart of a VirtualSpace. If the VirtualSpace is not virtualized, it will be done. If the VirtualSpace parameter already is a virtualized VirtualSpace, that instance is returned.

      This method is typically used by data connectors as action actors that have another target VirtualSpace. Focus can be set to a component in another VirtualSpace once virtualized.

      Parameters:
      virtualSpace - The VirtualSpace.
      doVirtualize - Flag to virtualize the virtualSpace if not already virtualized or not.
      Returns:
      A virtualized VirtualSpace for the virtualSpace parameter, or the virtualSpace parameter instance if it was virtualized.
    • getVirtualizedVSComponent

      <VSC extends VSComponent> VSC getVirtualizedVSComponent(VSC component)
      Gets the virtualized VSComponent counterpart from a non-virtualized VSComponent. If the component's VirtualSpace is not virtualized, it will be done. If the component parameter already is virtualized, that instance is returned.
      Parameters:
      component - A VS component.
      Returns:
      A virtualized component for the component parameter, or the component parameter instance if it was virtualized. null is returned if the VirtualSpace is virtualized and the VSComponent counterpart doesn't exist or the class instance is not the same as the original component, or if the component parameter is null.
    • getCurrentFocus

      IVSComponent getCurrentFocus()
      Returns the current focus in the VirtualSpace. If no particular component is in focus, the VirtualSpace that last had focus is returned.
      Returns:
      The component in focus, or null if no focus is currently set.
    • setVirtualizeSupportFocus

      String setVirtualizeSupportFocus(IVSComponent vsComp)
      Sets the focus to the specified VS component, regardless if the VS component is virtualized or not. If not virtualized, it will be prior to setting the focus.
      Parameters:
      vsComp - The VS component to focus.
      Returns:
      Error message, or null for success.
    • setVirtualizeSupportFocus

      String setVirtualizeSupportFocus(IVSComponent vsComp, IGProp<?> trigger)
      Sets the focus to the specified VS component, regardless if the VS component is virtualized or not. If not virtualized, it will be prior to setting the focus.
      Parameters:
      vsComp - The VS component to focus.
      trigger - The trigger component, null for none.
      Returns:
      Error message, or null for success.
    • getAppHistory

      IAppHistory getAppHistory()
      Returns the application session history used for backward and forward navigation.
      Returns:
      The application session history instance.
    • getLocationService

      ILocationService getLocationService()
      Returns an instance of the geolocation service.
      Returns:
      The instance, always non-null.
    • getAuthenticatedUserUUID

      String getAuthenticatedUserUUID()
      Gets the user ID for background location service identification.
      Returns:
      String made up of the authenticated user's UUID, null if the user is not yet authenticated or undefined.
    • getUserAuthenticationUI

      IUserAuthenticationUI getUserAuthenticationUI()
      Gets the user authentication UI interface used for the initial login.
      Returns:
      The user authentication interface.