Package com.oorian.html

Class HtmlPage

java.lang.Object
com.oorian.HttpFile
com.oorian.html.HtmlPage
Direct Known Subclasses:
HtmlTemplatePage
public abstract class HtmlPage extends HttpFile
Abstract base class for all Oorian HTML pages.

HtmlPage provides the foundation for building dynamic web pages with real-time client-server communication. It manages the page lifecycle, element hierarchy, event dispatching, and DOM synchronization via WebSocket, SSE, or AJAX.

Subclasses implement createHead(Head) and createBody(Body) to build the page content. The page maintains a persistent connection to the browser, allowing server-side code to update the DOM in real time.

Since:
2007
Version:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Details

    • HtmlPage

      public HtmlPage()
      Creates a new HtmlPage with default settings.

      Initializes the head, body, event dispatcher, request handler, and sets the communication mode to the application default.

  • Method Details

    • resolveUrl

      public static String resolveUrl(String url)
      Resolves a URL by prepending the application context path if necessary.

      This method handles URLs that start with "/" by prepending the servlet context path. URLs that are already absolute (http://, https://) or protocol-relative (//) are returned unchanged.

      This method should be used when constructing URLs for href, src, action attributes to ensure they work correctly regardless of the application's deployment context path.

      Parameters:
      url - The URL to resolve.
      Returns:
      The resolved URL with context path prepended if applicable.

    • createUrl

      public static String createUrl(Class pageClass, Object... args)
      Creates a URL for navigating to a page class with optional parameters.

      This method resolves the URL pattern defined in the page's @Page annotation and substitutes any path parameters with the provided arguments.

      The returned URL includes the application context path, so it can be used directly in href, src, or action attributes.

      Parameters:
      pageClass - The page class annotated with @Page.
      args - The arguments to substitute into URL path parameters, in order.
      Returns:
      The constructed URL string with context path included.
      Throws:
      PageUrlException - If the number of arguments doesn't match the number of URL parameters.

    • handleAjaxRequest

      public void handleAjaxRequest(OorianHttpRequest request, OorianHttpResponse response)
      Handles an incoming AJAX request from the client.

      Processes the request parameters, dispatches events to appropriate handlers, and sends the response back to the client.

      Parameters:
      request - The HTTP servlet request containing event data.
      response - The HTTP servlet response to send updates back to the client.

    • handleWebSocketRequest

      public void handleWebSocketRequest(Parameters params)
      Handles an incoming WebSocket request from the client.

      Processes the request parameters from a WebSocket message and sends any updates back through the WebSocket connection.

      Parameters:
      params - The parameters extracted from the WebSocket message.

    • handleWebsocketOpen

      public void handleWebsocketOpen(WebsocketConnection websocket)
      Called when a WebSocket connection is opened for this page.

      Stores the WebSocket reference and invokes the onWebsocketOpen() callback to allow subclasses to perform initialization when the connection is established.

      Parameters:
      websocket - The WebSocket connection instance.

    • handleWebsocketMessage

      public void handleWebsocketMessage(OorianHttpSession session, String msg)
      Handles an incoming WebSocket message.

      Parses the JSON message, extracts parameters, and dispatches the request to the appropriate handlers. Handles session validation and error cases.

      Parameters:
      session - The HTTP session associated with the WebSocket connection.
      msg - The raw JSON message string from the client.

    • handleWebsocketError

      public void handleWebsocketError(Throwable error)
      Handles a WebSocket error for this page.

      Delegates to onWebsocketError(Throwable) for custom error handling.

      Parameters:
      error - The error that occurred.

    • handleWebsocketClose

      public void handleWebsocketClose(ConnectionCloseInfo reason)
      Handles a WebSocket close event for this page.

      Delegates to onWebsocketClose(ConnectionCloseInfo) for custom close handling.

      Parameters:
      reason - The reason the WebSocket was closed.

    • handleSseOpen

      public void handleSseOpen(SseConnection sseConnection)
      Called when an SSE connection is opened for this page.
      Parameters:
      sseConnection - The SSE connection.

    • handleSseClose

      public void handleSseClose()
      Called when the SSE connection for this page is closed.

    • setHead

      public void setHead(Head head)
      Sets the head element for this page.
      Parameters:
      head - The head element containing metadata, scripts, and stylesheets.

    • setBody

      public void setBody(Body body)
      Sets the body element for this page.
      Parameters:
      body - The body element containing the page content.

    • setTitle

      public final void setTitle(String title)
      Sets the page title displayed in the browser tab.
      Parameters:
      title - The page title.

    • setKeywords

      public final void setKeywords(String keywords)
      Sets the meta keywords for search engine optimization.
      Parameters:
      keywords - A comma-separated list of keywords.

    • setDescription

      public final void setDescription(String descr)
      Sets the meta description for search engine optimization.
      Parameters:
      descr - The page description.

    • setRobots

      public final void setRobots(String robots)
      Sets the meta robots directive for search engine crawlers.
      Parameters:
      robots - The robots directive (e.g., "index, follow" or "noindex, nofollow").

    • setOorianScriptPath

      public final void setOorianScriptPath(String path)
      Sets the path to the Oorian JavaScript file for this page, overriding the application-wide default set via
      invalid reference 
      Application#setOorianScript(String)
      .

      The path should be the full path including the filename, relative to the application context root (e.g., "/js/oorian-core-2.0.500.js" or "/oorian.min.js").

      Parameters:
      path - The full path to the Oorian JavaScript file.

    • setTempFileDir

      public final void setTempFileDir(String tempFileDir)
      Sets the directory for temporary file uploads.
      Parameters:
      tempFileDir - The path to the temporary file directory.

    • setCsrfProtectionEnabled

      public final void setCsrfProtectionEnabled(boolean enableCsrfProtection)
      Overrides the application-level CSRF protection setting for this specific page.

      By default, pages inherit the CSRF protection setting from the application (see

      invalid reference 
      Application#setCsrfProtectionEnabled(boolean)
      ). This method allows individual pages to override that setting.

      Use this sparingly - it's generally better to keep CSRF protection enabled application-wide and only disable it for specific pages that require it (such as public API endpoints or webhook receivers).

      Parameters:
      enableCsrfProtection - true to enable CSRF protection for this page, false to disable it.

    • setEnableCsrfProtection

      @Deprecated public final void setEnableCsrfProtection(boolean enableCsrfProtection)
      Deprecated.
      Use setCsrfProtectionEnabled(boolean) instead.
      Parameters:
      enableCsrfProtection - true to enable, false to disable.

    • isCsrfProtectionEnabled

      public final boolean isCsrfProtectionEnabled()
      Checks whether CSRF protection is enabled for this page.

      Returns the page-level override if set, otherwise returns the application-level setting.

      Returns:
      true if CSRF protection is enabled, false otherwise.

    • setReloadOnBack

      public final void setReloadOnBack(boolean reloadOnBack)
      Sets whether the page should reload when navigating back.
      Parameters:
      reloadOnBack - true to reload on back navigation, false otherwise.

    • setCommunicationMode

      public final HtmlPage setCommunicationMode(CommunicationMode communicationMode)
      Sets the asynchronous communication mode for this page.
      Parameters:
      communicationMode - The communication mode to use.
      Returns:
      This HtmlPage instance for method chaining.

    • getCommunicationMode

      public final CommunicationMode getCommunicationMode()
      Gets the asynchronous communication mode for this page.
      Returns:
      The current communication mode.

    • setPollInterval

      public HtmlPage setPollInterval(long pollInterval)
      Sets the polling interval for AJAX_ONLY mode.

      When the communication mode is AJAX_ONLY, this interval determines how often the client will poll the server for pending updates.

      Parameters:
      pollInterval - The polling interval in milliseconds (-1 = app default, 0 = disabled).
      Returns:
      This HtmlPage instance for method chaining.
      See Also:

    • getPollInterval

      public long getPollInterval()
      Gets the polling interval for AJAX_ONLY mode.
      Returns:
      The polling interval in milliseconds.
      See Also:

    • addElement

      public final HtmlPage addElement(Element child)
      Adds a child element to the page.
      Parameters:
      child - The element to add.
      Returns:
      This page for method chaining.

    • removeElement

      public final void removeElement(Element child)
      Removes a child element from this page.
      Parameters:
      child - The element to remove.

    • removeElement

      public final void removeElement(String id)
      Removes a child element from this page by its ID.
      Parameters:
      id - The ID of the element to remove.

    • removeAllElements

      public final void removeAllElements()
      Removes all child elements from this page.

    • addAttribute

      public final void addAttribute(String key, String value)
      Adds an attribute to the HTML element of this page.
      Parameters:
      key - The attribute name.
      value - The attribute value.

    • setLang

      public final HtmlPage setLang(String languageCode)
      Sets the document language for accessibility and SEO.

      The lang attribute is required for WCAG compliance. It helps screen readers use the correct pronunciation rules and enables proper font selection for different scripts.

      Common language codes:

      • "en" - English
      • "en-US" - American English
      • "en-GB" - British English
      • "es" - Spanish
      • "fr" - French
      • "de" - German
      • "ja" - Japanese
      • "zh" - Chinese
      • "ar" - Arabic
      Parameters:
      languageCode - BCP 47 language code (e.g., "en", "en-US", "es", "fr").
      Returns:
      This page for method chaining.

    • setDir

      public final HtmlPage setDir(TextDirection direction)
      Sets the text direction for the document.

      Use this for languages that are written right-to-left, such as Arabic, Hebrew, Persian, and Urdu. This affects the default alignment and flow direction of text throughout the document.

      Parameters:
      direction - LTR for left-to-right, RTL for right-to-left.
      Returns:
      This page for method chaining.

    • setDir

      public final HtmlPage setDir(String direction)
      Sets the text direction for the document using a string value.
      Parameters:
      direction - "ltr" for left-to-right, "rtl" for right-to-left.
      Returns:
      This page for method chaining.

    • getPageId

      public final String getPageId()
      Returns the unique identifier for this page instance.
      Returns:
      The page ID.

    • getPreviousFullUrl

      public final String getPreviousFullUrl()
      Returns the full URL of the previous page in the browser history.
      Returns:
      The previous page URL, or null if not available.

    • getCookies

      public Cookies getCookies()
      Returns the cookies collection for this page's request.
      Returns:
      The cookies collection.

    • getCookie

      public final OorianCookie getCookie(String name)
      Returns a cookie by name.
      Parameters:
      name - The cookie name.
      Returns:
      The cookie, or null if not found.

    • getCookie

      public final OorianCookie getCookie(String name, String defaultValue)
      Returns a cookie by name, or a cookie with the default value if not found.
      Parameters:
      name - The cookie name.
      defaultValue - The default value if the cookie is not found.
      Returns:
      The cookie, or a new cookie with the default value.

    • getTempFileDir

      public String getTempFileDir()
      Returns the temporary file directory for uploads.
      Returns:
      The temporary file directory path.

    • getRequestHost

      public String getRequestHost()
      Returns the request host.
      Returns:
      The request host name.

    • getReferrer

      public String getReferrer()
      Returns the HTTP referrer header.
      Returns:
      The referrer URL.

    • getReferringPage

      public String getReferringPage()
      Returns the referring page path.
      Returns:
      The referring page path.

    • getHash

      public String getHash()
      Returns the current URL hash fragment, without the leading # character.

      The hash is set when the browser notifies the server of a hash change via the hashchange event. Returns null if no hash has been received.

      Returns:
      the hash fragment (e.g., "section-name"), or null if none

    • getLogicalDocumentWidth

      public final int getLogicalDocumentWidth()
      Returns the document width in logical (CSS) pixels.
      Returns:
      The document width in logical pixels.

    • getLogicalDocumentHeight

      public final int getLogicalDocumentHeight()
      Returns the document height in logical (CSS) pixels.
      Returns:
      The document height in logical pixels.

    • getPhysicalDocumentWidth

      public final int getPhysicalDocumentWidth()
      Returns the document width in physical (device) pixels.
      Returns:
      The document width in physical pixels.

    • getPhysicalDocumentHeight

      public final int getPhysicalDocumentHeight()
      Returns the document height in physical (device) pixels.
      Returns:
      The document height in physical pixels.

    • getElementById

      public final Element getElementById(String id)
      Finds and returns an element on this page by its ID.
      Parameters:
      id - The ID of the element to find.
      Returns:
      The element with the specified ID, or null if not found.

    • getElementsByTagName

      public final Elements getElementsByTagName(String tagName, boolean recursive)
      Returns all elements on this page that match the specified HTML tag name.
      Parameters:
      tagName - The HTML tag name to search for (e.g., "div", "span").
      recursive - true to search all descendants, false for direct children only.
      Returns:
      A collection of matching elements.

    • getHead

      public final Head getHead()
      Returns the head element of this page.
      Returns:
      The Head element containing metadata, scripts, and stylesheets.

    • getBody

      public final Body getBody()
      Returns the body element of this page.
      Returns:
      The Body element containing the page content.

    • getSession

      public final OorianSession getSession()
      Returns the current Oorian session.
      Returns:
      The OorianSession for the current request.

    • getInnerHtml

      public String getInnerHtml()
      Returns the inner HTML content of this page as a string.
      Returns:
      The inner HTML of the page.

    • isLoaded

      public final boolean isLoaded()
      Checks if this page has been loaded in the browser.
      Returns:
      true if the page is loaded, false otherwise.

    • isUnloaded

      public boolean isUnloaded()
      Checks if this page has been unloaded from the browser.
      Returns:
      true if the page is unloaded, false otherwise.

    • dispatchEvent

      public void dispatchEvent(ServerEvent event)
      Dispatches a server event to registered listeners.
      Parameters:
      event - The server event to dispatch.

    • dispatchEvent

      public void dispatchEvent(ExtServerEvent event)
      Dispatches an extended server event to registered listeners.
      Parameters:
      event - The extended server event to dispatch.

    • dispatchEvent

      public void dispatchEvent(PageEvent event)
      Dispatches a page event to registered listeners.
      Parameters:
      event - The page event to dispatch.

    • registerListener

      public void registerListener(ServerEventListener listener, Class<? extends ServerEvent>... eventTypes)
      Registers a listener for one or more server event types.
      Parameters:
      listener - The listener to register.
      eventTypes - The event types to listen for.

    • registerListener

      public void registerListener(ExtServerEventListener listener, Class<? extends ExtServerEvent>... eventTypes)
      Registers a listener for one or more extended server event types.
      Parameters:
      listener - The listener to register.
      eventTypes - The event types to listen for.

    • registerListener

      public void registerListener(PageEventListener listener, Class<? extends PageEvent>... eventTypes)
      Registers a listener for one or more page event types.
      Parameters:
      listener - The listener to register.
      eventTypes - The event types to listen for.

    • closeWebSocket

      public final void closeWebSocket()
      Closes the WebSocket connection for this page.

    • loadScript

      public final void loadScript(String filename)
      Loads a JavaScript file on the client.

      The script is cached by the browser. Duplicate load requests for the same file are ignored.

      Parameters:
      filename - The path to the JavaScript file.

    • loadScript

      public final void loadScript(String filename, boolean includeTimestamp)
      Loads a JavaScript file on the client with optional cache-busting.
      Parameters:
      filename - The path to the JavaScript file.
      includeTimestamp - true to append a timestamp for cache-busting.

    • sendCommand

      public final void sendCommand(Command command)
      Sends a command to the client.

      If the page is loaded, the command is added to the thread updates queue. Otherwise, it is added to the initial updates queue.

      Parameters:
      command - The command to send.

    • registerElementAddition

      public final void registerElementAddition(Element element)
      Registers an element addition to be synchronized with the client.
      Parameters:
      element - The element that was added.

    • registerElementSubtraction

      public final void registerElementSubtraction(Element element)
      Registers an element removal to be synchronized with the client.
      Parameters:
      element - The element that was removed.

    • registerElementUpdate

      public final void registerElementUpdate(Element element)
      Registers an element update to be synchronized with the client.
      Parameters:
      element - The element that was updated.

    • registerAttributeUpdate

      public final void registerAttributeUpdate(Element element)
      Registers an attribute update on an element to be synchronized with the client.
      Parameters:
      element - The element whose attributes were updated.

    • executeJs

      public final void executeJs(String script)
      Executes a JavaScript statement on the client.
      Parameters:
      script - The JavaScript code to execute.

    • executeJs

      public final void executeJs(String functionName, Object... parameters)
      Executes a JavaScript function on the client with the specified parameters.
      Parameters:
      functionName - The JavaScript function name.
      parameters - The parameters to pass to the function.

    • blockPageUnload

      public final void blockPageUnload()
      Blocks the page from unloading by showing a confirmation dialog.

    • unblockPageUnload

      public final void unblockPageUnload()
      Unblocks the page from unloading.

    • reloadAfterDelay

      public final void reloadAfterDelay(long msecs)
      Reloads the page after a delay.
      Parameters:
      msecs - The delay in milliseconds before reloading.

    • historyPushState

      public final void historyPushState(String title, String url)
      Pushes a new state onto the browser history stack.
      Parameters:
      title - The title for the new history entry.
      url - The URL for the new history entry.

    • historyReplaceState

      public final void historyReplaceState(String title, String url)
      Replaces the current state in the browser history.
      Parameters:
      title - The title for the history entry.
      url - The URL for the history entry.

    • openInNewWindow

      public final void openInNewWindow(String url)
      Opens a URL in a new browser window.
      Parameters:
      url - The URL to open.

    • openInNewWindow

      public final void openInNewWindow(String url, String target)
      Opens a URL in a new browser window with the specified target.
      Parameters:
      url - The URL to open.
      target - The target window name.

    • openInNewWindow

      public final void openInNewWindow(String url, String name, String specs)
      Opens a URL in a new browser window with the specified name and window features.
      Parameters:
      url - The URL to open.
      name - The window name.
      specs - The window features specification.

    • closeWindow

      public final void closeWindow(String windowName)
      Closes the browser window with the specified name.
      Parameters:
      windowName - The name of the window to close.

    • print

      public final void print()
      Opens the browser's print dialog.

    • print

      public final void print(URL url)
      Prints the content from the specified URL.
      Parameters:
      url - The URL of the content to print.

    • print

      public final void print(HtmlPage page)
      Prints the content of the specified page.
      Parameters:
      page - The page to print.

    • getScreenWidth

      public final int getScreenWidth()
      Returns the screen width in logical (CSS) pixels.
      Returns:
      The screen width in logical pixels.

    • getScreenHeight

      public final int getScreenHeight()
      Returns the screen height in logical (CSS) pixels.
      Returns:
      The screen height in logical pixels.

    • getScreenSize

      public final Size getScreenSize()
      Returns the screen size in logical (CSS) pixels.
      Returns:
      The Size object containing screen width and height.

    • getPhysicalScreenWidth

      public final int getPhysicalScreenWidth()
      Returns the screen width in physical (device) pixels.
      Returns:
      The screen width in physical pixels.

    • getPhysicalScreenHeight

      public final int getPhysicalScreenHeight()
      Returns the screen height in physical (device) pixels.
      Returns:
      The screen height in physical pixels.

    • getWindowWidth

      public final int getWindowWidth()
      Returns the browser window (viewport) width in logical (CSS) pixels.
      Returns:
      The window width in logical pixels.

    • getWindowHeight

      public final int getWindowHeight()
      Returns the browser window (viewport) height in logical (CSS) pixels.
      Returns:
      The window height in logical pixels.

    • getWindowSize

      public final Size getWindowSize()
      Returns the browser window size in logical (CSS) pixels.
      Returns:
      The Size object containing window width and height.

    • getPhysicalWindowWidth

      public final int getPhysicalWindowWidth()
      Returns the browser window width in physical (device) pixels.
      Returns:
      The window width in physical pixels.

    • getPhysicalWindowHeight

      public final int getPhysicalWindowHeight()
      Returns the browser window height in physical (device) pixels.
      Returns:
      The window height in physical pixels.

    • getPixelRatio

      public final float getPixelRatio()
      Returns the device pixel ratio.

      The pixel ratio indicates the relationship between physical pixels and logical (CSS) pixels. Standard displays have a ratio of 1.0, while high-DPI displays like Retina screens have ratios of 2.0 or higher.

      Returns:
      The device pixel ratio.

    • isHighDpi

      public final boolean isHighDpi()
      Checks if the device has a high-DPI (Retina) display.
      Returns:
      true if the pixel ratio is 1.5 or higher, false otherwise.

    • getScreenOrientation

      public final Orientation getScreenOrientation()
      Returns the current screen orientation.
      Returns:
      The screen orientation (PORTRAIT or LANDSCAPE).

    • getWindowOrientation

      public final Orientation getWindowOrientation()
      Returns the current window orientation.
      Returns:
      The window orientation (PORTRAIT or LANDSCAPE).

    • isPortrait

      public final boolean isPortrait()
      Checks if the screen is in portrait orientation.
      Returns:
      true if the screen is taller than it is wide, false otherwise.

    • isLandscape

      public final boolean isLandscape()
      Checks if the screen is in landscape orientation.
      Returns:
      true if the screen is wider than it is tall, false otherwise.

    • isMobile

      public boolean isMobile()
      Checks if the window width indicates a mobile device.

      Subclasses may override this method to use custom breakpoints.

      Returns:
      true if the window width is less than or equal to the mobile breakpoint.

    • isTablet

      public boolean isTablet()
      Checks if the window width indicates a tablet device.

      Subclasses may override this method to use custom breakpoints.

      Returns:
      true if the window width is between mobile and tablet breakpoints.

    • isDesktop

      public boolean isDesktop()
      Checks if the window width indicates a desktop device.

      Subclasses may override this method to use custom breakpoints.

      Returns:
      true if the window width is greater than the tablet breakpoint.

    • getUserAgent

      public final String getUserAgent()
      Returns the client's user agent string.
      Returns:
      The user agent string from the browser.

    • userAgentContains

      public final boolean userAgentContains(String keyword)
      Checks if the user agent contains a specified keyword.
      Parameters:
      keyword - The keyword to search for (case-insensitive).
      Returns:
      true if the user agent contains the keyword, false otherwise.

    • getUtcOffset

      public final int getUtcOffset()
      Returns the client's UTC timezone offset in minutes.
      Returns:
      The UTC offset in minutes (negative for west of UTC, positive for east).

    • getIpAddress

      public final String getIpAddress()
      Returns the client's IP address.
      Returns:
      The client's IP address as a string.

    • setClientTimeout

      public final void setClientTimeout(String script, long delayMs)
      Executes JavaScript code after a delay on the client.

      This is equivalent to JavaScript's setTimeout().

      Parameters:
      script - The JavaScript code to execute.
      delayMs - The delay in milliseconds before executing.

    • setClientInterval

      public final void setClientInterval(String script, long intervalMs)
      Executes JavaScript code repeatedly at a fixed interval on the client.

      This is equivalent to JavaScript's setInterval().

      Parameters:
      script - The JavaScript code to execute.
      intervalMs - The interval in milliseconds between executions.

    • getCurrentPosition

      public final void getCurrentPosition()
      Requests the current geographic position.

      This is a one-time request. When the position is obtained, a GeolocationEvent is dispatched to the page body. If an error occurs, a GeolocationErrorEvent is dispatched instead.

      To receive the events, register listeners on the body element:

      
 getBody().registerListener(this, GeolocationEvent.class);
 getBody().registerListener(this, GeolocationErrorEvent.class);

    • getCurrentPosition

      public final void getCurrentPosition(GeolocationOptions options)
      Requests the current geographic position with options.

      This is a one-time request. When the position is obtained, a GeolocationEvent is dispatched to the page body. If an error occurs, a GeolocationErrorEvent is dispatched instead.

      Parameters:
      options - Configuration options for the position request (accuracy, timeout, etc.).

    • watchPosition

      public final String watchPosition()
      Starts watching the geographic position.

      This sets up continuous position tracking. A GeolocationEvent is dispatched to the page body each time the position changes. The returned watch ID can be used to stop tracking via clearWatch(String).

      To receive the events, register listeners on the body element:

      
 getBody().registerListener(this, GeolocationEvent.class);
 getBody().registerListener(this, GeolocationErrorEvent.class);
      Returns:
      A watch ID that can be used to stop tracking.

    • watchPosition

      public final String watchPosition(GeolocationOptions options)
      Starts watching the geographic position with options.

      This sets up continuous position tracking. A GeolocationEvent is dispatched to the page body each time the position changes. The returned watch ID can be used to stop tracking via clearWatch(String).

      Parameters:
      options - Configuration options for position tracking (accuracy, timeout, etc.).
      Returns:
      A watch ID that can be used to stop tracking.

    • clearWatch

      public final void clearWatch(String watchId)
      Stops watching the geographic position.
      Parameters:
      watchId - The watch ID returned from watchPosition().

    • recreate

      public final void recreate()
      Recreates the page body by removing all elements and calling createBody(Body) again.

    • refresh

      public final void refresh()
      Refreshes the page and all its child elements.

    • refresh

      public final void refresh(Element refresher)
      Refreshes all child elements except the element that initiated the refresh.
      Parameters:
      refresher - The element that initiated the refresh, to be excluded.

    • reload

      public final void reload()
      Reloads the current page.

    • isResponseWritten

      public final boolean isResponseWritten()
      Returns whether the page response has been written to the client.
      Returns:
      true if the page has been written, false otherwise.

    • loadImages

      public final void loadImages(List<String> imageUrls)
      Preloads a list of images on the client for improved performance.
      Parameters:
      imageUrls - The list of image URLs to preload.

    • loadImage

      public final void loadImage(String imageUrl)
      Preloads a single image on the client for improved performance.
      Parameters:
      imageUrl - The URL of the image to preload.

    • createAppUrl

      public final String createAppUrl(String url)
      Creates an application-relative URL.

      Prepends the application context path to the given URL.

      Parameters:
      url - The relative URL.
      Returns:
      The full application URL.

    • createFullUrl

      public final String createFullUrl(String url) throws MalformedURLException
      Creates a fully-qualified URL from a relative URL.
      Parameters:
      url - The relative or absolute URL.
      Returns:
      The fully-qualified URL.
      Throws:
      MalformedURLException - If the URL is malformed.

    • makeSameSize

      public final void makeSameSize(Collection<Element> elements, Element match)
      Makes all specified elements the same size as the match element on page load.
      Parameters:
      elements - The elements to resize.
      match - The element whose size will be matched.

    • makeSameSizeMax

      public final void makeSameSizeMax(Collection<Element> elements)
      Makes all specified elements the same size, matching the largest element on page load.
      Parameters:
      elements - The elements to resize to match the largest.

    • makeSameSizeMin

      public final void makeSameSizeMin(Collection<Element> elements)
      Makes all specified elements the same size, matching the smallest element on page load.
      Parameters:
      elements - The elements to resize to match the smallest.

    • makeSameHeight

      public final void makeSameHeight(Collection<Element> elements, Element match)
      Makes all specified elements the same height as the match element on page load.
      Parameters:
      elements - The elements to resize.
      match - The element whose height will be matched.

    • makeSameHeight

      public final void makeSameHeight(Element element, Element match)
      Makes a single element the same height as the match element on page load.
      Parameters:
      element - The element to resize.
      match - The element whose height will be matched.

    • makeSameHeightMax

      public final void makeSameHeightMax(Collection<Element> elements)
      Makes all specified elements the same height, matching the tallest element on page load.
      Parameters:
      elements - The elements to resize to match the tallest.

    • makeSameHeightMin

      public final void makeSameHeightMin(Collection<Element> elements)
      Makes all specified elements the same height, matching the shortest element on page load.
      Parameters:
      elements - The elements to resize to match the shortest.

    • makeSameWidth

      public final void makeSameWidth(Collection<Element> elements, Element match)
      Makes all specified elements the same width as the match element on page load.
      Parameters:
      elements - The elements to resize.
      match - The element whose width will be matched.

    • makeSameWidthMax

      public final void makeSameWidthMax(Collection<Element> elements)
      Makes all specified elements the same width, matching the widest element on page load.
      Parameters:
      elements - The elements to resize to match the widest.

    • makeSameWidthMin

      public final void makeSameWidthMin(Collection<Element> elements)
      Makes all specified elements the same width, matching the narrowest element on page load.
      Parameters:
      elements - The elements to resize to match the narrowest.

    • initializeFile

      protected final boolean initializeFile()
      Initializes this page when first requested by the client.

      Sets up the page ID, cookies, session tracking, and delegates to initializePage() for custom initialization logic.

      Overrides:
      initializeFile in class HttpFile
      Returns:
      true if initialization succeeded, false to abort page processing.

    • initializePage

      protected boolean initializePage()
      Initializes this page for the current request.

      Subclasses can override this method to perform custom initialization logic such as access control checks, data loading, or session setup. Return false to abort page processing.

      Returns:
      true if initialization was successful, false to abort

    • createFile

      protected final void createFile()
      Creates the HTML structure of this page including head, body, scripts, and styles.

      Delegates to createHead(Head) and createBody(Body) for page-specific content. After creation, initializes all child elements and runs post-creation hooks.

      Specified by:
      createFile in class HttpFile

    • createHead

      protected abstract void createHead(Head head)
      Creates the head section of this page.

      Subclasses must implement this method to add stylesheets, scripts, meta tags, and other head content.

      Parameters:
      head - The Head element to populate.

    • createBody

      protected abstract void createBody(Body body)
      Creates the body section of this page.

      Subclasses must implement this method to build the page layout and content.

      Parameters:
      body - The Body element to populate.

    • toString

      protected final void toString(StringBuilder sb)
      Generates the complete HTML document string including the DOCTYPE declaration.
      Specified by:
      toString in class HttpFile
      Parameters:
      sb - The StringBuilder to append the HTML output to.

    • sendUpdate

      public void sendUpdate()
      Sends pending updates to the client using the configured communication mode.

      Routes updates to the appropriate transport based on the page's communication mode: WebSocket, SSE, or queues for AJAX polling.

      For AJAX modes, this method commits the current thread's updates to the shared queue, making them available for the next poll or SSE push. This ensures that updates from worker threads are not sent until the thread explicitly signals completion.

    • sendAjaxResponse

      public void sendAjaxResponse(OorianHttpResponse servletResponse)

    • sendWebSocketMessage

      public void sendWebSocketMessage()

    • sendSseMessage

      public void sendSseMessage()
      Sends pending updates to the client via the SSE connection.

    • onWebsocketOpen

      protected void onWebsocketOpen()
      Called when a WebSocket connection is opened for this page.

      Subclasses can override this method to perform actions when the WebSocket is established.

    • onWebsocketMessage

      protected void onWebsocketMessage(String msg)
      Called when a WebSocket message is received from the client.

      Subclasses can override this method to handle raw WebSocket messages.

      Parameters:
      msg - The raw message string received from the client.

    • onWebsocketError

      protected void onWebsocketError(Throwable error)
      Called when a WebSocket error occurs for this page.

      Subclasses can override this method to handle WebSocket errors.

      Parameters:
      error - The error that occurred on the WebSocket connection.

    • onWebsocketClose

      protected void onWebsocketClose(ConnectionCloseInfo reason)
      Called when the WebSocket connection for this page is closed.

      Subclasses can override this method to handle WebSocket disconnections.

      Parameters:
      reason - The reason the WebSocket was closed.

    • onSseOpen

      protected void onSseOpen()
      Called when an SSE connection is opened for this page.

      Subclasses can override this method to perform actions when the SSE connection is established.

    • onSseClose

      protected void onSseClose()
      Called when the SSE connection for this page is closed.

      Subclasses can override this method to perform cleanup or other actions when the SSE connection is closed.

    • onSessionExpired

      protected void onSessionExpired()
      Called when the user's session has expired during a WebSocket message.

      Subclasses can override this method to redirect the user or display a message.

    • onRequest

      protected void onRequest(OorianHttpRequest request, OorianHttpResponse response)
      Subclasses should override this method if they need to do any pre-processing before a request is processed by the framework and passed on to application level classes.
      Parameters:
      request -
      response -

    • onLoaded

      protected void onLoaded()
      Called when the page has finished loading in the browser.

      Subclasses can override this method to perform actions after the page is fully loaded.

    • onUnloaded

      protected void onUnloaded()
      Called when the page is unloaded from the browser.

      Subclasses can override this method to perform cleanup when the user leaves the page.

    • onRefresh

      protected void onRefresh()
      Called when the page is refreshed via refresh().

      Subclasses can override this method to perform actions before child elements are refreshed.

    • onScreenResize

      protected void onScreenResize()
      Called when the client's screen size changes.

      Subclasses can override this method to respond to screen orientation or resolution changes.

    • onWindowResize

      protected void onWindowResize()
      Called when the browser window (viewport) is resized.

      Subclasses can override this method to adjust layout in response to window size changes.

    • onDocumentResize

      protected void onDocumentResize()
      Called when the HTML document dimensions change.

      Subclasses can override this method to respond to document size changes caused by content additions or removals.

    • onCallback

      protected void onCallback(String callbackId)
      Called when a client-side callback is triggered.

      Subclasses can override this method to handle custom client-to-server callbacks.

      Parameters:
      callbackId - The identifier of the callback being invoked.

    • onJsReturn

      protected void onJsReturn(String elementId, String callbackId, String retval)
      Called when a JavaScript function returns a value to the server for a specific element.

      Subclasses can override this method to process JavaScript return values.

      Parameters:
      elementId - The ID of the element associated with the JavaScript call.
      callbackId - The identifier of the callback.
      retval - The return value from the JavaScript function.

    • onJsReturn

      protected void onJsReturn(String callbackId, String retval)
      Called when a JavaScript function returns a value to the server.

      Subclasses can override this method to process JavaScript return values.

      Parameters:
      callbackId - The identifier of the callback.
      retval - The return value from the JavaScript function.

    • onUserEvent

      protected void onUserEvent(Parameters params)
      Called when a custom user event is received from the client.

      Subclasses can override this method to handle application-specific client events.

      Parameters:
      params - The parameters sent with the user event.

    • onClientDataEvent

      protected void onClientDataEvent(Parameters params)
      Called when a client data event is received from the browser.

      Subclasses can override this method to handle data sent from client-side scripts.

      Parameters:
      params - The parameters containing the client data.

    • onResponseComplete

      protected void onResponseComplete()
      Called after a response has been successfully sent to the client.

      Subclasses can override this method to perform post-response actions such as logging or cleanup.

    • onException

      protected boolean onException(Exception exception)
      Called when an exception occurs during page creation or processing.

      Subclasses can override this method to handle exceptions. Return true to re-throw the exception, or false to suppress it.

      Parameters:
      exception - The exception that occurred.
      Returns:
      true to re-throw the exception, false to suppress it.

    • getPageState

      public PageState getPageState()
      Returns the current lifecycle state of this page.
      Returns:
      The current PageState.

    • getDisconnectedTime

      public long getDisconnectedTime()
      Returns the time when the page became disconnected.
      Returns:
      The disconnection timestamp in milliseconds, or 0 if the page is not disconnected.

    • getLastActivityTime

      public long getLastActivityTime()
      Returns the time of the last activity on this page.
      Returns:
      The last activity timestamp in milliseconds.

    • isDisconnectedTimeout

      public boolean isDisconnectedTimeout(long timeoutMillis)
      Checks if the page has been disconnected longer than the specified timeout.
      Parameters:
      timeoutMillis - The timeout duration in milliseconds.
      Returns:
      true if the page is disconnected and the timeout has expired, false otherwise.

    • addCookie

      public final OorianCookie addCookie(String name, String value)

    • addCookie

      public final OorianCookie addCookie(OorianCookie cookie)

    • addAttributeUpdate

      public void addAttributeUpdate(Element element)

    • addElementUpdate

      public void addElementUpdate(Element element)

    • addElementAddition

      public void addElementAddition(Element element)

    • addElementSubtraction

      public void addElementSubtraction(Element element)

    • addCommand

      public void addCommand(Command command)

    • getPage

      public static HtmlPage getPage()