Parameter handling

AWE services can read parameters from two places:

1. the live request, while the HTTP request is still active;
2. a propagated parameter snapshot, when code runs later in an async thread.

Use the API that matches what you need to do. Do not use getRequest() as the default parameter API.

API quick reference

Need	Use	Meaning
Access the live request object	getRequest()	"I need the current request bean."
Read parameters safely from the current context	getRequestParameters() / getRequestParameter(...)	"I want to read parameters safely."
Build a parameter object that I will change	getMutableRequestParameters()	"I want a snapshot that I am going to modify."
Add or replace values in an ObjectNode	putRequestParameter(parameters, name, value)	"I am preparing parameters for another call."
Make new values visible to descendant async tasks	mergePropagatedRequestParameters(...) or putPropagatedRequestParameter(...)	"Future async hops must inherit these values."
Work outside ServiceConfig	QueryUtil	Lower-level API used by the ServiceConfig helpers.

The simple rule

Recommended default

In services, prefer the parameter helpers exposed by ServiceConfig:

• getRequestParameters() for reading;
• getMutableRequestParameters() when you will modify a snapshot;
• putRequestParameter(...) to add values to that snapshot.

Use getRequest() only when you really need the live request bean itself.

getRequest()

Use getRequest() when the code is tied to an active HTTP request and needs request-specific behavior.

Typical use cases:

• read request-only metadata;
• access request token, target action, or servlet-related data;
• update the live request in a synchronous request flow.

String screenName = getRequest().getParameterAsString("screen");

warning

Do not use getRequest() just because you need a parameter value. In async code the live request may no longer exist.

getRequestParameters()

getRequestParameters() means:

"I want to read parameters safely."

Expected use:

• read values;
• inspect parameters from the current execution context;
• avoid depending on a live request in code that may run async;
• do not emphasize modification.

ObjectNode parameters = getRequestParameters();
String userName = getRequestParameterAsString("user", parameters);
JsonNode report = getRequestParameter("report", parameters);

How it resolves parameters:

1. if a live request exists, it reads from that request;
2. otherwise, it reads from the propagated async snapshot;
3. if neither exists, it returns an empty object.

Use this API for safe reads in services, especially when the method can be called from @Async, scheduler jobs, child threads, or reusable service flows.

getMutableRequestParameters()

getMutableRequestParameters() means:

"I want a snapshot that I am going to modify."

Expected use:

• build parameters for downstream calls;
• add values to an ObjectNode;
• prepare data for maintain, mail, report, print, or service calls;
• keep changes explicit instead of mutating request-scoped state.

ObjectNode parameters = getMutableRequestParameters();
putRequestParameter(parameters, "PdfNam", pdfPath);
putRequestParameter(parameters, "ScrTitFil", fileName);
putRequestParameter(parameters, "report", reportNode);

Then pass the object to the downstream operation:

maintainService.launchMaintain("SndRep", parameters);

This is the preferred pattern when threaded code prepares data for later maintain, mail, report, or print work.

Async parameter propagation

AWE can propagate a snapshot of request parameters to child threads, but only when the async task uses an AWE context-aware executor.

The common Spring annotation is:

@Async("threadPoolTaskExecutor")

threadPoolTaskExecutor is configured with the AWE task decoration needed to copy context. If a project uses another executor, that executor must provide the same context propagation behavior.

important

Async propagation gives you a parameter snapshot, not a live AweRequest.

Updating the propagated snapshot

Most code should pass an explicit ObjectNode to the next operation. That is usually enough.

Update the propagated snapshot only when new values must be inherited by descendant async hops.

ObjectNode parameters = getMutableRequestParameters();
putRequestParameter(parameters, "PdfNam", reportPath);

mergePropagatedRequestParameters(parameters);

For a single value, you can write directly to the propagated snapshot:

putPropagatedRequestParameter("PdfNam", reportPath);

Scenario guide

Scenario	Read with	Write / prepare with
Synchronous code that needs the request object	getRequest()	getRequest() if live request mutation is intended
Synchronous service that only needs parameters	getRequestParameters() / getRequestParameter(...)	getMutableRequestParameters() + putRequestParameter(...)
Async service using an AWE executor	getRequestParameters() / getRequestParameter(...)	getMutableRequestParameters() + putRequestParameter(...)
Async flow that calls another async flow	getRequestParameters() / getRequestParameter(...)	explicit ObjectNode; optionally update propagated snapshot
Maintain, mail, report, or print after thread work	explicit ObjectNode	getMutableRequestParameters() + putRequestParameter(...)
Class that does not extend ServiceConfig	QueryUtil	QueryUtil / explicit ObjectNode

Practical examples

Safe read

ObjectNode parameters = getRequestParameters();
String userName = getRequestParameterAsString("user", parameters);

Prepare report parameters

ObjectNode parameters = getMutableRequestParameters();
putRequestParameter(parameters, "ScrTit", screenTitle);
putRequestParameter(parameters, "ScrTitFil", fileName);
putRequestParameter(parameters, "PdfNam", pdfPath);

maintainService.launchMaintain("SndRep", parameters);

Prepare mail parameters

ObjectNode parameters = getMutableRequestParameters();
putRequestParameter(parameters, "subject", subject);
putRequestParameter(parameters, "body", body);
putRequestParameter(parameters, "recipients", recipients);

mailService.sendEmail(parameters);

Checklist

Before choosing an API, ask:

• Do I need the live request object, or only parameter values?
• Can this code run in @Async, a scheduler, or a child thread?
• Am I only reading parameters?
• Am I building parameters for maintain, mail, report, print, or another service?
• Must descendant async tasks inherit the new values?

Summary

• Use getRequest() only for live request-specific work.
• Use getRequestParameters() when the intent is safe parameter reading.
• Use getMutableRequestParameters() when the intent is to modify a parameter snapshot.
• Use putRequestParameter(...) to add values to that ObjectNode.
• Use mergePropagatedRequestParameters(...) or putPropagatedRequestParameter(...) only when descendant async hops must inherit new values.
• Use QueryUtil directly only outside ServiceConfig or for lower-level infrastructure code.

Next step

If you are preparing report or print parameters, also review the Print engine guide.