Spring Framework

https://docs.spring.io/spring-framework/reference/6.2
Admin
Spring Framework is a comprehensive programming and configuration model for modern Java-based...
Tokens:169,761
Snippets:1,575
Trust Score:10
Update:15 hours ago
Show doc for...
Tokens:
Raw
### @ConnectMapping

Source: https://docs.spring.io/spring-framework/reference/6.2/rsocket.html

Handles the SETUP frame at the start of an RSocket connection and subsequent metadata push notifications. Methods support the same arguments as @MessageMapping but based on metadata and data from SETUP and METADATA_PUSH frames. Cannot return data; must be declared with void or Mono<Void>.

```APIDOC
## @ConnectMapping

### Description
Handles the SETUP frame at the start of an RSocket connection and any subsequent metadata push notifications through the METADATA_PUSH frame. Methods support the same arguments as @MessageMapping but based on metadata and data from the SETUP and METADATA_PUSH frames. Can have a pattern to narrow handling to specific connections that have a route in the metadata; if no patterns are declared then all connections match.

### Method
Annotation on handler methods

### Usage
- Can be used on methods that handle SETUP and METADATA_PUSH frames.
- Methods cannot return data and must be declared with `void` or `Mono<Void>` as the return value.
- If handling returns an error for a new connection, the connection is rejected.
- Handling must not be held up to make requests to the `RSocketRequester` for the connection.

### Parameters
- Same arguments as @MessageMapping, based on metadata and data from the SETUP and METADATA_PUSH frames.
- Optional pattern to narrow handling to specific connections that have a route in the metadata.

### Return Value
- `void` or `Mono<Void>`
```

--------------------------------

### Output of the Boot application

Source: https://docs.spring.io/spring-framework/reference/6.2/core/beans/factory-extension.html

Example output showing the BeanPostProcessor message and the messenger's toString result.

```text
Bean 'messenger' created : org.springframework.scripting.groovy.GroovyMessenger@272961
org.springframework.scripting.groovy.GroovyMessenger@272961

```

--------------------------------

### fromServletMapping

Source: https://docs.spring.io/spring-framework/reference/6.2/web/webmvc/mvc-uri-building.html

Creates a URI relative to a Servlet (for example, '/main/*'), reusing scheme, host, port, context path, and Servlet mapping prefix. The example appends the path '/accounts' and builds the URI.

```APIDOC
## fromServletMapping

### Description
Creates a URI relative to a Servlet (for example, '/main/*'), reusing scheme, host, port, context path, and Servlet mapping prefix. The example appends the path '/accounts' and builds the URI.

### Method
Builder method

### Endpoint
ServletUriComponentsBuilder.fromServletMapping(HttpServletRequest request)

### Parameters
#### Method Parameters
- **request** (HttpServletRequest) - Required - The current HTTP request.

### Request Example
```java
HttpServletRequest request = ...
URI uri = ServletUriComponentsBuilder.fromServletMapping(request)
    .path("/accounts")
    .build()
    .toUri();
```

### Response
#### Success Response
- **uri** (URI) - The built URI relative to the servlet mapping.

#### Response Example
```java
URI uri = ...
```
```

--------------------------------

### Using regex in URI variables (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/web/webflux/controller/ann-requestmapping.html

Kotlin version of the regex URI variable example.

```kotlin
@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
fun handle(@PathVariable version: String, @PathVariable ext: String) {
	// ...
}
```

--------------------------------

### ServletThrowsAdviceWithArguments Kotlin example

Source: https://docs.spring.io/spring-framework/reference/6.2/core/aop-api/advice.html

Kotlin version of the throws advice with four arguments to access method, args, target, and exception.

```kotlin
class ServletThrowsAdviceWithArguments : ThrowsAdvice {

	fun afterThrowing(m: Method, args: Array<Any>, target: Any, ex: ServletException) {
		// Do something with all arguments
	}
}
```

--------------------------------

### Using custom @Offline annotation (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/core/beans/classpath-scanning.html

Kotlin version of the custom @Offline annotation example.

```kotlin
@Component
@Offline
class CachingMovieCatalog : MovieCatalog {
	// ...
}
```

--------------------------------

### Using custom @Genre("Action") annotation (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/core/beans/classpath-scanning.html

Kotlin version of the custom @Genre annotation example.

```kotlin
@Component
@Genre("Action")
class ActionMovieCatalog : MovieCatalog {
	// ...
}
```

--------------------------------

### Kotlin: PersonService interface and implementation

Source: https://docs.spring.io/spring-framework/reference/6.2/core/aop/schema.html

Kotlin version of the PersonService interface and its default implementation used in the around advice example.

```kotlin
package com.xyz.service

interface PersonService {

	fun getPerson(personName: String, age: Int): Person
}

class DefaultPersonService : PersonService {

	fun getPerson(name: String, age: Int): Person {
		return Person(name, age)
	}
}
```

--------------------------------

### IntroductionAdvisor and IntroductionInfo interfaces

Source: https://docs.spring.io/spring-framework/reference/6.2/core/aop-api/advice.html

Introduction advice uses IntroductionAdvisor, which has getClassFilter() and validateInterfaces() methods. IntroductionInfo provides getInterfaces() to return the introduced interfaces.

```java
public interface IntroductionAdvisor extends Advisor, IntroductionInfo {

	ClassFilter getClassFilter();

	void validateInterfaces() throws IllegalArgumentException;
}

public interface IntroductionInfo {

	Class<?>[] getInterfaces();
}
```

--------------------------------

### @MatrixVariable basic usage

Source: https://docs.spring.io/spring-framework/reference/6.2/web/webmvc/mvc-controller/ann-methods/matrix-variables.html

Shows how to bind a matrix variable from a path segment using @MatrixVariable. The example maps GET /pets/42;q=11;r=22 to a method that receives petId and q.

```APIDOC
## GET /pets/{petId}

### Description
Binds a matrix variable from the path segment to a method parameter using @MatrixVariable.

### Method
GET

### Endpoint
/pets/{petId}

### Parameters
#### Path Parameters
- **petId** (String) - Required - The pet identifier.

#### Matrix Variables
- **q** (int) - Required - The matrix variable value.

### Request Example
GET /pets/42;q=11;r=22

### Response
No response body (void).
```

--------------------------------

### Convention over configuration with @WebAppConfiguration and @ContextConfiguration (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/testing/testcontext-framework/ctx-management/web.html

Kotlin version of the convention over configuration example, using @WebAppConfiguration without a path and @ContextConfiguration without explicit locations.

```kotlin
@ExtendWith(SpringExtension::class)

// defaults to "file:src/main/webapp"
@WebAppConfiguration

// detects "WacTests-context.xml" in the same package
// or static nested @Configuration classes
@ContextConfiguration
class WacTests {
	//...
}
```

--------------------------------

### XML configuration for declarative transactions

Source: https://docs.spring.io/spring-framework/reference/6.2/data-access/transaction/declarative/first-example.html

Configures the service bean, transaction advice, pointcut, DataSource, and TransactionManager. The advice defines read-only semantics for methods starting with 'get' and default settings for others. The pointcut applies to all methods of FooService.

```xml
<!-- from the file 'context.xml' -->
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:aop="http://www.springframework.org/schema/aop"
	xmlns:tx="http://www.springframework.org/schema/tx"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/tx
		https://www.springframework.org/schema/tx/spring-tx.xsd
		http://www.springframework.org/schema/aop
		https://www.springframework.org/schema/aop/spring-aop.xsd">

	<!-- this is the service object that we want to make transactional -->
	<bean id="fooService" class="x.y.service.DefaultFooService"/>

	<!-- the transactional advice (what 'happens'; see the <aop:advisor> bean below) -->
	<tx:advice id="txAdvice" transaction-manager="txManager">
		<!-- the transactional semantics... -->
		<tx:attributes>
			<!-- all methods starting with 'get' are read-only -->
			<tx:method name="get*" read-only="true"/>
			<!-- other methods use the default transaction settings (see below) -->
			<tx:method name="*"/>
		</tx:attributes>
	</tx:advice>

	<!-- ensure that the above transactional advice runs for any execution
		of an operation defined by the FooService interface -->
	<aop:config>
		<aop:pointcut id="fooServiceOperation" expression="execution(* x.y.service.FooService.*(..))"/>
		<aop:advisor advice-ref="txAdvice" pointcut-ref="fooServiceOperation"/>
	</aop:config>

	<!-- don't forget the DataSource -->
	<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
		<property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/>
		<property name="url" value="jdbc:oracle:thin:@rj-t42:1521:elvis"/>
		<property name="username" value="scott"/>
		<property name="password" value="tiger"/>
	</bean>

	<!-- similarly, don't forget the TransactionManager -->
	<bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
		<property name="dataSource" ref="dataSource"/>
	</bean>

	<!-- other <bean/> definitions here -->

</beans>
```

--------------------------------

### PersonForm model with Bean Validation constraints (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/core/validation/beanvalidation.html

Kotlin version of PersonForm with @get:NotNull, @get:Size(max=64) on name and @get:Min(0) on age.

```kotlin
class PersonForm(
	@get:NotNull @get:Size(max=64)
	private val name: String,
	@get:Min(0)
	private val age: Int
)
```

--------------------------------

### DateFormatter Example

Source: https://docs.spring.io/spring-framework/reference/6.2/core/validation/format.html

An example Formatter implementation that formats and parses java.util.Date objects using a specified date pattern.

```APIDOC
## DateFormatter Example

### Description
`DateFormatter` is an example `Formatter` implementation that formats and parses `java.util.Date` objects using a specified date pattern. It is provided in both Java and Kotlin.

### Java Implementation
```java
package org.springframework.format.datetime;

public final class DateFormatter implements Formatter<Date> {

	private String pattern;

	public DateFormatter(String pattern) {
		this.pattern = pattern;
	}

	public String print(Date date, Locale locale) {
		if (date == null) {
			return "";
		}
		return getDateFormat(locale).format(date);
	}

	public Date parse(String formatted, Locale locale) throws ParseException {
		if (formatted.length() == 0) {
			return null;
		}
		return getDateFormat(locale).parse(formatted);
	}

	protected DateFormat getDateFormat(Locale locale) {
		DateFormat dateFormat = new SimpleDateFormat(this.pattern, locale);
		dateFormat.setLenient(false);
		return dateFormat;
	}
}
```

### Kotlin Implementation
```kotlin
class DateFormatter(private val pattern: String) : Formatter<Date> {

	override fun print(date: Date, locale: Locale)
			= getDateFormat(locale).format(date)

	@Throws(ParseException::class)
	override fun parse(formatted: String, locale: Locale)
			= getDateFormat(locale).parse(formatted)

	protected fun getDateFormat(locale: Locale): DateFormat {
		val dateFormat = SimpleDateFormat(this.pattern, locale)
		dateFormat.isLenient = false
		return dateFormat
	}
}
```

### Methods
- `print(Date date, Locale locale)` - Returns a formatted string for the given date, or an empty string if the date is null.
- `parse(String formatted, Locale locale)` - Parses the given formatted string into a Date, or returns null if the string is empty.
- `getDateFormat(Locale locale)` - Returns a `DateFormat` configured with the pattern and locale, with lenient parsing disabled.
```

--------------------------------

### Boot application (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/core/beans/factory-extension.html

Kotlin version of the Boot application that loads the XML context and prints the messenger bean.

```kotlin
import org.springframework.beans.factory.getBean

fun main() {
	val ctx = ClassPathXmlApplicationContext("scripting/beans.xml")
	val messenger = ctx.getBean<Messenger>("messenger")
	println(messenger)
}

```

--------------------------------

### Explicit resource semantics with @WebAppConfiguration and @ContextConfiguration (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/testing/testcontext-framework/ctx-management/web.html

Kotlin version of the explicit resource semantics example, using 'classpath:' for @WebAppConfiguration and 'file:' for @ContextConfiguration.

```kotlin
@ExtendWith(SpringExtension::class)

// classpath resource
@WebAppConfiguration("classpath:test-web-resources")

// file system resource
@ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml")
class WacTests {
	//...
}
```

--------------------------------

### Default resource semantics with @WebAppConfiguration and @ContextConfiguration (Kotlin)

Source: https://docs.spring.io/spring-framework/reference/6.2/testing/testcontext-framework/ctx-management/web.html

Kotlin version of the default resource semantics example, with @WebAppConfiguration using a file system path and @ContextConfiguration using a classpath location.

```kotlin
@ExtendWith(SpringExtension::class)

// file system resource
@WebAppConfiguration("webapp")

// classpath resource
@ContextConfiguration("/spring/test-servlet-config.xml")
class WacTests {
	//...
}
```

--------------------------------

### getForObject

Source: https://docs.spring.io/spring-framework/reference/6.2/integration/rest-clients.html

Retrieves a representation via GET.

```APIDOC
## getForObject

### Description
Retrieves a representation via GET.

### Method
GET

### Endpoint
(URI provided as argument)

### Parameters
- **url** (String or URI) - Required - The URL to retrieve.
- **responseType** (Class) - Required - The type of the response body.
- **uriVariables** (Object... or Map) - Optional - URI template variables.

### Response
Returns the representation of the resource as an object of the specified type.

```

--------------------------------

### getForEntity

Source: https://docs.spring.io/spring-framework/reference/6.2/integration/rest-clients.html

Retrieves a ResponseEntity (status, headers, and body) by using GET.

```APIDOC
## getForEntity

### Description
Retrieves a ResponseEntity (status, headers, and body) by using GET.

### Method
GET

### Endpoint
(URI provided as argument)

### Parameters
- **url** (String or URI) - Required - The URL to retrieve.
- **responseType** (Class) - Required - The type of the response body.
- **uriVariables** (Object... or Map) - Optional - URI template variables.

### Response
Returns a ResponseEntity containing status, headers, and body.

```

--------------------------------

### fromContextPath

Source: https://docs.spring.io/spring-framework/reference/6.2/web/webmvc/mvc-uri-building.html

Creates a URI relative to the context path, reusing scheme, host, port, and context path. The example appends the path '/accounts' and builds the URI.

```APIDOC
## fromContextPath

### Description
Creates a URI relative to the context path, reusing scheme, host, port, and context path. The example appends the path '/accounts' and builds the URI.

### Method
Builder method

### Endpoint
ServletUriComponentsBuilder.fromContextPath(HttpServletRequest request)

### Parameters
#### Method Parameters
- **request** (HttpServletRequest) - Required - The current HTTP request.

### Request Example
```java
HttpServletRequest request = ...
URI uri = ServletUriComponentsBuilder.fromContextPath(request)
    .path("/accounts")
    .build()
    .toUri();
```

### Response
#### Success Response
- **uri** (URI) - The built URI relative to the context path.

#### Response Example
```java
URI uri = ...
```
```

--------------------------------

### ResponseEntity with @GetMapping

Source: https://docs.spring.io/spring-framework/reference/6.2/web/webflux/controller/ann-methods/responseentity.html

Example of a controller method returning a ResponseEntity with a body and ETag header.

```APIDOC
## ResponseEntity with @GetMapping

### Description
Returns a ResponseEntity with a body and an ETag header from a GET endpoint.

### Method
GET

### Endpoint
/something

### Parameters
No parameters documented.

### Request Example
No request body.

### Response
#### Success Response (200)
- **body** (String) - The response body.
- **ETag** (String) - The ETag header value.

#### Response Example
```
HTTP/1.1 200 OK
ETag: <etag>

<body>
```
```

--------------------------------

### Boot application (Java)

Source: https://docs.spring.io/spring-framework/reference/6.2/core/beans/factory-extension.html

Java application that loads the XML context, retrieves the 'messenger' bean, and prints it. The output shows the BeanPostProcessor message and the messenger's toString.

```java
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.scripting.Messenger;

public final class Boot {

	public static void main(final String[] args) throws Exception {
		ApplicationContext ctx = new ClassPathXmlApplicationContext("scripting/beans.xml");
		Messenger messenger = ctx.getBean("messenger", Messenger.class);
		System.out.println(messenger);
	}

}

```

--------------------------------

### CombinedThrowsAdvice Kotlin example

Source: https://docs.spring.io/spring-framework/reference/6.2/core/aop-api/advice.html

Kotlin version of the combined throws advice handling both RemoteException and ServletException.

```kotlin
class CombinedThrowsAdvice : ThrowsAdvice {

	fun afterThrowing(ex: RemoteException) {
		// Do something with remote exception
	}

	fun afterThrowing(m: Method, args: Array<Any>, target: Any, ex: ServletException) {
		// Do something with all arguments
	}
}
```

--------------------------------

### IntroductionInterceptor interface

Source: https://docs.spring.io/spring-framework/reference/6.2/core/aop-api/advice.html

Defines the interface for introduction advice. The invoke() method must handle method calls on introduced interfaces and cannot call proceed().

```java
public interface IntroductionInterceptor extends MethodInterceptor {

	boolean implementsInterface(Class intf);
}
```

--------------------------------

### ServletThrowsAdviceWithArguments Java example

Source: https://docs.spring.io/spring-framework/reference/6.2/core/aop-api/advice.html

Throws advice with four arguments to access the invoked method, method arguments, and target object. Invoked when a ServletException is thrown.

```java
public class ServletThrowsAdviceWithArguments implements ThrowsAdvice {

	public void afterThrowing(Method m, Object[] args, Object target, ServletException ex) {
		// Do something with all arguments
	}
}
```

--------------------------------

### Return ResponseEntity with status and headers

Source: https://docs.spring.io/spring-framework/reference/6.2/web/webmvc/mvc-controller/ann-methods/responseentity.html

Example of a controller method returning a ResponseEntity with a custom ETag header and body.

```APIDOC
## GET /something

### Description
Returns a ResponseEntity with a custom ETag header and a body. The body is typically rendered to JSON by an HttpMessageConverter.

### Method
GET

### Endpoint
/something

### Response
#### Success Response (200)
- **body** (String) - The response body.
- **ETag** (String) - The ETag header value.

#### Response Example
```
HTTP/1.1 200 OK
ETag: <etag>
Content-Type: application/json

{"body": "..."}
```
```
Tokens:
Raw