Class VirtualHostConfig

java.lang.Object
com.ns.tcpframework.VirtualHostConfig
public class VirtualHostConfig extends Object
Configuration for a single virtual host in a name-based virtual hosting setup.

A virtual host represents a distinct website or domain served by the HTTP server. This class encapsulates all configuration necessary to serve content for a specific hostname, including the document root for static files and the routing configuration for dynamic request handling.

Virtual hosting enables a single HTTP server to serve multiple domain names, each with its own configuration. The server selects the appropriate virtual host based on the HTTP Host header in incoming requests. This is commonly used to host multiple websites on a single server instance.

Key components:

  • Host: The hostname this configuration applies to (e.g., "example.com", "www.example.com")
  • Document Root: The file system path where static content is located
  • Router: The routing configuration that maps URL paths to request handlers

The router is automatically initialized with the document root, enabling seamless integration of static file serving with dynamic route handling. Routes can be registered on the router after construction to add API endpoints and other dynamic functionality.

Usage example: 

// Create virtual host for example.com
VirtualHostConfig vhost = new VirtualHostConfig("example.com", "/var/www/example");

// Register dynamic routes
vhost.getRouter().register("/api/users", new UserHandler());
vhost.getRouter().register("/api/products/*", new ProductHandler());

// Register SSE endpoint
vhost.getRouter().register("/events", new SSEHandler());

// Static files are automatically served from /var/www/example

Thread-safety: This class is immutable after construction (all fields are final). The router can be modified after construction by registering routes, so care should be taken to complete route registration before concurrent request handling begins.

See Also:

  • Constructor Details

    • VirtualHostConfig

      public VirtualHostConfig(String host, String documentRoot)
      Constructs a VirtualHostConfig with the specified hostname and document root.

      This constructor initializes the virtual host with its essential configuration and creates a router configured to serve static files from the document root. Additional dynamic routes can be registered on the router after construction.

      The router is created with the document root as its static file handler base path, enabling automatic serving of static content for requests that don't match any registered dynamic route.

      Configuration steps performed:

      1. Store the hostname for virtual host matching
      2. Store the document root path for static file serving
      3. Create a RouterConfig initialized with the document root
      Parameters:
      host - The hostname this virtual host will serve (e.g., "example.com", "www.example.com"). Must not be null. Should not include port numbers.
      documentRoot - The file system path to the document root directory for static content. Must not be null. Should be a valid, readable directory path.

  • Method Details

    • getHost

      public String getHost()
      Gets the hostname for this virtual host.

      This is the hostname value used for virtual host matching against incoming HTTP Host headers. It represents the domain or hostname this virtual host serves.

      Returns:
      The hostname (e.g., "example.com", "www.example.com"). Never null.

    • getDocumentRoot

      public String getDocumentRoot()
      Gets the document root path for this virtual host.

      This is the file system path from which static content is served. The path is used by the default static file handler to locate and serve files when no dynamic route matches the request.

      Returns:
      The document root directory path. Never null.

    • getRouter

      public RouterConfig getRouter()
      Gets the router configuration for this virtual host.

      The router manages all request routing for this virtual host, including both dynamic routes that have been registered and the default static file handler. Use this router to register additional routes after virtual host construction.

      Common usage: 

      RouterConfig router = vhost.getRouter();
router.register("/api/users", new UserHandler());
router.register("/api/products/*", new ProductHandler());
      Returns:
      The RouterConfig instance for this virtual host. Never null.

    • getSSEHandler

      public SSEHandler getSSEHandler()
      Gets the first registered SSE handler from this virtual host's router.

      This is a convenience method that delegates to RouterConfig.getSSEHandler() to find an SSE handler registered on this virtual host's router. SSE handlers provide Server-Sent Events functionality for real-time server-to-client communication.

      This method is useful for:

      • Initializing server-wide logging with SSE broadcast support
      • Broadcasting events to all clients connected to this virtual host
      • Checking if SSE functionality is available for this virtual host

      If multiple SSE handlers are registered, only the first one found will be returned. Typically, each virtual host should have at most one SSE handler.

      Returns:
      The first SSEHandler registered on this virtual host's router, or null if no SSE handler is registered.
      See Also: