Process exception message templates
Goal: Technical
Developer: Heng Sin Low
Feature Ticket: IDEMPIERE-7210
Version: iDempiere 14
The problem
When a Java process executed through ProcessUtil.startJavaProcess throws an uncaught Throwable, iDempiere previously formatted the process error summary unconditionally as:
Msg.getMsg(Env.getCtx(), "ProcessError") + " " + e.getLocalizedMessage()
Administrators and implementers could not customize, wrap, or translate error summaries for specific exception types without modifying Java code.
What changed
ProcessUtil.startJavaProcess now looks up an AD_Message template for the thrown exception before building the error summary:
- Starting from the exception's own class, iDempiere checks the fully qualified class name (for example,
java.lang.IllegalStateException) and walks up the superclass chain up tojava.lang.Throwable. - For each class in the chain, it checks whether an
AD_Messageexists usingMsg.hasMsg(ctx, className). Lookup stops at the first match. - If a matching
AD_Messagetemplate is found:- When the template contains
{0}, iDempiere formats it withjava.text.MessageFormat, passinge.getLocalizedMessage()(or an empty string ifnull) as{0}and trimming the result. Single quotes in the template are preserved automatically. - When the template does not contain
{0}, or when the pattern is invalid forMessageFormat,e.getLocalizedMessage()is appended to the template text, separated by a space and trimmed.
- When the template contains
- If no
AD_Messageexists for any class in the exception hierarchy, iDempiere keeps the previous behavior and usese.getLocalizedMessage()directly. - The resulting text is prefixed with
Msg.getMsg(ctx, "ProcessError") + " ", using the passedctxinstead ofEnv.getCtx().
How to set it up
No database migration is required, and no exception class messages are preconfigured. To define a custom template for an exception class or superclass:
- Log in as System Administrator.
- Open the Message window.
- Create a record in the Message tab:
- Set Search Key (
Value) to the fully qualified exception class name (such asjava.lang.IllegalStateException), a superclass (such asjava.lang.RuntimeException), orjava.lang.Throwableas a general fallback. - Set Message Type (
MsgType) to Error. - Set Message Text (
MsgText) to your message template, using{0}where the exception's localized message should appear (for example,Invalid state: {0}).
- Set Search Key (
- Optionally, add localized texts in the Message => Translation subtab, or override per Tenant when Messages at Client Level is enabled.
- Save the record and run Cache Reset so the new message is loaded.
Examples
- Specific exception class with
{0}: Defining anAD_Messagewith Search Keyjava.lang.IllegalStateExceptionand Message TextInvalid state: {0}turns an uncaughtIllegalStateException("Document already closed")into the summary"Error: Invalid state: Document already closed". - Fallback for all exceptions: Defining an
AD_Messagewith Search Keyjava.lang.Throwableprovides a default template for any uncaught exception whose more specific classes do not have anAD_Message. - Single quotes in text: Defining
Can't complete: {0}keeps the apostrophe intact without requiring doubled quotes (''). - Template without
{0}: DefiningCustom IllegalStatewithout{0}appends the exception detail, producing"Error: Custom IllegalState Document already closed". - Exception without a message: When
e.getLocalizedMessage()isnull,{0}resolves to an empty string so"null"does not appear in the summary.
Technical notes
- New
Msg.hasMsghelper:org.compiere.util.Msgaddspublic static boolean hasMsg(Properties ctx, String AD_Message). It checks whether a non-empty message exists for the language resolved fromctx(falling back toLanguage.getBaseAD_Language()). UnlikeMsg.getMsg(Properties, String),hasMsgdoes not log a warning when the key is missing, allowingProcessUtilto probe the exception hierarchy without polluting logs. - Context propagation:
ProcessUtil.startJavaProcessnow passesctxtoMsg.getMsg(ctx, "ProcessError")as well asgetExceptionMessage(ctx, e). - Pattern safety: Single quotes in the
AD_Messagetemplate are escaped withtemplate.replace("'", "''")before callingMessageFormat.format. IfMessageFormat.formatthrowsIllegalArgumentException,ProcessUtillogs the invalid pattern atLevel.FINEand falls back to(template + " " + detail).trim().
Migration impact
None. Existing Java processes behave identically unless an AD_Message matching an exception class in the Throwable hierarchy is added.
Related tickets
- IDEMPIERE-7210
- Pull Request: #3466