Package com.rs.seagull.emulator.api

Interface BareSession

  • All Known Subinterfaces:
    Session
    public interface BareSession
    A BareSession represents a connection to a host and allows you to "drive" the host application. See SessionFactory for creating instances of HostSession. You can drive the application by using the basic underlying objects - BareScreen, Keyboard, and Cursor - or you can use HostSession directly via a variety of convenience methods. The kinds of things you can do fall into these categories: - connect/disconnect - get string content - send keystrokes - wait for a variety of conditions - execute script Note: All screen coordinates are based on upper left corner origin of 0,0. x coordinate is horizontal. y is vertical. units are characters.

    • Method Detail

      • getScreen

        BareScreen getScreen()
        Returns the currently visible screen.
        Returns:
        the currently visible screen.

      • getKeyboard

        Keyboard getKeyboard()
        Returns the keyboard for the current screen. Same as getScreen().getKeyboard().
        Returns:
        the keyboard for the current screen.

      • getCursor

        BareCursor getCursor()
        Returns the cursor for the current screen. Same as getScreen().getCursor().
        Returns:
        the current cursor.

      • getScreenList

        List<BareScreen> getScreenList()
        Returns all available screens.
        Returns:
        all available screens.

      • getCursorPosition

        com.seagullsw.common.toolbox.geometry.Point getCursorPosition()
        Returns the current cursor position. Same as getScreen().getCursor().getPosition(). All screen coordinates are relative to 0,0 origin upper left.
        Returns:
        the current cursor position.

      • isCursorVisible

        boolean isCursorVisible()
        Returns true if the cursor is visible. Same as getScreen().getCursor().isVisible().
        Returns:
        true if the cursor is visible.

      • sendText

        void sendText​(String string)
        Sends text to the host at the current cursor position. Same as getScreen().getKeyboard().sendText(string).
        Parameters:
        string - the text to send to the host.

      • sendBytes

        void sendBytes​(byte[] bytes)
        Sends "raw" bytes to the host at the current cursor position. Same as getScreen().getKeyboard().sendBytes(bytes). Typically used with VT to send "non standard" byte sequences.
        Parameters:
        bytes - the bytes to send to the host.

      • sendKey

        void sendKey​(String key)
        Sends a key to the host at the current cursor position. Same as getScreen().getKeyboard().sendKey(key). The list of possible keys is in Keys, specifically Keys.Ibm5250, Keys.Ibm3270, and Keys.AnsiVT.
        Parameters:
        key - the key to send to the host. See Keys.

      • getScreenSize

        com.seagullsw.common.toolbox.geometry.Dimension getScreenSize()
        Returns the size of the current screen. Same as getScreen().getSize().
        Returns:
        the size of the current screen.

      • getText

        String getText​(com.seagullsw.common.toolbox.geometry.Point at,
               int length)
        Returns the text content of a portion of the current screen. If the prescribed portion crosses a line boundary, the string returned is contiguous - there are no line break characters. Same as getScreen().getText(at,length).
        Parameters:
        at - the screen location of the beginning of the text to retrieve.
        length - the number of characters to retrieve.
        Returns:
        the text content of the specified portion of the current screen.

      • getId

        String getId()
        Returns a unique (within this JVM) identifier.
        Returns:
        a unique identifier

      • connect

        void connect​(com.seagullsw.common.toolbox.concurrent.Timeout timeout)
      throws IOException,
             TimeoutException,
             UnresolvedAddressException
        Connect to the host, waiting for the connection to be completed. Note that there is no public asynchronous connect - if you desire such a feature, please contact the CJL team.
        Parameters:
        timeout - if the connection is not completed within the timeout, throw IOException.
        Throws:
        TimeoutException - if the connecting took to long.
        UnresolvedAddressException - when connecting to a host whose name cannot be resolved.
        IOException - if the connection could not be established.

      • isConnected

        boolean isConnected()
        Returns true if the session is connected.
        Returns:
        true if the session is connected.

      • disconnect

        void disconnect()
        Disconnect from the host.

      • connectAsync

        com.seagullsw.common.emulator.physical.base.connection2.IConnection connectAsync​(com.seagullsw.common.toolbox.concurrent.Timeout timeout)
        Initiate a connection to the host asynchronously. It is the responsibility of the caller to first obtain the HostConnection via getHostConnection() and add a listener to it. When the listener indicates that a connection has been made, method completeConnect() must be called to finish some housekeeping.
        Parameters:
        timeout - the amount of time to attempt to connect
        Returns:
        an instance of IConnection which represents the connection

      • completeConnect

        void completeConnect()
        Complete the connection housekeeping after an asynchronous connection was made.
        See Also:
        connectAsync(Timeout)

      • disconnectAsync

        void disconnectAsync()
        Disconnect from the host asynchronously.
        See Also:
        connectAsync(Timeout)

      • getHostConnection

        com.seagullsw.common.emulator.physical.base.model2.connection.HostConnection getHostConnection()
        Get the HostConnection from the session. Can return null if the session was created without a ConnectionBuilder.
        Returns:
        the HostConnection or null

      • hasCapability

        boolean hasCapability​(BareSession.Capability capability)
        Check whether this session has the requested capability.
        Parameters:
        capability - the requested capability
        Returns:
        true if this session has the requested capability

      • getText

        String getText​(int start,
               int length)
        Returns the text content of a portion of the current screen. Same as getScreen().getText(start,length).
        Parameters:
        start - the zero-based character offset of the beginning of the text to retrieve.
        length - the number of characters to retrieve.
        Returns:
        the text content of the specified portion of the current screen.

      • getText

        String getText​(int x,
               int y,
               int length)
        Returns the text content of a portion of the current screen. Same as getScreen().getText(x,y,length).
        Parameters:
        x - the horizontal screen coordinate of the beginning of the text to retrieve.
        y - the vertical screen coordinate of the beginning of the text to retrieve.
        length - the number of characters to retrieve.
        Returns:
        the text content of the specified portion of the current screen.

      • getTextAtRowColumn

        String getTextAtRowColumn​(int row,
                          int column,
                          int length)
        Returns the text content of a portion of the current screen. NOTE: the parameters are the 1-based row and 1-based column index of the portion of the screen This method is in place to provide backward compatibility with HostScreenGetRaw which was available in SIP2
        Parameters:
        row - the vertical screen coordinate of the beginning of the text to retrieve.
        column - the horizontal screen coordinate of the beginning of the text to retrieve.
        length - the number of characters to retrieve.
        Returns:
        the text content of the specified portion of the current screen.

      • getTextLine

        String getTextLine​(int line)
        Returns a single line of text content.
        Parameters:
        line - the line number, the top line is 0.
        Returns:
        a single line of text content

      • getTextLines

        List<String> getTextLines​(com.seagullsw.common.toolbox.geometry.Point at,
                          int length)
        Returns the text content of a portion of the current screen, divided into individual lines matching the lines on the screen. So the first and last lines in the list will be less than full width unless the prescribed portion starts exactly at the left edge and ends at the right.
        Parameters:
        at - the screen location of the beginning of the lines to retrieve.
        length - the number of characters to retrieve.
        Returns:
        a list of strings, one for each line included in specified screen portion.

      • getTextLines

        List<String> getTextLines​(com.seagullsw.common.toolbox.geometry.Rectangle r)
        Returns the text content of a rectangular portion of the current screen, divided into individual lines matching the lines on the screen.
        Parameters:
        r - the rectangle to retrieve.
        Returns:
        a list of strings, one for each line.

      • toPoint

        com.seagullsw.common.toolbox.geometry.Point toPoint​(int offset)
        Convert a character offset to a screen coordinate.
        Parameters:
        offset - the character offset to convert.
        Returns:
        the screen coordinate of the offset.

      • toOffset

        int toOffset​(com.seagullsw.common.toolbox.geometry.Point point)
        Convert a screen coordinate to a character offset.
        Parameters:
        point - the screen coordinate to convert.
        Returns:
        the character offset of the screen coordinate.

      • waitFor

        void waitFor​(Condition condition,
             com.seagullsw.common.toolbox.concurrent.Timeout timeout)
      throws TimeoutException
        Waits for a condition to become true. Returns as soon as possible after the condition becomes true. If the timeout expires before the condition becomes true, throw TimeoutException.
        Parameters:
        condition - the condition to wait for.
        timeout - the amount of time to wait before timing out.
        Throws:
        TimeoutException - if the specified timeout elapses
        com.seagullsw.common.emulator.physical.base.connection2.DisconnectedWhileWaitingException - (a subclass of TimeoutException) if the connection disconnects while waiting
        See Also:
        for static methods that create several handy Condition instances.

      • showViewer

        void showViewer()
        Open a graphical viewer on the session, so a human can watch it "in action".

      • hideViewer

        void hideViewer()
        Hide the viewer.

      • setDebugDelaySendKey

        void setDebugDelaySendKey​(int delay,
                          TimeUnit units)
        Set the amount of time to pause before every sendKey call, to assist with simple debugging. Same as getScreen().getKeyboard().setDebugDelaySendKey(delay, units).
        Parameters:
        delay - the delay
        units - the delay unit

      • setDebugDelaySendText

        void setDebugDelaySendText​(int delay,
                           TimeUnit units)
        Set the amount of time to pause before every sendText call, to assist with simple debugging. Same as getScreen().getKeyboard().setDebugDelaySendText(delay, units).
        Parameters:
        delay - the delay
        units - the delay unit

      • produceTroubleshootLog

        String produceTroubleshootLog()
        Produce a troubleshoot log. The troubleshoot log contains generic information about the runtime environment and information about all sessions (so not only about this session).
        Returns:
        the troubleshoot log

      • changeBlackBoxCapacity

        void changeBlackBoxCapacity​(int capacity)
        Change the capacity of the Black Box recorder for this session. When the capacity is enlarged, all the existing Black Box events will be retained. When the capacity is reduced, some existing Black Box events might get lost when they don't fit.
        Parameters:
        capacity - the capacity of the Black Box recorder for this session

      • executeJavaScript

        Object executeJavaScript​(String script,
                         Map<String,​Object> inputParams,
                         Map<String,​Object> outputParams)
        Execute the provided Javascript in the context of this session. The context of this session is available as Javascript object hostSession. On entry, the provided input variables are added as objects to the Javascript scope. Upon finish, the names of the provided output variables are looked up and their values are inserted. These packages are imported automatically, for convenience: com.rs.seagull.emulator.api com.seagullsw.common.toolbox.geometry
        Parameters:
        script - the provided Javascript
        inputParams - the provided input variables, can be null
        outputParams - the provided output variables, can be null
        Returns:
        the value of the last line of the script

      • executeJavaScript

        Object executeJavaScript​(String script,
                         Map<String,​Object> inputParams,
                         Map<String,​Object> outputParams,
                         Callable<Boolean> interruptChecker)
        Execute the provided Javascript in the context of this session. The context of this session is available as Javascript object hostSession. On entry, the provided input variables are added as objects to the Javascript scope. Upon finish, the names of the provided output variables are looked up and their values are inserted. This variant allows the script to be interrupted. These packages are imported automatically, for convenience: com.rs.seagull.emulator.api com.seagullsw.common.toolbox.geometry
        Parameters:
        script - the provided Javascript
        inputParams - the provided input variables, can be null
        outputParams - the provided output variables, can be null
        interruptChecker - a method that is called for every line of script executed, if it returns true then script execution is stopped
        Returns:
        the value of the last line of the script

      • executeJavaScript

        Object executeJavaScript​(String script,
                         Map<String,​Object> inputParams,
                         Map<String,​Object> outputParams,
                         Callable<Boolean> interruptChecker,
                         org.apache.commons.vfs2.FileObject scriptFolder)
        Execute the provided Javascript in the context of this session. The context of this session is available as Javascript object hostSession. On entry, the provided input variables are added as objects to the Javascript scope. Upon finish, the names of the provided output variables are looked up and their values are inserted. This variant allows the script to be interrupted. These packages are imported automatically, for convenience: com.rs.seagull.emulator.api com.seagullsw.common.toolbox.geometry The script can refer to other scripts using the 'require' feature - the required scripts are found in scriptFolder.
        Parameters:
        script - the provided Javascript
        inputParams - the provided input variables, can be null
        outputParams - the provided output variables, can be null
        interruptChecker - a method that is called for every line of script executed, if it returns true then script execution is stopped
        scriptFolder - location of other script files
        Returns:
        the value of the last line of the script

      • isOperatorError

        boolean isOperatorError()
        Return true if there was an Operator Error.
        Returns:
        true if there was an Operator Error

      • addStartupInformationListener

        void addStartupInformationListener​(StartupInformationListener listener)
        Add the provided listener, so it will get notified of changes in the startup information. If the listener is an instance of StartupInformationListener.Ibm3270, the listener will be notified of changes in the startup information for IBM 3270. If the listener is an instance of StartupInformationListener.Ibm5250, the listener will be notified of changes in the startup information for IBM 5250.
        Parameters:
        listener - the provided listener

      • removeStartupInformationListener

        void removeStartupInformationListener​(StartupInformationListener listener)
        Remove the provided listener, so it will no longer get notified of changes in the startup information.
        Parameters:
        listener - the provided listener