Package org.gnome.soup

Class Cookie

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.soup.Cookie

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Cookie
extends ProxyInstance

Implements HTTP cookies, as described by RFC 6265.

To have a Session handle cookies for your appliction automatically, use a CookieJar.

name and value will be set for all cookies. If the cookie is generated from a string that appears to have no name, then name will be the empty string.

domain and path give the host or domain, and path within that host/domain, to restrict this cookie to. If domain starts with ".", that indicates a domain (which matches the string after the ".", or any hostname that has domain as a suffix). Otherwise, it is a hostname and must match exactly.

expires will be non-null if the cookie uses either the original "expires" attribute, or the newer "max-age" attribute. If expires is null, it indicates that neither "expires" nor "max-age" was specified, and the cookie expires at the end of the session.

If httpOnly is set, the cookie should not be exposed to untrusted code (eg, javascript), so as to minimize the danger posed by cross-site scripting attacks.

Constructor Summary

Constructors

Constructor	Description
Cookie(MemorySegment address)	Create a Cookie proxy instance for the provided memory address.
Cookie(String name, String value, String domain, String path, int maxAge)	Creates a new SoupCookie with the given attributes.

Method Summary

Modifier and Type	Method	Description
boolean	appliesToUri(Uri uri)	Tests if this Cookie should be sent to uri.
Cookie	copy()	Copies this Cookie.
boolean	domainMatches(String host)	Checks if the this Cookie's domain and host match.
boolean	equal(Cookie cookie2)	Tests if this Cookie and cookie2 are equal.
void	free()	Frees this Cookie.
String	getDomain()	Gets this Cookie's domain.
DateTime	getExpires()	Gets this Cookie's expiration time.
boolean	getHttpOnly()	Gets this Cookie's HttpOnly attribute.
String	getName()	Gets this Cookie's name.
String	getPath()	Gets this Cookie's path.
SameSitePolicy	getSameSitePolicy()	Returns the same-site policy for this cookie.
boolean	getSecure()	Gets this Cookie's secure attribute.
static Type	getType()	Get the GType of the Cookie class
String	getValue()	Gets this Cookie's value.
static Cookie	parse(String header, @Nullable Uri origin)	Parses header and returns a SoupCookie.
void	setDomain(String domain)	Sets this Cookie's domain to domain.
void	setExpires(DateTime expires)	Sets this Cookie's expiration time to expires.
void	setHttpOnly(boolean httpOnly)	Sets this Cookie's HttpOnly attribute to httpOnly.
void	setMaxAge(int maxAge)	Sets this Cookie's max age to maxAge.
void	setName(String name)	Sets this Cookie's name to name.
void	setPath(String path)	Sets this Cookie's path to path.
void	setSameSitePolicy(SameSitePolicy policy)	When used in conjunction with CookieJar.getCookieListWithSameSiteInfo(org.gnome.glib.Uri, org.gnome.glib.Uri, org.gnome.glib.Uri, boolean, boolean, boolean) this sets the policy of when this cookie should be exposed.
void	setSecure(boolean secure)	Sets this Cookie's secure attribute to secure.
void	setValue(String value)	Sets this Cookie's value to value.
String	toCookieHeader()	Serializes this Cookie in the format used by the Cookie header (ie, for returning a cookie from a Session to a server).
String	toSetCookieHeader()	Serializes this Cookie in the format used by the Set-Cookie header.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

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

Constructor Details

Cookie

public Cookie(MemorySegment address)

Create a Cookie proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Cookie

public Cookie(String name,
 String value,
 String domain,
 String path,
 int maxAge)
       throws UnsupportedPlatformException

Creates a new SoupCookie with the given attributes.

Use setSecure(boolean) and setHttpOnly(boolean) if you need to set those attributes on the returned cookie.

If domain starts with ".", that indicates a domain (which matches the string after the ".", or any hostname that has domain as a suffix). Otherwise, it is a hostname and must match exactly.

maxAge is used to set the "expires" attribute on the cookie; pass -1 to not include the attribute (indicating that the cookie expires with the current session), 0 for an already-expired cookie, or a lifetime in seconds. You can use the constants SOUP_COOKIE_MAX_AGE_ONE_HOUR, SOUP_COOKIE_MAX_AGE_ONE_DAY, SOUP_COOKIE_MAX_AGE_ONE_WEEK and SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (If you really care about setting the exact time that the cookie will expire, use setExpires(org.gnome.glib.DateTime).)

As of version 3.4.0 the default value of a cookie's same-site-policy is SameSitePolicy.LAX.

Parameters:

name - cookie name

value - cookie value

domain - cookie domain or hostname

path - cookie path, or null

maxAge - max age of the cookie, or -1 for a session cookie

Throws:

UnsupportedPlatformException - when run on a platform other than linux

Method Details

getType

public static Type getType()

Get the GType of the Cookie class

Returns:

the GType

parse

public static Cookie parse(String header,
 @Nullable
 @Nullable Uri origin)
                    throws UnsupportedPlatformException

Parses header and returns a SoupCookie.

If header contains multiple cookies, only the first one will be parsed.

If header does not have "path" or "domain" attributes, they will be defaulted from origin. If origin is null, path will default to "/", but domain will be left as null. Note that this is not a valid state for a SoupCookie, and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie.

As of version 3.4.0 the default value of a cookie's same-site-policy is SameSitePolicy.LAX.

Parameters:

header - a cookie string (eg, the value of a Set-Cookie header)

origin - origin of the cookie

Returns:

a new SoupCookie, or null if it could not be parsed, or contained an illegal "domain" attribute for a cookie originating from origin.

Throws:

UnsupportedPlatformException - when run on a platform other than linux

appliesToUri

public boolean appliesToUri(Uri uri)

Tests if this Cookie should be sent to uri.

(At the moment, this does not check that this Cookie's domain matches uri, because it assumes that the caller has already done that. But don't rely on that; it may change in the future.)

Parameters:

uri - a GUri

Returns:

true if this Cookie should be sent to uri, false if not

copy

public Cookie copy()

Copies this Cookie.

Returns:

a copy of this Cookie

domainMatches

public boolean domainMatches(String host)

Checks if the this Cookie's domain and host match.

The domains match if this Cookie should be sent when making a request to host, or that this Cookie should be accepted when receiving a response from host.

Parameters:

host - a URI

Returns:

true if the domains match, false otherwise

equal

public boolean equal(Cookie cookie2)

Tests if this Cookie and cookie2 are equal.

Note that currently, this does not check that the cookie domains match. This may change in the future.

Parameters:

cookie2 - a SoupCookie

Returns:

whether the cookies are equal.

free

public void free()

Frees this Cookie.

getDomain

public String getDomain()

Gets this Cookie's domain.

Returns:

this Cookie's domain

getExpires

public DateTime getExpires()

Gets this Cookie's expiration time.

Returns:

this Cookie's expiration time, which is owned by this Cookie and should not be modified or freed.

getHttpOnly

public boolean getHttpOnly()

Gets this Cookie's HttpOnly attribute.

Returns:

this Cookie's HttpOnly attribute

getName

public String getName()

Gets this Cookie's name.

Returns:

this Cookie's name

getPath

public String getPath()

Gets this Cookie's path.

Returns:

this Cookie's path

getSameSitePolicy

public SameSitePolicy getSameSitePolicy()

Returns the same-site policy for this cookie.

Returns:

a SoupSameSitePolicy

getSecure

public boolean getSecure()

Gets this Cookie's secure attribute.

Returns:

this Cookie's secure attribute

getValue

public String getValue()

Gets this Cookie's value.

Returns:

this Cookie's value

setDomain

public void setDomain(String domain)

Sets this Cookie's domain to domain.

Parameters:

domain - the new domain

setExpires

public void setExpires(DateTime expires)

Sets this Cookie's expiration time to expires.

If expires is null, this Cookie will be a session cookie and will expire at the end of the client's session.

(This sets the same property as setMaxAge(int).)

Parameters:

expires - the new expiration time, or null

setHttpOnly

public void setHttpOnly(boolean httpOnly)

Sets this Cookie's HttpOnly attribute to httpOnly.

If true, this Cookie will be marked as "http only", meaning it should not be exposed to web page scripts or other untrusted code.

Parameters:

httpOnly - the new value for the HttpOnly attribute

setMaxAge

public void setMaxAge(int maxAge)

Sets this Cookie's max age to maxAge.

If maxAge is -1, the cookie is a session cookie, and will expire at the end of the client's session. Otherwise, it is the number of seconds until the cookie expires. You can use the constants SOUP_COOKIE_MAX_AGE_ONE_HOUR, SOUP_COOKIE_MAX_AGE_ONE_DAY, SOUP_COOKIE_MAX_AGE_ONE_WEEK and SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (A value of 0 indicates that the cookie should be considered already-expired.)

This sets the same property as setExpires(org.gnome.glib.DateTime).

Parameters:

maxAge - the new max age

setName

public void setName(String name)

Sets this Cookie's name to name.

Parameters:

name - the new name

setPath

public void setPath(String path)

Sets this Cookie's path to path.

Parameters:

path - the new path

setSameSitePolicy

public void setSameSitePolicy(SameSitePolicy policy)

When used in conjunction with CookieJar.getCookieListWithSameSiteInfo(org.gnome.glib.Uri, org.gnome.glib.Uri, org.gnome.glib.Uri, boolean, boolean, boolean) this sets the policy of when this cookie should be exposed.

Parameters:

policy - a SoupSameSitePolicy

setSecure

public void setSecure(boolean secure)

Sets this Cookie's secure attribute to secure.

If true, this Cookie will only be transmitted from the client to the server over secure (https) connections.

Parameters:

secure - the new value for the secure attribute

setValue

public void setValue(String value)

Sets this Cookie's value to value.

Parameters:

value - the new value

toCookieHeader

public String toCookieHeader()

Serializes this Cookie in the format used by the Cookie header (ie, for returning a cookie from a Session to a server).

Returns:

the header

toSetCookieHeader

public String toSetCookieHeader()

Serializes this Cookie in the format used by the Set-Cookie header.

i.e. for sending a cookie from a Server to a client.

Returns:

the header