🔄 Hibernate Annotations
These annotations are used for Object-Relational Mapping (ORM) in Hibernate and JPA-based applications.
1. @Entity
-
What: @Entity is a JPA (Java Persistence API) annotation used to mark a class as a persistent entity, meaning the class is mapped to a table in a relational database. Hibernate uses this annotation to recognize which classes should be stored in the database..
-
Why: Enables Hibernate to persist the object in the DB.
-
Where: On top of POJO class.
-
When: When creating a model mapped to a database table.
2. @Table(name = "table_name")
-
What: @Table is a JPA annotation used to explicitly specify the name of the database table that an @Entity class should map to.
If this annotation is not used, the table name is assumed to be the same as the entity class name by default.
-
Why: To map the class to a specific table.
-
Where: On top of the entity class.
-
When: When table name differs from the class name.
3. @Id
-
What: Marks the primary key of the entity.
-
Why: Hibernate requires a unique identifier for persistence.
-
Where: On a field of the entity class.
-
When: For any field acting as a primary key.
4. @GeneratedValue
-
What: Specifies how the primary key is generated.
-
Why: For auto-increment or sequence-based IDs.
-
Where: Along with @Id.
-
When: When the DB should generate IDs.
5. @Column
-
What: Maps a field to a table column.
-
Why: To customize the column mapping (name, length, nullable).
-
Where: On entity fields.
-
When: For customization or matching different DB column names.
6. @OneToOne, @OneToMany, @ManyToOne, @ManyToMany
🔹 What:
These annotations define associations between two entity classes. They instruct Hibernate (and JPA) on how to map object relationships to database relationships, especially foreign keys.
📌 Why:
In relational databases:
These annotations bridge the gap between object-oriented programming and relational models (ORM - Object Relational Mapping).
🧭 Where:
-
Place on fields inside entity classes.
-
Often combined with @JoinColumn, @JoinTable, mappedBy, cascade, and fetch.
🕒 When to Use:
Use these when your domain model has real-world relationships:
-
Employee belongs to one Department: @ManyToOne
-
Department has many Employees: @OneToMany
-
A User has one Profile: @OneToOne
-
Students can enroll in many Courses: @ManyToMany
📘 Detailed Annotations
✅ @OneToOne
➤ Description:
Defines a one-to-one relationship between two entities.
➤ Example:
➤ Use Case:
✅ @OneToMany
➤ Description:
Defines a one-to-many relationship — one entity is related to multiple instances of another entity.
➤ Example:
Note: mappedBy tells Hibernate that the foreign key resides in the Employee entity.
✅ @ManyToOne
➤ Description:
Defines a many-to-one relationship — many instances relate to one instance of another entity.
➤ Example:
Typically used in the child or owning side of a bidirectional relationship.
✅ @ManyToMany
➤ Description:
Defines a many-to-many relationship — both sides can relate to multiple instances of the other.
➤ Example:
This creates a join table student_course with 2 foreign keys.
📌 Additional Attributes
-
mappedBy: Indicates the field that owns the relationship (used in bidirectional mapping).
-
cascade: Enables cascading operations like PERSIST, MERGE, REMOVE.
-
fetch: Defines loading strategy (FetchType.LAZY or FetchType.EAGER).
🧪 Summary Table
| Annotation | Cardinality | Example Use Case |
|---|
@OneToOne | 1 ↔ 1 | User ↔ Profile |
@OneToMany | 1 ↔ Many | Department ↔ Employees |
@ManyToOne | Many ↔ 1 | Employee ↔ Department |
@ManyToMany | Many ↔ Many | Student ↔ Course |
7. @JoinColumn
-
What: Specifies the foreign key column.
-
Why: For explicitly naming and customizing joins.
-
Where: On relational fields.
-
When: In associations.
8. @Lob
-
What: Maps large objects like BLOB or CLOB.
-
Why: For storing large text/images.
-
Where: On entity fields.
-
When: For binary or large content.
9. @Temporal
-
What: Maps java.util.Date or Calendar to SQL date/time.
-
Why: To handle date types properly.
-
Where: On date/time fields.
-
When: When storing time-sensitive data.
10. @Transient
-
What: Excludes a field from persistence.
-
Why: For non-persistent calculated or helper fields.
-
Where: On entity fields.
-
When: When field should not be saved to DB.
⚙️ Kafka Annotations in Spring Boot
1.@KafkaListener
✅ What: @KafkaListener is a Spring annotation used to designate a method as a Kafka message consumer.
✅ Why:
-
Automates the message consumption process from a Kafka topic.
-
Eliminates the need to manually poll the topic.
-
Supports batch consumption, filtering, error handling, concurrency, etc.
✅ Where:
✅ When:
🧩 Example:
2. @KafkaHandler
✅ What
@KafkaHandler is used to handle multiple message types (i.e., method overloading) within a single Kafka consumer class that is annotated with class-level @KafkaListener.
✅ Why
-
Kafka normally maps one listener method to one topic. But when you want to consume different object types from the same topic, @KafkaHandler allows handling them in separate methods.
-
This is useful for polymorphic deserialization — messages are deserialized to different POJOs based on type.
✅ Where
-
Used on multiple methods inside a class that has a class-level @KafkaListener.
-
Each method has a unique parameter type (POJO, String, etc.).
✅ When
Use @KafkaHandler:
-
When you want a single Kafka consumer to process different message types from a single topic.
-
When working with message classes like OrderCreated, OrderCancelled, etc., all published to the same topic.
✅ Example
Suppose you have a topic named "events" that sends different message types:
✅ POJO Classes
✅ Kafka Consumer with @KafkaHandler
🔧 Required Configuration for Deserialization
You must configure a message converter to automatically convert JSON messages to their respective Java objects:
3. @SendTo
-
What: Sends reply to another topic.
-
Why: For request-reply patterns.
-
Where: On Kafka consumer methods.
-
When: When response is needed after processing.
4. @EnableKafka
✅ What
@EnableKafka is a Spring annotation that enables support for Kafka listener annotations like @KafkaListener, @KafkaHandler, etc.
✅ Why
By default, Spring Boot does not scan or activate Kafka listener infrastructure.
-
This annotation registers the Kafka listener container factory and related beans in the Spring context.
-
Without @EnableKafka, your @KafkaListener methods will be ignored and not invoked, even if correctly defined.
✅ Where
-
On a Java configuration class (annotated with @Configuration).
-
Typically, the class where you define Kafka-related beans like ConsumerFactory, ConcurrentKafkaListenerContainerFactory, etc.
✅ When
-
Once per application, typically at startup.
-
Required only if you use annotation-based Kafka listeners, like @KafkaListener.
✅ Example
📄 Kafka Configuration Class
This is the minimum requirement to allow Spring to detect and activate Kafka listener methods.
🧠 Behind the Scenes
Internally, @EnableKafka:
-
Registers a KafkaListenerAnnotationBeanPostProcessor.
-
That bean processes all @KafkaListener annotations during application context initialization.
-
It then creates Kafka listener containers for each listener method.
Without this setup, message consumption won't happen even if topics are available and properly configured.
🔧 Typically used alongside
You usually combine @EnableKafka with Kafka consumer configurations like:
✅ Summary Table
| Attribute | Description |
|---|
| What | Enables Spring to detect and process Kafka-related annotations |
| Why | Required to make @KafkaListener, @KafkaHandler work |
| Where | In a @Configuration class |
| When | Once per application — at app configuration/startup |
🧱 Microservices Related Annotations
1. @EnableDiscoveryClient
-
What: @EnableDiscoveryClient is a Spring Cloud annotation that enables service registration and discovery capabilities in a Spring Boot application.
It tells the application to register itself with a Discovery Server like:
-
Why: To register microservices with Eureka/Consul.
-
Where: On Spring Boot app class.
-
When: When using service discovery.
@SpringBootApplication
@EnableDiscoveryClient
public class OrderServiceApplication {
public static void main(String[] args) {
SpringApplication.run(OrderServiceApplication.class, args);
}
}
2. @LoadBalanced
It allows the client to resolve service names (like http://order-service) into actual instances using the service discovery registry (like Eureka or Consul).
In microservices, multiple instances of the same service may be running for scalability and resilience. Instead of hardcoding IPs or ports, you use the service name:
3. @EnableFeignClients
@EnableFeignClients is a Spring Cloud annotation that enables the use of Feign, a declarative HTTP client, in your Spring Boot application.
It scans your project for interfaces annotated with @FeignClient and auto-generates implementations that handle HTTP requests to other microservices.
-
Why: To simplify inter-service HTTP calls.
-
Where: On main Spring Boot app or config class.
-
When: When using Feign clients.
@SpringBootApplication
@EnableFeignClients
public class UserServiceApplication {
public static void main(String[] args) {
SpringApplication.run(UserServiceApplication.class, args);
}
}
4. @FeignClient(name = "user-service")
✅ What
@FeignClient is a Spring Cloud annotation used to declare an interface as a REST client for another microservice.
It tells Spring to generate a proxy implementation of the interface that:
-
Automatically resolves the service name (user-service) using a discovery client (like Eureka)
-
Sends HTTP requests to the corresponding service
-
Handles serialization and deserialization of request/response data
✅ Why
Using @FeignClient simplifies HTTP communication between microservices by:
-
Eliminating manual RestTemplate setup
-
Avoiding repetitive HTTP call code
-
Supporting fallback mechanisms with Resilience4j or Hystrix
-
Integrating easily with Spring Cloud components (like Eureka, Ribbon/Spring LoadBalancer)
✅ Where
Place @FeignClient(name = "user-service"):
✅ When
Use @FeignClient:
-
When your service calls another microservice over HTTP
-
When using Eureka/Consul for dynamic service discovery
-
When you want clean, type-safe, declarative HTTP calls
✅ Example Usage
Let’s say your order-service wants to fetch user info from user-service.
1. 📄 Enable Feign Clients
2. 📄 Define Feign Client Interface
5. @CircuitBreaker, @Retry, @RateLimiter, @Bulkhead
What: Provide fault tolerance and resilience.
Why: To handle microservice failures gracefully.
Where: On service methods.
When: For timeout handling, retries, etc.
(from Resilience4j, a lightweight fault tolerance library)
These annotations help microservices stay resilient under failure, load, or latency by offering fault tolerance patterns like circuit breakers, retries, rate limiting, and thread isolation.
✅ A. @CircuitBreaker
🔹 What
Monitors the failure rate of a method and opens the circuit if the failure threshold is breached. Prevents further calls until the service is considered healthy again.
🔹 Why
To avoid repeated failed calls to a service that’s down or slow, improving system stability and responsiveness.
🔹 Where
On service methods that call remote services (e.g., REST APIs via Feign or RestTemplate).
🔹 When
Use it when calling unreliable downstream services.
✅ Example:
🔹 Configuration (in application.yml)
✅ B. @Retry
🔹 What
Automatically retries a failed method a fixed number of times.
🔹 Why
To handle temporary failures (e.g., network issues, service timeouts) without failing immediately.
🔹 Where
On methods calling remote services.
🔹 When
Use when there’s a high probability of transient failure that can be resolved with a retry.
✅ Example:
🔹 Configuration:
✅ C. @RateLimiter
🔹 What
Limits the rate of method invocations.
🔹 Why
To protect your service from being overwhelmed by too many requests in a short period.
🔹 Where
On methods that can tolerate throttling, such as public APIs or heavy DB operations.
🔹 When
Use when you need to control traffic to prevent overloading the system.
✅ Example:
🔹 Configuration:
✅ D. @Bulkhead
🔹 What
Limits the number of concurrent calls to a method, isolating failures.
🔹 Why
To prevent resource exhaustion (e.g., thread or memory) by restricting how many requests can be processed in parallel.
🔹 Where
On high-latency or high-resource methods.
🔹 When
Use when you need to isolate components to contain failure to a specific section of the system.
✅ Example:
🔹 Configuration:
🔄 Summary Table
| Annotation | Purpose | Use Case |
|---|
@CircuitBreaker | Prevents repeated failed calls | Unstable or flaky downstream service |
@Retry | Retries failed calls automatically | Temporary issues (e.g., timeouts) |
@RateLimiter | Controls number of calls per second | Public APIs, database-intensive operations |
@Bulkhead | Limits concurrent executions | Protect system from thread starvation |
🛠️ Dependencies
To use these annotations, add the following dependency:
