Skip to content

DEVELOPERS.adoc

Latest commit

 

History

History
393 lines (272 loc) · 11.2 KB

DEVELOPERS.adoc

File metadata and controls

393 lines (272 loc) · 11.2 KB
Raw

MicroProfile Tutorial - Developers Guide

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.

Table of Contents

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:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
Installing and Managing Java with SDKMAN
# 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:

git clone https://github.com/microprofile/microprofile-tutorial.git
cd microprofile-tutorial

Navigate to a Specific Chapter

# 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:

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:

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:

# 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:

<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:

<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:

<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:

# 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:

# 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

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 Contributors Guide.