Class WebClient

  • Direct Known Subclasses:
    ServletUnitClient, WebConversation

    public abstract class WebClient
    extends java.lang.Object
    The context for a series of web requests. This class manages cookies used to maintain session context, computes relative URLs, and generally emulates the browser behavior needed to build an automated test of a web site.
    Author:
    Russell Gold, Jan Ohrstrom, Seth Ladd, Oliver Imbusch
    • Constructor Detail

      • WebClient

        protected WebClient()
    • Method Detail

      • getMainWindow

        public WebWindow getMainWindow()
      • setMainWindow

        public void setMainWindow​(WebWindow mainWindow)
      • getOpenWindows

        public WebWindow[] getOpenWindows()
      • getOpenWindow

        public WebWindow getOpenWindow​(java.lang.String name)
      • getResponse

        public WebResponse getResponse​(java.lang.String urlString)
                                throws java.io.IOException,
                                       org.xml.sax.SAXException
        Submits a GET method request and returns a response.
        Throws:
        org.xml.sax.SAXException - thrown if there is an error parsing the retrieved page
        java.io.IOException
      • sendRequest

        public WebResponse sendRequest​(WebRequest request)
                                throws java.io.IOException,
                                       org.xml.sax.SAXException
        Submits a web request and returns a response. This is an alternate name for the getResponse method.
        Throws:
        java.io.IOException
        org.xml.sax.SAXException
      • getCurrentPage

        public WebResponse getCurrentPage()
        Returns the response representing the current top page in the main window.
      • getResponse

        public WebResponse getResponse​(WebRequest request)
                                throws java.io.IOException,
                                       org.xml.sax.SAXException
        Submits a web request and returns a response, using all state developed so far as stored in cookies as requested by the server.
        Throws:
        org.xml.sax.SAXException - thrown if there is an error parsing the retrieved page
        java.io.IOException
      • getFrameNames

        public java.lang.String[] getFrameNames()
        Returns the name of the currently active frames in the main window.
      • getFrameContents

        public WebResponse getFrameContents​(java.lang.String frameName)
        Returns the response associated with the specified frame name in the main window. Throws a runtime exception if no matching frame is defined.
      • getFrameContents

        public WebResponse getFrameContents​(FrameSelector targetFrame)
        Returns the response associated with the specified frame name in the main window. Throws a runtime exception if no matching frame is defined.
        Since:
        1.6
      • getResource

        public WebResponse getResource​(WebRequest request)
                                throws java.io.IOException
        Returns the resource specified by the request. Does not update the client or load included framesets or scripts. May return null if the resource is a JavaScript URL which would normally leave the client unchanged.
        Throws:
        java.io.IOException
      • clearContents

        public void clearContents()
        Resets the state of this client, removing all cookies, frames, and per-client headers. This does not affect any listeners or preferences which may have been set.
      • addCookie

        public void addCookie​(java.lang.String name,
                              java.lang.String value)
        Deprecated.
        as of 1.6, use #putCookie instead.
        Defines a cookie to be sent to the server on every request.
      • putCookie

        public void putCookie​(java.lang.String name,
                              java.lang.String value)
        Defines a cookie to be sent to the server on every request. This overrides any previous setting for this cookie name.
      • getCookieNames

        public java.lang.String[] getCookieNames()
        Returns the name of all the active cookies which will be sent to the server.
      • getCookieDetails

        public Cookie getCookieDetails​(java.lang.String name)
        Returns an object containing the details of the named cookie
        Since:
        [ 1488617 ] alternate patch for cookie bug #1371204
      • getCookieValue

        public java.lang.String getCookieValue​(java.lang.String name)
        Returns the value of the specified cookie.
      • getClientProperties

        public ClientProperties getClientProperties()
        Returns the properties associated with this client.
      • setUserAgent

        public void setUserAgent​(java.lang.String userAgent)
        Deprecated.
        as of 1.4.6. Use ClientProperties#setUserAgent instead.
        Specifies the user agent identification. Used to trigger browser-specific server behavior.
      • getUserAgent

        public java.lang.String getUserAgent()
        Deprecated.
        as of 1.4.6. Use ClientProperties#getUserAgent instead.
        Returns the current user agent setting.
      • setAuthorization

        public void setAuthorization​(java.lang.String userName,
                                     java.lang.String password)
        Deprecated.
        as of 1.7. Use #setAuthentication for more accurate emulation of browser behavior.
        Sets a username and password for a basic authentication scheme.
      • setAuthentication

        public void setAuthentication​(java.lang.String realm,
                                      java.lang.String username,
                                      java.lang.String password)
        Specifies a username and password for on-demand authentication. Will only send the authorization header when challenged for the specified realm.
        Parameters:
        realm - the realm for which the credentials apply.
        username - the user to authenticate
        password - the credentials for the user
      • setProxyServer

        public abstract void setProxyServer​(java.lang.String proxyHost,
                                            int proxyPort)
        Specifies a proxy server to use for requests from this client.
      • setProxyServer

        public void setProxyServer​(java.lang.String proxyHost,
                                   int proxyPort,
                                   java.lang.String userName,
                                   java.lang.String password)
        Specifies a proxy server to use, along with a user and password for authentication.
        Since:
        1.6
      • clearProxyServer

        public void clearProxyServer()
        Clears the proxy server settings.
      • getProxyHost

        public java.lang.String getProxyHost()
        Returns the name of the active proxy server.
      • getProxyPort

        public int getProxyPort()
        Returns the number of the active proxy port, or 0 is none is specified.
      • setHeaderField

        public void setHeaderField​(java.lang.String fieldName,
                                   java.lang.String fieldValue)
        Sets the value for a header field to be sent with all requests. If the value set is null, removes the header from those to be sent.
      • getHeaderField

        public java.lang.String getHeaderField​(java.lang.String fieldName)
        Returns the value for the header field with the specified name. This method will ignore the case of the field name.
      • setExceptionsThrownOnErrorStatus

        public void setExceptionsThrownOnErrorStatus​(boolean throwExceptions)
        Specifies whether an exception will be thrown when an error status (4xx or 5xx) is detected on a response. Defaults to the value returned by HttpUnitOptions.getExceptionsThrownOnErrorStatus.
      • getExceptionsThrownOnErrorStatus

        public boolean getExceptionsThrownOnErrorStatus()
        Returns true if an exception will be thrown when an error status (4xx or 5xx) is detected on a response.
      • addClientListener

        public void addClientListener​(WebClientListener listener)
        Adds a listener to watch for requests and responses.
      • removeClientListener

        public void removeClientListener​(WebClientListener listener)
        Removes a listener to watch for requests and responses.
      • addWindowListener

        public void addWindowListener​(WebWindowListener listener)
        Adds a listener to watch for window openings and closings.
      • removeWindowListener

        public void removeWindowListener​(WebWindowListener listener)
        Removes a listener to watch for window openings and closings.
      • getNextAlert

        public java.lang.String getNextAlert()
        Returns the next javascript alert without removing it from the queue.
      • popNextAlert

        public java.lang.String popNextAlert()
        Returns the next javascript alert and removes it from the queue. If the queue is empty, will return an empty string.
      • setDialogResponder

        public void setDialogResponder​(DialogResponder responder)
        Specifies the object which will respond to all dialogs.
      • newResponse

        protected abstract WebResponse newResponse​(WebRequest request,
                                                   FrameSelector targetFrame)
                                            throws java.io.IOException
        Creates a web response object which represents the response to the specified web request.
        Parameters:
        request - the request to which the response should be generated
        targetFrame - the frame in which the response should be stored
        Throws:
        java.io.IOException
      • writeMessageBody

        protected final void writeMessageBody​(WebRequest request,
                                              java.io.OutputStream stream)
                                       throws java.io.IOException
        Writes the message body for the request.
        Throws:
        java.io.IOException
      • getHeaderFields

        protected java.util.Dictionary getHeaderFields​(java.net.URL targetURL)
        Returns the value of all current header fields.
      • updateMainWindow

        protected final void updateMainWindow​(FrameSelector frame,
                                              WebResponse response)
                                       throws java.io.IOException,
                                              org.xml.sax.SAXException
        Updates this web client based on a received response. This includes updating cookies and frames. This method is required by ServletUnit, which cannot call the updateWindow method directly.
        Throws:
        java.io.IOException
        org.xml.sax.SAXException
      • getCookieJar

        public CookieJar getCookieJar()
        Deprecated.
        - use with care - was not public in the past
        Support Request [ 1288796 ] getCookieJar() in WebClient
        Returns:
        the cookie jar