Using the Web Request Broker

Oracle's web architecture is composed of several components that work together to provide a complete application environment. Not all components apply to every deployment — the specific components present depend on the Oracle version, deployment model, and application requirements. Understanding the original Web Request Broker architecture and its evolution into Oracle REST Data Services (ORDS) is essential for tuning Oracle web-facing workloads in any era.

The classic Oracle web architecture (Oracle 8i and 9i era) was built from the following components, each handling a distinct layer of the request-to-database pipeline:

• Web Listener: received incoming HTTP requests from browsers and routed them to the appropriate handler.
• Common Gateway Interface (CGI): executed programs in real time to generate dynamic output for each HTTP request.
• Web Request Broker (WRB): routed requests from the web listener to the appropriate cartridge or handler, maintaining persistent cartridge processes to avoid the per-request overhead of CGI.
• PL/SQL Agent: executed PL/SQL stored procedures in response to HTTP requests, returning HTML output generated by database code.
• Oracle WebToolkit: a set of PL/SQL packages used by the PL/SQL Agent to generate HTML output directly from stored procedures.
• Oracle Java Cartridges: Java-based request handlers running within the WRB process pool.
• Oracle LiveHTML Cartridges: server-side HTML processing cartridges for embedding dynamic database content in static HTML templates.

In Oracle 23ai, all of these components have been consolidated into a simpler, more scalable stack:

• HTTPS Listener / Web Server: Standalone ORDS/Jetty, Apache Tomcat, or Oracle WebLogic — the servlet container that receives incoming HTTP requests.
• Oracle REST Data Services (ORDS): the unified mid-tier gateway that replaces CGI, WRB, PL/SQL Agent, and all cartridges in a single Java web application.
• Oracle Database 23ai: executes SQL, PL/SQL, APEX Engine processing, and JSON/Duality View operations.

The Common Gateway Interface was the first major gateway between the web and Oracle database systems. A CGI program is executed in real time to produce dynamic documents that respond to user requests. The mechanism is straightforward: an HTTP request arrives at the web listener, the listener spawns a new OS process to execute the CGI program, the program queries the database and generates HTML output, and the process terminates when the response is complete.

This per-request process model was simple to implement but not scalable under load. Spawning a new OS process for every incoming HTTP request consumes significant CPU and memory. On a server handling hundreds of concurrent web requests, the process creation overhead becomes the dominant performance bottleneck — not the database queries themselves. CGI remained the primary gateway mechanism through the late 1990s and early 2000s, but its limitations drove Oracle to develop the Web Request Broker architecture as a more scalable alternative.

The Oracle Web Request Broker was introduced to address CGI's fundamental scalability problem. Rather than spawning a new process for each request, the WRB maintained a pool of persistent cartridge processes that handled requests as they arrived. The three core WRB components were:

• Dispatcher: received requests from the web listener and routed them to the appropriate cartridge process from the pool. The dispatcher was the traffic coordinator of the WRB architecture.
• Cartridge instances: persistent processes — PL/SQL Agent, Java Cartridge, LiveHTML Cartridge — that remained alive between requests and handled specific content types. A cartridge instance serviced a request, returned the result, and then waited for the next request rather than terminating.
• Shared memory broker: managed cartridge lifecycle, monitored cartridge health, and handled request queuing when all cartridge instances were busy.

The cartridge pool model was a significant improvement over CGI for sustained concurrent load. Process creation overhead was eliminated — the cartridge processes were already running when requests arrived. The WRB's architectural descendant in Oracle 23ai is the ORDS JDBC connection pool, which solves the same problem at the database connection layer rather than the OS process layer.

Oracle REST Data Services is the direct replacement for the entire legacy WRB stack. Every legacy component maps to a modern ORDS equivalent:

ORDS runs as a Java web application inside a servlet container. It accepts HTTP/HTTPS requests from browsers, mobile clients, and REST consumers; routes requests to the appropriate handler (REST API, APEX, PL/SQL Gateway, or Database Actions); manages a pool of JDBC connections to Oracle Database 23ai; and bridges stateless HTTP requests to stateful Oracle database sessions. Responses are returned as HTML, JSON, APEX pages, or binary data depending on the request type and Accept header.

The ORDS JDBC connection pool is the most significant performance advantage over the legacy CGI model. A single ORDS instance handles hundreds of concurrent HTTP requests using a pool of database connections that is an order of magnitude smaller than the number of active HTTP connections. This is possible because database work — SQL execution, result set fetch — occupies only a small fraction of the total HTTP request lifecycle. The remainder of the request time is spent on network I/O and client-side rendering, during which the JDBC connection can be returned to the pool and reused by another request.

As shown in Panel 3 of the diagram above, four distinct input types route through ORDS to Oracle 23ai:

• HTML Form submission: a user submits form data via POST. ORDS routes the request to a PL/SQL Gateway handler or APEX process, which executes the database operation and returns an HTML response.
• Application Link: a user clicks a link or button that triggers an HTTPS GET request. ORDS routes to the appropriate REST handler or APEX page process.
• REST API Call: an application or microservice calls a REST endpoint using GET, POST, PUT, or DELETE. ORDS handles authentication, routes to the AutoREST or custom REST handler, executes against Oracle 23ai, and returns JSON.
• APEX Page: a user interacts with an Oracle APEX application. ORDS serves as the APEX runtime, routing page requests to the APEX Engine inside Oracle Database 23ai and returning rendered HTML pages.

All four input types are handled by the same ORDS mid-tier and the same Oracle Database 23ai instance — ORDS provides a unified gateway that the legacy WRB architecture with its separate cartridge types could not match.

Understanding the architectural evolution from WRB to ORDS has direct tuning implications for Oracle DBAs managing web-facing workloads:

• Connection pool sizing: the ORDS JDBC connection pool (`jdbc.MaxLimit` in ORDS configuration) is the primary tuning lever that replaces cartridge instance count tuning in the WRB era. Setting this too low causes request queuing; setting it too high exhausts Oracle session resources.
• Stateless transaction design: Oracle 23ai's sessionless transaction support in ORDS allows HTTP requests to complete database work without holding a database session open between HTTP calls — reducing session count requirements for high-concurrency web workloads.
• PL/SQL Gateway performance: PL/SQL procedures called via the ORDS PL/SQL Gateway should minimize round-trips to the database and use bulk operations where possible — the same SQL tuning principles that applied to the legacy PL/SQL Agent apply here.

The next lesson examines the Web Listener — the component that receives incoming HTTP requests and routes them to the application tier.