Item Management System - Spring Boot ORM Application

A RESTful API for managing inventory items with full CRUD operations, validation, filtering, and pagination support.

📋 Table of Contents

• Features
• Technology Stack
• Project Structure
• Getting Started
• API Endpoints
• Data Model
• Validation Rules
• Usage Examples
• Error Handling

✨ Features

• CRUD Operations: Create, Read, Update, Delete items
• Input Validation: Bean validation using Jakarta Validation API
• Custom Validators: Custom user validation
• Filtering: Search items by status and user
• Pagination: Paginated results with sorting
• Audit Trail: Automatic timestamp tracking for creation and modification
• Transaction Management: Transactional service layer
• Status Management: Enum-based item status tracking

🛠 Technology Stack

• Java: JDK 17+
• Spring Boot: 3.x
• Spring Data JPA: For data persistence
• Hibernate: ORM framework
• Jakarta Validation: Bean validation
• Lombok: Reduce boilerplate code
• H2/MySQL/PostgreSQL: Database (configurable)
• Maven/Gradle: Build tool

📁 Project Structure

src/main/java/com/hackerrank/orm/
├── controller/
│   └── ItemController.java          # REST API endpoints
├── service/
│   └── ItemService.java             # Business logic layer
├── repository/
│   └── ItemRepository.java          # Data access layer
├── model/
│   └── Item.java                    # Entity class
├── enums/
│   └── ItemStatus.java              # Item status enum
├── validator/
│   └── ValidUser.java               # Custom validator annotation
└── exception/
    └── BadRequestException.java     # Custom exception

🚀 Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.6+ or Gradle 7+
• IDE with Lombok support (IntelliJ IDEA, Eclipse, VS Code)

Installation

1. Clone the repository

   git clone <repository-url>
   cd item-management-system

2. Configure Lombok in your IDE

   IntelliJ IDEA:

   • Install Lombok plugin: Settings → Plugins → Search "Lombok"
   • Enable annotation processing: Settings → Build, Execution, Deployment → Compiler → Annotation Processors → Enable

   Eclipse:

   • Download lombok.jar from projectlombok.org
   • Run: java -jar lombok.jar and select Eclipse installation

3. Configure Database

   Edit application.properties:

   # H2 Database (Default - for testing)
   spring.datasource.url=jdbc:h2:mem:testdb
   spring.datasource.driver-class-name=org.h2.Driver
   spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
   
   # MySQL (Production)
   # spring.datasource.url=jdbc:mysql://localhost:3306/item_db
   # spring.datasource.username=root
   # spring.datasource.password=yourpassword
   # spring.jpa.database-platform=org.hibernate.dialect.MySQLDialect
   
   # JPA/Hibernate Settings
   spring.jpa.hibernate.ddl-auto=update
   spring.jpa.show-sql=true
   spring.jpa.properties.hibernate.format_sql=true

4. Build the project

   # Maven
   mvn clean install
   
   # Gradle
   ./gradlew clean build

5. Run the application

   # Maven
   mvn spring-boot:run
   
   # Gradle
   ./gradlew bootRun

The application will start on http://localhost:8080

🔌 API Endpoints

Base URL: /app/item

Method	Endpoint	Description
POST	/app/item	Create a new item
GET	/app/item	Get all items (with optional filters)
GET	/app/item/{id}	Get item by ID
PUT	/app/item/{id}	Update an existing item
DELETE	/app/item/{id}	Delete an item
DELETE	/app/item	Delete all items

Query Parameters

GET /app/item supports:

• status - Filter by ItemStatus (AVAILABLE, SOLD, etc.)
• enteredBy - Filter by user who entered the item
• page - Page number for pagination (0-indexed)
• size - Number of items per page
• sortBy - Field name to sort by

📊 Data Model

Item Entity

{
  "itemId": 1,                              // Auto-generated
  "itemName": "Laptop",                     // Required
  "itemEnteredByUser": "john_doe",          // Required, immutable
  "itemEnteredDate": "2024-03-16T10:30:00", // Auto-generated
  "itemBuyingPrice": 800.00,                // Must be > 0
  "itemSellingPrice": 1200.00,
  "itemLastModifiedDate": "2024-03-16T14:20:00",
  "itemLastModifiedByUser": "admin",        // Custom validated
  "itemStatus": "AVAILABLE"                 // Enum: AVAILABLE, SOLD, etc.
}

ItemStatus Enum

public enum ItemStatus {
    AVAILABLE,
    SOLD,
    RESERVED,
    OUT_OF_STOCK
}

✅ Validation Rules

Field	Validation	Message
itemName	@NotBlank	"Item name is required"
itemEnteredByUser	@NotBlank	"user name is required"
itemBuyingPrice	@Positive	"Buying price must be > 0"
itemLastModifiedByUser	@ValidUser	Custom validation

📝 Usage Examples

Create an Item

POST http://localhost:8080/app/item
Content-Type: application/json

{
  "itemName": "Wireless Mouse",
  "itemEnteredByUser": "user1",
  "itemBuyingPrice": 15.00,
  "itemSellingPrice": 25.00
}

Response (201 Created):

{
  "itemId": 1,
  "itemName": "Wireless Mouse",
  "itemEnteredByUser": "user1",
  "itemEnteredDate": "2024-03-16T10:30:00.000+00:00",
  "itemBuyingPrice": 15.0,
  "itemSellingPrice": 25.0,
  "itemLastModifiedDate": "2024-03-16T10:30:00.000+00:00",
  "itemLastModifiedByUser": null,
  "itemStatus": "AVAILABLE"
}

Get All Items

GET http://localhost:8080/app/item

Get Item by ID

GET http://localhost:8080/app/item/1

Update an Item

PUT http://localhost:8080/app/item/1
Content-Type: application/json

{
  "itemName": "Wireless Mouse Pro",
  "itemBuyingPrice": 20.00,
  "itemSellingPrice": 35.00,
  "itemStatus": "AVAILABLE",
  "itemLastModifiedByUser": "admin"
}

Note: itemEnteredByUser is immutable and won't be updated.

Filter Items

# By status and user
GET http://localhost:8080/app/item?status=AVAILABLE&enteredBy=user1

Paginated Results

# Page 0, 10 items per page, sorted by itemName
GET http://localhost:8080/app/item?page=0&size=10&sortBy=itemName

Delete an Item

DELETE http://localhost:8080/app/item/1

⚠️ Error Handling

Common HTTP Status Codes

Status	Description
200 OK	Successful GET request
201 Created	Item successfully created
400 Bad Request	Validation failed or item already exists
404 Not Found	Item not found
500 Internal Server Error	Server error

Error Response Example

{
  "timestamp": "2024-03-16T10:30:00.000+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Item with id 5 already exists"
}

Validation Error Example

{
  "timestamp": "2024-03-16T10:30:00.000+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "itemName",
      "message": "Item name is required"
    },
    {
      "field": "itemBuyingPrice",
      "message": "Buying price must be > 0"
    }
  ]
}

🔍 Key Design Decisions

1. Immutable Fields: itemEnteredByUser and itemEnteredDate are set once and never updated (audit trail)
2. Automatic Timestamps: itemEnteredDate uses @CreationTimestamp for automatic creation time
3. Transaction Management: Service layer is transactional to ensure data consistency
4. Separation of Concerns: Clear separation between Controller, Service, and Repository layers
5. Custom Validation: @ValidUser annotation for business-specific validation rules

🧪 Testing

Run tests with:

# Maven
mvn test

# Gradle
./gradlew test
``

## 🐛 Known Issues

- None currently

## 📞 Support

For issues or questions, please open an issue in the repository.