Provide a library that can serve swagger UI in Jersey application. Inspiration for this library was the SpringFox Swagger UI project that works with spring boot application.
Use Case
Suppose you have a runnable Jar Jersey REST API application with Open API annotations and would like to provide a swagger UI for API consumers to learn and play with your APIs. Swagger UI comes as a set of static Javascript files that need to be included in your application. In addition, you need to configure a web context that will serve swagger UI pages. By including itzap-jerseyswagger.jarin your project you will get an endpoint that will load functional Swagger UI with your API definitions.
Implementation Details
Here is the code that starts embedded Tomcat in the project that I described in my previous post itzap-message. I modified it to use Open API annotations and include swagger UI.
Let’s say you built spring-boot executable jar and uploaded it into nexus repository. To deploy your spring-boot application you create a Dockerfile that downloads your jar using nexus rest search and download API. For example:
FROM openjdk:8-jre-alpine
MAINTAINER itzap <mailer@itzap.com>
WORKDIR /
RUN wget -O app-service.jar \
'https://nexus.companyUrl.com/nexus/service/rest/v1/search/assets/download?group=com.mycompany.service&name=app-service&repository=company-snapshots&sort=version&direction=des'
EXPOSE 8080
ENTRYPOINT [ "java", "-jar","app-service.jar"]
When you run docker container you see the following error message:
no main manifest attribute, in app-service.jar
Diagnostic
When you build and run jar locally everything is working fine. app-service.jar inside docker container appears to be corrupted. To diagnose the issue run the wget command from the terminal:
$ wget -O app-service.jar 'https://nexus.companyUrl.com/nexus/service/rest/v1/search/assets/download?group=com.mycompany.service&name=app-service&repository=company-snapshots&sort=version&direction=desc'
--2019-10-21 21:48:27-- https://nexus.companyUrl.com/nexus/service/rest/v1/search/assets/download?group=com.mycompany.service&name=app-service&repository=company-snapshots&sort=version&direction=desc
Распознаётся nexus.compnyUrl.com (nexus.companyUrl.com)… 00.00.00.00
Подключение к nexus.compnyUrl.com (nexus.compnyUrl.com)|00.00.00.00|:443... соединение установлено.
HTTP-запрос отправлен. Ожидание ответа… 302 Found
Адрес: https://nexus.compnyUrl.com/nexus/repository/company-snapshots/com/mycompany/service/app-service/0.0.1-SNAPSHOT/app-service-0.0.1-20191021.220127-1-javadoc.jar [переход]
--2019-10-21 21:48:28-- https://nexus.compnyUrl.com/nexus/repository/app-snapshots/com/mycompany/service/app-service/0.0.1-SNAPSHOT/app-service-0.0.1-20191021.220127-1-javadoc.jar
Повторное использование соединения с nexus.compnyUrl.com:443.
HTTP-запрос отправлен. Ожидание ответа… 200 OK
Длина: 247463 (242K) [application/java-archive]
Сохранение в: «app-service.jar»
Do not get all these messages in Russian fool you. This is not a Russian hacker attack. Pay attention to what is actually being downloaded. app-service-0.0.1-20191021.220127-1-javadoc.jarjavadoc!!!
Solution
Solution to this issue can be found in sonatype Search API. Looking through documentation I came across this query parameter maven.classifier This issue happens when your repository contains javadoc jar alnog side your artifact. &sort=version&direction=desc parameters are also critical to insure you are downloading the latest version, but not enough to uniquely identify artifact. Final URL that works looks like this:
Let’s say you are building a spring-boot library and would like to tap into spring-boot auto-configuration feature. You create class MyAutoConfiguration and annotate it with the spring @Configuration annotation. Then, in you application, you use this library as a dependency, run the application and get the following exception
Caused by: java.lang.IllegalStateException: Unable to read meta-data for class com.mylib.autoconfigure.MyAutoConfiguration
at org.springframework.boot.autoconfigure.AutoConfigurationSorter$AutoConfigurationClass.getAnnotationMetadata (AutoConfigurationSorter.java:233)
at org.springframework.boot.autoconfigure.AutoConfigurationSorter$AutoConfigurationClass.getOrder (AutoConfigurationSorter.java:204)
at org.springframework.boot.autoconfigure.AutoConfigurationSorter$AutoConfigurationClass.access$000 (AutoConfigurationSorter.java:150)
at org.springframework.boot.autoconfigure.AutoConfigurationSorter.lambda$getInPriorityOrder$0 (AutoConfigurationSorter.java:63)
Steps to Reproduce
Create spring-boot project and add the following class
@Configuration
public class MyAutoConfiguration {
private static final Logger LOGGER = LoggerFactory.getLogger(MyAutoConfiguration.class);
@PostConstruct
public void printConfigurationMessage() {
LOGGER.info("Configuration for My Lib is complete...");
}
}
Do not forget to add spring.factories file to resources -> META-INF -> spring.factories
Finally, you add your library as a dependency to your application, run it and get the runtime error mentioned above.
Diagnostic
Online search suggests that either spring.factories file is missing, or the name of the class is not correct, … Everything is checked out and fine. To make sure MyAutoConfiguration class is in fact included I start looking into my library jar:
jar tvf target/mylib.jar | grep MyAutoConfiguration
Here, I can see that the class is under BOOT-INF/classes root.
Solution
Apparently, auto configuration classes cannot be found under BOOT-INF/classes root. The main issue with my setup was the fact that I used spring-boot-maven-plugin to build the library module. After removing the plugin and rebuilding the library jar tvf target/mylib.jar | grep MyAutoConfiguration is showing this:
com/mylib/autoconfigure/MyAutoConfiguration.class
Now, spring-boot application builds fine and MyAutoConfiguration class is found and ready to be used to configure library.
In a spring-boot application that uses spring-boot-dependencies instead of spring-boot-starter-parent and a third party library that depends on elasticsearch version that is not comparable with version 6.x, elasticsearch dependency version get mixed up creating class loading issue.
Steps to reproduce
Create a spring-boot project and include spring-boot-dependencies in the dependency management section of the maven pom.xml
Turns out mvn dependency:tree shows the issue, but it does not say where org.elasticsearch:elasticsearch:jar:6.4.3:compile is comming from. The best command for the job is:
mvn -Dverbose=true help:effective-pom
This command outputs effective POM that can be redirected to a file mvn -Dverbose=true help:effective-pom > ~/pom.xml and analysed. The effective pom will look something like this
...
<dependency>
<groupId>org.elasticsearch</groupId> <!-- org.springframework.boot:spring-boot-dependencies:2.1.6.RELEASE, line 1965 -->
<artifactId>elasticsearch</artifactId> <!-- org.springframework.boot:spring-boot-dependencies:2.1.6.RELEASE, line 1966 -->
<version>6.4.3</version> <!-- org.springframework.boot:spring-boot-dependencies:2.1.6.RELEASE, line 1967 -->
</dependency>
...
Magic! now we can see exactly where the problem is:
<!-- org.springframework.boot:spring-boot-dependencies:2.1.6.RELEASE, line 1967 -->
spring-boot-dependencies is imported, so there is no easy way to exclude elasticsearch dependency that it pulls into our project. A simple maven <exclude> will not work here. The only way to solve the issue is to bring elasticsearch dependencies into your project dependency management block like this:
Create a very lightweight email micro-service that will be self-contained, easy to deploy and integrate with. Micro-service could not use any out of the box email servers or email as a service solutions.
Use Case
Suppose, you have an application that needs to send user emails to update a forgotten password or to invite new users to the system. The email capability of your application should be designed as a shared component that can be later extended to send text messages. Email templates should be consistent across different applications and maintained in one place. Email server configuration can be complex, so it needs to be isolated and easily reproducible.
Design Considerations
Spring boot or no spring boot, that is the question. For the itzap-message micro-service, I choose Jersey with hk2 as dependency injection framework. It turns out, that it is quite easy to build executable Jar micro-service with embedded Tomcat without spring/spring-boot. As a result, executable Jar is a lot smaller, faster to load, and deploy. Another component of the system is an email server. To solve email server configuration problems I looked for a Docker container that provides an email server. The Docker container that I found was boky/postfix . Now, to build the application, I can use docker-composeto put everything together.
Implementation Details
Jersey, Tomcat, and HK2
To start building micro-service using Jersey, Tomcat, and HK2 drop theses dependencies in your pom.xml file.
public class EmailApplication
{
private static final Logger LOGGER = LoggerFactory.getLogger(EmailApplication.class);
public static void main(String[] args) {
try {
start();
} catch (Exception e) {
LOGGER.error("ITZap Email application failed to run", e);
}
}
private static void start() throws Exception {
String contextPath = "";
String appBase = ".";
String port = System.getenv("PORT");
if (port == null || port.isEmpty()) {
port = "8025";
}
Tomcat tomcat = new Tomcat();
tomcat.setPort(Integer.parseInt(port));
tomcat.getHost().setAppBase(appBase);
Context context = tomcat.addWebapp(contextPath, appBase);
Tomcat.addServlet(context, "jersey-container-servlet",
new ServletContainer(resourceConfig()));
context.addServletMappingDecoded(UDecoder.URLDecode("/v1/itzap/message/*", Charset.defaultCharset()),
"jersey-container-servlet");
// initialize Tomcat. (Since version 9.xx need to add tomcat.getConnector() here)
tomcat.getConnector();
tomcat.start();
tomcat.getServer().await();
}
private static ResourceConfig resourceConfig() {
return new JerseyConfig();
}
}
HK2 Dependency Injection
I drop all factories as static nested classes in one Factories class for convenience.
public final class Factories {
private static final Config CONFIG = ConfigFactory.load();
private Factories() {}
public static class MailServiceFactory extends AbstractFactory<EMailService> {
public MailServiceFactory() {
}
@Override
public EMailService provide() {
return new EMailService(CONFIG);
}
}
}
Put it all together.
public class JerseyConfig extends ResourceConfig {
JerseyConfig() {
register(JacksonFeature.class);
// register endpoints
packages("com.itzap.message.rest");
register(new ContainerLifecycleListener()
{
public void onStartup(Container container)
{
// access the ServiceLocator here
// serviceLocator = container.getApplicationHandler().
ServiceLocator serviceLocator = ((ImmediateHk2InjectionManager)container
.getApplicationHandler().getInjectionManager()).getServiceLocator();
enableTopicDistribution(serviceLocator);
// ... do what you need with ServiceLocator ...
}
public void onReload(Container container) {/*...*/}
public void onShutdown(Container container) {/*...*/}
});
register(new AbstractBinder() {
@Override
protected void configure() {
// hk2 bindings
bindFactory(Factories.MailServiceFactory.class)
.to(EMailService.class)
.in(Singleton.class);
}
});
}
}
More Jersey
One of the features of Jersey that I like is @Provider mechanism. Here is an example of how to centralize error handling in the Jersey application.
@Provider
public class IZapExceptionMapper implements ExceptionMapper<IZapException> {
@Override
public Response toResponse(IZapException e) {
ErrorResponse response = MapperUtils.toReturn(e);
return Response.status(response.getStatus())
.entity(response)
.type(MediaType.APPLICATION_JSON_TYPE)
.build();
}
}
Not shown here, but Jersey can actually inject beans into @Provider classes.
Other
I think one of the undervalued configuration/properties management libraries is com.typesafe I like this library for the ease of use, handling property hierarchies, flexibility, and out of the box property loading convention.
I usually, unpack all dependencies and merge them into a final jar. There are other strategies for building executable Jar that can be configured in the descriptor file.
Deployment
I already mentioned adocker-compose as a mechanism for running itzap-message micro-service. Here is an example of the docker-compose.yml
version: '3.2'
services:
mail:
image: boky/postfix
environment:
ALLOWED_SENDER_DOMAINS: ${ALLOWED_DOMAINS}
ports:
- 1587:587
message:
# Builds message service
build: "."
image: message-service:latest
environment:
MAIL_HOST: mail
MAIL_FROM: ${MAIL_FROM}
privileged: true
ports:
- 8025:8025
links:
- mail
depends_on:
- mail
Here, you can see two containers mailandmessage. Mail container comes straight from the Docker Hub boky/postfix while message is a simple java contaner defined in the following Dockerfile
# Alpine Linux with OpenJDK JRE
FROM openjdk:8-jre-alpine
COPY message-impl/target/message-impl-0.0.1-SNAPSHOT.jar /opt/lib/
ENTRYPOINT ["/usr/bin/java"]
CMD ["-jar", "/opt/lib/message-impl-0.0.1-SNAPSHOT.jar"]
EXPOSE 8025
Notes
itzap-messagemicro-service application contains two modules: message-api and message-impl. Assuming application consuming itzap-message micro-service is a Java application, having message-apijar streamlines the development of the Java client. API library provides common POJOs and a service interface that can be implemented on the client-side.
Readme
itzap-message
itzap-message micro-service project designed to send email messages.
Visit my ITZap blog to read more about this project.
Usage
itzap-message desinged to run in a Docker container along with postfix that is also running in a Docker. Using docker-composeitzap-message can be deployed anyware and ready to send emails.
Before running set environment variables export MAIL_FROM = mailer@test.com to whater email address will be used to send messages from and export ALLOWED_DOMAINS=test.com domain used to send emails.
To run the itzap-message micro-service docker-compose up
Testing
Once both Docker containers are running open Postman and call micro-service API to send an email
POST http://localhost:8025/v1/itzap/message/emailBody