Module org.htmlunit
Package org.htmlunit

Class WebClientOptions

java.lang.Object
org.htmlunit.WebClientOptions
All Implemented Interfaces:
Serializable
public class WebClientOptions extends Object implements Serializable
Configuration options for WebClient instances. This class provides fine-grained control over client behavior including:
  • JavaScript and CSS processing
  • SSL/TLS configuration and certificates
  • HTTP timeouts and proxy settings
  • Memory management and temporary file handling
  • WebSocket and geolocation support

All options have sensible defaults and can be modified independently.

Author:
Ahmed Ashour, Marc Guillemot, Madis Pärn, Ronald Brill
See Also:

  • Constructor Details

    • WebClientOptions

      public WebClientOptions()

  • Method Details

    • setSSLContext

      public void setSSLContext(SSLContext sslContext)
      Sets the SSLContext; if this is set it is used and some other settings are ignored (protocol, keyStore, keyStorePassword, trustStore, sslClientCertificateStore, sslClientCertificatePassword).

      This property is transient (because SSLContext is not serializable)

      Parameters:
      sslContext - the SSLContext, null to use for default value

    • getSSLContext

      public SSLContext getSSLContext()
      Gets the SSLContext; if this is set this is used and some other settings are ignored (protocol, keyStore, keyStorePassword, trustStore, sslClientCertificateStore, sslClientCertificatePassword).

      This property is transient (because SSLContext is not serializable)

      Returns:
      the SSLContext

    • setUseInsecureSSL

      public void setUseInsecureSSL(boolean useInsecureSSL)
      If set to true, the client will accept connections to any host, regardless of whether they have valid certificates or not. This is especially useful when you are trying to connect to a server with expired or corrupt certificates.
      Parameters:
      useInsecureSSL - whether or not to use insecure SSL

    • isUseInsecureSSL

      public boolean isUseInsecureSSL()
      Indicates if insecure SSL should be used.
      Returns:
      true if insecure SSL should be used. Default is false.

    • setRedirectEnabled

      public void setRedirectEnabled(boolean enabled)
      Sets whether or not redirections will be followed automatically on receipt of a redirect status code from the server.
      Parameters:
      enabled - true to enable automatic redirection

    • setPageRefreshLimit

      public void setPageRefreshLimit(int pageRefreshLimit)
      Sets the redirect limit for page refresh operations using HTTP refresh headers or meta tags. This prevents infinite refresh loops by limiting the number of consecutive refreshes allowed. Set to -1 to allow unlimited refreshes.

      Note: The NiceRefreshHandler and ImmediateRefreshHandler have additional loop protection that may trigger before this limit.

      Parameters:
      pageRefreshLimit - the maximum number of refresh loops, or -1 for unlimited

    • getTempFileDirectory

      public File getTempFileDirectory()
      Returns the directory to be used for storing the response content in a temporary file see getMaxInMemory().
      Returns:
      the directory to be used for storing temp files or null to use the system default

    • setTempFileDirectory

      public void setTempFileDirectory(File tempFileDirectory) throws IOException
      Sets the directory to be used for storing response content in temporary files. See setMaxInMemory(int) for when temporary files are created. If the directory doesn't exist, it will be created automatically.
      Parameters:
      tempFileDirectory - the directory to use, or null for system default
      Throws:
      IOException - if directory creation fails
      IllegalArgumentException - if the path points to an existing file

    • isRedirectEnabled

      public boolean isRedirectEnabled()
      Returns whether or not redirections will be followed automatically on receipt of a redirect status code from the server.
      Returns:
      true if automatic redirection is enabled

    • getPageRefreshLimit

      public int getPageRefreshLimit()
      Returns the limit to be used when a page refreshes itself by using a http refresh header or meta tag. Negative values are interpreted as endless refresh support.
      Returns:
      pageRefreshLimit the number of refresh loops before throwing an exception

    • setSSLClientCertificateKeyStore

      public void setSSLClientCertificateKeyStore(KeyStore keyStore, char[] keyStorePassword)
      Sets the SSL client certificate KeyStore to use.

      If the web server requires Renegotiation, you have to set system property "sun.security.ssl.allowUnsafeRenegotiation" to true, as hinted in TLS Renegotiation Issue.

      In some cases the impl seems to pick old certificates from the KeyStore. To avoid that, wrap your KeyStore inside your own KeyStore impl and filter out outdated certificates.

      This property is transient (because KeyStore is not serializable)

      Parameters:
      keyStore - KeyStore to use
      keyStorePassword - the keystore password

    • setSSLClientCertificateKeyStore

      public void setSSLClientCertificateKeyStore(URL keyStoreUrl, String keyStorePassword, String keyStoreType)
      Sets the SSL client certificate to use. The needed parameters are used to construct a KeyStore.

      If the web server requires Renegotiation, you have to set system property "sun.security.ssl.allowUnsafeRenegotiation" to true, as hinted in TLS Renegotiation Issue.

      This property is transient (because KeyStore is not serializable)

      Parameters:
      keyStoreUrl - the URL which locates the certificate KeyStore
      keyStorePassword - the certificate KeyStore password
      keyStoreType - the type of certificate KeyStore, usually jks or pkcs12

    • setSSLClientCertificateKeyStore

      public void setSSLClientCertificateKeyStore(InputStream keyStoreInputStream, String keyStorePassword, String keyStoreType)
      Sets the SSL client certificate KeyStore to use. The parameters are used to construct the KeyStore.

      If the web server requires Renegotiation, you have to set system property "sun.security.ssl.allowUnsafeRenegotiation" to true, as hinted in TLS Renegotiation Issue.

      In some cases the impl seems to pick old certificates from the KeyStore. To avoid that, wrap your KeyStore inside your own KeyStore impl and filter out outdated certificates. Provide the KeyStore to the options instead of the input stream.

      Parameters:
      keyStoreInputStream - the input stream which represents the KeyStore holding the certificates
      keyStorePassword - the KeyStore password
      keyStoreType - the type of KeyStore, usually jks or pkcs12

    • getSSLClientCertificateStore

      public KeyStore getSSLClientCertificateStore()
      Gets the SSLClientCertificateStore.

      This property is transient (because KeyStore is not serializable)

      Returns:
      the KeyStore for use on SSL connections

    • getSSLClientCertificatePassword

      public char[] getSSLClientCertificatePassword()
      Gets the SSLClientCertificatePassword.
      Returns:
      the password

    • getSSLClientProtocols

      public String[] getSSLClientProtocols()
      Gets the protocol versions enabled for use on SSL connections.
      Returns:
      the protocol versions enabled for use on SSL connections
      See Also:

    • setSSLClientProtocols

      public void setSSLClientProtocols(String... sslClientProtocols)
      Sets the protocol versions enabled for use on SSL connections, null to use default ones.
      Parameters:
      sslClientProtocols - the protocol versions
      See Also:

    • getSSLClientCipherSuites

      public String[] getSSLClientCipherSuites()
      Gets the cipher suites enabled for use on SSL connections.
      Returns:
      the cipher suites enabled for use on SSL connections
      See Also:

    • setSSLClientCipherSuites

      public void setSSLClientCipherSuites(String... sslClientCipherSuites)
      Sets the cipher suites enabled for use on SSL connections, null to use default ones.
      Parameters:
      sslClientCipherSuites - the cipher suites
      See Also:

    • setJavaScriptEnabled

      public void setJavaScriptEnabled(boolean enabled)
      Enables/disables JavaScript support. By default, this property is enabled.
      Parameters:
      enabled - true to enable JavaScript support

    • isJavaScriptEnabled

      public boolean isJavaScriptEnabled()
      Returns true if JavaScript is enabled and the script engine was loaded successfully.
      Returns:
      true if JavaScript is enabled

    • setCssEnabled

      public void setCssEnabled(boolean enabled)
      Enables/disables CSS support. By default, this property is enabled. If disabled HtmlUnit will not download the linked css files and also not triggered the associated onload/onerror events.
      Parameters:
      enabled - true to enable CSS support

    • isCssEnabled

      public boolean isCssEnabled()
      Returns true if CSS is enabled.
      Returns:
      true if CSS is enabled

    • setPopupBlockerEnabled

      public void setPopupBlockerEnabled(boolean enabled)
      Enable/disable the popup window blocker. By default, the popup blocker is disabled, and popup windows are allowed. When set to true, window.open() has no effect and returns null.
      Parameters:
      enabled - true to enable the popup window blocker

    • isPopupBlockerEnabled

      public boolean isPopupBlockerEnabled()
      Returns true if the popup window blocker is enabled.
      Returns:
      true if the popup window blocker is enabled

    • setDoNotTrackEnabled

      public void setDoNotTrackEnabled(boolean enabled)
      Enables/disables "Do Not Track" support. By default, this property is disabled.
      Parameters:
      enabled - true to enable "Do Not Track" support

    • isDoNotTrackEnabled

      public boolean isDoNotTrackEnabled()
      Returns true if "Do Not Track" is enabled.
      Returns:
      true if "Do Not Track" is enabled

    • setPrintContentOnFailingStatusCode

      public void setPrintContentOnFailingStatusCode(boolean enabled)
      Specify whether or not the content of the resulting document will be printed to the console in the event of a failing response code. Successful response codes are in the range 200-299. The default is true.
      Parameters:
      enabled - True to enable this feature

    • isPrintContentOnFailingStatusCode

      public boolean isPrintContentOnFailingStatusCode()
      Returns true if the content of the resulting document will be printed to the console in the event of a failing response code.
      Returns:
      true if the content of the resulting document will be printed to the console in the event of a failing response code
      See Also:

    • setThrowExceptionOnFailingStatusCode

      public void setThrowExceptionOnFailingStatusCode(boolean enabled)
      Specify whether or not an exception will be thrown in the event of a failing status code. Successful status codes are in the range 200-299. The default is true.
      Parameters:
      enabled - true to enable this feature

    • isThrowExceptionOnFailingStatusCode

      public boolean isThrowExceptionOnFailingStatusCode()
      Returns true if an exception will be thrown in the event of a failing response code.
      Returns:
      true if an exception will be thrown in the event of a failing response code
      See Also:

    • isThrowExceptionOnScriptError

      public boolean isThrowExceptionOnScriptError()
      Indicates if an exception should be thrown when a script execution fails (the default) or if it should be caught and just logged to allow page execution to continue.
      Returns:
      true if an exception is thrown on script error (the default)

    • setThrowExceptionOnScriptError

      public void setThrowExceptionOnScriptError(boolean enabled)
      Changes the behavior of this webclient when a script error occurs.
      Parameters:
      enabled - indicates if exception should be thrown or not

    • getHomePage

      public String getHomePage()
      Returns the client's current homepage.
      Returns:
      the client's current homepage

    • setHomePage

      public void setHomePage(String homePage)
      Sets the client's homepage.
      Parameters:
      homePage - the new homepage URL

    • getProxyConfig

      public ProxyConfig getProxyConfig()
      Returns the proxy configuration for this client.
      Returns:
      the proxy configuration for this client

    • setProxyConfig

      public void setProxyConfig(ProxyConfig proxyConfig)
      Sets the proxy configuration for this client.
      Parameters:
      proxyConfig - the proxy configuration for this client

    • getTimeout

      public int getTimeout()
      Gets the timeout value for the WebConnection. The default timeout is 90 seconds.
      Returns:
      the timeout value in milliseconds
      See Also:

    • setTimeout

      public void setTimeout(int timeout)

      Sets the timeout of the WebConnection. Set to zero for an infinite wait.

      Note: The timeout is used twice. The first is for making the socket connection, the second is for data retrieval. If the time is critical you must allow for twice the time specified here.

      Parameters:
      timeout - the value of the timeout in milliseconds

    • getConnectionTimeToLive

      public long getConnectionTimeToLive()
      Gets the connTimeToLive value for the HttpClient connection pool.
      Returns:
      the timeout value in milliseconds

    • setConnectionTimeToLive

      public void setConnectionTimeToLive(long connectionTimeToLive)
      Sets the connection time-to-live for the HttpClient connection pool. This is useful when working with web pages behind DNS-based load balancers where IP addresses may change frequently.
      Parameters:
      connectionTimeToLive - the timeout in milliseconds, or -1 to disable (default)

    • setSSLInsecureProtocol

      public void setSSLInsecureProtocol(String sslInsecureProtocol)
      Sets the SSL protocol, used only when setUseInsecureSSL(boolean) is set to true.
      Parameters:
      sslInsecureProtocol - the SSL protocol for insecure SSL connections, null to use for default value

    • getSSLInsecureProtocol

      public String getSSLInsecureProtocol()
      Gets the SSL protocol, to be used only when setUseInsecureSSL(boolean) is set to true.
      Returns:
      the SSL protocol for insecure SSL connections

    • setSSLTrustStore

      public void setSSLTrustStore(URL sslTrustStoreUrl, String sslTrustStorePassword, String sslTrustStoreType)
      Sets the SSL server certificate trust store. All server certificates will be validated against this trust store.

      This property is transient (because KeyStore is not serializable)

      The needed parameters are used to construct a KeyStore.

      Parameters:
      sslTrustStoreUrl - the URL which locates the trust store
      sslTrustStorePassword - the trust store password
      sslTrustStoreType - the type of trust store, usually jks or pkcs12

    • getSSLTrustStore

      public KeyStore getSSLTrustStore()
      Gets the SSL TrustStore.

      This property is transient (because KeyStore is not serializable)

      Returns:
      the SSL TrustStore for insecure SSL connections

    • getMaxInMemory

      public int getMaxInMemory()
      Returns the maximum bytes stored in memory before content is saved to temporary files. When response content exceeds this limit, it will be written to a temporary file in the directory specified by getTempFileDirectory().
      Returns:
      the maximum bytes in memory (default: 500 * 1024)
      See Also:

    • setMaxInMemory

      public void setMaxInMemory(int maxInMemory)
      Sets the maximum bytes to have in memory, after which the content is saved to a temporary file. Set this to zero or -1 to deactivate the saving at all.
      Parameters:
      maxInMemory - maximum bytes in memory

    • getHistorySizeLimit

      public int getHistorySizeLimit()
      Returns the maximum number of pages kept in WebWindow.getHistory().
      Returns:
      the maximum number of pages in history

    • setHistorySizeLimit

      public void setHistorySizeLimit(int historySizeLimit)
      Sets the History size limit. HtmlUnit uses SoftReferences<Page> for storing the pages that are part of the history. If you like to fine tune this you can use setHistoryPageCacheLimit(int) to limit the number of page references stored by the history.
      Parameters:
      historySizeLimit - maximum number of pages in history

    • getHistoryPageCacheLimit

      public int getHistoryPageCacheLimit()
      Returns the maximum number of pages to cache in history.
      Returns:
      the maximum number of pages to cache in history

    • setHistoryPageCacheLimit

      public void setHistoryPageCacheLimit(int historyPageCacheLimit)
      Sets the maximum number of pages to cache in history. If this value is smaller than the {getHistorySizeLimit() than HtmlUnit will only use soft references for the first historyPageCacheLimit entries in the history. For older entries only the url is saved; the page will be (re)retrieved on demand.
      Parameters:
      historyPageCacheLimit - maximum number of pages to cache in history default is Integer.MAX_VALUE; negative values are having the same effect as setting this to zero.

    • getLocalAddress

      public InetAddress getLocalAddress()
      Returns local address to be used for request execution.

      On machines with multiple network interfaces, this parameter can be used to select the network interface from which the connection originates.

      Default: null

      Returns:
      the local address

    • setLocalAddress

      public void setLocalAddress(InetAddress localAddress)
      Sets the local network interface address for outgoing HTTP requests. Useful on multi-homed machines to control which network interface is used.
      Parameters:
      localAddress - the local IP address to bind to, or null for automatic selection

    • setDownloadImages

      public void setDownloadImages(boolean downloadImages)
      Sets whether to automatically download images by default, or not.
      Parameters:
      downloadImages - whether to automatically download images by default, or not

    • isDownloadImages

      public boolean isDownloadImages()
      Returns whether to automatically download images by default, or not.
      Returns:
      whether to automatically download images by default, or not.

    • setScreenWidth

      public void setScreenWidth(int screenWidth)
      Sets the screen width. This value is used by JavaScript's screen.width property.
      Parameters:
      screenWidth - the screen width in pixels (must be positive)

    • getScreenWidth

      public int getScreenWidth()
      Returns the screen width.
      Returns:
      the screen width

    • setScreenHeight

      public void setScreenHeight(int screenHeight)
      Sets the screen height.
      Parameters:
      screenHeight - the screen height

    • getScreenHeight

      public int getScreenHeight()
      Returns the screen height.
      Returns:
      the screen height

    • getNekoReaderBufferSize

      public int getNekoReaderBufferSize()
      Returns the Neko HTML parser reader buffer size. This controls the internal buffer size used by the NekoHTML parser for reading HTML content. Larger buffers can improve performance for large documents but consume more memory.
      Returns:
      the buffer size in bytes, or -1 for parser default

    • setNekoReaderBufferSize

      public void setNekoReaderBufferSize(int nekoReaderBufferSize)
      Sets the Neko HTML parser reader buffer size. A larger buffer size can improve parsing performance for large HTML documents but will consume more memory. Set to -1 to use the parser's default buffer size.
      Parameters:
      nekoReaderBufferSize - the buffer size in bytes, or -1 for default

    • setWebSocketEnabled

      public void setWebSocketEnabled(boolean enabled)
      Enables/disables WebSocket support. By default, this property is enabled.
      Parameters:
      enabled - true to enable WebSocket support

    • isWebSocketEnabled

      public boolean isWebSocketEnabled()
      Returns true if WebSockets are enabled.
      Returns:
      true if WebSockets are enabled

    • getWebSocketMaxTextMessageSize

      public int getWebSocketMaxTextMessageSize()
      Returns the maximum size in bytes for WebSocket text messages. Set to -1 to use the default.
      Returns:
      the maximum text message size in bytes, or -1 for default

    • setWebSocketMaxTextMessageSize

      public void setWebSocketMaxTextMessageSize(int webSocketMaxTextMessageSize)
      Sets the maximum size in bytes for WebSocket text messages. This limit applies to individual text frames received by the WebSocket.
      Parameters:
      webSocketMaxTextMessageSize - the maximum size in bytes, or -1 for default

    • getWebSocketMaxBinaryMessageSize

      public int getWebSocketMaxBinaryMessageSize()
      Returns the maximum size in bytes for WebSocket binary messages. Set to -1 to use the default.
      Returns:
      the maximum binary message size in bytes, or -1 for default

    • setWebSocketMaxBinaryMessageSize

      public void setWebSocketMaxBinaryMessageSize(int webSocketMaxBinaryMessageSize)
      Sets the maximum size in bytes for WebSocket binary messages. This limit applies to individual binary frames received by the WebSocket.
      Parameters:
      webSocketMaxBinaryMessageSize - the maximum size in bytes, or -1 for default

    • setFetchPolyfillEnabled

      public void setFetchPolyfillEnabled(boolean enabled)
      Sets whether or not fetch polyfill should be used.
      Parameters:
      enabled - true to enable fetch polyfill

    • isFetchPolyfillEnabled

      public boolean isFetchPolyfillEnabled()
      Returns:
      true if the fetch api polyfill is enabled

    • setGeolocationEnabled

      public void setGeolocationEnabled(boolean enabled)
      Enables/disables Geolocation support. By default, this property is disabled.
      Parameters:
      enabled - true to enable Geolocation support

    • isGeolocationEnabled

      public boolean isGeolocationEnabled()
      Returns:
      true if Geolocation is enabled

    • getGeolocation

      public WebClientOptions.Geolocation getGeolocation()
      Returns:
      the WebClientOptions.Geolocation

    • setGeolocation

      public void setGeolocation(WebClientOptions.Geolocation geolocation)
      Sets the WebClientOptions.Geolocation to be used.
      Parameters:
      geolocation - the new location or null

    • setFileProtocolForXMLHttpRequestsAllowed

      public void setFileProtocolForXMLHttpRequestsAllowed(boolean fileProtocolForXMLHttpRequestsAllowed)
      If set to true, the client will accept XMLHttpRequests to URL's using the 'file' protocol. Allowing this introduces security problems and is therefore not allowed by current browsers. But some browsers have special settings to open this door; therefore we have this option also.

      Security Warning: Enabling this feature may expose local files to web content, which can be a serious security risk.

      Parameters:
      fileProtocolForXMLHttpRequestsAllowed - whether or not allow (local) file access

    • isFileProtocolForXMLHttpRequestsAllowed

      public boolean isFileProtocolForXMLHttpRequestsAllowed()
      Indicates if the client will accept XMLHttpRequests to URL's using the 'file' protocol.
      Returns:
      true if access to local files is allowed.