Package rife.engine

Class Context

java.lang.Object

rife.engine.Context

public class Context
extends Object

This class provides the context for the current HTTP request.

Since:

1.0

Field Summary

Fields

Modifier and Type	Field	Description
static final boolean	DEFAULT_BOOLEAN
static final double	DEFAULT_DOUBLE
static final float	DEFAULT_FLOAT
static final int	DEFAULT_INTEGER
static final long	DEFAULT_LONG
static final int	SC_FORBIDDEN	Status code (403) indicating the server understood the request but refused to fulfill it.
static final int	SC_INTERNAL_SERVER_ERROR	Status code (500) indicating an error inside the HTTP server which prevented it from fulfilling the request.
static final int	SC_NOT_MODIFIED	Status code (304) indicating that a conditional GET operation found that the resource was available and not modified.

Method Summary

Modifier and Type	Method	Description
void	addCookie(CookieBuilder builder)	Adds the Cookie created by a CookieBuilder to the response.
void	addDateHeader(String name, long date)	Adds a response header with the given name and date-value.
void	addHeader(String name, int value)	Adds a response header with the given name and integer value.
void	addHeader(String name, String value)	Adds a response header with the given name and value.
Object	attribute(String name)	Returns the value of the named attribute.
List<String>	attributeNames()	Returns a list of attribute names available to this request.
String	body()	Retrieves the body of this context's request as a string.
byte[]	bodyAsBytes()	Retrieves the body of this context's request as a byte array.
String	characterEncoding()	Returns the name of the character encoding used in the body of this request.
void	clearBuffer()	Clears the text buffer is it's enabled.
String	contentType()	Returns the MIME type of the body of the request, or null if the type is not known.
String	contextPath()	Returns the portion of the request URI that indicates the context of the request.
String	continuationId()	Returns the unique identifier of the current continuation.
boolean	cookieBoolean(String name)	Retrieves the value of a named cookie and converts it to a boolean.
boolean	cookieBoolean(String name, boolean defaultValue)	Retrieves the value of a named cookie and converts it to a boolean, using a default value if no input value is present.
double	cookieDouble(String name)	Retrieves the value of a named cookie and converts it to a double.
double	cookieDouble(String name, double defaultValue)	Retrieves the value of a named cookie and converts it to a double, using a default value if no input value is present.
float	cookieFloat(String name)	Retrieves the value of a named cookie and converts it to a float.
float	cookieFloat(String name, float defaultValue)	Retrieves the value of a named cookie and converts it to a float, using a default value if no input value is present.
int	cookieInt(String name)	Retrieves the value of a named cookie and converts it to an integer.
int	cookieInt(String name, int defaultValue)	Retrieves the value of a named cookie and converts it to an integer, using a default value if no input value is present.
long	cookieLong(String name)	Retrieves the value of a named cookie and converts it to a long.
long	cookieLong(String name, long defaultValue)	Retrieves the value of a named cookie and converts it to a long, using a default value if no input value is present.
List<String>	cookieNames()	Retrieves the names of the cookies.
String	cookieValue(String name)	Retrieves the value of a cookie.
String	cookieValue(String name, String defaultValue)	Retrieves the value of a named cookie, using a default value as fallback.
Map<String,String>	cookieValues()	Retrieves all current cookies names with their values.
String	csrfToken()	Retrieves the CSRF token of the browser that performs this request, establishing one with ensureCsrfToken() when the browser doesn't have one yet.
void	defer()	Interrupts the execution in RIFE2 completely and defers it to the servlet container.
void	enableTextBuffer(boolean enabled)	Enables or disables the response text buffer.
Throwable	engineException()	Retrieves the exception that was triggered during the RIFE2 web engine execution.
void	ensureCsrfToken()	Ensures that a CSRF token is established for this request, generating a new one and setting its cookie when the browser doesn't have one yet.
UploadedFile	file(String name)	Retrieves an uploaded file.
Set<String>	fileNames()	Retrieves the list of uploaded file names.
Map<String,UploadedFile[]>	files()	Retrieves the files that were uploaded in this context.
UploadedFile[]	files(String name)	Retrieves all files that have been uploaded for a particular name.
void	flush()	Forces all the streamed content to be output to the client.
static Context	fromTemplate(Template template)	Retrieves the context that was stored in a template attribute.
String	gateUrl()	Retrieves the URL portion that corresponds to the entrance gate of the RIFE2 web engine, this is usually equivalent with the HTTP request context path.
void	generateEmptyForm(Template template, Class beanClass)	Generates a form that corresponds to an empty instance of a bean class.
void	generateEmptyForm(Template template, Class beanClass, String prefix)	Generates a form that corresponds to an empty instance of a bean class.
void	generateForm(Template template, Object beanInstance)	Generates a form that corresponds to a bean instance.
void	generateForm(Template template, Object beanInstance, String prefix)	Generates a form that corresponds to a bean instance.
boolean	hasAttribute(String name)	Checks if a request attribute exists.
boolean	hasContinuationId()	Indicates whether a continuation identifier is available
boolean	hasCookie(String name)	Checks whether a cookie is present.
boolean	hasCsrfToken()	Indicates whether a CSRF token is available for this request, either because one was already established while processing it, or because the browser sent its token cookie.
boolean	hasFile(String name)	Checks if a particular file has been uploaded in this context.
boolean	hasParameterValue(String name)	Checks whether a value has been provided to a parameter.
boolean	hasProperty(String name)	Checks for the existence of a property in this context's HierarchicalProperties.
String	header(String name)	Returns the value of the specified request header as a String.
long	headerDate(String name)	Returns the value of the specified request header as a long value that represents a date.
int	headerInt(String name)	Returns the value of the specified request header as an int.
List<String>	headerNames()	Returns a list of all the header names in the request.
List<String>	headers(String name)	Returns all the values of the specified request header as a list of String objects.
String	hxCurrentUrl()	Returns the browser's current URL at the time of the htmx request, from the HX-Current-URL request header.
void	hxLocation(String url)	Tells htmx to do a client-side redirect to a new location without a full page reload, by setting the HX-Location response header.
void	hxLocation(HxLocation location)	Tells htmx to do a client-side redirect with navigation context, by setting the HX-Location response header to its JSON form.
void	hxLocation(Route route)	Tells htmx to do a client-side redirect to a route without a full page reload, by setting the HX-Location response header.
void	hxNoPushUrl()	Tells htmx not to push a URL into the browser history for this response, by setting the HX-Push-Url response header to false.
void	hxNoReplaceUrl()	Tells htmx not to replace the current URL in the browser history for this response, by setting the HX-Replace-Url response header to false.
String	hxPrompt()	Returns the user's response to an hx-prompt, from the HX-Prompt request header.
void	hxPushUrl(String url)	Tells htmx to push a new URL into the browser history, by setting the HX-Push-Url response header.
void	hxPushUrl(Route route)	Tells htmx to push a route's URL into the browser history by setting the HX-Push-Url response header.
void	hxRedirect(String url)	Tells htmx to do a full-page redirect, by setting the HX-Redirect response header.
void	hxRedirect(Route route)	Tells htmx to do a full-page redirect to a route, by setting the HX-Redirect response header.
void	hxRefresh()	Tells htmx to refresh the whole page, by setting the HX-Refresh response header.
void	hxReplaceUrl(String url)	Tells htmx to replace the current URL in the browser history, by setting the HX-Replace-Url response header.
void	hxReplaceUrl(Route route)	Tells htmx to replace the current URL in the browser history with a route's URL, by setting the HX-Replace-Url response header.
void	hxReselect(String cssSelector)	Tells htmx to select only part of the response for swapping, by setting the HX-Reselect response header to a CSS selector.
void	hxReswap(String swapStyle)	Tells htmx to change how the response is swapped in, by setting the HX-Reswap response header to an hx-swap value such as outerHTML or beforeend.
void	hxRetarget(String cssSelector)	Tells htmx to swap the response into a different target than the triggering element's, by setting the HX-Retarget response header to a CSS selector.
String	hxTarget()	Returns the id of the target element of an htmx request, from the HX-Target request header.
void	hxTrigger(String event)	Triggers a client-side event as soon as the response is received, by adding it to the HX-Trigger response header.
void	hxTrigger(String event, Object data)	Triggers a client-side event with a data payload as soon as the response is received, by adding it to the HX-Trigger response header.
void	hxTriggerAfterSettle(String event)	Triggers a client-side event after the settle step, by adding it to the HX-Trigger-After-Settle response header.
void	hxTriggerAfterSettle(String event, Object data)	Triggers a client-side event with a data payload after the settle step, by adding it to the HX-Trigger-After-Settle response header.
void	hxTriggerAfterSwap(String event)	Triggers a client-side event after the swap step, by adding it to the HX-Trigger-After-Swap response header.
void	hxTriggerAfterSwap(String event, Object data)	Triggers a client-side event with a data payload after the swap step, by adding it to the HX-Trigger-After-Swap response header.
String	hxTriggerId()	Returns the id of the element that triggered an htmx request, from the HX-Trigger request header.
String	hxTriggerName()	Returns the name of the element that triggered an htmx request, from the HX-Trigger-Name request header.
boolean	isFileEmpty(String name)	Checks if an uploaded file wasn't sent or if it is empty.
boolean	isHxBoosted()	Indicates whether the current request was made by an htmx-boosted link or form, reading the HX-Boosted header.
boolean	isHxHistoryRestoreRequest()	Indicates whether the current request is htmx restoring a page from its history after a cache miss, reading the HX-History-Restore-Request header.
boolean	isHxRequest()	Indicates whether the current request was issued by htmx.
boolean	isParameterEmpty(String name)	Checks whether a parameter is empty.
Locale	locale()	Returns the preferred Locale that the client will accept content in, based on the Accept-Language header.
List<Locale>	locales()	Returns a list of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language} header.
RequestMethod	method()	Returns the HTTP RequestMethod with which this context's request was made.
void	next()	Interrupts the execution in this element, moving processing on to the next element in the before/route/after chain
OutputStream	outputStream()	Returns an output stream suitable for writing binary data in the response.
String	parameter(String name)	Retrieves the value of a parameter.
String	parameter(String name, String defaultValue)	Retrieves the value of a parameter and returns a default value if no parameter value is present
boolean	parameterBoolean(String name)	Retrieves the value of a parameter and converts it to a boolean.
boolean	parameterBoolean(String name, boolean defaultValue)	Retrieves the value of a parameter and converts it to a boolean, using a default value if no parameter value is present.
double	parameterDouble(String name)	Retrieves the value of a parameter and converts it to a double.
double	parameterDouble(String name, double defaultValue)	Retrieves the value of a parameter and converts it to a double, using a default value if no parameter value is present.
double[]	parameterDoubles(String name)	Retrieves the values of a parameter as an array of doubles.
float	parameterFloat(String name)	Retrieves the value of a parameter and converts it to a float.
float	parameterFloat(String name, float defaultValue)	Retrieves the value of a parameter and converts it to a float, using a default value if no parameter value is present.
float[]	parameterFloats(String name)	Retrieves the values of a parameter as an array of floats.
int	parameterInt(String name)	Retrieves the value of a parameter and converts it to an integer.
int	parameterInt(String name, int defaultValue)	Retrieves the value of a parameter and converts it to an integer, using a default value if no parameter value is present.
int[]	parameterInts(String name)	Retrieves the values of a parameter as an array of integers.
long	parameterLong(String name)	Retrieves the value of a parameter and converts it to a long.
long	parameterLong(String name, long defaultValue)	Retrieves the value of a parameter and converts it to a long, using a default value if no parameter value is present.
long[]	parameterLongs(String name)	Retrieves the values of a parameter as an array of longs.
Set<String>	parameterNames()	Retrieves the names of all the parameters that are present.
Map<String,String[]>	parameters()	Retrieves the parameters that were sent to this context.
<BeanType> BeanType	parametersBean(Class<BeanType> beanClass)	Creates an instance of a bean and populates the properties with the parameter values.
<BeanType> BeanType	parametersBean(Class<BeanType> beanClass, String prefix)	Creates an instance of a bean and populates the properties with the parameter values, taking the provided prefix into account.
<BeanType> BeanType	parametersBean(Class<BeanType> beanClass, String prefix, String group)	Creates an instance of a bean and populates the properties of one of its validation groups with the parameter values that were sent.
void	parametersBean(Object bean)	Fills the properties of an existing bean with the parameter values.
void	parametersBean(Object bean, String prefix)	Fills the properties of an existing bean with the parameter values that were sent, taking the provided prefix into account.
void	parametersBean(Object bean, String prefix, String group)	Fills the properties of a validation group of an existing bean with the parameter values that were sent.
String[]	parameterValues(String name)	Retrieves the values of a parameter.
String	pathInfo()	The pathinfo that was captured or matched.
final void	pause()	Pauses the execution of the element and creates a new continuation.
void	preventCaching()	Sets up the current response to prevent all caching of the response by the client.
void	print(Object object)	Prints the string representation of an object to the request text output.
void	print(Template template)	Prints a template to the response.
void	printBlock(Template template, String blockId)	Prints a single named block of a template to the response.
void	printHtmxFragment(Template template, String blockId)	Prints a template as a full page or as one of its blocks, depending on whether the request came from htmx.
HierarchicalProperties	properties()	The hierarchical properties accessible to this context.
Object	property(String name)	Retrieve a property from this context's HierarchicalProperties.
Collection<String>	propertyNames()	Returns a collection of the names in this context's HierarchicalProperties.
String	protocol()	Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1.
void	redirect(Object url)	Interrupts the execution in this element and redirects the client to another URL.
void	redirect(Route route)	Interrupts the execution in this element and redirects the client to another URL.
String	remoteAddr()	Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.
String	remoteHost()	Returns the fully qualified name of the client or the last proxy that sent the request.
String	remoteUser()	Returns the login of the user making this request.
void	removeAttribute(String name)	Removes an attribute from this request.
void	removeCookie(String name)	Removes a cookie with path "/".
void	removeCookie(String path, String name)	Removes a cookie with given path and name.
void	removeForm(Template template, Class beanClass)	Removes a generated form, leaving the builder value tags empty again as if this form had never been generated.
void	removeForm(Template template, Class beanClass, String prefix)	Removes a generated form, leaving the builder value tags empty again as if this form had never been generated.
void	removeParameter(String name)	Removes a name parameter that was previously set.
Request	request()	The request of this context.
void	respond()	Interrupts the execution in this element, stops processing any other element, and sends the current response directly to the client.
Response	response()	The response of this context.
Route	route()	The route of this context.
Router	router()	The router in which this context's route was defined.
String	scheme()	Returns the name of the scheme used to make this request.
boolean	secure()	Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
Collection<String>	selectParameter(Template template, String name, String[] values)	Sets a select box option, a radio button or a checkbox to selected or checked.
String	serverName()	Returns the host name of the server to which the request was sent.
int	serverPort()	Returns the port number to which the request was sent.
String	serverRootUrl(int port)	Returns the root URL of the server that is running this web applications.
Session	session()	Returns the current session associated with this request, or if the request does not have a session, creates one.
Session	session(boolean create)	Returns the current Session associated with this request or, if there is no current session and create is true, returns a new session.
void	setAttribute(String name, Object object)	Stores an attribute in this request.
void	setContentLength(int length)	Sets the length of the content body in the response.
void	setContentType(String contentType)	Sets the content type of the response being sent to the client.
void	setDateHeader(String name, long date)	Adds a response header with the given name and date-value.
void	setHeader(String name, int value)	Adds a response header with the given name and integer value.
void	setHeader(String name, String value)	Sets a response header with the given name and value.
void	setLocale(Locale locale)	Sets the locale of the response.
void	setParameter(String name, Object value)	Sets a named parameter value for URL generation with urlFor(rife.engine.Route) or the `route:` filtered template value tags.
void	setParametersBean(Object bean)	Sets named parameters values from bean properties for URL generation with urlFor(rife.engine.Route) or the `route:` filtered template value tags.
void	setParametersBean(Object bean, String prefix)	Sets named parameters values from bean properties for URL generation with urlFor(rife.engine.Route) or the `route:` filtered template value tags.
void	setStatus(int statusCode)	Sets the status code for the response.
Site	site()	The active site this context is executing in.
SseConnection	sse()	Turns the response into a server-sent events (SSE) stream that remains under the control of this element.
SseConnection	sse(SseBroadcaster broadcaster)	Turns the response into a server-sent events (SSE) stream that is detached from this element and registered with a broadcaster.
Template	template()	Instantiates an HTML template with the name corresponding to the identifier of this route's element.
Template	template(String name)	Instantiates an HTML template with a given name.
Template	template(String name, String encoding)	Instantiates an HTML template with a given name and encoding.
Template	templateJson()	Instantiates an JSON template with the name corresponding to the identifier of this route's element.
Template	templateJson(String name)	Instantiates an JSON template with a given name.
Template	templateJson(String name, String encoding)	Instantiates an JSON template with a given name and encoding.
Template	templateSvg()	Instantiates an SVG template with the name corresponding to the identifier of this route's element.
Template	templateSvg(String name)	Instantiates an SVG template with a given name.
Template	templateSvg(String name, String encoding)	Instantiates an SVG template with a given name and encoding.
Template	templateTxt()	Instantiates a TXT template with the name corresponding to the identifier of this route's element.
Template	templateTxt(String name)	Instantiates a TXT template with a given name.
Template	templateTxt(String name, String encoding)	Instantiates a TXT template with a given name and encoding.
Template	templateXml()	Instantiates an XML template with the name corresponding to the identifier of this route's element.
Template	templateXml(String name)	Instantiates an XML template with a given name.
Template	templateXml(String name, String encoding)	Instantiates an XML template with a given name and encoding.
boolean	textBufferEnabled()	Indicates whether the response text buffer is enabled or disabled.
UrlBuilder	urlFor(Route route)	Start building a URL towards a particular route.
void	varyOn(String... headers)	Declares that the response depends on one or more request headers, by adding each to the response's Vary header so a cache keeps responses that differ on those headers apart.
void	verifyCsrfToken()	Verifies that this request provides the CSRF token of the browser that performs it.
String	webappRootUrl()	Returns the root URL of this web application.
String	webappRootUrl(int port)	Returns the root URL of this web application.

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_BOOLEAN

public static final boolean DEFAULT_BOOLEAN

See Also:

• Constant Field Values

DEFAULT_INTEGER

public static final int DEFAULT_INTEGER

See Also:

• Constant Field Values

DEFAULT_LONG

public static final long DEFAULT_LONG

See Also:

• Constant Field Values

DEFAULT_DOUBLE

public static final double DEFAULT_DOUBLE

See Also:

• Constant Field Values

DEFAULT_FLOAT

public static final float DEFAULT_FLOAT

See Also:

• Constant Field Values

SC_NOT_MODIFIED

public static final int SC_NOT_MODIFIED

Status code (304) indicating that a conditional GET operation found that the resource was available and not modified.

See Also:

• Constant Field Values

SC_FORBIDDEN

public static final int SC_FORBIDDEN

Status code (403) indicating the server understood the request but refused to fulfill it.

See Also:

• Constant Field Values

SC_INTERNAL_SERVER_ERROR

public static final int SC_INTERNAL_SERVER_ERROR

Status code (500) indicating an error inside the HTTP server which prevented it from fulfilling the request.

See Also:

• Constant Field Values

Method Details

site

public Site site()

The active site this context is executing in.

Returns:

the currently active site

Since:

1.0

request

public Request request()

The request of this context.

Most request methods have direct counterparts in the context for easier and more convenient usage.

Returns:

this context's request

Since:

1.0

response

public Response response()

The response of this context.

Most response methods have direct counterparts in the context for easier and more convenient usage.

Returns:

this context's response

Since:

1.0

pathInfo

public String pathInfo()

The pathinfo that was captured or matched.

The slash separated between the route path in the pathinfo will have been stripped already.

Returns:

the captured or matching pathinfo; or null if no pathinfo was captured or matched

Since:

1.0

route

public Route route()

The route of this context.

Returns:

this context's route; or null if the context doesn't belong to a specific route

Since:

1.0

router

public Router router()

The router in which this context's route was defined.

Returns:

this context's route's router; or null if the context doesn't belong to a specific route

Since:

1.0

properties

public HierarchicalProperties properties()

The hierarchical properties accessible to this context.

Returns:

this context's hierarchical properties; or null if those properties can't be found

Since:

1.0

property

public Object property(String name)

Retrieve a property from this context's HierarchicalProperties.

Returns:

the requested property; or null if it doesn't exist

Since:

1.0

hasProperty

public boolean hasProperty(String name)

Checks for the existence of a property in this context's HierarchicalProperties.

Returns:

true if the property exists; or false otherwise

Since:

1.0

propertyNames

public Collection<String> propertyNames()

Returns a collection of the names in this context's HierarchicalProperties.

Returns:

the requested collection of names

Since:

1.0

pause

public final void pause()

Pauses the execution of the element and creates a new continuation.

The next request will resume exactly at the same location with a completely restored call stack and variable stack.

Since:

1.0

hasContinuationId

public boolean hasContinuationId()

Indicates whether a continuation identifier is available

Returns:

true when a continuation identifier is available; or

false otherwise

Since:

1.0

continuationId

public String continuationId()

Returns the unique identifier of the current continuation.

Returns:

the unique identifier of the current continuation; or

null if no continuation is active

Since:

1.0

print

public void print(Object object)
           throws EngineException

Prints the string representation of an object to the request text output. The string representation will be created through a String.valueOf(value) call.

Parameters:

object - the object that will be output

Throws:

EngineException - if an error occurs during the output of the content

SseOutputRefusedException - when an SSE connection has been established for this request

Since:

1.0

See Also:

• print(Template)

print

public void print(Template template)
           throws TemplateException

Prints a template to the response.

If no response content type was set yet, the template's content type will be used.

Printing a template will automatically process all the filtered tags.

Printing a template instead of the string representation of its content has many advantages, the biggest one being that the out-of-container testing API will have access to this template instance, allowing you to assert of value content, instead of having to parse a response.

Parameters:

template - the template to print

Throws:

TemplateException - if an error occurs while processing the template

EngineException - if an error occurs during the output of the content

SseOutputRefusedException - when an SSE connection has been established for this request

Since:

1.0

printBlock

public void printBlock(Template template,
 String blockId)
                throws TemplateException

Prints a single named block of a template to the response.

The template's filtered tags (values, routes, application and context tags) are processed just as with print(Template), but only the content of the requested block is written out, not the whole template. This is the low-level primitive for sending HTML fragments to htmx and other hypermedia libraries.

When you want to serve the full page on a normal request and just a block on an htmx request, you should use printHtmxFragment(rife.template.Template, java.lang.String), which makes that choice for you and which, unlike a bare isHxRequest() check, still serves the full page when htmx is restoring a page from its history. This method is what you use when you specifically want a block, such as an htmx out-of-band update. Give the block's root element an hx-swap-oob attribute in the template and print it after the main content, so that htmx swaps it in wherever it belongs.

c.print(mainTemplate);          // the primary swap
 c.printBlock(mainTemplate, "cartBadge"); // an hx-swap-oob block, updated too

Parameters:

template - the template whose block should be printed

blockId - the id of the block to print

Throws:

TemplateException - if an error occurs while processing the template

EngineException - if an error occurs during the output

SseOutputRefusedException - when an SSE connection has been established for this request

Since:

1.10

See Also:

• printHtmxFragment(rife.template.Template, java.lang.String)
• print(Template)

printHtmxFragment

public void printHtmxFragment(Template template,
 String blockId)
                       throws TemplateException

Prints a template as a full page or as one of its blocks, depending on whether the request came from htmx.

This is the whole "one element serves both" pattern in a single call: on a normal request the entire template is printed with print(Template), and on an htmx request only the named block is printed with printBlock(rife.template.Template, java.lang.String). Pair it with a block value (<!--bv blockId-->) and the same element handles the full page and the fragment with no branching of its own:

get("/books", c -> {
     var t = c.template("books");
     // ... fill it ...
     c.printHtmxFragment(t, "list");   // full page normally, just the list to htmx
 });

An htmx history-restoration request is deliberately served the full page, since htmx replaces the whole document when restoring from history and a fragment would corrupt back/forward navigation.

Because the response genuinely differs on these headers, this adds HX-Request and HX-History-Restore-Request to the response's Vary header, so a cache never hands the full page to an htmx request or the other way around. Using this instead of a hand-written isHxRequest() branch keeps the history-restoration guard and the Vary header from being forgotten.

Parameters:

template - the template to print

blockId - the id of the block to send on an htmx request

Throws:

TemplateException - if an error occurs while processing the template

EngineException - if an error occurs during the output

SseOutputRefusedException - when an SSE connection has been established for this request

Since:

1.10

See Also:

• isHxRequest()
• printBlock(rife.template.Template, java.lang.String)
• print(Template)
• varyOn(java.lang.String...)

fromTemplate

public static Context fromTemplate(Template template)

Retrieves the context that was stored in a template attribute.

Each template that was obtained through a context, automatically has the context store itself in the template as an attribute. This convenience method makes it easy to retrieve that context elsewhere.

Returns:

the current context stored in a template attribute.

Since:

1.8.0

template

public Template template()
                  throws TemplateException

Instantiates an HTML template with the name corresponding to the identifier of this route's element.

For lambda elements, this will be the path of the route and for class elements this will be the shortened uncapitalized name of the class.

Returns:

the HTML template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• template(String)
• template(String, String)

template

public Template template(String name)
                  throws TemplateException

Instantiates an HTML template with a given name.

Parameters:

name - the template name

Returns:

the HTML template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• template()
• template(String, String)

template

public Template template(String name,
 String encoding)
                  throws TemplateException

Instantiates an HTML template with a given name and encoding.

Parameters:

name - the template name

encoding - the template's encoding

Returns:

the HTML template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• template(String)
• template(String, String)

templateTxt

public Template templateTxt()
                     throws TemplateException

Instantiates a TXT template with the name corresponding to the identifier of this route's element.

For lambda elements, this will be the path of the route and for class elements this will be the shortened uncapitalized name of the class.

Returns:

the TXT template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateTxt(String)
• templateTxt(String, String)

templateTxt

public Template templateTxt(String name)
                     throws TemplateException

Instantiates a TXT template with a given name.

Parameters:

name - the template name

Returns:

the TXT template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateTxt()
• templateTxt(String, String)

templateTxt

public Template templateTxt(String name,
 String encoding)
                     throws TemplateException

Instantiates a TXT template with a given name and encoding.

Parameters:

name - the template name

encoding - the template's encoding

Returns:

the TXT template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateTxt(String)
• templateTxt(String, String)

templateXml

public Template templateXml()
                     throws TemplateException

Instantiates an XML template with the name corresponding to the identifier of this route's element.

For lambda elements, this will be the path of the route and for class elements this will be the shortened uncapitalized name of the class.

Returns:

the XML template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateXml(String)
• templateXml(String, String)

templateXml

public Template templateXml(String name)
                     throws TemplateException

Instantiates an XML template with a given name.

Parameters:

name - the template name

Returns:

the XML template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateXml()
• templateXml(String, String)

templateXml

public Template templateXml(String name,
 String encoding)
                     throws TemplateException

Instantiates an XML template with a given name and encoding.

Parameters:

name - the template name

encoding - the template's encoding

Returns:

the XML template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateXml(String)
• templateXml(String, String)

templateJson

public Template templateJson()
                      throws TemplateException

Instantiates an JSON template with the name corresponding to the identifier of this route's element.

For lambda elements, this will be the path of the route and for class elements this will be the shortened uncapitalized name of the class.

Returns:

the JSON template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateJson(String)
• templateJson(String, String)

templateJson

public Template templateJson(String name)
                      throws TemplateException

Instantiates an JSON template with a given name.

Parameters:

name - the template name

Returns:

the JSON template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateJson()
• templateJson(String, String)

templateJson

public Template templateJson(String name,
 String encoding)
                      throws TemplateException

Instantiates an JSON template with a given name and encoding.

Parameters:

name - the template name

encoding - the template's encoding

Returns:

the JSON template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateJson(String)
• templateJson(String, String)

templateSvg

public Template templateSvg()
                     throws TemplateException

Instantiates an SVG template with the name corresponding to the identifier of this route's element.

For lambda elements, this will be the path of the route and for class elements this will be the shortened uncapitalized name of the class.

Returns:

the SVG template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateSvg(String)
• templateSvg(String, String)

templateSvg

public Template templateSvg(String name)
                     throws TemplateException

Instantiates an SVG template with a given name.

Parameters:

name - the template name

Returns:

the SVG template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateSvg()
• templateSvg(String, String)

templateSvg

public Template templateSvg(String name,
 String encoding)
                     throws TemplateException

Instantiates an SVG template with a given name and encoding.

Parameters:

name - the template name

encoding - the template's encoding

Returns:

the SVG template if it was found.

Throws:

TemplateException - when an error occurred instantiating the template

Since:

1.0

See Also:

• templateSvg(String)
• templateSvg(String, String)

gateUrl

public String gateUrl()

Retrieves the URL portion that corresponds to the entrance gate of the RIFE2 web engine, this is usually equivalent with the HTTP request context path.

Returns:

the URL of the web engine gate

Since:

1.0

serverRootUrl

public String serverRootUrl(int port)

Returns the root URL of the server that is running this web applications.

This includes the protocol, the server name and the server port, for example: http://www.somehost.com:8080.

Parameters:

port - the server port to use, or -1 to use the sane port as the active request

Returns:

the server's root url

Since:

1.0

webappRootUrl

public String webappRootUrl()

Returns the root URL of this web application.

This includes the protocol, the server name and the server port, and the gate URL.

Returns:

this web application's root URL

Since:

1.0

webappRootUrl

public String webappRootUrl(int port)

Returns the root URL of this web application.

This includes the protocol, the server name and the server port, and the gate URL.

Parameters:

port - the server port to use, or -1 to use the sane port as the active request

Returns:

this web application's root URL

Since:

1.0

urlFor

public UrlBuilder urlFor(Route route)

Start building a URL towards a particular route.

The result is a instance that can be used for further customization of the URL, if needed.

Parameters:

route - the target route

Returns:

an instance of

Since:

1.0

engineException

public Throwable engineException()

Retrieves the exception that was triggered during the RIFE2 web engine execution.

Returns:

the triggered exception; or

null if no exception was triggered

Since:

1.0

selectParameter

public Collection<String> selectParameter(Template template,
 String name,
 String[] values)

Sets a select box option, a radio button or a checkbox to selected or checked.

This method delegates all logic to the FormBuilder.selectParameter(Template, String, String[]) method of the provided template instance.

Parameters:

template - the template instance where the selection should happen

name - the name of the parameter

values - the values that should be selected or checked

Returns:

a list with the identifiers of the template values that have been set, this is never null, when no values are set an empty list is returned

Since:

1.0

See Also:

• FormBuilder
• FormBuilder.selectParameter(rife.template.Template, java.lang.String, java.lang.String[])

generateForm

public void generateForm(Template template,
 Object beanInstance)

Generates a form that corresponds to a bean instance.

Parameters:

template - the template instance where the generation should happen

beanInstance - the instance of the bean that should be used to generate the form

Since:

1.0

See Also:

• FormBuilder
• generateForm(Template, Object, String)
• generateEmptyForm(Template, Class, String)
• removeForm(Template, Class)

generateForm

public void generateForm(Template template,
 Object beanInstance,
 String prefix)

Generates a form that corresponds to a bean instance.

This method delegates all logic to the FormBuilder.generateForm(Template, Object, Map, String) method of the provided template instance.

Parameters:

template - the template instance where the generation should happen

beanInstance - the instance of the bean that should be used to generate the form

prefix - the prefix that will be prepended to all bean property names

Since:

1.0

See Also:

• FormBuilder
• generateEmptyForm(Template, Class, String)
• removeForm(Template, Class)

generateEmptyForm

public void generateEmptyForm(Template template,
 Class beanClass)

Generates a form that corresponds to an empty instance of a bean class.

Parameters:

template - the template instance where the generation should happen

beanClass - the class of the bean that should be used to generate the form

Since:

1.0

See Also:

• FormBuilder
• generateForm(Template, Object, String)
• generateEmptyForm(Template, Class, String)
• removeForm(Template, Class)

generateEmptyForm

public void generateEmptyForm(Template template,
 Class beanClass,
 String prefix)

Generates a form that corresponds to an empty instance of a bean class.

An 'empty' instance is an object that has been created by calling the default constructor of the bean class, without making any additional changes to it afterward.

This method delegates all logic to the FormBuilder.generateForm(Template, Class, Map, String) method of the provided template instance.

Parameters:

template - the template instance where the generation should happen

beanClass - the class of the bean that should be used to generate the form

prefix - the prefix that will be prepended to all bean property names

Since:

1.0

See Also:

• FormBuilder
• generateForm(Template, Object, String)
• removeForm(Template, Class)

removeForm

public void removeForm(Template template,
 Class beanClass)

Removes a generated form, leaving the builder value tags empty again as if this form had never been generated.

Parameters:

template - the template instance where the form should be removed from

beanClass - the class of the bean that should be used to remove the form

Since:

1.0

See Also:

• FormBuilder
• generateForm(Template, Object, String)
• generateEmptyForm(Template, Class, String)
• removeForm(Template, Class)

removeForm

public void removeForm(Template template,
 Class beanClass,
 String prefix)

Removes a generated form, leaving the builder value tags empty again as if this form had never been generated.

This method delegates all logic to the FormBuilder.removeForm(Template, Class, String) method of the provided template instance.

Parameters:

template - the template instance where the form should be removed from

beanClass - the class of the bean that should be used to remove the form

prefix - the prefix that will be prepended to all bean property names

Since:

1.0

See Also:

• FormBuilder
• generateForm(Template, Object, String)
• generateEmptyForm(Template, Class, String)

defer

public void defer()
           throws DeferException

Interrupts the execution in RIFE2 completely and defers it to the servlet container.

If RIFE2 is being run as a filter, it will execute the next filter in the chain.

If RIFE2 is being run as a servlet, the status code 404: Not Found will be sent to the client.

Throws:

DeferException - an exception that is used to immediately interrupt the execution, don't catch this exception

Since:

1.0

redirect

public void redirect(Object url)
              throws RedirectException

Interrupts the execution in this element and redirects the client to another URL.

Parameters:

url - the URL to which the request will be redirected, String.valueOf() will be called with this object, so a variety of types can be used

Throws:

RedirectException - an exception that is used to immediately interrupt the execution, don't catch this exception

Since:

1.0

redirect

public void redirect(Route route)
              throws RedirectException

Interrupts the execution in this element and redirects the client to another URL.

Parameters:

route - the route to which the request will be redirected

Throws:

RedirectException - an exception that is used to immediately interrupt the execution, don't catch this exception

Since:

1.0

respond

public void respond()

Interrupts the execution in this element, stops processing any other element, and sends the current response directly to the client.

Throws:

RespondException - an exception that is used to immediately interrupt the execution, don't catch this exception

Since:

1.0

next

public void next()

Interrupts the execution in this element, moving processing on to the next element in the before/route/after chain

Throws:

NextException - an exception that is used to immediately interrupt the execution, don't catch this exception

Since:

1.0

preventCaching

public void preventCaching()

Sets up the current response to prevent all caching of the response by the client.

Since:

1.0

method

public RequestMethod method()

Returns the HTTP RequestMethod with which this context's request was made.

Returns:

the RequestMethod of this context's request

Since:

1.0

parameters

public Map<String,String[]> parameters()

Retrieves the parameters that were sent to this context.

Returns:

a Map with all the parameter names and values

Since:

1.0

hasParameterValue

public boolean hasParameterValue(String name)

Checks whether a value has been provided to a parameter.

Parameters:

name - the name of the parameter

Returns:

true if the parameter has a value; or

false otherwise

Since:

1.0

See Also:

• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

isParameterEmpty

public boolean isParameterEmpty(String name)

Checks whether a parameter is empty.

Parameters:

name - the name of the parameter

Returns:

true if the parameter is empty; or

false otherwise

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameter

public String parameter(String name)

Retrieves the value of a parameter.

Parameters:

name - the name of the parameter

Returns:

the value of the parameter; or

null if no value is present for this parameter

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameter

public String parameter(String name,
 String defaultValue)

Retrieves the value of a parameter and returns a default value if no parameter value is present

Parameters:

name - the name of the parameter

defaultValue - the default value that will be used when no parameter value is present

Returns:

the parameter value; or

the default value if no parameter value is present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameterValues(String)
• parameterNames()

parameterNames

public Set<String> parameterNames()

Retrieves the names of all the parameters that are present.

Returns:

the list with the parameter names

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)

parameterValues

public String[] parameterValues(String name)

Retrieves the values of a parameter.

Parameters:

name - the name of the parameter

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterNames()

parameterBoolean

public boolean parameterBoolean(String name)

Retrieves the value of a parameter and converts it to a boolean.

Parameters:

name - the name of the parameter

Returns:

the converted parameter value; or

false if no parameter value is present or if the parameter value is not a valid boolean

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterBoolean

public boolean parameterBoolean(String name,
 boolean defaultValue)

Retrieves the value of a parameter and converts it to a boolean, using a default value if no parameter value is present.

Parameters:

name - the name of the parameter

defaultValue - the default value that will be used when no parameter value is present

Returns:

the converted parameter value; or

the default value if no parameter value is present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterInt

public int parameterInt(String name)

Retrieves the value of a parameter and converts it to an integer.

Parameters:

name - the name of the parameter

Returns:

the converted parameter value; or

0 if no parameter value is present or if the parameter value is not a valid integer

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterInt

public int parameterInt(String name,
 int defaultValue)

Retrieves the value of a parameter and converts it to an integer, using a default value if no parameter value is present.

Parameters:

name - the name of the parameter

defaultValue - the default value that will be used when no parameter value is present

Returns:

the converted parameter value; or

the default value if no parameter value is present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterLong

public long parameterLong(String name)

Retrieves the value of a parameter and converts it to a long.

Parameters:

name - the name of the parameter

Returns:

the converted parameter value; or

0L if no parameter value is present or if the parameter value is not a valid long

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterLong

public long parameterLong(String name,
 long defaultValue)

Retrieves the value of a parameter and converts it to a long, using a default value if no parameter value is present.

Parameters:

name - the name of the parameter

defaultValue - the default value that will be used when no parameter value is present

Returns:

the converted parameter value; or

the default value if no parameter value is present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterDouble

public double parameterDouble(String name)

Retrieves the value of a parameter and converts it to a double.

Parameters:

name - the name of the parameter

Returns:

the converted parameter value; or

0.0d if no parameter value is present or if the parameter value is not a valid double

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterDouble

public double parameterDouble(String name,
 double defaultValue)

Retrieves the value of a parameter and converts it to a double, using a default value if no parameter value is present.

Parameters:

name - the name of the parameter

defaultValue - the default value that will be used when no parameter value is present

Returns:

the converted parameter value; or

the default value if no parameter value is present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterFloat

public float parameterFloat(String name)

Retrieves the value of a parameter and converts it to a float.

Parameters:

name - the name of the parameter

Returns:

the converted parameter value; or

0.0f if no parameter value is present or if the parameter value is not a valid float

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterFloat

public float parameterFloat(String name,
 float defaultValue)

Retrieves the value of a parameter and converts it to a float, using a default value if no parameter value is present.

Parameters:

name - the name of the parameter

defaultValue - the default value that will be used when no parameter value is present

Returns:

the converted parameter value; or

the default value if no parameter value is present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterInts

public int[] parameterInts(String name)

Retrieves the values of a parameter as an array of integers.

Parameters:

name - the name of the parameter

Returns:

an integer array with all the parameter values; or

null if no parameter values are present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterLongs

public long[] parameterLongs(String name)

Retrieves the values of a parameter as an array of longs.

Parameters:

name - the name of the parameter

Returns:

a long array with all the parameter values; or

null if no parameter values are present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterFloats

public float[] parameterFloats(String name)

Retrieves the values of a parameter as an array of floats.

Parameters:

name - the name of the parameter

Returns:

a float array with all the parameter values; or

null if no parameter values are present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parameterDoubles

public double[] parameterDoubles(String name)

Retrieves the values of a parameter as an array of doubles.

Parameters:

name - the name of the parameter

Returns:

a double array with all the parameter values; or

null if no parameter values are present

Since:

1.0

See Also:

• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parametersBean

public <BeanType> BeanType parametersBean(Class<BeanType> beanClass)
                                   throws EngineException

Creates an instance of a bean and populates the properties with the parameter values.

This bean is not serialized or de-serialized, each property corresponds to a parameter and is individually sent by the client.

Parameters:

beanClass - the class of the submission bean

Returns:

the populated bean instance

Throws:

EngineException

Since:

1.0

See Also:

• parametersBean(Class, String)
• parametersBean(Object)
• parametersBean(Object, String)
• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parametersBean

public <BeanType> BeanType parametersBean(Class<BeanType> beanClass,
 String prefix)
                                   throws EngineException

Creates an instance of a bean and populates the properties with the parameter values, taking the provided prefix into account.

This bean is not serialized or de-serialized, each property corresponds to a parameter and is individually sent by the client.

Parameters:

beanClass - the class of the submission bean

prefix - the prefix that will be put in front of each property name

Returns:

the populated bean instance

Throws:

EngineException

Since:

1.0

See Also:

• parametersBean(Class)
• parametersBean(Object)
• parametersBean(Object, String)
• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parametersBean

public void parametersBean(Object bean)
                    throws EngineException

Fills the properties of an existing bean with the parameter values.

Parameters:

bean - the submission bean instance that will be filled

Throws:

EngineException

Since:

1.0

See Also:

• parametersBean(Class)
• parametersBean(Class, String)
• parametersBean(Object, String)
• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parametersBean

public void parametersBean(Object bean,
 String prefix)
                    throws EngineException

Fills the properties of an existing bean with the parameter values that were sent, taking the provided prefix into account.

A parameter that is present with an empty value will reset the property to the value of a new bean instance, while an absent parameter will leave the property untouched.

Parameters:

bean - the submission bean instance that will be filled

prefix - the prefix that will be put in front of each property name

Throws:

EngineException

Since:

1.0

See Also:

• parametersBean(Class)
• parametersBean(Class, String)
• parametersBean(Object)
• hasParameterValue(String)
• isParameterEmpty(String)
• parameter(String)
• parameter(String, String)
• parameterValues(String)
• parameterNames()

parametersBean

public <BeanType> BeanType parametersBean(Class<BeanType> beanClass,
 String prefix,
 String group)
                                   throws EngineException

Creates an instance of a bean and populates the properties of one of its validation groups with the parameter values that were sent.

This does the same as parametersBean(Object, String, String), but with a newly created bean instance.

Parameters:

beanClass - the class of the submission bean

prefix - the prefix that will be put in front of each property name, or null

group - the name of the validation group whose properties will be populated

Returns:

the populated bean instance

Throws:

EngineException

Since:

1.10

See Also:

• parametersBean(Object, String, String)

parametersBean

public void parametersBean(Object bean,
 String prefix,
 String group)
                    throws EngineException

Fills the properties of a validation group of an existing bean with the parameter values that were sent.

The validation group declares which properties are part of the form. Only those properties will be populated, and a property whose parameter is absent will be reset instead of keeping its current value: a boolean property becomes false since browsers don't send checkboxes that aren't checked, the other properties are reset to the value of a new bean instance. A restored bean will thus reflect exactly what the form submitted, while the properties outside of the group preserve their current values.

Each property is populated through a single transport: a property with a file constraint is only assigned from file uploads, while the other properties are only assigned from regular parameter values. A file property is left untouched when no upload actually arrived, an absent file input never clears the stored content.

Since every property of the group is expected to be part of the form, a group should only contain the properties that are actually submitted. Controls that the browser doesn't send, like disabled ones, and partial submissions of a group's form will reset the properties that didn't arrive.

Parameters:

bean - the submission bean instance that will be filled

prefix - the prefix that will be put in front of each property name, or null

group - the name of the validation group whose properties will be populated

Throws:

EngineException

Since:

1.10

See Also:

• parametersBean(Class, String, String)

body

public String body()

Retrieves the body of this context's request as a string.

Returns:

the string of the request body

Since:

1.0

See Also:

• bodyAsBytes()

bodyAsBytes

public byte[] bodyAsBytes()

Retrieves the body of this context's request as a byte array.

Returns:

the byte array of the request body

Since:

1.0

See Also:

• body()

fileNames

public Set<String> fileNames()

Retrieves the list of uploaded file names.

Returns:

the set of uploaded file names

Since:

1.0

See Also:

• hasFile(String)
• isFileEmpty(String)
• file(String)
• files(String)

isFileEmpty

public boolean isFileEmpty(String name)

Checks if an uploaded file wasn't sent or if it is empty.

Parameters:

name - the name of the file

Since:

1.0

See Also:

• fileNames()
• hasFile(String)
• file(String)
• files(String)

files

public Map<String,UploadedFile[]> files()

Retrieves the files that were uploaded in this context.

Returns:

a Map with all the uploaded files

Since:

1.0

See Also:

• hasFile(String)
• file(String)
• files(String)

hasFile

public boolean hasFile(String name)

Checks if a particular file has been uploaded in this context.

Parameters:

name - the name of the file

Returns:

true if the file was uploaded; or

false otherwise

Since:

1.0

See Also:

• files()
• file(String)
• files(String)

file

public UploadedFile file(String name)

Retrieves an uploaded file.

Parameters:

name - the name of the file

Returns:

the uploaded file; or

null if no file was uploaded

Since:

1.0

See Also:

• files()
• hasFile(String)
• files(String)

files

public UploadedFile[] files(String name)

Retrieves all files that have been uploaded for a particular name.

Parameters:

name - the name of the file

Returns:

the uploaded files; or

null if no files were uploaded for that name

Since:

1.0

See Also:

• files()
• hasFile(String)
• file(String)

hasCookie

public boolean hasCookie(String name)

Checks whether a cookie is present.

Parameters:

name - the name of the cookie

Returns:

true if the cookie was present; or

false otherwise

Since:

1.0

See Also:

• cookieValue(String)
• cookieValues()

cookieNames

public List<String> cookieNames()

Retrieves the names of the cookies.

Returns:

a list of strings with the cookie names

Since:

1.0

See Also:

• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieValue

public String cookieValue(String name)

Retrieves the value of a cookie.

Parameters:

name - the name of the cookie

Returns:

the value of the cookie; or

null if no such cookie is present

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String, String)
• cookieValues()

cookieValues

public Map<String,String> cookieValues()

Retrieves all current cookies names with their values.

Returns:

a new map of all the current cookies names with their values

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)

cookieValue

public String cookieValue(String name,
 String defaultValue)

Retrieves the value of a named cookie, using a default value as fallback.

Parameters:

name - the name of the cookie

defaultValue - the default value that will be used when no cookie value is present

Returns:

the cookie value; or

the default value if no cookie value is present

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieBoolean

public boolean cookieBoolean(String name)

Retrieves the value of a named cookie and converts it to a boolean.

Parameters:

name - the name of the cookie

Returns:

the converted cookie value; or

false if no cookie value is present or if the cookie value is not a valid boolean

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieBoolean

public boolean cookieBoolean(String name,
 boolean defaultValue)

Retrieves the value of a named cookie and converts it to a boolean, using a default value if no input value is present.

Parameters:

name - the name of the cookie

defaultValue - the default value that will be used when no cookie value is present

Returns:

the converted cookie value; or

the default value if no cookie value is present

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieInt

public int cookieInt(String name)

Retrieves the value of a named cookie and converts it to an integer.

Parameters:

name - the name of the cookie

Returns:

the converted cookie value; or

0 if no cookie value is present or if the cookie value is not a valid integer

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieInt

public int cookieInt(String name,
 int defaultValue)

Retrieves the value of a named cookie and converts it to an integer, using a default value if no input value is present.

Parameters:

name - the name of the cookie

defaultValue - the default value that will be used when no cookie value is present

Returns:

the converted cookie value; or

the default value if no cookie value is present

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieLong

public long cookieLong(String name)

Retrieves the value of a named cookie and converts it to a long.

Parameters:

name - the name of the cookie

Returns:

the converted cookie value; or

0L if no cookie value is present or if the cookie value is not a valid long

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieLong

public long cookieLong(String name,
 long defaultValue)

Retrieves the value of a named cookie and converts it to a long, using a default value if no input value is present.

Parameters:

name - the name of the cookie

defaultValue - the default value that will be used when no cookie value is present

Returns:

the converted cookie value; or

the default value if no cookie value is present

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieDouble

public double cookieDouble(String name)

Retrieves the value of a named cookie and converts it to a double.

Parameters:

name - the name of the cookie

Returns:

the converted cookie value; or

0.0d if no cookie value is present or if the cookie value is not a valid double

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieDouble

public double cookieDouble(String name,
 double defaultValue)

Retrieves the value of a named cookie and converts it to a double, using a default value if no input value is present.

Parameters:

name - the name of the cookie

defaultValue - the default value that will be used when no cookie value is present

Returns:

the converted cookie value; or

the default value if no cookie value is present

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieFloat

public float cookieFloat(String name)

Retrieves the value of a named cookie and converts it to a float.

Parameters:

name - the name of the cookie

Returns:

the converted cookie value; or

0.0f if no cookie value is present or if the cookie value is not a valid float

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

cookieFloat

public float cookieFloat(String name,
 float defaultValue)

Retrieves the value of a named cookie and converts it to a float, using a default value if no input value is present.

Parameters:

name - the name of the cookie

defaultValue - the default value that will be used when no cookie value is present

Returns:

the converted cookie value; or

the default value if no cookie value is present

Since:

1.0

See Also:

• cookieNames()
• hasCookie(String)
• cookieValue(String)
• cookieValue(String, String)
• cookieValues()

attribute

public Object attribute(String name)

Returns the value of the named attribute.

Parameters:

name - the name of the attribute

Returns:

an Object containing the value of the attribute; or

null if the attribute does not exist

Since:

1.0

See Also:

• hasAttribute(java.lang.String)
• attributeNames()
• removeAttribute(java.lang.String)
• setAttribute(java.lang.String, java.lang.Object)

hasAttribute

public boolean hasAttribute(String name)

Checks if a request attribute exists.

Parameters:

name - a String specifying the name of the attribute

false otherwise

Since:

1.0

See Also:

• attribute(java.lang.String)
• attributeNames()
• removeAttribute(java.lang.String)
• setAttribute(java.lang.String, java.lang.Object)

attributeNames

public List<String> attributeNames()

Returns a list of attribute names available to this request.

Returns:

a list of strings containing the names of the request's attributes; or

an empty list if not attributes are present

Since:

1.0

See Also:

• attribute(java.lang.String)
• hasAttribute(java.lang.String)
• removeAttribute(java.lang.String)
• setAttribute(java.lang.String, java.lang.Object)

removeAttribute

public void removeAttribute(String name)

Removes an attribute from this request. This method is not generally needed as attributes only persist as long as the request is being handled.

Parameters:

name - the name of the attribute to remove

Since:

1.0

See Also:

• attribute(java.lang.String)
• hasAttribute(java.lang.String)
• attributeNames()
• setAttribute(java.lang.String, java.lang.Object)

setAttribute

public void setAttribute(String name,
 Object object)

Stores an attribute in this request. Attributes are reset between requests.

Attribute names should follow the same conventions as package names. If the object passed in is null, the effect is the same as calling removeAttribute.

Parameters:

name - the name of the attribute to set

object - the object to store

Since:

1.0

See Also:

• attribute(java.lang.String)
• hasAttribute(java.lang.String)
• attributeNames()
• removeAttribute(java.lang.String)

characterEncoding

public String characterEncoding()

Returns the name of the character encoding used in the body of this request.

Returns:

a String containing the name of the character encoding; or

null if the request does not specify a character encoding

Since:

1.0

contentType

public String contentType()

Returns the MIME type of the body of the request, or null if the type is not known.

Returns:

a String containing the name of the MIME type of the request; or null if the type is not known

Since:

1.0

header

public String header(String name)

Returns the value of the specified request header as a String.

Parameters:

name - the case-insensitive name of the header

Returns:

a String with the value of the requested header; or null if the request does not have a header of that name

Since:

1.0

See Also:

• headerDate(java.lang.String)
• headerInt(java.lang.String)
• headerNames()
• headers(java.lang.String)

headerDate

public long headerDate(String name)

Returns the value of the specified request header as a long value that represents a date. Use this method with headers that contain dates, such as If-Modified-Since.

Parameters:

name - the case-insensitive name of the header

Returns:

a long value representing the date specified in the header expressed as the number of milliseconds since January 1, 1970 GMT; or

-1 if the named header was not included with the request

Throws:

IllegalArgumentException - if the header can't be converted to a date

Since:

1.0

See Also:

• header(java.lang.String)
• headerInt(java.lang.String)
• headerNames()
• headers(java.lang.String)

headerInt

public int headerInt(String name)

Returns the value of the specified request header as an int.

Parameters:

name - the case-insensitive name of the header

Returns:

an integer expressing the value of the request header; or

-1 if the request doesn't have a header of this name

Throws:

NumberFormatException - if the header value can't be converted to an int

Since:

1.0

See Also:

• header(java.lang.String)
• headerDate(java.lang.String)
• headerNames()
• headers(java.lang.String)

headerNames

public List<String> headerNames()

Returns a list of all the header names in the request.

Returns:

a list of all the header names sent with this request;

if the request has no headers, an empty list will be returned

Since:

1.0

See Also:

• header(java.lang.String)
• headerDate(java.lang.String)
• headerInt(java.lang.String)
• headers(java.lang.String)

headers

public List<String> headers(String name)

Returns all the values of the specified request header as a list of String objects.

Some headers, such as Accept-Language can be sent by clients as several headers each with a different value rather than sending the header as a comma separated list.

Parameters:

name - the case-insensitive name of the header

Returns:

a list containing the values of the requested header;

itf the request does not have any headers of that name an empty list will be returned

Since:

1.0

See Also:

• header(java.lang.String)
• headerDate(java.lang.String)
• headerInt(java.lang.String)
• headerNames()

locale

public Locale locale()

Returns the preferred Locale that the client will accept content in, based on the Accept-Language header.

If the client request doesn't provide an Accept-Language header, this method returns the default locale for the server.

Returns:

the preferred Locale for the client

Since:

1.0

locales

public List<Locale> locales()

Returns a list of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language} header.

If the client request doesn't provide an Accept-Language header, this method returns a list containing one Locale, the default locale for the server.

Returns:

a list of preferred Locale objects for the client

Since:

1.0

remoteAddr

public String remoteAddr()

Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.

Returns:

a String containing the IP address of the client that sent the request

Since:

1.0

remoteUser

public String remoteUser()

Returns the login of the user making this request.

Whether the username is sent with each subsequent request depends on the browser and type of authentication.

Returns:

a String specifying the login of the user making this request; or null if the user login is not known

Since:

1.0

remoteHost

public String remoteHost()

Returns the fully qualified name of the client or the last proxy that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this method returns the dotted-string form of the IP address.

Returns:

a String containing the fully qualified name of the client

Since:

1.0

session

public Session session()

Returns the current session associated with this request, or if the request does not have a session, creates one.

Returns:

the Session associated with this request

Since:

1.0

See Also:

• session(boolean)

session

public Session session(boolean create)

Returns the current Session associated with this request or, if there is no current session and create is true, returns a new session.

If create is false and the request has no valid Session, this method returns null.

Parameters:

create - true to create a new session for this request if necessary; false to return null if there's no current session

Returns:

the Session associated with this request or null if create is false and the request has no valid session

Since:

1.0

serverPort

public int serverPort()

Returns the port number to which the request was sent.

Returns:

an integer specifying the port number

Since:

1.0

protocol

public String protocol()

Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1.

Returns:

a String containing the protocol name and version number

Since:

1.0

scheme

public String scheme()

Returns the name of the scheme used to make this request.

Returns:

the name of the scheme used to make this request

Since:

1.0

serverName

public String serverName()

Returns the host name of the server to which the request was sent.

Returns:

the name of the server

Since:

1.0

contextPath

public String contextPath()

Returns the portion of the request URI that indicates the context of the request. The context path always comes first in a request URI. The path starts with a "/" character but does not end with a "/" character. For servlets in the default (root) context, this method returns "". The container does not decode this string.

Returns:

the portion of the request URI that indicates the context of the request

Since:

1.0

secure

public boolean secure()

Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.

Returns:

a boolean indicating whether the request was made using a secure channel

Since:

1.0

enableTextBuffer

public void enableTextBuffer(boolean enabled)

Enables or disables the response text buffer. By default, it is enabled.

Disabling an enabled text buffer, flushes the already buffered content first.

If the text buffer is disabled, text content will be sent immediately to the client, this can decrease performance. Unless you need to stream content in real time, it's best to leave the text buffer enabled. It will be flushed and sent in one go at the end of the request.

Parameters:

enabled - true to enable the text buffer; or

false to disable it

Since:

1.0

See Also:

• textBufferEnabled()
• flush()
• clearBuffer()

textBufferEnabled

public boolean textBufferEnabled()

Indicates whether the response text buffer is enabled or disabled.

Returns:

true if the text buffer is enabled; or

false if it is disabled

Since:

1.0

See Also:

• enableTextBuffer(boolean)
• flush()
• clearBuffer()

clearBuffer

public void clearBuffer()

Clears the text buffer is it's enabled.

If the text buffer is disabled, this method does nothing.

Since:

1.0

flush

public void flush()

Forces all the streamed content to be output to the client.

If the text buffer is enabled, this will flush its content to the output stream first.

Since:

1.0

outputStream

public OutputStream outputStream()
                          throws EngineException

Returns an output stream suitable for writing binary data in the response.

When possible and applicable, this output stream will automatically handle gzip encoding.

Returns:

an OutputStream for binary data output

Throws:

EngineException

Since:

1.0

sse

public SseConnection sse()
                  throws EngineException

Turns the response into a server-sent events (SSE) stream that remains under the control of this element.

The response is prepared for event streaming and the headers are immediately sent to the client. The connection stays open for as long as this element is executing, so the element typically sends events in a loop until SseConnection.isOpen() indicates that the client has disconnected.

Returns:

the SSE connection for this response

Throws:

SseConnectionAlreadyEstablishedException - when an SSE connection has already been established for this request

SseConnectionAfterOutputException - when response content has already been produced

EngineException

Since:

1.10

See Also:

• SseConnection
• sse(SseBroadcaster)

sse

public SseConnection sse(SseBroadcaster broadcaster)
                  throws EngineException

Turns the response into a server-sent events (SSE) stream that is detached from this element and registered with a broadcaster.

The response is prepared for event streaming and the headers are immediately sent to the client. The element returns immediately while the connection stays open, and events are pushed to it afterwards through the broadcaster, from anywhere in the application.

Parameters:

broadcaster - the broadcaster this connection will be registered with

Returns:

the SSE connection for this response

Throws:

SseConnectionAlreadyEstablishedException - when an SSE connection has already been established for this request

SseConnectionAfterOutputException - when response content has already been produced

EngineException

Since:

1.10

See Also:

• SseConnection
• SseBroadcaster

ensureCsrfToken

public void ensureCsrfToken()

Ensures that a CSRF token is established for this request, generating a new one and setting its cookie when the browser doesn't have one yet.

Once a token is active for a request, the route:inputs: filtered tag adds it to the forms it generates, and the token is available on its own through the context:csrfToken template value, for the headers that JavaScript sends. The CsrfProtected element calls this on the pages that display protected forms.

This doesn't return the token, use csrfToken() to obtain its value.

Since:

1.10

See Also:

• csrfToken()
• CsrfProtected

csrfToken

public String csrfToken()

Retrieves the CSRF token of the browser that performs this request, establishing one with ensureCsrfToken() when the browser doesn't have one yet. The same token is returned for the rest of this request.

Returns:

the CSRF token of this browser

Since:

1.10

See Also:

• ensureCsrfToken()
• CsrfProtected

hasCsrfToken

public boolean hasCsrfToken()

Indicates whether a CSRF token is available for this request, either because one was already established while processing it, or because the browser sent its token cookie.

Unlike csrfToken() this method will not create a token, so that you can decide whether to include the token without minting one for browsers that don't have it yet. The route:inputs: filtered tag uses it to add the token to the forms of the pages where it's active.

Returns:

true when a CSRF token is available; or

false otherwise

Since:

1.10

See Also:

• csrfToken()

verifyCsrfToken

public void verifyCsrfToken()

Verifies that this request provides the CSRF token of the browser that performs it.

The token is looked up in the request parameter and in the request header that RifeConfig.engine() configures, in that order.

Throws:

CsrfTokenMissingException - when the browser has no token cookie, or when the request provides no token

CsrfTokenInvalidException - when the provided token doesn't correspond to the token cookie

Since:

1.10

See Also:

• CsrfProtected

setContentType

public void setContentType(String contentType)

Sets the content type of the response being sent to the client.

Parameters:

contentType - the MIME type of the content

Since:

1.0

setContentLength

public void setContentLength(int length)

Sets the length of the content body in the response.

Parameters:

length - an integer specifying the length of the content being returned to the client

Since:

1.0

setLocale

public void setLocale(Locale locale)

Sets the locale of the response.

Parameters:

locale - the locale of the response

Since:

1.0

setParameter

public void setParameter(String name,
 Object value)

Sets a named parameter value for URL generation with urlFor(rife.engine.Route) or the `route:` filtered template value tags.

The parameter value will be converted to a string array.

Setting parameters acts on a different collection than incoming request parameters and is used for RIFE2 state-related features like URL generation.

Parameters:

name - the name of the parameter to set

value - the value of the parameter

Since:

1.0

See Also:

• urlFor(rife.engine.Route)
• setParametersBean(Object)
• setParametersBean(Object, String)
• removeParameter(java.lang.String)

setParametersBean

public void setParametersBean(Object bean)

Sets named parameters values from bean properties for URL generation with urlFor(rife.engine.Route) or the `route:` filtered template value tags.

Parameters:

bean - the bean whose properties will be set as parameters

Since:

1.0

See Also:

• urlFor(rife.engine.Route)
• setParameter(java.lang.String, java.lang.Object)
• setParametersBean(Object, String)
• removeParameter(java.lang.String)

setParametersBean

public void setParametersBean(Object bean,
 String prefix)

Sets named parameters values from bean properties for URL generation with urlFor(rife.engine.Route) or the `route:` filtered template value tags.

Parameters:

bean - the bean whose properties will be set as parameters

prefix - the prefix that will be added to the parameter names

Since:

1.0

See Also:

• urlFor(rife.engine.Route)
• setParameter(java.lang.String, java.lang.Object)
• setParametersBean(Object)
• removeParameter(java.lang.String)

removeParameter

public void removeParameter(String name)

Removes a name parameter that was previously set.

Parameters:

name - the name of the parameter to remove

Since:

1.0

See Also:

• urlFor(rife.engine.Route)
• setParameter(java.lang.String, java.lang.Object)
• setParametersBean(Object)
• setParametersBean(Object, String)

addCookie

public void addCookie(CookieBuilder builder)

Adds the Cookie created by a CookieBuilder to the response. This method can be called multiple times to set more than one cookie.

Parameters:

builder - the CookieBuilder to use for building the Cookie

Since:

1.0

removeCookie

public void removeCookie(String name)

Removes a cookie with path "/".

Parameters:

name - name of the cookie

Since:

1.0

removeCookie

public void removeCookie(String path,
 String name)

Removes a cookie with given path and name.

Parameters:

path - path of the cookie

name - name of the cookie

Since:

1.0

setHeader

public void setHeader(String name,
 String value)

Sets a response header with the given name and value.

If the header had already been set, the new value overwrites the previous one.

Parameters:

name - the name of the header

value - the additional header value

Since:

1.0

addHeader

public void addHeader(String name,
 String value)

Adds a response header with the given name and value.

This method allows response headers to have multiple values.

Parameters:

name - the name of the header

value - the additional header value

Since:

1.0

setDateHeader

public void setDateHeader(String name,
 long date)

Adds a response header with the given name and date-value. The date is specified in terms of milliseconds since the epoch.

If the header had already been set, the new value overwrites the previous one.

Parameters:

name - the name of the header to set

date - the additional date value

Since:

1.0

addDateHeader

public void addDateHeader(String name,
 long date)

Adds a response header with the given name and date-value. The date is specified in terms of milliseconds since the epoch.

This method allows response headers to have multiple values.

Parameters:

name - the name of the header to set

date - the additional date value

Since:

1.0

setHeader

public void setHeader(String name,
 int value)

Adds a response header with the given name and integer value.

If the header had already been set, the new value overwrites the previous one.

Parameters:

name - the name of the header

value - the assigned integer value

Since:

1.0

addHeader

public void addHeader(String name,
 int value)

Adds a response header with the given name and integer value.

This method allows response headers to have multiple values.

Parameters:

name - the name of the header

value - the assigned integer value

Since:

1.0

setStatus

public void setStatus(int statusCode)

Sets the status code for the response.

Parameters:

statusCode - the status code

Since:

1.0

isHxRequest

public boolean isHxRequest()

Indicates whether the current request was issued by htmx.

This reads the HX-Request header that htmx sets on every request it makes. It's a plain read with no side effects, so consulting it for logging or a decision that doesn't change the output is free.

To serve a fragment to htmx and the full page otherwise, prefer printHtmxFragment(rife.template.Template, java.lang.String): it makes that choice, guards the history-restoration case, and declares Vary for you. You should only branch on this method yourself when that helper doesn't fit, and then declare the dependency with varyOn("HX-Request"), since a shared cache could otherwise hand the fragment to a browser or the full page to htmx.

Returns:

true when this is an htmx request; or

false otherwise

Since:

1.10

See Also:

• printHtmxFragment(rife.template.Template, java.lang.String)
• varyOn(java.lang.String...)
• printBlock(rife.template.Template, java.lang.String)

isHxBoosted

public boolean isHxBoosted()

Indicates whether the current request was made by an htmx-boosted link or form, reading the HX-Boosted header.

This method will only read the header without having any side effects. When the response depends on it, you should declare that with varyOn("HX-Boosted") so that a cache keeps a boosted response apart from an ordinary one.

Returns:

true when this is an htmx-boosted request; or

false otherwise

Since:

1.10

See Also:

• varyOn(java.lang.String...)

isHxHistoryRestoreRequest

public boolean isHxHistoryRestoreRequest()

Indicates whether the current request is htmx restoring a page from its history after a cache miss, reading the HX-History-Restore-Request header.

Such a request expects the whole page instead of a fragment, since htmx replaces the entire document when it restores from history, which means that a fragment would corrupt the back and forward navigation. printHtmxFragment(rife.template.Template, java.lang.String) will serve the full page for you. If you branch between a fragment and a page yourself with isHxRequest(), you should guard that branch with this method too, since a history restore that carries the same parameters as a fragment request would otherwise receive a fragment. This method will only read the header without having any side effects.

Returns:

true when this is an htmx history-restoration request; or

false otherwise

Since:

1.10

See Also:

• printHtmxFragment(rife.template.Template, java.lang.String)
• isHxRequest()

hxTriggerId

public String hxTriggerId()

Returns the id of the element that triggered an htmx request, from the HX-Trigger request header.

Returns:

the triggering element's id, or null if absent

Since:

1.10

hxTriggerName

public String hxTriggerName()

Returns the name of the element that triggered an htmx request, from the HX-Trigger-Name request header.

Returns:

the triggering element's name, or null if absent

Since:

1.10

hxTarget

public String hxTarget()

Returns the id of the target element of an htmx request, from the HX-Target request header.

Returns:

the target element's id, or null if absent

Since:

1.10

hxCurrentUrl

public String hxCurrentUrl()

Returns the browser's current URL at the time of the htmx request, from the HX-Current-URL request header.

Returns:

the current URL, or null if absent

Since:

1.10

hxPrompt

public String hxPrompt()

Returns the user's response to an hx-prompt, from the HX-Prompt request header.

Returns:

the prompt response, or null if absent

Since:

1.10

hxLocation

public void hxLocation(String url)

Tells htmx to do a client-side redirect to a new location without a full page reload, by setting the HX-Location response header.

Parameters:

url - the location to navigate to

Since:

1.10

See Also:

• hxLocation(HxLocation)

hxLocation

public void hxLocation(Route route)

Tells htmx to do a client-side redirect to a route without a full page reload, by setting the HX-Location response header.

Parameters:

route - the route to navigate to

Since:

1.10

See Also:

• hxLocation(HxLocation)

hxLocation

public void hxLocation(HxLocation location)

Tells htmx to do a client-side redirect with navigation context, by setting the HX-Location response header to its JSON form.

The HxLocation argument carries the context of the navigation, like the target to swap into or the swap style:

c.hxLocation(new HxLocation(books).target("#main").swap("outerHTML"));

A location without any context is sent as the plain path, the same as hxLocation(String).

Parameters:

location - the location to navigate to, with its context

Since:

1.10

hxRedirect

public void hxRedirect(String url)

Tells htmx to do a full-page redirect, by setting the HX-Redirect response header.

Parameters:

url - the location to redirect to

Since:

1.10

hxRedirect

public void hxRedirect(Route route)

Tells htmx to do a full-page redirect to a route, by setting the HX-Redirect response header.

Parameters:

route - the route to redirect to

Since:

1.10

hxRefresh

public void hxRefresh()

Tells htmx to refresh the whole page, by setting the HX-Refresh response header.

Since:

1.10

hxPushUrl

public void hxPushUrl(String url)

Tells htmx to push a new URL into the browser history, by setting the HX-Push-Url response header.

Parameters:

url - the URL to push

Since:

1.10

hxPushUrl

public void hxPushUrl(Route route)

Tells htmx to push a route's URL into the browser history by setting the HX-Push-Url response header.

Since the URL is generated from the route, it will survive renaming and refactoring.

Parameters:

route - the route whose URL to push

Since:

1.10

hxNoPushUrl

public void hxNoPushUrl()

Tells htmx not to push a URL into the browser history for this response, by setting the HX-Push-Url response header to false.

This suppresses the history entry that an hx-push-url attribute or a boosted element would otherwise record.

Since:

1.10

See Also:

• hxPushUrl(String)

hxReplaceUrl

public void hxReplaceUrl(String url)

Tells htmx to replace the current URL in the browser history, by setting the HX-Replace-Url response header.

Parameters:

url - the replacement URL

Since:

1.10

hxReplaceUrl

public void hxReplaceUrl(Route route)

Tells htmx to replace the current URL in the browser history with a route's URL, by setting the HX-Replace-Url response header.

Parameters:

route - the route whose URL replaces the current one

Since:

1.10

hxNoReplaceUrl

public void hxNoReplaceUrl()

Tells htmx not to replace the current URL in the browser history for this response, by setting the HX-Replace-Url response header to false.

This suppresses the URL replacement that an hx-replace-url attribute would otherwise perform.

Since:

1.10

See Also:

• hxReplaceUrl(String)

hxRetarget

public void hxRetarget(String cssSelector)

Tells htmx to swap the response into a different target than the triggering element's, by setting the HX-Retarget response header to a CSS selector.

Parameters:

cssSelector - the CSS selector of the new target

Since:

1.10

hxReswap

public void hxReswap(String swapStyle)

Tells htmx to change how the response is swapped in, by setting the HX-Reswap response header to an hx-swap value such as outerHTML or beforeend.

Parameters:

swapStyle - the swap style to use

Since:

1.10

hxReselect

public void hxReselect(String cssSelector)

Tells htmx to select only part of the response for swapping, by setting the HX-Reselect response header to a CSS selector.

Parameters:

cssSelector - the CSS selector to select from the response

Since:

1.10

hxTrigger

public void hxTrigger(String event)

Triggers a client-side event as soon as the response is received, by adding it to the HX-Trigger response header.

Calls accumulate: each one adds its event to the same header, so independent pieces of code can trigger their own events without overwriting each other. A single event without a payload travels as a plain event name; as soon as several events or a payload are involved, the header switches to htmx's JSON object form, where an event without a payload carries a null detail. Triggering the same event again replaces its payload.

Parameters:

event - the name of the event to trigger

Since:

1.10

hxTrigger

public void hxTrigger(String event,
 Object data)

Triggers a client-side event with a data payload as soon as the response is received, by adding it to the HX-Trigger response header.

The payload is serialized to JSON with RIFE2's own Json support, so records, beans, maps and collections all work without an extra dependency. Calls accumulate like hxTrigger(String).

Parameters:

event - the name of the event to trigger

data - the payload delivered as the event's detail

Since:

1.10

hxTriggerAfterSettle

public void hxTriggerAfterSettle(String event)

Triggers a client-side event after the settle step, by adding it to the HX-Trigger-After-Settle response header.

Calls accumulate like hxTrigger(String), separately from the other trigger headers.

Parameters:

event - the name of the event to trigger

Since:

1.10

hxTriggerAfterSettle

public void hxTriggerAfterSettle(String event,
 Object data)

Triggers a client-side event with a data payload after the settle step, by adding it to the HX-Trigger-After-Settle response header.

Calls accumulate like hxTrigger(String), separately from the other trigger headers.

Parameters:

event - the name of the event to trigger

data - the payload delivered as the event's detail

Since:

1.10

hxTriggerAfterSwap

public void hxTriggerAfterSwap(String event)

Triggers a client-side event after the swap step, by adding it to the HX-Trigger-After-Swap response header.

Calls accumulate like hxTrigger(String), separately from the other trigger headers.

Parameters:

event - the name of the event to trigger

Since:

1.10

hxTriggerAfterSwap

public void hxTriggerAfterSwap(String event,
 Object data)

Triggers a client-side event with a data payload after the swap step, by adding it to the HX-Trigger-After-Swap response header.

Calls accumulate like hxTrigger(String), separately from the other trigger headers.

Parameters:

event - the name of the event to trigger

data - the payload delivered as the event's detail

Since:

1.10

varyOn

public void varyOn(String... headers)

Declares that the response depends on one or more request headers, by adding each to the response's Vary header so a cache keeps responses that differ on those headers apart.

You should use this method whenever you shape the response from a request header that you read, such as branching on isHxRequest() or isHxBoosted() to serve different content. The htmx accessors only read their headers and don't vary on their own, precisely so that reading a header for logging, or for a decision that doesn't change the output, never fragments a cache. printHtmxFragment(rife.template.Template, java.lang.String) declares its own variance, which means that this method is only needed when you do the branching yourself. Each name is added at most once per request, so that repeated calls don't have any additional effect.

Parameters:

headers - the request header names the response varies on

Since:

1.10

See Also:

• isHxRequest()
• printHtmxFragment(rife.template.Template, java.lang.String)