Class Session.Builder<B extends Session.Builder<B>>

java.lang.Object
org.javagi.gobject.Builder<B>
org.gnome.gobject.GObject.Builder<B>
org.gnome.soup.Session.Builder<B>
Type Parameters:
B - the type of the Builder that is returned
All Implemented Interfaces:
BuilderInterface
Enclosing class:
Session
public static class Session.Builder<B extends Session.Builder<B>> extends GObject.Builder<B>
Inner class implementing a builder pattern to construct a GObject with properties.

  • Constructor Details

    • Builder

      protected Builder()
      Default constructor for a Builder object.

  • Method Details

    • build

      public Session build()
      Finish building the Session object. This will call GObject.withProperties(Type, String[], Value[]) to create a new GObject instance, which is then cast to Session.
      Overrides:
      build in class GObject.Builder<B extends Session.Builder<B>>
      Returns:
      a new instance of Session with the properties that were set in the Builder object.

    • setAcceptLanguage

      public B setAcceptLanguage(String acceptLanguage)

      If non-null, the value to use for the "Accept-Language" header on Messages sent from this session.

      Setting this will disable Session:accept-language-auto.

      Parameters:
      acceptLanguage - the value for the accept-language property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setAcceptLanguageAuto

      public B setAcceptLanguageAuto(boolean acceptLanguageAuto)

      If true, Session will automatically set the string for the "Accept-Language" header on every Message sent, based on the return value of GLib#getLanguageNames.

      Setting this will override any previous value of Session:accept-language.

      Parameters:
      acceptLanguageAuto - the value for the accept-language-auto property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setIdleTimeout

      public B setIdleTimeout(int idleTimeout)

      Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed.

      Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call Session.abort() after setting this if you want to ensure that all future connections will have this timeout value.

      Parameters:
      idleTimeout - the value for the idle-timeout property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setLocalAddress

      public B setLocalAddress(InetSocketAddress localAddress)

      Sets the InetSocketAddress to use for the client side of the connection.

      Use this property if you want for instance to bind the local socket to a specific IP address.

      Parameters:
      localAddress - the value for the local-address property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setMaxConns

      public B setMaxConns(int maxConns)
      The maximum number of connections that the session can open at once.
      Parameters:
      maxConns - the value for the max-conns property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setMaxConnsPerHost

      public B setMaxConnsPerHost(int maxConnsPerHost)
      The maximum number of connections that the session can open at once to a given host.
      Parameters:
      maxConnsPerHost - the value for the max-conns-per-host property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setProxyResolver

      public B setProxyResolver(ProxyResolver proxyResolver)

      A ProxyResolver to use with this session.

      If no proxy resolver is set, then the default proxy resolver will be used. See ProxyResolver#getDefault. You can set it to null if you don't want to use proxies, or set it to your own ProxyResolver if you want to control what proxies get used.

      Parameters:
      proxyResolver - the value for the proxy-resolver property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setRemoteConnectable

      public B setRemoteConnectable(SocketConnectable remoteConnectable)

      Sets a socket to make outgoing connections on. This will override the default behaviour of opening TCP/IP sockets to the hosts specified in the URIs.

      This function is not required for common HTTP usage, but only when connecting to a HTTP service that is not using standard TCP/IP sockets. An example of this is a local service that uses HTTP over UNIX-domain sockets, in that case a UnixSocketAddress can be passed to this function.

      Parameters:
      remoteConnectable - the value for the remote-connectable property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setTimeout

      public B setTimeout(int timeout)

      The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request).

      Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call Session.abort() after setting this if you want to ensure that all future connections will have this timeout value.

      Not to be confused with Session:idle-timeout (which is the length of time that idle persistent connections will be kept open).

      Parameters:
      timeout - the value for the timeout property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setTlsDatabase

      public B setTlsDatabase(TlsDatabase tlsDatabase)

      Sets the TlsDatabase to use for validating SSL/TLS certificates.

      If no certificate database is set, then the default database will be used. See TlsBackend#getDefaultDatabase.

      Parameters:
      tlsDatabase - the value for the tls-database property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setTlsInteraction

      public B setTlsInteraction(TlsInteraction tlsInteraction)

      A TlsInteraction object that will be passed on to any TlsConnections created by the session.

      This can be used to provide client-side certificates, for example.

      Parameters:
      tlsInteraction - the value for the tls-interaction property
      Returns:
      the Builder instance is returned, to allow method chaining

    • setUserAgent

      public B setUserAgent(String userAgent)

      User-Agent string.

      If non-null, the value to use for the "User-Agent" header on Messages sent from this session.

      RFC 2616 says: "The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests."

      The User-Agent header contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although "-", "_", and "." are also allowed), and may optionally include a "/" followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens.

      If you set a Session:user-agent property that has trailing whitespace, Session will append its own product token (eg, libsoup/2.3.2) to the end of the header for you.

      Parameters:
      userAgent - the value for the user-agent property
      Returns:
      the Builder instance is returned, to allow method chaining

    • onRequestQueued

      public B onRequestQueued(Session.RequestQueuedCallback handler)

      Emitted when a request is queued on session.

      When sending a request, first Session::request-queued is emitted, indicating that the session has become aware of the request.

      After a connection is available to send the request various Message signals are emitted as the message is processed. If the message is requeued, it will emit Message::restarted, which will then be followed by other Message signals when the message is re-sent.

      Eventually, the message will emit Message::finished. Normally, this signals the completion of message processing. However, it is possible that the application will requeue the message from the "finished" handler. In that case the process will loop back.

      Eventually, a message will reach "finished" and not be requeued. At that point, the session will emit Session::request-unqueued to indicate that it is done with the message.

      To sum up: Session::request-queued and Session::request-unqueued are guaranteed to be emitted exactly once, but Message::finished (and all of the other Message signals) may be invoked multiple times for a given message.

      Parameters:
      handler - the signal handler
      Returns:
      the Builder instance is returned, to allow method chaining
      See Also:

    • onRequestUnqueued

      public B onRequestUnqueued(Session.RequestUnqueuedCallback handler)

      Emitted when a request is removed from session's queue, indicating that session is done with it.

      See Session::request-queued for a detailed description of the message lifecycle within a session.

      Parameters:
      handler - the signal handler
      Returns:
      the Builder instance is returned, to allow method chaining
      See Also: