Package com.iizix.server.gyro

Class ClientSessionGyro

    • Method Detail

      • getSessionInstance

        public static ClientSessionGyro 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

        public static ClientSessionGyro 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.

      • setApplication

        public void setApplication​(RuntimeApp runtimeApp)
        Sets the runtime application. This method is not intended to be called by user code, it is used by the framework.
        Parameters:
        runtimeApp - The runtime application.
        Throws:
        java.lang.IllegalStateException - If runtime application has been set.

      • addDisposeListener

        public boolean addDisposeListener​(IClientSessionDisposeListener listener)
        Adds a dispose listener for the client session. Calling this method multiple times with the same listener will have no effect (but to return false).
        Specified by:
        addDisposeListener in interface IClientSessionGyro
        Parameters:
        listener - The listener to add.
        Returns:
        true if the listener was added, false otherwise.
        Throws:
        java.lang.NullPointerException - If the listener is null.

      • dispose

        public boolean dispose()
        Disposes of the Gyro instance so the client session ends.
        Specified by:
        dispose in interface IClientSessionGyro
        Returns:
        true for dispose success, false if already disposed of.

      • isDisposed

        public boolean isDisposed()
        Checks if the client session Gyro is disposed of.
        Specified by:
        isDisposed in interface IClientSessionGyro
        Returns:
        true if disposed, false otherwise.

      • getPrivateStorageMap

        public java.util.Map<java.lang.String,​java.lang.Object> getPrivateStorageMap()
        Gets the concurrent hash map used to store the private data.
        Specified by:
        getPrivateStorageMap in interface IPrivateStorage
        Returns:
        The private storage map.

      • getClientEndPoint

        public ClientEndPoint getClientEndPoint()
        Gets the client end point instance.

      • getRuntimeApp

        public RuntimeApp getRuntimeApp()
        Gets the RuntimeApp for the Gyro instance.
        Returns:
        The runtime app for the client session.

      • getEnvironment

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

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

        Specified by:
        getEnvironment in interface IClientSessionGyro
        Returns:
        The current environment properties for selectors, null if client hasn't sent them yet.

      • getLanguageCode

        public java.lang.String getLanguageCode()
        Gets the language code to use for the client session, or if not defined, the application session language code.
        Specified by:
        getLanguageCode in interface IClientSessionGyro
        Returns:
        The language code, or null for default.

      • getFocusEngine

        public IFocusEngine getFocusEngine​(IFocusComp comp)
        Returns the focus engine instance for the specified component.
        Specified by:
        getFocusEngine in interface IFocusEngineProvider
        Parameters:
        comp - The component requesting the focus engine.
        Returns:
        The focus engine instance, or null if not found.

      • getClientTimerEngine

        public ITimerEngine getClientTimerEngine()
        Gets the client timer engine. All timer tasks as disposed of automatically when the client session exits.
        Specified by:
        getClientTimerEngine in interface IClientSessionGyro
        Returns:
        The client session implementation of the timeout engine.

      • getPrettyLocaledTexts

        public PrettyLocaledTexts getPrettyLocaledTexts()
        Gets the locale'd texts instance for the sessions language and text tables.
        Specified by:
        getPrettyLocaledTexts in interface IClientSessionGyro
        Returns:
        The instance used to create locale'd strings for e.g. duration and distances.

      • cacheSVG

        public int cacheSVG​(java.lang.String svgString)
        Adds the SVG image information as being sent to the client.

        This method is not intended to be called and logs a severe error and returns 1 (one).

        Parameters:
        svgString - The SVG string.
        Returns:
        The cached index value for the SVG string. A negative value indicates that it needs sending to the client, whereas a positive means only the index is required to be sent. Zero is never returned.

      • getAppSessionFileProvider

        public WSFileProvider getAppSessionFileProvider()
                                         throws java.io.IOException
        Get the web server file provider for the client session.
        Returns:
        The web server file provider.
        Throws:
        java.io.IOException - If the directory for the client session files failed to be created.
        java.lang.IllegalStateException - If the client session is disposed of.

      • getVirtualizedPanels

        public UIPanelBase[] getVirtualizedPanels()
        Gets the cached and sorted array of panels that is currently displayed.

        The index 0 is the topmost panel and the higher the index, the more overlapped the panel is. The highest index is the top-level main panel covering the screen.

        Do not modify this array!

        Specified by:
        getVirtualizedPanels in interface IClientSessionGyro
        Returns:
        The virtualized panels.

      • getMatchingPanels

        public UIPanelBase[] getMatchingPanels​(VirtualSpace virtualSpace)
        Gets the panels that matches a VirtualSpace for this client session. The VirtualSpace can be virtualized or not, and the client session environment properties are used to determine the panels in question (i.e. depending on their selectors).

        This method is quite CPU intensive and should NOT be done too often. The return value is however cached during the focus handler mappings from VirtualSpace to the UI, so only one such call is done.

        The ordering is significant and can be a mix of primary and secondary panels, however the matching panel is the virtualized instance if one is present, otherwise it is the non-virtualized instance.

        Note: The result from this method should not be cached because the matching panels may very well change during a client session due to e.g. a change in client capabilities or alike (that affects the result of the selectors used).

        Specified by:
        getMatchingPanels in interface IClientSessionGyro
        Parameters:
        virtualSpace - The VirtualSpace to look-up the panels for.
        Returns:
        A cloned cached array of the matching panels.

        The array of matching panels, can be a mix of virtualized and non-virtualized panels!

      • requestUILock

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

        Specified by:
        requestUILock in interface IClientSessionGyro
        Returns:
        The lock state object.
        Throws:
        java.lang.IllegalStateException - If the client session is disposed of.

      • setBusy

        public void setBusy​(KString msg,
                    int delay,
                    int progress)
        Sets the UI busy state and optionally updates the message and/or progress.

        This method is intended to be used with advanced UI programming where a message is used in conjunction with a progress.

        If this functionality is not required, it is recommended to let the AppSessionGyro handle the busy state.

        Specified by:
        setBusy in interface IClientSessionGyro
        Parameters:
        msg - Optional 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).
        progress - Progress value, -1 for none, otherwise a value between 0 and 100.
        Throws:
        java.lang.IllegalArgumentException - If progress value is not -1 or 0 to 100, or delay is smaller than -2 or larger than 20000.

      • setReady

        public void setReady()
        Sets the UI to "ready", i.e. clears busy state.

        Note: the state is not set to ready immediately, merely the busy state. The UI is triggered to be synchronized with the VirtualSpace in the Client Worker thread, and a change of panel may be the result.

        This method is intended to be used with advanced UI programming where a message is used in conjunction with a progress.

        If this functionality is not required, it is recommended to let the AppSessionGyro handle the busy state.

        Specified by:
        setReady in interface IClientSessionGyro

      • setReady

        public boolean setReady​(java.lang.Runnable runnable)
        Sets the UI to "ready", i.e. clears busy state.

        Note: the state is not set to ready immediately, merely the busy state. The UI is triggered to be synchronized with the VirtualSpace in the Client Worker thread, and a change of panel may be the result.

        Specify a runnable instance if you wish to be notified when the panel is unlocked. This runnable will be called at a later stage from the Client Worker thread.

        The runnable will be be called if the busy state is turned on or the client has been locked.

        This method is intended to be used with advanced UI programming where a message is used in conjunction with a progress.

        If this functionality is not required, it is recommended to let the AppSessionGyro handle the busy state.

        Specified by:
        setReady in interface IClientSessionGyro
        Parameters:
        runnable - The runnable to be notified, null for none.
        Returns:
        true if the runnable will be called (if present), false if it will not be called.

      • enterClientLock

        public void enterClientLock​(boolean isFromClient)
        Method called whenever the client lock state is enabled.
        Specified by:
        enterClientLock in interface IClientSessionGyro
        Parameters:
        isFromClient - Flag indicating the state change is induced from client side. If this flag is false, the lock state

      • exitClientLock

        public void exitClientLock()
        Releases client lock state if the client is not in busy state. The lock state will be released when the VS has been synchronized at a later stage, but very quickly.
        Specified by:
        exitClientLock in interface IClientSessionGyro

      • getHistoryRequest

        public HistoryRequest getHistoryRequest()
        Gets the history request instance for the client session.
        Specified by:
        getHistoryRequest in interface IClientSessionGyro
        Returns:
        This client session's instance for history requests, never changes during the session's lifetime.

      • addHistoryEntry

        public IAppHistoryEntry addHistoryEntry()
        Adds a new focus entry at the current location for this client session. The VirtualSpace and UI location is recorded to the previous and forward locations in the entry.

        The entry is added at the current index and will clear all forward operations at that point to the end, i.e. IAppHistory.clearForwardEntries() is called before adding the entry and moving the index forward by one (1).

        Once added, the history entry forward and backward information can be set or adjusted.

        Specified by:
        addHistoryEntry in interface IClientSessionGyro
        Returns:
        The newly added history entry, null if history operations are currently in progress (i.e. a forward or backward history operation is running).

      • synchronizeCurrentFocusWithVS

        public boolean synchronizeCurrentFocusWithVS()
        Updates the focus to the VS from the current focused UI component. This may be needed to synchronize the VS focus for a particular UI session to make sure it is synchronized.
        Specified by:
        synchronizeCurrentFocusWithVS in interface IClientSessionGyro
        Returns:
        true for success, false if nothing was done.

      • setPseudoActionFocusToVS

        public void setPseudoActionFocusToVS​(IUIFocusComp focusComp,
                                     IGProp<?> trigger)
        Called when a "pseudo UI action" is executed, making sure its VS counterpart has the current focus. This "pseudo action" can be e.g. a MLItemProp that has a context menu, as well as an direct action such as a UIButton.

        This method is not intended to be called but is used internally by the framework.

        Specified by:
        setPseudoActionFocusToVS in interface IClientSessionGyro
        Parameters:
        focusComp - The "pseudo action" focus component.
        trigger - The trigger component, null for none.

      • onFocusChanged

        public void onFocusChanged​(IFocusComp newComp,
                           IFocusComp oldComp,
                           IGProp<?> trigger,
                           boolean isRemoteInduced,
                           boolean isInternal)
        Called when focus changes.
        Specified by:
        onFocusChanged in interface IGyroFocusEngineOwner
        Parameters:
        newComp - New focus component.
        oldComp - Old focus component.
        trigger - The trigger property, null for none.
        isRemoteInduced - If the event is remote induced.
        isInternal - The internal flag as specified in the setFocus method to the focus engine.

      • getCurrentFocus

        public UIComp getCurrentFocus()
        Returns the current focus in the UI. If no particular component is in focus, the panel that last has focus or the topmost panel is returned.
        Specified by:
        getCurrentFocus in interface IClientSessionGyro
        Returns:
        The component in focus, or null if not a single panel has yet been created.

      • installFonts

        public boolean installFonts​(java.util.List<FontFiles> fontList)
        Installs the font face as specified by the FontFiles instance for the Client Session. Once installed, the font family can be used.
        Parameters:
        fontList - The list of font files to install.
        Returns:
        true for success, false if the remote part doesn't support installation, e.g. in a preview browser.

      • installFont

        public boolean installFont​(java.lang.String fontFamily)
        Installs the font families as specified by the font family.
        Parameters:
        fontFamily - The font family or families.
        Returns:
        true for success, false if the remote part doesn't support installation, e.g. in a preview browser.

      • getClientContextMenuReference

        public java.lang.String getClientContextMenuReference​(UIContextMenu contextMenu)
        Gets the reference to use for a context menu.
        Parameters:
        contextMenu - The context menu.
        Returns:
        The reference to use, empty string for none (never null).

      • getClientContextMenuReference

        public java.lang.String getClientContextMenuReference​(UIContextMenu contextMenu,
                                                      boolean fullPropReference)
        Gets the reference to use for a context menu.
        Specified by:
        getClientContextMenuReference in interface IClientSessionGyro
        Parameters:
        contextMenu - The context menu.
        fullPropReference - Flag indicating a full property reference string should be returned, false for short (used internally by the server).
        Returns:
        The reference to use, empty string for none (never null).
        Throws:
        java.lang.IllegalArgumentException - If the context menu is not a stand-alone context menu but a child of a panel component.

      • getLocale

        public LocaleInfo getLocale()
        Gets the local info class instance.
        Specified by:
        getLocale in interface ILocaleString
        Returns:
        The locale info class instance when the client environment has been set, otherwise the default client locale info instance specified for the server.

      • setLocale

        public LocaleInfo setLocale​(LocaleInfo locale)
        Changes or sets the LocaleInfo for the environment.
        Specified by:
        setLocale in interface IClientSessionGyro
        Parameters:
        locale - localeInfo The locale information to use.
        Returns:
        The old LocaleInfo, or null if not set.

      • getLocaleKString

        public KString getLocaleKString​(java.lang.String id,
                                boolean system)
        Gets the KString of a particular ID from the app's text tables that are flagged to also handle LocaleString's depending on the flag.
        Specified by:
        getLocaleKString in interface ILocaleString
        Parameters:
        id - The text ID.
        system - Flagged to handle system strings for LocaleString's.
        Returns:
        The KString for the text ID in current locale, null if not found.

      • messageBox

        public void messageBox​(IMessageBoxReply reply,
                       IMessageBox.Icon icon,
                       KString title,
                       KString message,
                       KString... buttons)
        Displays a message box with the specified title and message.

        The callback is done in the client worker thread.

        Specified by:
        messageBox in interface IMessageBox
        Parameters:
        reply - The reply callback that is called when the user chooses a button or session is closed, null for none.
        icon - Icon to display, see the {link Icon} enumeration.
        title - The title string, must be non-null.
        message - The message to display, must be non-null.
        buttons - The strings for the buttons to display, if none, just an OK button is displayed. This array of buttons defined the index value returned by this method.
        Throws:
        java.lang.NullPointerException - If icon or message is null, or if any of the elements in buttons array is null.

      • toast

        public void toast​(KString message,
                  IToaster.Position position,
                  IToaster.Direction direction,
                  IToaster.Type type,
                  int duration)
        Displays a simple, unobstructive and ephemeral text message to the user.
        Specified by:
        toast in interface IToaster
        Parameters:
        message - The message to display, cannot be null.
        position - Position of toast, default value is Position.BOTTOM_CENTER if null.
        direction - Direction of the toast animation, default Direction.UP if null.
        type - Type of message style: message, warning, error of fatal, default is message if null.
        duration - Duration of the toast message being shown in ms. Valid values are in the interval [0, 10000], 0 for a sticky toast.

      • getScreenWidth

        public int getScreenWidth()
        Gets the current screen width.
        Specified by:
        getScreenWidth in interface IClientSessionGyro
        Returns:
        The current screen width, or zero if not initialized.

      • getScreenHeight

        public int getScreenHeight()
        Gets the current screen height.
        Specified by:
        getScreenHeight in interface IClientSessionGyro
        Returns:
        The current screen height, or zero if not initialized.

      • getScreenSize

        public Size getScreenSize()
        Gets the current screen size.
        Specified by:
        getScreenSize in interface IClientSessionGyro
        Returns:
        The current screen size, zero width and/or height if not initialized.

      • addScreenSizeListener

        public boolean addScreenSizeListener​(IScreenSizeListener listener)
        Adds a screen size listener for the client session. Calling this method multiple times with the same listener will have no effect (but to return false).
        Specified by:
        addScreenSizeListener in interface IClientSessionGyro
        Parameters:
        listener - The listener to add.
        Returns:
        true if the listener was added, false otherwise.
        Throws:
        java.lang.NullPointerException - If the listener is null.

      • removeScreenSizeListener

        public boolean removeScreenSizeListener​(IScreenSizeListener listener)
        Removes a screen size listener for the client session.
        Specified by:
        removeScreenSizeListener in interface IClientSessionGyro
        Parameters:
        listener - The listener to remove.
        Returns:
        true if listener is successfully removed, false otherwise.

      • isScreenOrientationLockSupported

        public boolean isScreenOrientationLockSupported()
        Checks if screen orientation locking is supported or not.
        Specified by:
        isScreenOrientationLockSupported in interface IClientSessionGyro
        Returns:
        true if the functions to lock or unlock screen orientation are supported, false otherwise.

      • addScreenOrientationListener

        public boolean addScreenOrientationListener​(IScreenOrientationListener listener)
        Adds a screen orientation listener for the client session. Calling this method multiple times with the same listener will have no effect (but to return false).
        Specified by:
        addScreenOrientationListener in interface IClientSessionGyro
        Parameters:
        listener - The listener to add.
        Returns:
        true if the listener was added, false otherwise.
        Throws:
        java.lang.NullPointerException - If the listener is null.

      • setScreenOrientation

        public boolean setScreenOrientation​(ScreenOrientation orientation)
        Locks the screen orientation.

        Note that there may be a delay in the orientation change after calling this method. This could be due to slow client connection, disconnected client or just due to device lag.

        Specified by:
        setScreenOrientation in interface IClientSessionGyro
        Parameters:
        orientation - The orientation.
        Returns:
        true for success, false for not supported.
        Throws:
        java.lang.IllegalArgumentException - If orientation is ScreenOrientation.unknown.

      • unlockScreenOrientation

        public boolean unlockScreenOrientation()
        Unlocks the screen orientation.

        Note that there may be a delay in the orientation change after calling this method. This could be due to slow client connection, disconnected client or just due to device lag.

        Specified by:
        unlockScreenOrientation in interface IClientSessionGyro
        Returns:
        true for success, false for not supported.

      • getImage

        public RuntimeImageDefinition getImage​(java.lang.String name)
        Gets an image definition from the image container for the client session.
        Specified by:
        getImage in interface IRuntimeImageCache
        Parameters:
        name - The image name.
        Returns:
        The predefined image definition, or null if not found.

      • setImage

        public boolean setImage​(RuntimeImageDefinition image)
        Adds the image definition to the image container for the client session. If the image already exists, it is replaced with the new definition.
        Specified by:
        setImage in interface IRuntimeImageCache
        Parameters:
        image - The image definition.
        Returns:
        true if the container was changed, i.e. image was added or replaced, false for no change.

      • removeImage

        public boolean removeImage​(java.lang.String name)
        Removes an image with a name from the client session.
        Specified by:
        removeImage in interface IRuntimeImageCache
        Parameters:
        name - The image to remove.
        Returns:
        true for removed, false if not found.

      • sendStat

        public void sendStat​(java.lang.String event,
                     DeviceParameter... params)
        Sends statistics event to the analytics engine on the client to log the event.
        Specified by:
        sendStat in interface IClientSessionGyro
        Parameters:
        event - The event name.
        params - Parameters to send, null values and sensitive parameters are ignored.

      • saveDeviceParameters

        public boolean saveDeviceParameters​(DeviceParameter... params)
        Saves parameters on the device.

        This method is only supported on devices running iiziRun and will always fail for other devices.

        Sensitive parameters are encrypted with a key kept on the server side. The encrypted data is padded and sent to the client and no key is used on the client side. Only the fingerprint of the server key used is included in the encrypted data. This means that the sensitive parameter is virtually undecipherable on the client side.

        Specified by:
        saveDeviceParameters in interface IClientSessionGyro
        Parameters:
        params - Parameters to save. A value of null means that the value is removed from storage.
        Returns:
        true for success, false for failure (or no parameters to save). In case of failure, an error is logged in the server.

      • getDeviceParameters

        public boolean getDeviceParameters​(DeviceParameter... params)
        Retrieves parameters from the device. The variables values and state are filled in before the return of this method call. The state indicates success, some error or if the parameter is not found.

        This method will always fail if the device is not running with iiziRun.

        Specified by:
        getDeviceParameters in interface IClientSessionGyro
        Parameters:
        params - The parameter to retrieve.
        Returns:
        true for success, false if iiziRun is not present and device parameters are not present.

      • triggerRemoteOpenWindow

        public boolean triggerRemoteOpenWindow​(java.lang.String url,
                                       java.lang.String target,
                                       WindowOptions options,
                                       IWindowCloseListener windowListener)
        Triggers opening of a browser window on the client.
        Specified by:
        triggerRemoteOpenWindow in interface IClientSessionGyro
        Parameters:
        url - The URL to open.
        target - The target, null for _blank.
        options - Options to use, null for "new tab" for a browser client.
        windowListener - Callback to listen to blocked or user close window, null for none. When "spawn mode" is used in the options, this parameter is ignored, i.e. as if set to null.
        Returns:
        true for success, false if the window cannot be opened because another window already is open or that the session is disposed of. In case of failure, any callback close listener will not be invoked.

      • triggerRemoteCloseWindow

        public boolean triggerRemoteCloseWindow​(boolean ignoreCallbackListener)
        Triggers closing of the window on the client that was opened with triggerRemoteOpenWindow.
        Specified by:
        triggerRemoteCloseWindow in interface IClientSessionGyro
        Parameters:
        ignoreCallbackListener - Flag to ignore calling a potential callback listener.
        Returns:
        true for success, false if no open window is present.

      • restartRemoteClient

        public void restartRemoteClient()
        Restarts the remote client. This is done without asking anything: it will just restart the iiziRun or browser by disconnecting from server and reloading the page directly. For iiziRun Developer/Custom sessions, this will bring up that interface.
        Specified by:
        restartRemoteClient in interface IClientSessionGyro