Package org.gnome.soup

Class Message.Builder<B extends Message.Builder<B>>

java.lang.Object

io.github.jwharm.javagi.gobject.Builder<B>

org.gnome.gobject.GObject.Builder<B>

org.gnome.soup.Message.Builder<B>

Type Parameters:

B - the type of the Builder that is returned

All Implemented Interfaces:

BuilderInterface

Enclosing class:

Message

public static class Message.Builder<B extends Message.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
Message	build()	Finish building the Message object.
B	onAcceptCertificate(Message.AcceptCertificateCallback handler)	Emitted during the msg's connection TLS handshake after an unacceptable TLS certificate has been received.
B	onAuthenticate(Message.AuthenticateCallback handler)	Emitted when the message requires authentication.
B	onContentSniffed(Message.ContentSniffedCallback handler)	This signal is emitted after Message::got-headers.
B	onFinished(Message.FinishedCallback handler)	Emitted when all HTTP processing is finished for a message.
B	onGotBody(Message.GotBodyCallback handler)	Emitted after receiving the complete message response body.
B	onGotBodyData(Message.GotBodyDataCallback handler)	Emitted after reading a portion of the message body from the network.
B	onGotHeaders(Message.GotHeadersCallback handler)	Emitted after receiving the Status-Line and response headers.
B	onGotInformational(Message.GotInformationalCallback handler)	Emitted after receiving a 1xx (Informational) response for a (client-side) message.
B	onHstsEnforced(Message.HstsEnforcedCallback handler)	Emitted when HSTSEnforcer has upgraded the protocol for msg to HTTPS as a result of matching its domain with a HSTS policy.
B	onNetworkEvent(Message.NetworkEventCallback handler)	Emitted to indicate that some network-related event related to msg has occurred.
B	onRequestCertificate(Message.RequestCertificateCallback handler)	Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate from the client.
B	onRequestCertificatePassword(Message.RequestCertificatePasswordCallback handler)	Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate password from the client.
B	onRestarted(Message.RestartedCallback handler)	Emitted when a request that was already sent once is now being sent again.
B	onStarting(Message.StartingCallback handler)	Emitted just before a message is sent.
B	onWroteBody(Message.WroteBodyCallback handler)	Emitted immediately after writing the complete body for a message.
B	onWroteBodyData(Message.WroteBodyDataCallback handler)	Emitted immediately after writing a portion of the message body to the network.
B	onWroteHeaders(Message.WroteHeadersCallback handler)	Emitted immediately after writing the request headers for a message.
B	setFirstParty(Uri firstParty)	The GLib.Uri loaded in the application when the message was queued.
B	setFlags(Set<MessageFlags> flags)	Various message options.
B	setFlags(MessageFlags... flags)	Various message options.
B	setIsOptionsPing(boolean isOptionsPing)	Whether the message is an OPTIONS ping.
B	setIsTopLevelNavigation(boolean isTopLevelNavigation)	Set when the message is navigating between top level domains.
B	setMethod(String method)	The message's HTTP method.
B	setPriority(MessagePriority priority)	Sets the priority of the SoupMessage.
B	setSiteForCookies(Uri siteForCookies)	Site used to compare cookies against.
B	setUri(Uri uri)	The message's Request-URI.

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 Message build()
              throws UnsupportedPlatformException

Finish building the Message 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 Message.

Overrides:

build in class GObject.Builder<B extends Message.Builder<B>>

Returns:

a new instance of Message with the properties that were set in the Builder object.

Throws:

UnsupportedPlatformException - when run on an unsupported platform

setFirstParty

public B setFirstParty(Uri firstParty)

The GLib.Uri loaded in the application when the message was queued.

Parameters:

firstParty - the value for the first-party property

Returns:

the Builder instance is returned, to allow method chaining

setFlags

public B setFlags(Set<MessageFlags> flags)

Various message options.

Parameters:

flags - the value for the flags property

Returns:

the Builder instance is returned, to allow method chaining

setIsOptionsPing

public B setIsOptionsPing(boolean isOptionsPing)

Whether the message is an OPTIONS ping.

The SoupMessage is intended to be used to send OPTIONS * to a server. When set to true, the path of Message:uri will be ignored and Message:method set to SOUP_METHOD_OPTIONS.

Parameters:

isOptionsPing - the value for the is-options-ping property

Returns:

the Builder instance is returned, to allow method chaining

setIsTopLevelNavigation

public B setIsTopLevelNavigation(boolean isTopLevelNavigation)

Set when the message is navigating between top level domains.

Parameters:

isTopLevelNavigation - the value for the is-top-level-navigation property

Returns:

the Builder instance is returned, to allow method chaining

setMethod

public B setMethod(String method)

The message's HTTP method.

Parameters:

method - the value for the method property

Returns:

the Builder instance is returned, to allow method chaining

setPriority

public B setPriority(MessagePriority priority)

Sets the priority of the SoupMessage. See Message.setPriority(org.gnome.soup.MessagePriority) for further details.

Parameters:

priority - the value for the priority property

Returns:

the Builder instance is returned, to allow method chaining

setSiteForCookies

public B setSiteForCookies(Uri siteForCookies)

Site used to compare cookies against. Used for SameSite cookie support.

Parameters:

siteForCookies - the value for the site-for-cookies property

Returns:

the Builder instance is returned, to allow method chaining

setUri

public B setUri(Uri uri)

The message's Request-URI.

Parameters:

uri - the value for the uri property

Returns:

the Builder instance is returned, to allow method chaining

setFlags

public B setFlags(MessageFlags... flags)

Various message options.

Parameters:

flags - the value for the flags property

Returns:

the Builder instance is returned, to allow method chaining

onAcceptCertificate

public B onAcceptCertificate(Message.AcceptCertificateCallback handler)

Emitted during the msg's connection TLS handshake after an unacceptable TLS certificate has been received.

You can return true to accept tlsCertificate despite tlsErrors.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.AcceptCertificateCallback.run(org.gnome.gio.TlsCertificate, java.util.Set<org.gnome.gio.TlsCertificateFlags>)

onAuthenticate

public B onAuthenticate(Message.AuthenticateCallback handler)

Emitted when the message requires authentication.

If credentials are available call Auth.authenticate(java.lang.String, java.lang.String) on auth. If these credentials fail, the signal will be emitted again, with retrying set to true, which will continue until you return without calling Auth.authenticate(java.lang.String, java.lang.String) on auth.

Note that this may be emitted before msg's body has been fully read.

You can authenticate auth asynchronously by calling GObject.ref() on auth and returning true. The operation will complete once either Auth.authenticate(java.lang.String, java.lang.String) or Auth.cancel() are called.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.AuthenticateCallback.run(org.gnome.soup.Auth, boolean)

onContentSniffed

public B onContentSniffed(Message.ContentSniffedCallback handler)

This signal is emitted after Message::got-headers.

If content sniffing is disabled, or no content sniffing will be performed, due to the sniffer deciding to trust the Content-Type sent by the server, this signal is emitted immediately after Message::got-headers, and type is null.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.ContentSniffedCallback.run(java.lang.String, org.gnome.glib.HashTable<java.lang.String, java.lang.String>)

onFinished

public B onFinished(Message.FinishedCallback handler)

Emitted when all HTTP processing is finished for a message.

(After Message::got_body).

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.FinishedCallback.run()

onGotBody

public B onGotBody(Message.GotBodyCallback handler)

Emitted after receiving the complete message response body.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.GotBodyCallback.run()

onGotBodyData

public B onGotBodyData(Message.GotBodyDataCallback handler)

Emitted after reading a portion of the message body from the network.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.GotBodyDataCallback.run(int)

onGotHeaders

public B onGotHeaders(Message.GotHeadersCallback handler)

Emitted after receiving the Status-Line and response headers.

See also Message.addHeaderHandler(java.lang.String, java.lang.String, org.gnome.gobject.Callback) and Message.addStatusCodeHandler(java.lang.String, int, org.gnome.gobject.Callback), which can be used to connect to a subset of emissions of this signal.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg's connection will be closed. (If you need to requeue a message--eg, after handling authentication or redirection--it is usually better to requeue it from a Message::got-body handler rather than a Message::got_headers handler, so that the existing HTTP connection can be reused.)

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.GotHeadersCallback.run()

onGotInformational

public B onGotInformational(Message.GotInformationalCallback handler)

Emitted after receiving a 1xx (Informational) response for a (client-side) message.

The response_headers will be filled in with the headers associated with the informational response; however, those header values will be erased after this signal is done.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg's connection will be closed.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.GotInformationalCallback.run()

onHstsEnforced

public B onHstsEnforced(Message.HstsEnforcedCallback handler)

Emitted when HSTSEnforcer has upgraded the protocol for msg to HTTPS as a result of matching its domain with a HSTS policy.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.HstsEnforcedCallback.run()

onNetworkEvent

public B onNetworkEvent(Message.NetworkEventCallback handler)

Emitted to indicate that some network-related event related to msg has occurred.

This essentially proxies the Gio.SocketClient::event signal, but only for events that occur while msg "owns" the connection; if msg is sent on an existing persistent connection, then this signal will not be emitted. (If you want to force the message to be sent on a new connection, set the MessageFlags.NEW_CONNECTION flag on it.)

See Gio.SocketClient::event for more information on what the different values of event correspond to, and what connection will be in each case.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.NetworkEventCallback.run(org.gnome.gio.SocketClientEvent, org.gnome.gio.IOStream)

onRequestCertificate

public B onRequestCertificate(Message.RequestCertificateCallback handler)

Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate from the client.

You can set the client certificate by calling Message.setTlsClientCertificate(org.gnome.gio.TlsCertificate) and returning true. It's possible to handle the request asynchornously by returning true and call Message.setTlsClientCertificate(org.gnome.gio.TlsCertificate) later once the certificate is available. Note that this signal is not emitted if Session:tls-interaction was set, or if Message.setTlsClientCertificate(org.gnome.gio.TlsCertificate) was called before the connection TLS handshake started.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.RequestCertificateCallback.run(org.gnome.gio.TlsClientConnection)

onRequestCertificatePassword

public B onRequestCertificatePassword(Message.RequestCertificatePasswordCallback handler)

Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate password from the client.

You can set the certificate password on password, then call Message.tlsClientCertificatePasswordRequestComplete() and return true to handle the signal synchronously. It's possible to handle the request asynchornously by calling GObject.ref() on password, then returning true and call Message.tlsClientCertificatePasswordRequestComplete() later after setting the password on password. Note that this signal is not emitted if Session:tls-interaction was set.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.RequestCertificatePasswordCallback.run(org.gnome.gio.TlsPassword)

onRestarted

public B onRestarted(Message.RestartedCallback handler)

Emitted when a request that was already sent once is now being sent again.

e.g. because the first attempt received a redirection response, or because we needed to use authentication.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.RestartedCallback.run()

onStarting

public B onStarting(Message.StartingCallback handler)

Emitted just before a message is sent.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.StartingCallback.run()

onWroteBody

public B onWroteBody(Message.WroteBodyCallback handler)

Emitted immediately after writing the complete body for a message.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.WroteBodyCallback.run()

onWroteBodyData

public B onWroteBodyData(Message.WroteBodyDataCallback handler)

Emitted immediately after writing a portion of the message body to the network.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.WroteBodyDataCallback.run(int)

onWroteHeaders

public B onWroteHeaders(Message.WroteHeadersCallback handler)

Emitted immediately after writing the request headers for a message.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• Message.WroteHeadersCallback.run()