Spring Boot allows for the creation of "starters:" Convenient dependency descriptors that often provide some specific but complex functionality. Examples from Spring Boot discussed in this series of articles include spring-boot-starter-web, spring-boot-starter-thymeleaf, and spring-boot-starter-actuator.
This article describes some reusable code targeted for development and testing (a REST controller @ /jig/bean/{name}.json and /jig/bean/{name}.xml) and the steps necessary to create a Spring Boot starter. It also describes a starter for the embedded MySQL server process described in "Spring Embedded MySQL Server".
Complete javadoc is provided.
Theory of Operation
As discussed in part 1, the spring-boot-starter-actuator may be configured. One of its sevices may be used to get the list (with attributes) of the configured beans. Sample partial output below:
$ curl -is -X GET http://localhost:5001/actuator/beans/
HTTP/1.1 200
Content-Type: application/vnd.spring-boot.actuator.v3+json
Transfer-Encoding: chunked
Date: Sun, 19 Jul 2020 20:22:10 GMT
{
"contexts" : {
"application" : {
"beans" : {
...
"discoveryService" : {
"scope" : "singleton",
"type" : "upnp.DiscoveryService",
"resource" : "file [/Users/ball/upnp-media-server/target/classes/upnp/DiscoveryService.class]",
"dependencies" : [ "mediaServer" ]
},
...
},
"parentId" : null
}
}
}
The ball-spring-jig-starter will provide the following two REST APIs to retrieve a specific bean's value and demonstrate serialization to JSON or XML as appropriate. JSON partial output:
$ curl -is -X GET http://localhost:5000/jig/bean/discoveryService.json
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 19 Jul 2020 20:23:38 GMT
{
"uuid:00000000-0000-1010-8000-0024BEF18BCC" : {
"expiration" : 1595191949391,
"ssdpmessage" : {
"params" : { },
"entity" : null,
"locale" : null,
"inetAddress" : "10.0.1.9",
"st" : "uuid:00000000-0000-1010-8000-0024BEF18BCC",
"location" : "http://10.0.1.9:52323/dmr.xml",
"usn" : "uuid:00000000-0000-1010-8000-0024BEF18BCC",
"protocolVersion" : {
"protocol" : "HTTP",
"major" : 1,
"minor" : 1
},
...
},
...
},
...
}
And corresponding XML output:
$ curl -is -X GET http://localhost:5000/jig/bean/discoveryService.xml
HTTP/1.1 200
Content-Type: application/xml
Transfer-Encoding: chunked
Date: Sun, 19 Jul 2020 20:29:47 GMT
<DiscoveryService>
<uuid:00000000-0000-1010-8000-0024BEF18BCC>
<expiration>1595192286661</expiration>
<ssdpmessage>
<params/>
<entity/>
<locale/>
<inetAddress>10.0.1.9</inetAddress>
<st>uuid:00000000-0000-1010-8000-0024BEF18BCC</st>
<location>http://10.0.1.9:52323/dmr.xml</location>
<usn>uuid:00000000-0000-1010-8000-0024BEF18BCC</usn>
<protocolVersion>
<protocol>HTTP</protocol>
<major>1</major>
<minor>1</minor>
</protocolVersion>
...
</ssdpmessage>
</uuid:00000000-0000-1010-8000-0024BEF18BCC>
...
</DiscoveryService>
The implementation is described in the next section.
Implementation
The steps to create the "jig" starter:
Implement the REST controller
Create a project and POM for the starter artifact
Create the auto-configuration class(es)
Link the auto-configuration class(es) into the starter's
META-INF/spring.factoriesresource1
The BeanRestController implementation is shown below.
@RestController
@RequestMapping(value = { "/jig/bean/" })
@ResponseBody
@NoArgsConstructor @ToString @Log4j2
public class BeanRestController implements ApplicationContextAware {
private ApplicationContext context = null;
@Override
public void setApplicationContext(ApplicationContext context) {
this.context = context;
}
@RequestMapping(method = { GET }, value = { "{name}.json" }, produces = APPLICATION_JSON_VALUE)
public Object json(@PathVariable String name) throws Exception {
return context.getBean(name);
}
@RequestMapping(method = { GET }, value = { "{name}.xml" }, produces = APPLICATION_XML_VALUE)
public Object xml(@PathVariable String name) throws Exception {
return context.getBean(name);
}
@ExceptionHandler({ NoSuchBeanDefinitionException.class, NoSuchElementException.class })
@ResponseStatus(value = NOT_FOUND, reason = "Resource not found")
public void handleNOT_FOUND() { }
}
Its implementation is straightforward: A method each to look-up the requested bean and then serialize to JSON and XML.
In the project for the starter, add the AutoConfiguration class.
@Configuration
@ConditionalOnClass({ BeanRestController.class })
@Import({ BeanRestController.class })
@NoArgsConstructor @ToString @Log4j2
public class AutoConfiguration {
}
It is critical that @Configuration classes are added through @Import annotations and not @ComponentScan Neither the starter author nor the integrator will be able to predict what components will or will not be included in a scan.
It is a good practice to include a "conditional-on" annotation (e.g., @ConditionalOnClass to test any required dependency software has been configured and/or is on the class path.
Finally, META-INF/spring.factories must be configured in the starter JAR to notify Spring Boot to add the AutoConfiguration.
org.springframework.boot.autoconfigure.EnableAutoConfiguration: ball.spring.jig.autoconfigure.AutoConfiguration
Creating a starter for the embedded MySQL process described in "Spring Embedded MySQL Server" is equally straightforward. Its AutoConfiguration class is shown below:
@Configuration
@ConditionalOnClass({ MysqldConfiguration.class })
@Import({ EntityManagerFactoryComponent.class, MysqldConfiguration.class })
@NoArgsConstructor @ToString @Log4j2
public class AutoConfiguration {
}
With it corresponding META-INF/spring.factories:
org.springframework.boot.autoconfigure.EnableAutoConfiguration: ball.spring.mysqld.autoconfigure.AutoConfiguration
Summary
Creating a Spring Boot starter is straightfoward: Create a project/POM to host the starter's dependencies and auto-configuration class(es), add the annotated auto-configuration class(es), and configure the starter JAR's META-INF/spring.factories with the auto-configuration class(es). That starter's functionality can then be added to a Spring Boot application simply by including a single dependency in the application POM.
[1] Many Spring Boot components provide separate auto-configuration and starter artifacts to support all use cases. The author feels these example implementations do not benefit from separate auto-configuration artifacts. ↩
Top comments (0)