From 4283de42cd16df4b85a35422ab3a17257102a737 Mon Sep 17 00:00:00 2001 From: Oliver Wolff <23139298+cuioss@users.noreply.github.com> Date: Sat, 22 Feb 2025 15:25:07 +0100 Subject: [PATCH] Updated documentation --- .../portal-authentication-api/README.adoc | 4 + .../portal-authentication-mock/README.adoc | 4 + .../portal-authentication-oauth/README.adoc | 3 +- .../portal-authentication-token/README.adoc | 4 + modules/core/portal-common-cdi/README.adoc | 4 + modules/core/portal-configuration/README.adoc | 5 + .../portal-configuration/doc/LogMessages.md | 243 ++++-------------- modules/core/portal-core/README.adoc | 5 +- modules/core/portal-core/doc/LogMessage.md | 45 ---- modules/core/portal-core/doc/LogMessages.md | 26 ++ .../portal-metrics-api/README.adoc | 4 + .../portal-metrics-api/doc/LogMessages.md | 9 - .../portal-mp-rest-client/README.adoc | 4 + 13 files changed, 113 insertions(+), 247 deletions(-) delete mode 100644 modules/core/portal-core/doc/LogMessage.md create mode 100644 modules/core/portal-core/doc/LogMessages.md diff --git a/modules/authentication/portal-authentication-api/README.adoc b/modules/authentication/portal-authentication-api/README.adoc index 57a2862..e7e2fae 100644 --- a/modules/authentication/portal-authentication-api/README.adoc +++ b/modules/authentication/portal-authentication-api/README.adoc @@ -117,6 +117,10 @@ public class DepartmentEnricher implements PortalUserEnricher { } ---- +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Best Practices === Security Guidelines diff --git a/modules/authentication/portal-authentication-mock/README.adoc b/modules/authentication/portal-authentication-mock/README.adoc index 45555e0..3f3e38c 100644 --- a/modules/authentication/portal-authentication-mock/README.adoc +++ b/modules/authentication/portal-authentication-mock/README.adoc @@ -140,6 +140,10 @@ void shouldProvideCustomUserInfo() { * Document test scenarios * Use meaningful user configurations +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Related Modules * link:../portal-authentication-api/[portal-authentication-api] - Core authentication API diff --git a/modules/authentication/portal-authentication-oauth/README.adoc b/modules/authentication/portal-authentication-oauth/README.adoc index 23ad43c..3fce49e 100644 --- a/modules/authentication/portal-authentication-oauth/README.adoc +++ b/modules/authentication/portal-authentication-oauth/README.adoc @@ -89,4 +89,5 @@ link:https://github.com/cuioss/cui-portal-ui/tree/main/modules/portal-ui-oauth[p * link:src/main/java/de/cuioss/portal/authentication/oauth/package-info.java[API Documentation] * link:src/main/java/de/cuioss/portal/authentication/oauth/impl/package-info.java[Implementation Details] -* https://openid.net/specs/openid-connect-rpinitiated-1_0.html[OpenID Connect RP-Initiated Logout Specification] \ No newline at end of file +* https://openid.net/specs/openid-connect-rpinitiated-1_0.html[OpenID Connect RP-Initiated Logout Specification] +* link:doc/LogMessages.md[Log Messages] \ No newline at end of file diff --git a/modules/authentication/portal-authentication-token/README.adoc b/modules/authentication/portal-authentication-token/README.adoc index 8aae634..63f3769 100644 --- a/modules/authentication/portal-authentication-token/README.adoc +++ b/modules/authentication/portal-authentication-token/README.adoc @@ -95,6 +95,10 @@ The module supports three token types, each with specific functionality: * link:src/main/java/de/cuioss/portal/authentication/token/ParsedIdToken.java[ParsedIdToken]: OpenID Connect ID token for user identity * link:src/main/java/de/cuioss/portal/authentication/token/ParsedRefreshToken.java[ParsedRefreshToken]: OAuth2 refresh token +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Security Considerations * All token validation is performed using cryptographic signatures diff --git a/modules/core/portal-common-cdi/README.adoc b/modules/core/portal-common-cdi/README.adoc index ab877ee..1c39785 100644 --- a/modules/core/portal-common-cdi/README.adoc +++ b/modules/core/portal-common-cdi/README.adoc @@ -114,6 +114,10 @@ Priority-based component ordering utilities. === link:src/main/java/de/cuioss/portal/common/stage[stage] Project stage management and environment configuration. +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Best Practices === CDI Usage diff --git a/modules/core/portal-configuration/README.adoc b/modules/core/portal-configuration/README.adoc index 8b77b3e..4c0ff0f 100644 --- a/modules/core/portal-configuration/README.adoc +++ b/modules/core/portal-configuration/README.adoc @@ -134,6 +134,7 @@ my.connection.read.timeout=30000 # Proxy Configuration (Optional) my.connection.proxy.host=proxy.company.com my.connection.proxy.port=8080 + ---- Usage in code: @@ -160,6 +161,10 @@ Configuration Notes: * Proxy configuration is optional and requires both host and port to be set * Use `failOnInvalidConfiguration = false` to handle missing or invalid configuration gracefully +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Best Practices === Key Naming diff --git a/modules/core/portal-configuration/doc/LogMessages.md b/modules/core/portal-configuration/doc/LogMessages.md index 558e572..963c6ad 100644 --- a/modules/core/portal-configuration/doc/LogMessages.md +++ b/modules/core/portal-configuration/doc/LogMessages.md @@ -1,191 +1,52 @@ -# Portal Configuration Module Log Messages - -## Message Categories - -- INFO (001-099): Informational messages about normal operation -- WARN (100-199): Warning messages about potential issues -- ERROR (200-299): Error messages about operational failures -- FATAL (300-399): Critical system failures - -## INFO Messages (001-099) - -### Project Stage Messages -- **001**: Running in Production-Mode - - Logged when the system is running in production mode - - Level: INFO - -### System Configuration Messages -- **003**: JVM Configuration:\n%s - - Logged when displaying system JVM configuration - - Parameters: Configuration properties as string - - Level: INFO - -- **004**: Environment Configuration:\n%s - - Logged when displaying environment configuration - - Parameters: Environment variables as string - - Level: INFO - -- **005**: Portal Configuration:\n%s - - Logged when displaying portal configuration - - Parameters: Portal properties as string - - Level: INFO - -### File System Messages -- **020**: Watching for file changes at path: %s - - Logged when file watching is initialized for a path - - Parameters: Absolute path being watched - - Level: INFO - -## WARN Messages (100-199) - -### Authentication Messages -- **100**: Unable to determine AuthenticationType for connection='%s' and properties, returning AuthenticationType.NONE - - Logged when authentication type cannot be determined - - Parameters: Connection name - - Level: WARN - -### Project Stage Messages -- **101**: Project stage 'development' detected. Set the property 'portal.stage' to 'production' for productive usage. - - Logged when development mode is detected - - Level: WARN - -- **110**: Project stage 'test' detected. Set the property 'portal.stage' to 'production' for productive usage. - - Logged when test mode is detected - - Level: WARN - -### Configuration Messages -- **102**: Invalid configuration found for .type, actual '%s', expected one of '%s', defaulting to 'ConnectionType.UNDEFINED' - - Logged when invalid connection type is configured - - Parameters: Actual type, Expected types - - Level: WARN - -- **120**: Invalid configuration found for Locale: %s - - Logged when invalid locale configuration is found - - Parameters: Invalid locale string - - Level: WARN - -### File System Messages -- **130**: Invalid element found, watchKey='%s', ignoring - - Logged when invalid watch key is encountered - - Parameters: Watch key - - Level: WARN - -- **140**: Path '%s' %s, therefore it can not be watched - - Logged when path cannot be watched - - Parameters: Path, Reason - - Level: WARN - -- **141**: Unable to read metadata for file %s - - Logged when file metadata cannot be read - - Parameters: File path - - Level: WARN - -- **142**: Directory %s could not be read - - Logged when directory cannot be read - - Parameters: Directory path - - Level: WARN - -### Connection Messages -- **150**: Unable to construct ConnectionMetadata, due to %s - - Logged when connection metadata construction fails - - Parameters: Error message - - Level: WARN - -### Missing Configuration Messages -- **160**: Configuration setting for baseName is missing. - - Logged when base name configuration is missing - - Level: WARN - -- **161**: Missing configuration for %s detected. - - Logged when required configuration is missing - - Parameters: Configuration key - - Level: WARN - -- **170**: Configuration for basic authentication is incomplete. Missing: %s - - Logged when basic auth configuration is incomplete - - Parameters: Missing fields - - Level: WARN - -- **171**: Configuration for token based authentication is incomplete. Missing: %s - - Logged when token auth configuration is incomplete - - Parameters: Missing fields - - Level: WARN - -## ERROR Messages (200-299) - -### Configuration Errors -- **200**: Invalid content for '%s%s', expected a number but was '%s' - - Logged when number configuration is invalid - - Parameters: Config prefix, Key, Invalid value - - Level: ERROR - -- **210**: Invalid content for '%s%s', expected one of %s but was '%s' - - Logged when time unit configuration is invalid - - Parameters: Config prefix, Key, Valid values, Invalid value - - Level: ERROR - -- **212**: Could not convert input value '%s' to enum of type: %s. Reason: %s - - Logged when enum conversion fails - - Parameters: Input value, Enum class, Error reason - - Level: ERROR - -- **220**: Invalid content for '%s%s', expected a boolean but was '%s' - - Logged when boolean configuration is invalid - - Parameters: Config prefix, Key, Invalid value - - Level: ERROR - -- **230**: Invalid content for '%s', expected a number but was '%s' - - Logged when number value is invalid - - Parameters: Key, Invalid value - - Level: ERROR - -### File System Errors -- **240**: Unable to access File-system for detecting changes, due to '%s', use the configuration property '%s' to disable this feature - - Logged when file system access fails - - Parameters: Error message, Configuration property - - Level: ERROR - -- **241**: Error while polling / accessing the file-system - - Logged when file system polling fails - - Level: ERROR - -- **242**: Handling fileChangedEvent failed for file %s - - Logged when file change event handling fails - - Parameters: File path - - Level: ERROR - -### Connection Errors -- **250**: Connection error for %s: %s - - Logged when general connection error occurs - - Parameters: Connection name, Error message - - Level: ERROR - -- **251**: Connection timeout for %s: %s - - Logged when connection timeout occurs - - Parameters: Connection name, Error message - - Level: ERROR - -- **252**: Connection refused for %s: %s - - Logged when connection is refused - - Parameters: Connection name, Error message - - Level: ERROR - -- **260**: Missing connection metadata for %s - - Logged when connection metadata is missing - - Parameters: Connection name - - Level: ERROR - -- **261**: Invalid connection metadata for %s - - Logged when connection metadata is invalid - - Parameters: Connection name - - Level: ERROR - -- **270**: Unable to schedule given Path for tracking for changes, due to '%s' - - Logged when path scheduling fails - - Parameters: Error message - - Level: ERROR - -- **280**: Unable to create SSLContext for connection '%s', due to '%s', defaulting to default ssl configuration - - Logged when SSL context creation fails - - Parameters: Connection ID, Error message - - Level: ERROR +# Log Messages for Portal Configuration Module + +All messages follow the format: PortalConfig-[identifier]: [message] + +## INFO Level (001-099) + +| ID | Component | Message | Parameters | Description | +|----|-----------|---------|------------|-------------| +| PortalConfig-001 | STAGE | Running in Production-Mode | None | Indicates that the system is running in production mode | +| PortalConfig-003 | CONFIG | JVM Configuration:\n%s | 1. JVM configuration string | Displays the current JVM configuration settings | +| PortalConfig-004 | CONFIG | Environment Configuration:\n%s | 1. Environment configuration string | Displays the current environment configuration | +| PortalConfig-005 | CONFIG | Portal Configuration:\n%s | 1. Portal configuration string | Displays the current portal configuration | +| PortalConfig-020 | FILE | Watching for file changes at path: %s | 1. File path | Indicates that file watching has been initialized for the specified path | + +## WARN Level (100-199) + +| ID | Component | Message | Parameters | Description | +|----|-----------|---------|------------|-------------| +| PortalConfig-100 | AUTH | Unable to determine AuthenticationType for connection='%s' and properties, returning AuthenticationType.NONE | 1. Connection name | Authentication type could not be determined for the connection | +| PortalConfig-101 | STAGE | Project stage 'development' detected. Set the property 'portal.stage' to 'production' for productive usage | None | Warns that the system is running in development mode | +| PortalConfig-102 | CONFIG | Invalid configuration found for .type, actual '%s', expected one of '%s', defaulting to 'ConnectionType.UNDEFINED' | 1. Actual type
2. Expected types | Invalid connection type configuration detected | +| PortalConfig-110 | STAGE | Project stage 'test' detected. Set the property 'portal.stage' to 'production' for productive usage | None | Warns that the system is running in test mode | +| PortalConfig-120 | CONFIG | Invalid configuration found for Locale: %s | 1. Invalid locale | Invalid locale configuration detected | +| PortalConfig-130 | FILE | Invalid element found, watchKey='%s', ignoring | 1. Watch key | Invalid watch key encountered during file monitoring | +| PortalConfig-140 | FILE | Path '%s' %s, therefore it can not be watched | 1. Path
2. Reason | Path cannot be monitored for changes | +| PortalConfig-141 | FILE | Unable to read metadata for file %s | 1. File path | File metadata could not be read | +| PortalConfig-142 | FILE | Directory %s could not be read | 1. Directory path | Directory contents could not be read | +| PortalConfig-150 | CONN | Unable to construct ConnectionMetadata, due to %s | 1. Error reason | Connection metadata construction failed | +| PortalConfig-160 | CONFIG | Configuration setting for baseName is missing | None | Required base name configuration is missing | +| PortalConfig-161 | CONFIG | Missing configuration for %s detected | 1. Configuration key | Required configuration value is missing | +| PortalConfig-170 | AUTH | Configuration for basic authentication is incomplete. Missing: %s | 1. Missing fields | Basic authentication configuration is incomplete | +| PortalConfig-171 | AUTH | Configuration for token based authentication is incomplete. Missing: %s | 1. Missing fields | Token authentication configuration is incomplete | + +## ERROR Level (200-299) + +| ID | Component | Message | Parameters | Description | +|----|-----------|---------|------------|-------------| +| PortalConfig-200 | CONFIG | Invalid content for '%s%s', expected a number but was '%s' | 1. Config prefix
2. Config key
3. Invalid value | Number configuration value is invalid | +| PortalConfig-210 | CONFIG | Invalid content for '%s%s', expected one of %s but was '%s' | 1. Config prefix
2. Config key
3. Valid options
4. Invalid value | Time unit configuration value is invalid | +| PortalConfig-212 | CONFIG | Could not convert input value '%s' to enum of type: %s. Reason: %s | 1. Input value
2. Enum type
3. Error reason | Enum conversion failed | +| PortalConfig-220 | CONFIG | Invalid content for '%s%s', expected a boolean but was '%s' | 1. Config prefix
2. Config key
3. Invalid value | Boolean configuration value is invalid | +| PortalConfig-230 | CONFIG | Invalid content for '%s', expected a number but was '%s' | 1. Config key
2. Invalid value | Number value is invalid | +| PortalConfig-240 | FILE | Unable to access File-system for detecting changes, due to '%s', use the configuration property '%s' to disable this feature | 1. Error reason
2. Config property | File system access failed | +| PortalConfig-241 | FILE | Error while polling / accessing the file-system | None | File system polling failed | +| PortalConfig-242 | FILE | Handling fileChangedEvent failed for file %s | 1. File path | File change event handling failed | +| PortalConfig-250 | CONN | Connection error for %s: %s | 1. Connection name
2. Error message | General connection error occurred | +| PortalConfig-251 | CONN | Connection timeout for %s: %s | 1. Connection name
2. Error message | Connection timeout occurred | +| PortalConfig-252 | CONN | Connection refused for %s: %s | 1. Connection name
2. Error message | Connection was refused | +| PortalConfig-260 | CONN | Missing connection metadata for %s | 1. Connection name | Connection metadata is missing | +| PortalConfig-261 | CONN | Invalid connection metadata for %s | 1. Connection name | Connection metadata is invalid | +| PortalConfig-270 | FILE | Unable to schedule given Path for tracking for changes, due to '%s' | 1. Error reason | Path scheduling for change tracking failed | +| PortalConfig-280 | SSL | Unable to create SSLContext for connection '%s', due to '%s', defaulting to default ssl configuration | 1. Connection name
2. Error reason | SSL context creation failed | diff --git a/modules/core/portal-core/README.adoc b/modules/core/portal-core/README.adoc index 706b5e9..11c4167 100644 --- a/modules/core/portal-core/README.adoc +++ b/modules/core/portal-core/README.adoc @@ -38,6 +38,10 @@ Core components and infrastructure for building enterprise portal applications. * Resource cleanup * Startup/shutdown coordination +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Detailed Component Documentation === ServletLifecycleListener @@ -107,7 +111,6 @@ public void storeUserPreference(String key, String value) { portal.application.contextPath=/myapp ---- - == Best Practices === Security diff --git a/modules/core/portal-core/doc/LogMessage.md b/modules/core/portal-core/doc/LogMessage.md deleted file mode 100644 index d40de3b..0000000 --- a/modules/core/portal-core/doc/LogMessage.md +++ /dev/null @@ -1,45 +0,0 @@ -# Log Messages for Portal Core Module - -All messages follow the format: PortalCore-[identifier]: [message] - -## INFO Level (001-099) - -| ID | Component | Message | Description | -|----------------|-----------|---------|-------------| -| PortalCore-001 | LIFECYCLE | Initializing Context for %s | Indicates the start of context initialization for a given path | -| PortalCore-002 | LIFECYCLE | Shutting down '%s' | Indicates the start of context shutdown for a given path | - -## WARN Level (100-199) - -| ID | Component | Message | Description | -|----------------|-----------|---------|-------------| -| PortalCore-100 | SERVLET | User not logged in for protected resource | Request failed due to missing user authentication | -| PortalCore-101 | SERVLET | User should provide the roles %s | Request failed due to insufficient user permissions | -| PortalCore-110 | LIFECYCLE | Error while destroying '%s' for '%s': %s | Error occurred during component destruction | - -## ERROR Level (200-299) - -| ID | Component | Message | Description | -|----------------|-----------|---------|-------------| -| PortalCore-201 | SERVLET | Could not process Request, due to %s | Indicates a request processing error with details about the cause | - -## DEBUG Level (500-599) - -| ID | Component | Message | Description | -|----------------|-----------|---------|-------------| -| PortalCore-500 | SERVLET | Disabled by configuration | Request processing skipped due to configuration settings | -| PortalCore-510 | LIFECYCLE | ServletLifecycleListener called for '%s', initializing with order: %s | Details about initialization order for ServletLifecycleListener | -| PortalCore-511 | LIFECYCLE | Initializing '%s' for '%s' | Component initialization in progress | -| PortalCore-512 | LIFECYCLE | Initialize successfully called for all elements for '%s' | All components initialized successfully | -| PortalCore-513 | LIFECYCLE | Executing applicationDestroyListener for '%s' | Starting application destroy process | -| PortalCore-514 | LIFECYCLE | ServletLifecycleListener called for '%s', finalizing with order: %s | Details about finalization order for ServletLifecycleListener | -| PortalCore-515 | LIFECYCLE | Destroying '%s' for '%s' | Component destruction in progress | -| PortalCore-516 | LIFECYCLE | Finalize successfully called for all elements for '%s' | All components finalized successfully | -| PortalCore-520 | SERVLET | Resolved hostname: %s | Successfully resolved external hostname | - -## TRACE Level (600-699) - -| ID | Component | Message | Description | -|----------------|-----------|---------|-------------| -| PortalCore-600 | SERVLET | Checking call preconditions | Starting precondition checks for request processing | -| PortalCore-601 | SERVLET | All preconditions are ok, generating payload | Preconditions passed, proceeding with payload generation | diff --git a/modules/core/portal-core/doc/LogMessages.md b/modules/core/portal-core/doc/LogMessages.md new file mode 100644 index 0000000..738af57 --- /dev/null +++ b/modules/core/portal-core/doc/LogMessages.md @@ -0,0 +1,26 @@ +# Log Messages for Portal Core Module + +All messages follow the format: PortalCore-[identifier]: [message] + +## INFO Level (001-009) + +| ID | Component | Message | Parameters | Description | +|----|-----------|---------|------------|-------------| +| PortalCore-001 | LIFECYCLE | Initializing Context for %s | 1. Context path | Context initialization started | +| PortalCore-002 | LIFECYCLE | Shutting down '%s' | 1. Context name | Context shutdown initiated | + +## WARN Level (100-119) + +| ID | Component | Message | Parameters | Description | +|----|-----------|---------|------------|-------------| +| PortalCore-100 | SERVLET | Could not process Request, because the user must be logged in for this request | None | Authentication required | +| PortalCore-101 | SERVLET | Could not process Request, because of the condition '%s' is not met for user '%s' | 1. Condition
2. User | User lacks required condition | +| PortalCore-102 | SERVLET | Could not process Request, because the user must be logged in for this request | None | Authentication required | +| PortalCore-103 | SERVLET | Could not process Request, because of the condition '[%s]' is not met for user '%s' | 1. Roles
2. User | User lacks required roles | +| PortalCore-110 | LIFECYCLE | Error during servlet context destroy | None | Context destruction failed | + +## ERROR Level (200-209) + +| ID | Component | Message | Parameters | Description | +|----|-----------|---------|------------|-------------| +| PortalCore-200 | SERVLET | Could not process Request, due to %s | 1. Error details | Request processing failed | diff --git a/modules/micro-profile/portal-metrics-api/README.adoc b/modules/micro-profile/portal-metrics-api/README.adoc index 0e045dd..2ca7791 100644 --- a/modules/micro-profile/portal-metrics-api/README.adoc +++ b/modules/micro-profile/portal-metrics-api/README.adoc @@ -136,6 +136,10 @@ portal.cache.user.timeunit=MINUTES portal.cache.user.record-stats=true ---- +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Best Practices === Metric Naming diff --git a/modules/micro-profile/portal-metrics-api/doc/LogMessages.md b/modules/micro-profile/portal-metrics-api/doc/LogMessages.md index d2f5b9c..f22a003 100644 --- a/modules/micro-profile/portal-metrics-api/doc/LogMessages.md +++ b/modules/micro-profile/portal-metrics-api/doc/LogMessages.md @@ -1,14 +1,5 @@ # Portal Metrics Module Log Messages -## Overview -This document describes the log messages used in the Portal Metrics module. All messages are defined as LogRecords and follow the DSL-Style Nested Constants Pattern. - -## Message Categories - -* **INFO (001-099)**: General metrics operations -* **WARN (100-199)**: Warning conditions -* **ERROR (200-299)**: Error conditions - ## Log Messages ### INFO Level (001-099) diff --git a/modules/micro-profile/portal-mp-rest-client/README.adoc b/modules/micro-profile/portal-mp-rest-client/README.adoc index 0b79bb6..c2d00df 100644 --- a/modules/micro-profile/portal-mp-rest-client/README.adoc +++ b/modules/micro-profile/portal-mp-rest-client/README.adoc @@ -31,6 +31,10 @@ Module providing a builder-based approach for creating and configuring MicroProf * Error tracking and reporting * See link:doc/LogMessages.md[Log Messages Documentation] +== Documentation + +* link:doc/LogMessages.md[Log Messages] + == Usage Examples === Basic REST Client