Skip to content

Commit

Permalink
Updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
cuioss committed Feb 22, 2025
1 parent dec6205 commit 4283de4
Show file tree
Hide file tree
Showing 13 changed files with 113 additions and 247 deletions.
4 changes: 4 additions & 0 deletions modules/authentication/portal-authentication-api/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,10 @@ public class DepartmentEnricher implements PortalUserEnricher {
}
----

== Documentation

* link:doc/LogMessages.md[Log Messages]

== Best Practices

=== Security Guidelines
Expand Down
4 changes: 4 additions & 0 deletions modules/authentication/portal-authentication-mock/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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]
* https://openid.net/specs/openid-connect-rpinitiated-1_0.html[OpenID Connect RP-Initiated Logout Specification]
* link:doc/LogMessages.md[Log Messages]
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions modules/core/portal-common-cdi/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions modules/core/portal-configuration/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
243 changes: 52 additions & 191 deletions modules/core/portal-configuration/doc/LogMessages.md
Original file line number Diff line number Diff line change
@@ -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<br>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<br>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<br>2. Config key<br>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<br>2. Config key<br>3. Valid options<br>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<br>2. Enum type<br>3. Error reason | Enum conversion failed |
| PortalConfig-220 | CONFIG | Invalid content for '%s%s', expected a boolean but was '%s' | 1. Config prefix<br>2. Config key<br>3. Invalid value | Boolean configuration value is invalid |
| PortalConfig-230 | CONFIG | Invalid content for '%s', expected a number but was '%s' | 1. Config key<br>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<br>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<br>2. Error message | General connection error occurred |
| PortalConfig-251 | CONN | Connection timeout for %s: %s | 1. Connection name<br>2. Error message | Connection timeout occurred |
| PortalConfig-252 | CONN | Connection refused for %s: %s | 1. Connection name<br>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<br>2. Error reason | SSL context creation failed |
5 changes: 4 additions & 1 deletion modules/core/portal-core/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -107,7 +111,6 @@ public void storeUserPreference(String key, String value) {
portal.application.contextPath=/myapp
----


== Best Practices

=== Security
Expand Down
45 changes: 0 additions & 45 deletions modules/core/portal-core/doc/LogMessage.md

This file was deleted.

Loading

0 comments on commit 4283de4

Please sign in to comment.