Class Cookie

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.soup.Cookie
All Implemented Interfaces:
Proxy
@Generated("org.javagi.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 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)

      Creates a new Cookie 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(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

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Cookie class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • parse

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

      Parses header and returns a Cookie.

      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 Cookie, 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.

    • appliesToUri

      public boolean appliesToUri(Uri uri)

      Tests if this Cookie should be sent to uri.

      (At the moment, this does not check that 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 cookie.
      Returns:
      a copy of this Cookie

    • domainMatches

      public boolean domainMatches(String host)

      Checks if the 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 cookie.

    • getDomain

      public String getDomain()
      Gets cookie's domain.
      Returns:
      cookie's domain

    • getExpires

      public @Nullable DateTime getExpires()
      Gets cookie's expiration time.
      Returns:
      cookie's expiration time, which is owned by this Cookie and should not be modified or freed.

    • getHttpOnly

      public boolean getHttpOnly()
      Gets cookie's HttpOnly attribute.
      Returns:
      cookie's HttpOnly attribute

    • getName

      public String getName()
      Gets cookie's name.
      Returns:
      cookie's name

    • getPath

      public String getPath()
      Gets cookie's path.
      Returns:
      cookie's path

    • getSameSitePolicy

      public SameSitePolicy getSameSitePolicy()
      Returns the same-site policy for this cookie.
      Returns:
      a SoupSameSitePolicy

    • getSecure

      public boolean getSecure()
      Gets cookie's secure attribute.
      Returns:
      cookie's secure attribute

    • getValue

      public String getValue()
      Gets cookie's value.
      Returns:
      cookie's value

    • setDomain

      public void setDomain(String domain)
      Sets cookie's domain to domain.
      Parameters:
      domain - the new domain

    • setExpires

      public void setExpires(DateTime expires)

      Sets 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 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 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(DateTime).

      Parameters:
      maxAge - the new max age

    • setName

      public void setName(String name)
      Sets cookie's name to name.
      Parameters:
      name - the new name

    • setPath

      public void setPath(String path)
      Sets cookie's path to path.
      Parameters:
      path - the new path

    • setSameSitePolicy

      public void setSameSitePolicy(SameSitePolicy policy)
      When used in conjunction with CookieJar.getCookieListWithSameSiteInfo(Uri, Uri, 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 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 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