refactor: restrict webforj to one app and unfiy error handling

[hyyan]

The (PR) enforces a single application limit in webforJ and shifts all error handling responsibilities to the Java side, giving developers full control over error management.

Application Discovery Rules:

1. During the webforJ bootstrap process, all classes that extend com.webforj.App are scanned. If multiple applications are found, the system looks for the com.webforj.annotation.AppEntry annotation. If any of the discovered classes are annotated with @AppEntry, the first one encountered is considered the entry point.

   • If a class is annotated with @AppEntry, that class is selected as the entry point.
   • If multiple classes are annotated with @AppEntry, an exception is thrown, listing all the discovered classes.
   • If no class is annotated and only one subclass of App is found, that class is selected as the entry point.
   • If no class is annotated and multiple subclasses of App are found, an exception is thrown, detailing each subclass.

Error Handling

webforJ will capture all errors during the application lifecycle and forward them to the appropriate error handler through the ErrorHandler interface.

Applications can implement this interface to manage specific exceptions. The implementing class should be named after the exception it handles, followed by the suffix ErrorHandler. it must be registered in the com.webforj.error.ErrorHandler placed in the META-INF/services directory. For example, to handle a java.lang.NullPointerException, the class should be named NullPointerExceptionErrorHandler, registered in com.webforj.error.ErrorHandler which is placed in META-INF/services directory.

If no error handler is found, webforJ will use its own global error handler. The default error handler will:

1. Log the exception to the BBj debug log.
2. Log the exception to the browser console if debug mode is enabled.
3. Create and display an exception page if debug mode is enabled; otherwise, it will fall back to a generic error page.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details

Scanned Manifest Files

[github-actions]

Code Coverage

Overall Project	68.84% -0.61%	🍏
Files changed	15.42%	❌

Module	Coverage
webforj-foundation	65.92% -0.9%	❌

Files

Module	File	Coverage
webforj-foundation	Environment.java	44.05% -11.9%	🍏
	App.java	34.81% -3.87%	❌
	GlobalErrorHandler.java	10.34% -89.66%	❌
	StackTracePageBuilder.java	0%	❌
	ErrorHandler.java	0%	❌
	Bootstrap.java	0%	❌

[sonarcloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud