Java Collections Demo

A hands-on educational project demonstrating the Java Collections Framework through a REST API built with Spring Boot.

Overview

This project serves as a practical companion to learning Java Collections, showcasing how to use each collection type in real-world scenarios through interactive API endpoints.

Tech Stack

Technology	Version
Java	17+
Spring Boot	3.2
SpringDoc OpenAPI	2.3
Maven	3.8+
JUnit 5	-

Project Structure

src/main/java/com/giovaneitosa/collections/
├── CollectionsApplication.java
├── config/
│   └── OpenApiConfig.java           # Swagger/OpenAPI configuration
├── model/
│   ├── Produto.java                 # Record with Comparable
│   └── Pessoa.java                  # Record with equals/hashCode
├── service/
│   ├── ListService.java             # ArrayList, LinkedList, Iterator
│   ├── SetService.java              # HashSet, LinkedHashSet, TreeSet
│   ├── MapService.java              # HashMap, TreeMap, LinkedHashMap
│   └── QueueService.java            # Queue, Deque, PriorityQueue
├── controller/
│   └── CollectionController.java    # REST endpoints with @Tag grouping
├── comparator/
│   ├── ProdutoPorNomeComparator.java
│   └── ProdutoPorPrecoComparator.java
└── exception/
    └── GlobalExceptionHandler.java  # Global error handling

Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.8+

Installation

# Clone the repository
git clone https://github.com/giofeitosa-dev/java-collections-demo.git

# Navigate to project directory
cd java-collections-demo

# Run the application
mvn spring-boot:run

The API will be available at: http://localhost:8080

API Documentation

Once the application is running, access:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/api-docs

API Endpoints

List Operations

Method	Endpoint	Description
GET	/api/collections/list/arraylist	Create ArrayList of products
GET	/api/collections/list/linkedlist	Create LinkedList with addFirst/addLast
GET	/api/collections/list/ordenar-preco	Sort by price (Comparator)
GET	/api/collections/list/ordenar-nome	Sort by name (Comparable)
GET	/api/collections/list/sublist	Return sublist

Set Operations

Method	Endpoint	Description
GET	/api/collections/set/hashset	HashSet without duplicates
GET	/api/collections/set/linkedhashset	LinkedHashSet preserving order
GET	/api/collections/set/treeset	TreeSet sorted naturally
GET	/api/collections/set/tags?texto=...	Create unique tags
GET	/api/collections/set/operacoes	Intersection, union, difference

Map Operations

Method	Endpoint	Description
GET	/api/collections/map/hashmap	HashMap key-value pairs
GET	/api/collections/map/treemap	TreeMap sorted by key
GET	/api/collections/map/linkedhashmap	LinkedHashMap preserving order
GET	/api/collections/map/buscar?chave=...	Search with getOrDefault
GET	/api/collections/map/ordenar-valor	Sort by value
GET	/api/collections/map/contar	Count word occurrences

Queue/Deque Operations

Method	Endpoint	Description
GET	/api/collections/queue/fila	FIFO queue with LinkedList
GET	/api/collections/queue/prioridade	PriorityQueue by price
GET	/api/collections/queue/pilha	LIFO stack with Deque

Key Concepts Demonstrated

Collection Types

Collection	Use Case	When to Use
ArrayList	Fast random access	Read-heavy operations
LinkedList	Fast insert/delete	Frequent add/remove at ends
HashSet	Unique elements	Fast lookup, no ordering
TreeSet	Sorted unique elements	Need sorted order
LinkedHashSet	Insertion-order preserved	Need uniqueness + order
HashMap	Key-value pairs	Fast lookup by key
TreeMap	Sorted keys	Need sorted keys
LinkedHashMap	Insertion-order preserved	Need order + key-value
Queue	FIFO processing	Sequential processing
Deque	Stack/Queue flexibility	Both LIFO and FIFO

Java Features

• Java Records: Immutable models (Produto, Pessoa)
• Comparable: Natural ordering (Produto implements Comparable)
• Comparator: Custom ordering (ProdutoPorNomeComparator)
• @FunctionalInterface: Lambda-ready comparators
• Iterator: Safe collection traversal
• Collections Utility: sort, shuffle, reverse, frequency
• Stream API: Functional operations
• Validation: Record constructors with validation

Usage Examples

List all products

curl http://localhost:8080/api/collections/list/arraylist

Search product by key

curl http://localhost:8080/api/collections/map/buscar?chave=notebook

Create unique tags

curl "http://localhost:8080/api/collections/set/tags?texto=java collections spring boot"

Sort products by price

curl http://localhost:8080/api/collections/list/ordenar-preco

Testing

# Run all tests (27 tests)
mvn test

# Run specific test suites
mvn test -Dtest=ListServiceTest
mvn test -Dtest=SetServiceTest
mvn test -Dtest=MapServiceTest
mvn test -Dtest=QueueServiceTest

Learning Resources

This project is designed to help developers understand:

1. When to use each collection type based on performance characteristics
2. Comparable vs Comparator for sorting strategies
3. Java Records for immutable data models
4. Spring Boot REST API best practices
5. API documentation with SpringDoc OpenAPI

Author

Giovani Feitosa - Educational material on Java Collections Framework

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is educational material for learning purposes.