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 Details

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

    • disconnectAsync

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

    • 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

    • getCapability

      Object getCapability(BareSession.Capability capability) throws UnsupportedOperationException
      Get the value of the requested capability. The type of the value depends on the capability. If the requested capability is not available for this session, an UnsupportedOperationException is thrown. Check the availability of the capability with hasCapability(com.rs.seagull.emulator.api.BareSession.Capability).
      Parameters:
      capability - the requested capability
      Returns:
      the value of the requested capability
      Throws:
      UnsupportedOperationException - thrown if the requested capability is not available in this session

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

    • 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

    • getStartupInformation

      StartupInformation getStartupInformation()
      Get the Startup Information which is provided by the host during negotiation/startup. The returned instance can be an instance of StartupInformation.Ibm3270 or StartupInformation.Ibm5250. This can be determined by calling it's method StartupInformation.getEmulator() and check the returned value against StartupInformation.Ibm3270 or StartupInformation.Ibm5250 Can return null.
      Returns:
      the Startup Information or null

    • 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

    • sendKeyAndCapture

      void sendKeyAndCapture(String key, BareSession.Capture capture)
      Send a key and capture the response text.
      Parameters:
      key - the key to send
      capture - the BareSession.Capture instance that will receive the response text