Package org.gnome.soup

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

java.lang.Object

io.github.jwharm.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 Summary

Constructors

Modifier	Constructor	Description
protected	Builder()	Default constructor for a Builder object.

Method Summary

Modifier and Type	Method	Description
Session	build()	Finish building the Session object.
B	onRequestQueued(Session.RequestQueuedCallback handler)	Emitted when a request is queued on session.
B	onRequestUnqueued(Session.RequestUnqueuedCallback handler)	Emitted when a request is removed from session's queue, indicating that session is done with it.
B	setAcceptLanguage(String acceptLanguage)	If non-null, the value to use for the "Accept-Language" header on Messages sent from this session.
B	setAcceptLanguageAuto(boolean acceptLanguageAuto)	If true, SoupSession will automatically set the string for the "Accept-Language" header on every Message sent, based on the return value of GLib.getLanguageNames().
B	setIdleTimeout(int idleTimeout)	Connection lifetime (in seconds) when idle.
B	setLocalAddress(InetSocketAddress localAddress)	Sets the InetSocketAddress to use for the client side of the connection.
B	setMaxConns(int maxConns)	The maximum number of connections that the session can open at once.
B	setMaxConnsPerHost(int maxConnsPerHost)	The maximum number of connections that the session can open at once to a given host.
B	setProxyResolver(ProxyResolver proxyResolver)	A ProxyResolver to use with this session.
B	setRemoteConnectable(SocketConnectable remoteConnectable)	Sets a socket to make outgoing connections on.
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).
B	setTlsDatabase(TlsDatabase tlsDatabase)	Sets the TlsDatabase to use for validating SSL/TLS certificates.
B	setTlsInteraction(TlsInteraction tlsInteraction)	A TlsInteraction object that will be passed on to any TlsConnections created by the session.
B	setUserAgent(String userAgent)	User-Agent string.

Methods inherited from class org.gnome.gobject.GObject.Builder

onNotify

Methods inherited from class io.github.jwharm.javagi.gobject.Builder

addBuilderProperty, connect, connect, connectSignals, getArena, getNames, getValues

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Builder

protected Builder()

Default constructor for a Builder object.

Method Details

build

public Session build()
              throws UnsupportedPlatformException

Finish building the Session object. This will call GObject.withProperties(org.gnome.glib.Type, java.lang.String[], org.gnome.gobject.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.

Throws:

UnsupportedPlatformException - when run on an unsupported platform

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, SoupSession 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, SoupSession 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:

• Session.RequestQueuedCallback.run(org.gnome.soup.Message)

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:

• Session.RequestUnqueuedCallback.run(org.gnome.soup.Message)