microprofile
diff --git a/‎.github/workflows/build-and-deploy-tutorial.yml‎
Lines changed: 294 additions & 65 deletions b/‎.github/workflows/build-and-deploy-tutorial.yml‎
Lines changed: 294 additions & 65 deletions
diff --git a/‎CONTRIBUTORS.adoc‎
Lines changed: 1034 additions & 0 deletions b/‎CONTRIBUTORS.adoc‎
Lines changed: 1034 additions & 0 deletions
diff --git a/‎DEVELOPERS.adoc‎
Lines changed: 393 additions & 0 deletions b/‎DEVELOPERS.adoc‎
Lines changed: 393 additions & 0 deletions
@@ -0,0 +1,393 @@
+= MicroProfile Tutorial - Developers Guide
+:toc: macro
+:toc-title: Table of Contents
+:toclevels: 3
+:doctype: book
+
+This guide provides information for developers who want to download and work with the MicroProfile e-commerce application source code. Each chapter of the tutorial includes practical code examples that demonstrate various MicroProfile features.
+
+toc::[]
+
+## Overview
+
+The MicroProfile Tutorial includes a comprehensive e-commerce application built with Jakarta EE 10 and MicroProfile 7.1. The application demonstrates real-world use of MicroProfile features through a multi-service architecture that includes catalog, inventory, user, payment, and order services.
+
+## Code Organization
+
+The source code for the tutorial is organized by chapter in the `code/` directory. Each chapter builds upon the previous one, introducing new MicroProfile features and concepts:
+
+```
+code/
+├── chapter02/    # Getting Started
+├── chapter03/    # Jakarta EE 10 Core Profile
+├── chapter04/    # OpenAPI
+├── chapter05/    # Configuration
+├── chapter06/    # Health Checks
+├── chapter07/    # Metrics
+├── chapter08/    # Fault Tolerance
+├── chapter09/    # Telemetry
+├── chapter10/    # JWT Authentication
+├── chapter11/    # REST Client
+├── chapter12/    # Graph QL
+└── chapter13/    # Reactive Messaging
+
+```
+
+### Chapter Structure
+
+Each chapter directory contains one or more microservices with the following structure:
+
+```
+chapterXX/
+├── <service-name>/
+│   ├── src/
+│   │   ├── main/
+│   │   │   ├── java/           # Java source code
+│   │   │   ├── liberty/config/ # Open Liberty configuration
+│   │   │   └── resources/      # Application resources
+│   │   └── test/               # Unit and integration tests
+│   ├── pom.xml                 # Maven build configuration
+│   └── README.adoc             # Service-specific documentation
+```
+
+## Getting Started
+
+### Prerequisites
+
+Before working with the code, ensure you have the following installed:
+
+#### Required Software
+
+* **Java Development Kit (JDK) 21 or later**
+* **Maven 3.9.12 or later** - For building the applications
+* **Git** - For cloning the repository
+
+#### Development Environment Setup
+
+We recommend using SDKMAN for managing Java versions, as it makes it easy to switch between different JDK versions.
+
+##### Installing SDKMAN
+
+If SDKMAN is not already installed, follow the official instructions at https://sdkman.io/install/ or run:
+
+[source,bash]
+----
+curl -s "https://get.sdkman.io" | bash
+source "$HOME/.sdkman/bin/sdkman-init.sh"
+----
+
+##### Installing and Managing Java with SDKMAN
+
+[source,bash]
+----
+# List available Java versions
+sdk list java
+
+# Install JDK 21 (Microsoft build)
+sdk install java 21.0.11-ms
+
+# List installed Java versions
+sdk list java | grep -E ".*\s+installed"
+
+# Switch to JDK 21 for the current shell session
+sdk use java 21.0.11-ms
+
+# Make JDK 21 the default for all sessions
+sdk default java 21.0.11-ms
+
+# Verify the current Java version
+java -version
+----
+
+##### Recommended IDEs and Extensions
+
+**Visual Studio Code:**
+
+* Java Extension Pack
+* Language Support for Java by Red Hat
+* Liberty Tools for VS Code
+* AsciiDoc extension (for viewing documentation)
+
+**IntelliJ IDEA:**
+
+* Built-in Java and Maven support
+* MicroProfile plugin (available in the marketplace)
+* Liberty plugin (available in the marketplace)
+
+**Eclipse:**
+
+* Eclipse IDE for Enterprise Java and Web Developers
+* Liberty Developer Tools
+
+## Downloading the Source Code
+
+### Clone the Repository
+
+To get all the code for the tutorial:
+
+[source,bash]
+----
+git clone https://github.com/microprofile/microprofile-tutorial.git
+cd microprofile-tutorial
+----
+
+### Navigate to a Specific Chapter
+
+[source,bash]
+----
+# For example, to work with Chapter 3 code
+cd code/chapter03/catalog
+----
+
+## Building and Running the Code
+
+The tutorial uses Maven and the Open Liberty Maven plugin to build and run the application.
+
+### Building an Application
+
+To build any microservice, navigate to its directory and run:
+
+[source,bash]
+----
+mvn clean package
+----
+
+This command:
+- Compiles the Java source code
+- Runs unit tests
+- Packages the application as a WAR file
+
+### Running an Application
+
+The easiest way to run an application is using the Liberty Maven plugin in development mode:
+
+[source,bash]
+----
+mvn liberty:dev
+----
+
+**Development mode features:**
+
+- Automatically rebuilds and redeploys on code changes
+- Runs tests on demand by pressing Enter
+- Supports hot reload for faster development
+- Provides debugging capabilities
+
+To exit development mode, press `Ctrl+C` or type `q` and press Enter.
+
+### Accessing the Application
+
+Once the server is running, you can access the application endpoints. The default configuration typically uses:
+
+* **Host**: localhost (or your system hostname)
+* **Port**: Varies by service (commonly 9080)
+
+For example, for the catalog service in Chapter 3:
+```
+http://localhost:9080/catalog/api/products
+```
+
+Replace `localhost` with your system hostname if accessing from a different machine.
+
+### Running Tests
+
+To run the unit and integration tests:
+
+[source,bash]
+----
+# Run all tests
+mvn test
+
+# Run a specific test class
+mvn test -Dtest=YourTestClassName
+----
+
+## Working with Individual Chapters
+
+Each chapter introduces specific MicroProfile features. 
+
+## Common Development Tasks
+
+### Changing Server Ports
+
+If you need to run multiple services simultaneously or avoid port conflicts, you can change the HTTP port in the Liberty server configuration.
+
+Edit `src/main/liberty/config/server.xml`:
+
+[source,xml]
+----
+<httpEndpoint id="defaultHttpEndpoint"
+              host="*"
+              httpPort="9080"  <!-- Change this port -->
+              httpsPort="9443" />
+----
+
+### Configuring the Database
+
+Most chapters use the Derby embedded database for simplicity. The database configuration is in `src/main/resources/META-INF/persistence.xml`:
+
+[source,xml]
+----
+<persistence-unit name="prod" transaction-type="JTA">
+    <jta-data-source>jdbc/DefaultDataSource</jta-data-source>
+    <properties>
+        <!-- JPA and database properties -->
+    </properties>
+</persistence-unit>
+----
+
+### Adding Dependencies
+
+To add new dependencies, edit the `pom.xml` file. The tutorial uses Maven for dependency management:
+
+[source,xml]
+----
+<dependencies>
+    <!-- Add your dependencies here -->
+    <dependency>
+        <groupId>org.example</groupId>
+        <artifactId>example-library</artifactId>
+        <version>1.0.0</version>
+    </dependency>
+</dependencies>
+----
+
+## Technology Stack
+
+The MicroProfile Tutorial applications use the following technology stack:
+
+### Core Technologies
+
+* **Jakarta EE 10** - Enterprise Java specifications
+* **MicroProfile 7.1** - Cloud-native microservices specifications
+* **Maven** - Build and dependency management
+
+### Jakarta EE APIs Used
+
+* **Jakarta RESTful Web Services (JAX-RS)** - REST API development
+* **Jakarta Persistence (JPA)** - Database persistence
+* **Jakarta Contexts and Dependency Injection (CDI)** - Dependency injection
+* **Jakarta Bean Validation** - Input validation
+* **Jakarta JSON Binding (JSON-B)** - JSON serialization
+* **Jakarta JSON Processing (JSON-P)** - JSON processing
+
+### MicroProfile APIs Used
+
+* **MicroProfile Config** - Configuration management
+* **MicroProfile Health** - Health check endpoints
+* **MicroProfile Metrics** - Application metrics
+* **MicroProfile OpenAPI** - API documentation
+* **MicroProfile JWT** - JWT authentication
+* **MicroProfile Fault Tolerance** - Resilience patterns
+* **MicroProfile REST Client** - Type-safe REST clients
+* **MicroProfile GraphQL** - GraphQL based calls
+* **MicroProfile Reactive Messaging** - Event Driven Architecture and Reactive Messaging using Asynchronous calls
+
+### Additional Libraries
+
+* **Lombok** - Reduces boilerplate code with annotations
+* **JUnit 5** - Unit testing framework
+* **Derby** - Embedded database (for development)
+
+## Best Practices
+
+When working with the tutorial code, consider these best practices:
+
+### Development Workflow
+
+1. **Start with Early Chapters**: If you're new to MicroProfile, start with Chapter 2 and progress sequentially.
+2. **Read the Documentation**: Each service includes a README.adoc with specific instructions and explanations.
+3. **Experiment**: The code is designed for learning - modify it, break it, and understand how it works.
+
+### Code Organization
+
+1. **Follow the Layered Architecture**: The code uses a clear separation between resources, services, repositories, and entities.
+2. **Keep Services Small**: Each microservice focuses on a specific business capability.
+3. **Use DTOs When Appropriate**: Don't expose entity classes directly in REST APIs for complex scenarios.
+
+### Testing
+
+1. **Write Tests**: Add unit tests for your changes to ensure they work correctly.
+2. **Test in Development Mode**: Use the interactive testing feature in `mvn liberty:dev` by pressing Enter.
+3. **Integration Tests**: Some chapters include integration tests that verify end-to-end functionality.
+
+### Configuration
+
+1. **Externalize Configuration**: Use MicroProfile Config for values that may vary across environments.
+2. **Use Profiles**: Configure different settings for development, testing, and production.
+3. **Document Configuration**: Keep track of required configuration properties.
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Port Already in Use
+
+**Problem**: Error message indicates the port is already in use.
+
+**Solution**:
+```bash
+# Find process using the port (e.g., 9080)
+lsof -i :9080
+
+# Kill the process
+kill <PID>
+
+# Or change the port in server.xml
+```
+
+#### Maven Build Failures
+
+**Problem**: Maven fails to download dependencies or build the project.
+
+**Solution**:
+```bash
+# Clean Maven cache and rebuild
+mvn clean install -U
+
+# Verify Maven is properly configured
+mvn -version
+
+# Check your internet connection and proxy settings if behind a firewall
+```
+
+#### Database Connection Errors
+
+**Problem**: Application cannot connect to the database.
+
+**Solution**:
+
+- Verify the database configuration in `persistence.xml`
+- Check that Derby is included in dependencies
+- Look for database lock files that might need deletion
+- Review server logs for detailed error messages
+
+## Next Steps
+
+After setting up your development environment and exploring the code:
+
+1. **Run the Examples**: Start with Chapter 2 and work through each chapter sequentially
+2. **Modify the Code**: Try adding new features or changing existing functionality
+3. **Build Your Own Service**: Create a new microservice using the patterns learned
+4. **Integrate Services**: Practice calling one service from another using the REST Client
+5. **Deploy to Production**: Learn about deploying MicroProfile applications to cloud platforms
+
+## Additional Resources
+
+### Official Documentation
+
+* **MicroProfile**: https://microprofile.io
+* **Jakarta EE**: https://jakarta.ee
+
+## Contributing
+
+If you find issues with the code or have suggestions for improvements:
+
+1. Check existing issues in the GitHub repository
+2. Create a new issue with:
+   - Clear description of the problem or suggestion
+   - Steps to reproduce (for bugs)
+   - Expected vs. actual behavior
+3. Consider submitting a pull request with fixes or enhancements
+
+For documentation improvements, see the link:CONTRIBUTORS.adoc[Contributors Guide].