MyEclipse for Spring Reference – Annotations

1. Spring Annotations

The following sections detail each of the Spring annotations.

Note: Spring scaffolding requires a MyEclipse Spring or Bling subscription.

1.1 @Controller

The @Controller annotation is a specialized Spring stereotype  for Spring MVC web layer components. Java classes annotated  with @Controller are responsible for receiving requests from a web  client (typically from end-user generated events) and invoking a re quest handler, which orchestrates all server logic necessary for  processing the request.

Relevant configurations:

  • Bean name – If id or name not specified, defaults to class name. See bean name for more info.
  • Scope – If not specified, defaults to singleton. See @Scope for more info.

For more information, see @Controller in the Spring Framework – Reference documentation.

1.2 @Service

The @Service annotation is a specialized Spring stereotype for service layer components. POJOs  annotated with @Service are typically used to implement the business  logic.

The logic found in a typical web application is associated with  either (a) the behavior of the application or (b) the business logic. While a controller could technically be used to implement both the  behavior and business logic, the best practice is for the web layer to be focused on implementing the  behavior of the application, and the service layer focused on implementing  the business logic.

Relevant configurations:

  • Bean name – If id or name not specified, defaults to class name. See bean name for more info.
  • Scope – If not specified, defaults to singleton. See @Scope for more info.

For more information, see @Service in the Spring Framework – Reference documentation.

1.3 @Component

The @Component annotation is a Spring stereotype for general  purpose components, and they aren’t specific to a particular application layer. The @Component  annotation is used for POJOs that need to be managed by Spring, but  aren’t one of the more specialized components like @Controller, @Service or @Repository. A component isn’t tied to  any particular application  layer, and it can be used for many different purposes, including the definition of data transfer objects (DTOs) in the service layer or form backing objects in  the web layer.

Relevant configurations:

  • Bean name – If id or name not specified, defaults to class name. See bean name for more info.
  • Scope – If not specified, defaults to singleton. See @Scope for more info.

For more information, see @Component in the Spring Framework – Reference documentation.

1.4 @Repository

The @Repository annotation is a Spring stereotype for data access layer components. Data  access objects (DAO) is a pattern for separating data access logic  from business logic. Data access objects are  abstract representations of real databases (or persistence  mechanisms), and they manage persistence for a set of JPA entities (domain objects). When writing code to  read, write, delete and update persisted data objects, with DAO there  is no need to know the details of the database (vendor, version, IP, etc.).

For more information, see @Repository in the Spring Framework – Reference documentation.

1.5 Bean Name

An attribute on @Service, @Controller, @Component or @Repository annotations for uniquely  identify the bean. If the bean name and id are omitted, Spring generates a name from the class name. For an example how to reference a  bean by its bean name, see the @Resource annotation.

For more information, see Naming  Beans in the Spring Framework – Reference documentation.

1.6 @Scope

Scope is used to configure how a bean should be provisioned by  the Spring container. Spring web applications support several scopes, and below are some of the most commonly used scopes:

NameDescription
singletonOne single bean instance per Spring container; default scope for Spring
prototypeNew instance per bean request
requestOne bean instance per HTTP request; every request has a new bean instance
sessionOne bean instance per HTTP session; every session has a new bean instance

For more information, see Bean  Scopes in the Spring Framework – Reference documentation.

1.7 @RequestMapping

The @RequestMapping annotation is used to map incoming URLs to request handlers, which can  be a controller class or a controller method. When a request comes in  that matches the specified URL path or pattern, the respective Java  class/method is used to handle the request.

For more information, see @RequestMapping in the Spring Framework – Reference documentation.

1.7.1 Request Mapping URL

The request path (URL) or pattern that should be mapped to a class or method that’s configured to be a request handler (@RequestMapping).

1.7.2 Request Mapping Methods

The specific HTTP methods handled by a class or method that is configured to be a request handler (@RequestMapping).

Typical values:

  • GET – typically used to fetch data; data is passed in URL.
  • POST – used to update data on server; data is passed in body.
  • PUT – supported by HTTP; typically used only for REST-based request handlers.
  • DELETE – supported by HTTP; typically used only for REST-based request handlers.

1.7.3 ResponseBody

Indicates the return type should be written directly to the HTTP response body.

1.7.4 Parameters

Used to map a request parameter to an argument of a request handler. The @RequestParm annotation is applied on the method argument of a request handler. This provides the request handler with access to the request parameter. The Spring MVC framework automatically extracts and  convert the parameter to the method argument type.

1.8 @SessionAttributes

Specifies attributes that should be stored in session.

For more information, see @SessionAttributes in the Spring Framework – Reference documentation.

1.9 @InitBinder

Used to customize the data binding for a controller. The Spring MVC has some default data binding. Both the @RequestParam and  @ModelAttribute annotations convert (bind) the data to Java types, but  the converters can be customized by an @InitBinder annotated method in the controller.

For more information, see @InitBinder in the Spring Framework – Reference documentation.

1.9.1 InitBinder Name

This is a description of the @Controller annotation, with  links to Spring doc.

1.10 @ModelAttribute

The annotation has two purposes:

  • When the @ModelAttribute annotation is applied on a method parameter of  a request handler, it maps the model attribute (i.e., form backing  object) to a request handler input parameter. This can be used provide the request handler with access to the form backing  object. The Spring MVC framework automatically converts the  parameter to the method argument type.
  • When the @ModelAttribute annotation is applied on a controller method, the Spring MVC framework executes the method prior to  executing any request handlers. These methods typically load  reference data that is used by all request handlers in the  controller and/or views

For more information, see @ModelAttribute in the Spring Framework – Reference documentation.

1.10.1 ModelAttribute Name

The name of the model attribute. Used by Spring framework to identify form data or reference data.

1.11 @Resource

The @Resource annotation is a Java annotation (JSR-250)  supported by the Spring framework. The @Resource annotation is used for  injecting Spring managed beans (dependencies) into a Java class. The bean to be injected is identified by bean name. Spring also supports dependency injection using the @Autowired annoation.

For more information, see @Resource in the Spring Framework – Reference documentation.

1.12 @Autowired

The @Autowired annotation is a Spring annotation for injecting Spring managed beans into the current class.

For more information, see @Autowired in the Spring Framework – Reference documentation.

1.12.1 Autowired Required

This is an optional true/false attribute that specifies whether the autowiring should fail if the dependency cannot be resolved. If this attribute isn’t specified, Spring defaults to true by convention.

1.12.2 Name

Applies to both @Resource and @Autowired annotation. The name is used to provide the Spring Framework additional guidance on which Spring bean (by name) should be injected into the current class.

For more information, see @Resource in the Spring Framework – Reference documentation.

1.12.3 Qualifier

Qualifies the dependency resolution.

For more information, see @Qualifier in the Spring Framework – Reference documentation.

1.13 @Transactional

For more information, see @Transactional in the Spring Framework – Reference Documentation.

1.13.1 ReadOnly

Specifies a read-only  transaction.

1.13.2 Timeout

Specifies how  long a transaction can run before timing out.

1.13.3 Propagation

Specifies the transaction  propagation.

1.13.4 Isolation

Specifies the degree of isolation this transaction has from the work of other  transactions.

1.13.5 RollbackForName

The exception names that should trigger a transaction  rollback.

1.13.6 NoRollbackForName

The exception names that should not trigger a transaction  rollback.

1.13.7 RollbackForClass

Specifies the exceptions  that must cause a rollback.

1.13.8 NoRollbackForClass

Specifies the exceptions  that must not cause a rollback.


2. JAX-WS Annotations

The following sections detail each of the JAX-WS annotations.

2.1 @WebService

The @WebService annotation is used to identify Java classes that should be exposed as SOAP web service endpoints.

Relevant configurations:

  • Name – name of the web service; if omitted, defaults to class name
  • Namespace – XML namespace used for the WSDL and XML elements generated from this web service
  • Service Name – service name of the web service
  • Port Name – Name of the endpoint port
  • Service Mode – Indicates how the Provider implementation works with protocol messages, either Message or Payload
  • Binding Type – Indicates the binding used for a web service endpoint implementation
  • Handler Chain File – Indicates the use of a handler chain file to alter incoming and outgoing SOAP messages

2.2 @SOAPBinding

The @SOAPBinding annotation is used to map the web service to a SOAP binding.

Relevant configurations:

  • Style – encoding style (DOCUMENT or RPC) for messages sent to/from the web service; if omitted, defaults to DOCUMENT.
  • Use – formatting style (LITERAL or ENCODED) for messages sent to and from the web service; if omitted, defaults to LITERAL.
  • Parameter Style – speficies whether method parameters represent the entire message body (BARE), or whether the parameters are elements wrapped inside a top-level element named after the operation (WRAPPED); if omitted, defaults to WRAPPED.

2.3 @WebMethod

The @WebMethod annotation identifies methods that should be exposed as a web service operation.

Relevant configurations:

  • Name – name of the service operation; if omitted, defaults to method name.
  • Action – action for the operation

2.4 @RequestWrapper

The @RequestWrapper annotation is used to specify the JAXB generated request wrapper bean and the element name and namespace for marshalling / unmarshalling the bean.

Relevant configurations:

  • Name – local name of the element.
  • Name Space – namespace name of the element.
  • Class Name – name of the wrapper class.

2.5 @ResponseWrapper

The @ResponseWrapper annotation is used to specify the JAXB generated response wrapper bean and the element name and namespace for marshalling / unmarshalling the bean.

Relevant configurations:

  • Name – local name of the element.
  • Name Space – namespace name of the element.
  • Class Name – name of the wrapper class.

2.6 @WebParam

The @WebParam annotation is used to map Web Service parameters to method parameters.

Relevant configurations:

  • Name – name of the web service parameter; if omitted, defaults to method parameter name.
  • Part Name – used with RPC or DOCUMENT/BARE operations
  • Mode – flow direction for this paramter, either IN, OUT, or INOUT
  • Header – specifies if the parameter should be carried in the header
  • Name Space – XML namespace for the parameter; if omitted, defaults to @WebService targetNamespace.

2.7 @WebResult

The @WebResult annotation is used to map the method return type to a Web Service result

Relevant configurations:

  • Name – name of the web service result; if omitted, defaults to “return.”
  • Part Name – used with RPC or DOCUMENT/BARE operations
  • Header – specifies if the parameter should be carried in the header
  • Name Space – XML namespace for the parameter; if omitted, defaults to @WebService targetNamespace.


3. JPA Annotations

The following sections detail each of the JPA annotations.

3.1 @Basic

The @Basic annotation is used to specify the simplest mapping of an Entity property to a database column.

Relevant configurations:

For more information, see @Basic [JPA Ref] and JPA Wikibook.

3.2 @Cacheable

The @Cacheable annotation is used to specify whether an entity  should be cached. This annotation has an effect only if JPA  caching has been enabled.

Relevant configurations:

  • value – optional; TRUE or FALSE; specifies whether or not the entity should be cached; defaults to TRUE.

For more information, see @Cacheable [JPA Ref]

3.3 @Column

The @Column annotation is used to specify the mapped column for a persistent property. If no @Column annotation is specified, the default values apply.

Relevant configurations:

For more information, see @Column [JPA Ref] and JPA Wikibook.

3.3.1 name

Optional; the name of the database column; defaults to the name of the property of the entity class.

3.3.2. columnDefinition

Optional; the SQL fragment for generating DDL.

3.3.3 table

Optional; the database table that contains the column; defaults to the entity’s database table.

3.3.4 length

Optional; the column length; defaults to 255.

3.3.5 precision

Optional; precision for a decimal column; defaults to zero.

3.3.6 scale

Optional; scale for a decimal column; defaults to zero.

3.4 Common JPA properties

The following sections describe the common JPA properties.

3.4.1 insertable

Specifies if the column is included in SQL INSERT statements  generated by the persistence provider.

For more information, see JPA Wikibook.

3.4.2 nullable

Specifies if the database column is nullable.

3.4.3. updateable

Specifies if the column is included in SQL UPDATE statements  generated by the persistence provider.

For more information, see JPA Wikibook.

3.4.4 unique

Specifies if the column is a unique key.

3.4.5 cascade

Specifies the operations that must be cascaded to the target of the association.

Relevant configurations:

  • type – options are ALL, DETACH, MERGE, PERSIST, REFRESH, REMOVE

For more information see cascade [JPA Ref] and JPA Wikibook.

3.4.6 fetch

Specifies if the association should be lazily loaded or must be  eagerly fetched.

Relevant configurations:

  • type – options are EAGER, LAZY

For more information, see fetch [JPA Ref] and JPA Wikibook.

3.4.7 mappedBy

The field that owns the relationship.

3.4.8 optional

Defines whether the value of the field or property can be null

3.4.9 targetEntity

The entity class that is the target of the association.

3.5 @Embeddable

The @Embeddable annotation is used to specify a class that is part of an owning entity.

For more information, see @Embeddable [JPA Ref] and JPA Wikibook.

3.6 @EmbeddedId

The @EmbeddedId annotation is used to specify the composite primary key of an embedded class.

For more information, see @EmbeddedId [JPA Ref] and JPA Wikibook.

3.7 @Entity

The @Entity annotation is applied to a class that is to be persisted using JPA and specifies that the class is an entity.

Relevant configurations:

  • name – optional; the entity name to be used in queries. Defaults to the entity class name.

For more information, see @Entity [JPA Ref] and JPA Wikibook.

3.8 @EntityListeners

The @EntityListeners annotation specifies a callback listener class to be used for an entity or mapped super class to designate methods that should be executed during lifecycle events.

Relevant configurations:

  • value – required; the callback listener  classes

For more information, see @EntityListeners [JPA Ref].

3.9 @Enumerated

The @Enumerated annotation indcates that a persistent field should be persisted as an enumerated type.

Relevant configurations:

  • value – optional; the type used in mapping an enum type; ORDINAL or STRING; defaults to ORDINAL.

For more information, see @Enumerated [JPA Ref] and JPA Wikibook.

3.10 @ExcludeDefaultListeners

The @ExcludeDefaultListeners annotation specifies that the invocation of default listeners is to be excluded for the entity class or mapped superclass.

For more information, see @ExcludeDefaultListeners [JPA Ref].

3.11 @ExcludeSuperclassListeners

The @ExcludeSuperclassListeners annotation specifies that the invocation of superclass listeners is to be excluded for the entity class or mapped superclass.

For more information, see @ExcludeSuperclassListeners [JPA Ref].

3.12 @GeneratedValue

The @GeneratedValue annotation is used to specify the generation strategy of a primary key field of an entity.

Relevant configurations:

  • generator – optional; the generator to use; defaults to a generator specified by JPA provider.
  • strategy – optional; AUTO, TABLE, SEQUENCE, IDENTITY; defaults to AUTO.

For more information, see @GeneratedValue [JPA Ref] and JPA Wikibook.

3.13 @IdClass

The @IdClass annotation specifies the composite primary key class. A composite primary key class must be used when there are multiple primary key fields for an entity.

Relevant configurations:

  • name – the primary key class.

For more information, see @IdClass [JPA Ref] and JPA Wikibook.

3.14 @Id

The @Id annotation specifies the primary key of an entity.

For more information, see @Id [JPA Ref] and JPA Wikibook.

3.15 @Inheritence

The @Inheritence annotation is used to specify the inheritance strategy to be used for an entity class hierarchy. It is specified on the entity class that is the root of the entity class hierarchy.

Relevant configurations:

For more information, see @Inheritence [JPA Ref] and JPA Wikibook.

3.16 @JoinColumns

The @JoinColumns annotation is used to specify multiple join columns. It serves as a container for multiple instances of the @JoinColumn annotation.

Relevant configurations:

  • value – one or more @JoinColumn annotations.

For more information, see @JoinColumns [JPA Ref].

3.17 @JoinTable

The @JoinTable annotation is used to specify associations.

Relevant configurations:

  • catalog – optional; the catalog of the  table.
  • inverseJoinColumns – optional; the foreign key columns from the opposite relationship; an array of @JoinColumn.
  • joinColumns – optional; the foreign key columns from the owning relationship; an array of @JoinColumn.
  • name – optional; the name of the join table.
  • schema – optional; the schema of the table.
  • uniqueConstraints – optional; unique constraints.

For more information, see @JoinTable [JPA Ref].

3.18 @Lob

The @Lob annotation specifies that a persistent field should be persisted as a large object to a database-supported large object type.

For more information, see @Lob [JPA Ref] and JPA Wikibook.

3.19 @MapKey

The @MapKey annotation specifies the associated entity property used as the map key.

Relevant configurations:

  • name – optional

For more information, see @MapKey [JPA Ref] and JPA Wikibook.

3.20 @ManyToMany

The @ManyToMany annotation is used to specify a a many-valued association with many-to-many multiplicity.

Relevant configurations:

For more information, see @ManyToMany [JPA Ref] and JPA Wikibook.

3.21 @ManyToOne

The @ManyToOne annotation is used to specify a single-valued association to another entity class that has many-to-one multiplicity.

Relevant configurations:

For more information, see @ManyToOne [JPA Ref] and JPA Wikibook.

3.22 @NamedNativeQueries

The @NamedNativeQueries annotation specifies multiple named native queries. It serves as a container for multiple instances of the @NamedNativeQuery annotation.

Relevant configurations:

NamedNativeQuery[ ] – array of named native queries

For more information, see @NamedNativeQueries [JPA Ref] and JPA Wikibook.

3.23 @NamedNativeQuery

The @NamedNativeQuery annotation specifies a named native SQL query.

Relevant configurations:

  • Name – name used to refer to the query with the EntityManager methods that create query objects.
  • Query – The SQL query string.

For more information, see @NamedNativeQuery [JPA Ref] and JPA Wikibook.

3.24 @NamedQueries

The @NamedQueries specifies multiple JPA named queries. It serves as a container for multiple query instances of the @NamedQuery annotation.

Relevant configurations:

  • value – one or more NamedQuery annotations

For more information, see @NamedQueries [JPA Ref] and JPA Wikibook.

3.25 @NamedQuery

The @NamedQuery annotation is used to specify a pre-defined JPA named query for an entity.

Relevant configurations:

3.25.1 name

Optional; the name of the database column; defaults to the name of the property of the entity class.

3.25.2 columnDefinition

Optional; the SQL fragment for generating DDL.

3.25.3 table

optional; the database table that contains the column; defaults to the Entity’s database table

3.25.4 referencedColumnName

Optional; scale for a decimal column; defaults to zero.

3.25.5 query

Required; a JPA query language query.

3.25.6 hints

A collection of query hints (see @QueryHint).

For more information, see @NamedQuery [JPA Ref] and JPA Wikibook.

3.26 @MappedSuperClass

The @MappedSuperclass annotation is used to specify a class whose mapping information is applied to the entities that inherit from it.

For more information, see @MappedSuperClass [JPA Ref].

3.27 @OneToMany

The @OneToMany annotation is used to specofy a many-valued association with one-to-many multiplicity.

Relevant configurations:

For more information, see @OneToMany [JPA Ref] and JPA Wikibook.

3.28 @OneToOne

The @OneToOne annotation is used to specify a single-value association to another entity that has one-to-one multiplicity.

Relevant configurations:

For more information, see @OneToOne [JPA Ref] and JPA Wikibook.

3.29 @OrderBy

The @OrderBy annotation is used to specify the ordering of the elements at the point when the association or collection is retrieved.

Relevant configurations:

  • value – order by list

For more information, see @OrderBy [JPA Ref] and JPA Wikibook.

3.30 @QueryHint

The @QueryHint annotation is used to provide properties or hints to named queries.

Relevant configurations:

  • name – name of the hint.
  • value – value of the hint.

For more information, see @QueryHint [JPA Ref] and JPA Wikibook.

3.31 @Table

The @Table annotation specifies the primary database table for the annotated entity. The class is mapped to the specified table.

Relevant configurations:

  • name – optional; the database table name. Defaults to entity name.
  • catalog – optional; the database catalog name. Defaults to default catalog.
  • schema – optional; the database schema name. Defaults to default schema.

For more information, see @Table [JPA Ref] and JPA Wikibook.

3.32 @Temporal

The @Temporal annotation is used to specify persistent fields of type java.util.Date and java.util.Calendar.

Relevant configurations:

  • value – temporal type.

For more information, see @Temporal [JPA Ref] and JPA Wikibook.

3.33 @Transient

The @Transient annotation is used to specify that the property is not persistent.

For more information, see @Transient [JPA Ref] and JPA Wikibook.

3.34 @Version

The @Version annotation is used to specify the version field or property of an entity class that serves as its optimistic lock value.

For more information, see @Version [JPA Ref] and JPA Wikibook.