Package com.oorian

Class HttpFile

java.lang.Object
com.oorian.HttpFile
Direct Known Subclasses:
CssFile, ErrorPage, HtmlPage, TextPage
public abstract class HttpFile extends Object
Abstract base class for HTTP-based content generation in the Oorian framework.

HttpFile provides the foundation for all HTTP request/response handling in Oorian applications. It serves as the parent class for HTML pages, API endpoints, and other web content generators. This class manages the HTTP request lifecycle, parameter handling, URL routing, and content output.

Key Features:

  • HTTP request/response lifecycle management
  • Automatic parameter extraction and type conversion
  • URL parameter parsing and handling
  • Session management integration
  • Content generation through abstract methods
  • Page annotation support for routing

Usage Pattern:


 @Page("/api/users/{id}")
 public class UserApiPage extends HttpFile {
     @Override
     protected boolean initializeFile() {
         setContentType("application/json");
         return true;
     }

     @Override
     protected void createFile() {
         // Generate content
         Integer userId = getParameterAsInt("id");
         // ... process request
     }

     @Override
     protected void toString(StringBuilder sb) {
         sb.append(generateContent());
     }
 }

Integration:

  • Works with OorianSession for session management
  • Integrates with Parameters for request data handling
  • Supports UrlParameters for RESTful URL patterns
  • Coordinates with page routing through Page annotations
Since:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Details

  • Method Details

    • write

      public void write(OorianHttpRequest request, OorianHttpResponse response) throws HttpFileException
      Writes the content of this HttpFile directly to the response.

      This method initializes the HttpFile with the request/response context, generates the content, and writes it directly to the response's PrintWriter. It checks if the response has already been committed before attempting to write.

      Parameters:
      request - the web request
      response - the web response
      Throws:
      HttpFileException - if an error occurs during content generation or writing

    • create

      public final void create()
      Manually triggers the content creation process.

      This method calls the abstract createFile() method to generate the content without writing it to any output stream. Useful for pre-generating content or testing purposes.

    • setUrlParameters

      public void setUrlParameters(UrlParameters urlParams)
      Sets the URL parameters for this HttpFile.

      URL parameters are typically extracted from RESTful URL patterns (e.g., /users/{id}/posts/{postId}) and provide access to dynamic path segments.

      Parameters:
      urlParams - the URL parameters to set

    • getHttpRequest

      public final OorianHttpRequest getHttpRequest()
      Returns the web request for this file.
      Returns:
      the web request, or null if not yet initialized

    • getWebResponse

      public final OorianHttpResponse getWebResponse()
      Returns the web response for this file.
      Returns:
      the web response, or null if not yet initialized

    • getSessionId

      public String getSessionId()
      Returns the session identifier for the current request.
      Returns:
      the session ID, or null if no session exists or not yet initialized

    • getHost

      public String getHost()
      Returns the host header from the HTTP request.
      Returns:
      the host header value, or null if not yet initialized

    • getFullUrl

      public final String getFullUrl()
      Returns the complete URL including query string parameters.
      Returns:
      the full URL with query string, or null if not yet initialized

    • getDocumentUrl

      public final String getDocumentUrl()
      Returns the document URL without query parameters.

      This URL includes the protocol, host, and path but excludes the query string parameters.

      Returns:
      the document URL without query parameters, or null if not yet initialized

    • getServletPath

      public String getServletPath()
      Returns the servlet path portion of the request URL.

      The servlet path is the portion of the request URL that corresponds to the path mapping of the servlet that is handling the request.

      Returns:
      the servlet path, or null if not yet initialized

    • getOriginalParameters

      public final RequestParameters getOriginalParameters()
      Returns the original request parameters captured at initialization.

      These parameters represent the state of request parameters when the HttpFile was first initialized and remain unchanged throughout the request lifecycle.

      Returns:
      the original request parameters, or null if not yet initialized

    • getParameters

      public final RequestParameters getParameters()
      Returns the current request parameters.

      Creates a new RequestParameters object from the current request state. This may differ from getOriginalParameters() if the request has been modified during processing.

      Returns:
      a new RequestParameters object with current request data

    • hasParameter

      public final boolean hasParameter(String name)
      Checks if a request parameter with the specified name exists.
      Parameters:
      name - the parameter name to check
      Returns:
      true if the parameter exists, false otherwise

    • getParameter

      public final String getParameter(String name)
      Returns the value of the specified request parameter.

      If the parameter has multiple values, this method returns the first value. Use getParameterValues(String) to get all values for multi-valued parameters.

      Parameters:
      name - the parameter name
      Returns:
      the parameter value, or null if the parameter does not exist

    • getParameterValues

      public final String[] getParameterValues(String name)
      Returns all values for the specified request parameter.

      Use this method when a parameter may have multiple values, such as checkbox groups or multi-select lists.

      Parameters:
      name - the parameter name
      Returns:
      an array of parameter values, or null if the parameter does not exist

    • getParameterAsInt

      public final Integer getParameterAsInt(String name)
      Returns the value of the specified request parameter as an Integer.

      Attempts to parse the parameter value as an integer. If parsing fails or the parameter does not exist, returns null.

      Parameters:
      name - the parameter name
      Returns:
      the parameter value as an Integer, or null if parsing fails or parameter doesn't exist

    • getParametersAsInt

      public final List<Integer> getParametersAsInt(String name)
      Returns all values for the specified request parameter as a list of Integers.

      Attempts to parse each parameter value as an integer. Values that cannot be parsed are silently skipped and not included in the returned list.

      Parameters:
      name - the parameter name
      Returns:
      a list of Integer values; empty list if no valid integers found

    • getParameterAsShort

      public final Short getParameterAsShort(String name)
      Returns the value of the specified request parameter as a Short.

      Attempts to parse the parameter value as a short. If parsing fails or the parameter does not exist, returns null.

      Parameters:
      name - the parameter name
      Returns:
      the parameter value as a Short, or null if parsing fails or parameter doesn't exist

    • getParametersAsShort

      public final List<Short> getParametersAsShort(String name)
      Returns all values for the specified request parameter as a list of Shorts.

      Attempts to parse each parameter value as a short. Values that cannot be parsed are silently skipped and not included in the returned list.

      Parameters:
      name - the parameter name
      Returns:
      a list of Short values; empty list if no valid shorts found

    • getParameterAsLong

      public final Long getParameterAsLong(String name)
      Returns the value of the specified request parameter as a Long.

      Attempts to parse the parameter value as a long. If parsing fails or the parameter does not exist, returns null.

      Parameters:
      name - the parameter name
      Returns:
      the parameter value as a Long, or null if parsing fails or parameter doesn't exist

    • getParametersAsLong

      public final List<Long> getParametersAsLong(String name)
      Returns all values for the specified request parameter as a list of Longs.

      Attempts to parse each parameter value as a long. Values that cannot be parsed are silently skipped and not included in the returned list.

      Parameters:
      name - the parameter name
      Returns:
      a list of Long values; empty list if no valid longs found

    • getParameterAsFloat

      public final Float getParameterAsFloat(String name)
      Returns the value of the specified request parameter as a Float.

      Attempts to parse the parameter value as a float. If parsing fails or the parameter does not exist, returns null.

      Parameters:
      name - the parameter name
      Returns:
      the parameter value as a Float, or null if parsing fails or parameter doesn't exist

    • getParametersAFloat

      public final List<Float> getParametersAFloat(String name)
      Returns all values for the specified request parameter as a list of Floats.

      Attempts to parse each parameter value as a float. Values that cannot be parsed are silently skipped and not included in the returned list.

      Parameters:
      name - the parameter name
      Returns:
      a list of Float values; empty list if no valid floats found

    • hasUrlParams

      public boolean hasUrlParams()
      Checks if this HttpFile has URL parameters from RESTful routing.

      URL parameters are extracted from path patterns like /users/{id}/posts/{postId} and provide access to dynamic segments of the URL path.

      Returns:
      true if URL parameters exist and are not empty, false otherwise

    • getUrlParameters

      public UrlParameters getUrlParameters()
      Returns the URL parameters extracted from RESTful routing patterns.

      URL parameters provide access to dynamic path segments defined in page routing annotations (e.g., @Page("/users/{id}")).

      Returns:
      the URL parameters, or null if none are set

    • isWritten

      protected final boolean isWritten()
      Checks if the content has been written to the response.
      Returns:
      true if content has been written, false otherwise

    • setCacheControl

      protected void setCacheControl(CacheControl cacheControl)
      Sets the CacheControl policy for this file.

      The policy is automatically applied as a Cache-Control response header after initializeFile() returns. It can be called from subclass constructors or from initializeFile().

      Parameters:
      cacheControl - the cache control policy to apply to responses

    • getCacheControl

      public CacheControl getCacheControl()
      Returns the custom CacheControl policy set for this file, if any.
      Returns:
      the cache control policy, or null if none has been set

    • setContentType

      protected void setContentType(String contentType)
      Sets the content type for the HTTP response.

      This method collects the content type to be applied to the response after initializeFile() returns. It can be called from subclass constructors or from initializeFile().

      Parameters:
      contentType - the MIME content type (e.g., "text/html; charset=UTF-8")

    • setCharacterEncoding

      protected void setCharacterEncoding(String encoding)
      Sets the character encoding for the HTTP response.

      This method collects the character encoding to be applied to the response after initializeFile() returns. It can be called from subclass constructors or from initializeFile().

      Parameters:
      encoding - the character encoding name (e.g., "UTF-8")

    • setResponseHeader

      protected void setResponseHeader(String name, String value)
      Sets a custom header on the HTTP response, replacing any existing header with the same name.

      This method collects the header to be applied to the response after initializeFile() returns. It can be called from subclass constructors or from initializeFile().

      Parameters:
      name - the header name
      value - the header value

    • addResponseHeader

      protected void addResponseHeader(String name, String value)
      Adds a custom header to the HTTP response without replacing existing headers of the same name.

      Unlike setResponseHeader(String, String), this method appends an additional value for the specified header name rather than replacing it. Use this when multiple values are needed for the same header (e.g., multiple Cache-Control directives).

      Parameters:
      name - the header name
      value - the header value to add

    • toString

      public final String toString(OorianHttpRequest request, OorianHttpResponse response)
      Generates the string representation of this HttpFile with the given request/response context.

      This method initializes the HttpFile if the response hasn't been committed, then returns the generated content as a string.

      Parameters:
      request - the web request
      response - the web response
      Returns:
      the generated content as a string, or empty string if response is committed

    • toString

      public final String toString()
      Returns the string representation of this HttpFile's content.

      This method creates a StringBuilder and calls the abstract toString(StringBuilder) method to generate the content.

      Overrides:
      toString in class Object
      Returns:
      the generated content as a string

    • getPath

      public static String getPath(Class<? extends HttpFile> pageClass)
      Extracts the path from a page class's @Page annotation.

      This method examines the @Page annotation on the given class and returns the first available path from the annotation's value, path, or paths attributes.

      Parameters:
      pageClass - the HttpFile subclass to examine
      Returns:
      the path defined in the annotation, or null if no path is found

    • getUrl

      public static String getUrl(Class<? extends HttpFile> pageClass, Object... urlParams)
      Generates a URL for the specified page class with the given URL parameters.

      This method takes the path from the page class's @Page annotation and substitutes URL parameter placeholders (e.g., {id}) with the provided values. Parameters are substituted in the order they appear in the path.

      Example:

      
 @Page("/users/{id}/posts/{postId}")
 public class UserPostPage extends HttpFile { ... }

 String url = HttpFile.getUrl(UserPostPage.class, 123, 456);
 // Returns: "/users/123/posts/456"
      Parameters:
      pageClass - the HttpFile subclass to generate URL for
      urlParams - the parameters to substitute in the URL path
      Returns:
      the generated URL with parameters substituted

    • initializeFile

      protected boolean initializeFile()
      Initializes this HttpFile for the current request.

      Subclasses may override this method to perform custom initialization logic. It is called during the request processing lifecycle before content generation begins.

      Subclasses should use the convenience methods setContentType(String), setCharacterEncoding(String), and setResponseHeader(String, String) to configure the HTTP response. The collected headers are applied automatically after this method returns.

      Returns:
      true if initialization was successful, false to abort processing

    • createFile

      protected abstract void createFile()
      Generates the content for this HttpFile.

      This abstract method must be implemented by subclasses to create the actual content. It is called after successful initialization and before the content is rendered to a string.

    • onCreated

      protected void onCreated()
      Callback method invoked after successful content creation.

      This method is called after createFile() completes successfully. Subclasses can override this method to perform any post-creation tasks.

    • onWriteComplete

      protected void onWriteComplete()
      Callback method invoked after content has been written to the output.

      This method is called after the content has been successfully written to the HTTP response or JSP writer. Subclasses can override this method to perform cleanup or logging tasks.

    • toString

      protected abstract void toString(StringBuilder sb)
      Renders the content of this HttpFile to the provided StringBuilder.

      This abstract method must be implemented by subclasses to append their generated content to the StringBuilder. This method is the final step in the content generation process.

      Parameters:
      sb - the StringBuilder to append content to