In my blog on java.util.ServiceLoader, we discussed how it can be used to discover third party implementations of your interfaces. This can be useful if your application is a container that executes code written by developers. In this blog, we discuss dynamic discovery and registration for Servlets.
All Java Web developers are already familiar with javax.servlet.ServletContextListerner interface. If you want to do initialization when the application starts or clean up when it is destroyed, you implement the contextInitialized and contextDestroyed methods of this interface.
In Servlet 3.0 specification, they added a couple interesting features that help with dynamicity, that are particularly useful to developers of libraries or containers.
(1) javax.servlet.ServletContainerInitializer is another interface that can notify your code of application start.
Library or container developers typically provide an implementation of this interface. The implementation should be annotated with the HandlesTypes annotation. When the application starts, the Servlet container calls the OnStart method of this interface, passing in as a parameter a set of all classes that implement, extend or are annotated with the type(s) declared in the HandlesTypes annotation.
(2) The specification also add a number of methods to dynamically register Servlets, filters and listeners. You will recall that previously, if you needed to add a new Servlet to you application, you needed to modify web.xml.
Combining (1) and (2), it should be possible to dynamically discover and add Servlets to a web application. This is a powerful feature that allows you to make the web application modular and spread development across teams without build dependencies. Note that this technique can be used to discover any interface, class or annotation. I am killing 2 birds with one stone by using this to discover servlets.
In the rest of the blog, we will build a simple web app, that illustrates the above concepts. For this tutorial you will need
(1) JDK 7.x or higher
(2) Apache Tomcat or any Servlet container
(3) Apache Maven
In this example we will
(1) We will implement SevletContainerInitializer called WebContainerInitializer and package it in a jar containerlib.jar.
(2) To make the example interesting, we will create a new annotation @MyServlet, which will act like the @WebServlet annotation in the servlet specification. WebContainerInitializer will handle types that are annotated with @MyServlet.
(3) We will write a simple web app that has a Servlet annotated with @MyServlet and has containerlib.jar in the lib directory. No entries in web.xml.
(4) When the app starts, the servlet is discovered and registered. You can go to a browser and invoke it.
Before we proceed any further, you may download the code from my github respository, So you can look at the code as I explain. The code for this example is in the dynamicservlets directory.
Step 0: Get the code
git clone https://github.com/mdkhanga/my-blog-code.git
dynamicservlets has 2 subdirectories: containerlib and dynamichello.
The containerlib project has the MyServlet annotation and the WebContainerInitializer which implements ServletContainerInitializer.
DynamicHello is a web application that uses containerlib jar.
Step 1: The MyServlet annotation
MyServlet.java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface MyServlet {
String path() ;
}
The annotation applies to classes and is used as
@MyServlet(path = "/someuri")
Step 2: A Demo servlet
HelloWorldServlet.java
@MyServlet(path = "/greeting")
public class HelloWorldServlet extends HttpServlet {
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
PrintWriter p = response.getWriter() ;
p.write(" hello world ");
p.close();
}
}
This is a simple hello servlet that we discover and register. Nothing needs to be added to web.xml.
Step 3: WebContainerInitializer
WebContainerInitializer.java
This is the implementation of ServletContainerInitializer.
@HandlesTypes({MyServlet.class})
public class WebContainerInitializer implements ServletContainerInitializer {
public void onStartup(Set> classes, ServletContext ctx)
throws ServletException {
for (Class c : classes) {
MyServlet ann = (MyServlet)c.getAnnotation(MyServlet.class) ;
ServletRegistration.Dynamic d = ctx.addServlet("hello", c) ;
d.addMapping(ann.path()) ;
}
}
The implementation needs to be in separate jar and included as a jar in the lib directory of the application war. WebContainerInitializer is annotated with @HandleTypes that takes MyServlet.class as parameter. When the application starts, the servlet container finds all classes that are annotated with MyServlet and passes them to the onStartup method. In the onStartup method, we go through each class found by the container, get the value of the path attribute from the annotation and register the servlet.
To make this work, we need one more thing, which is in the META-INF/services directory, a file whose name is javax.servlet.ServletContainerInitializer, which contains 1 line com.mj.WebContainerInitializer. If you are wondering why this is required, please see my this blog.
Step 4: Build and run the app
To build,
cd containerlib
mvn clean install
cd dynamichello
mvn clean install
This builds dynamichello/target/dynamichello.war that can be deployed to tomcat or any servlet container.
When the application starts, you will see the following messages in the log
Initializing container app .....
Found ...com.mj.servlets.HelloWorldServlet
path = /greeting
Point you browser to http://localhost:8080/hello/greeting.
The servlet will respond with a hello message.
In summary, this technique can be used to dynamically discover classes during application startup. This is typically used to implement libraries or containers such as JAX-RS implementation. This allows implementations to be provided by different developers. There is no hard wiring.
All Java Web developers are already familiar with javax.servlet.ServletContextListerner interface. If you want to do initialization when the application starts or clean up when it is destroyed, you implement the contextInitialized and contextDestroyed methods of this interface.
In Servlet 3.0 specification, they added a couple interesting features that help with dynamicity, that are particularly useful to developers of libraries or containers.
(1) javax.servlet.ServletContainerInitializer is another interface that can notify your code of application start.
Library or container developers typically provide an implementation of this interface. The implementation should be annotated with the HandlesTypes annotation. When the application starts, the Servlet container calls the OnStart method of this interface, passing in as a parameter a set of all classes that implement, extend or are annotated with the type(s) declared in the HandlesTypes annotation.
(2) The specification also add a number of methods to dynamically register Servlets, filters and listeners. You will recall that previously, if you needed to add a new Servlet to you application, you needed to modify web.xml.
Combining (1) and (2), it should be possible to dynamically discover and add Servlets to a web application. This is a powerful feature that allows you to make the web application modular and spread development across teams without build dependencies. Note that this technique can be used to discover any interface, class or annotation. I am killing 2 birds with one stone by using this to discover servlets.
In the rest of the blog, we will build a simple web app, that illustrates the above concepts. For this tutorial you will need
(1) JDK 7.x or higher
(2) Apache Tomcat or any Servlet container
(3) Apache Maven
In this example we will
(1) We will implement SevletContainerInitializer called WebContainerInitializer and package it in a jar containerlib.jar.
(2) To make the example interesting, we will create a new annotation @MyServlet, which will act like the @WebServlet annotation in the servlet specification. WebContainerInitializer will handle types that are annotated with @MyServlet.
(3) We will write a simple web app that has a Servlet annotated with @MyServlet and has containerlib.jar in the lib directory. No entries in web.xml.
(4) When the app starts, the servlet is discovered and registered. You can go to a browser and invoke it.
Before we proceed any further, you may download the code from my github respository, So you can look at the code as I explain. The code for this example is in the dynamicservlets directory.
Step 0: Get the code
git clone https://github.com/mdkhanga/my-blog-code.git
dynamicservlets has 2 subdirectories: containerlib and dynamichello.
The containerlib project has the MyServlet annotation and the WebContainerInitializer which implements ServletContainerInitializer.
DynamicHello is a web application that uses containerlib jar.
Step 1: The MyServlet annotation
MyServlet.java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface MyServlet {
String path() ;
}
The annotation applies to classes and is used as
@MyServlet(path = "/someuri")
Step 2: A Demo servlet
HelloWorldServlet.java
@MyServlet(path = "/greeting")
public class HelloWorldServlet extends HttpServlet {
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
PrintWriter p = response.getWriter() ;
p.write(" hello world ");
p.close();
}
}
This is a simple hello servlet that we discover and register. Nothing needs to be added to web.xml.
Step 3: WebContainerInitializer
WebContainerInitializer.java
This is the implementation of ServletContainerInitializer.
@HandlesTypes({MyServlet.class})
public class WebContainerInitializer implements ServletContainerInitializer {
public void onStartup(Set
throws ServletException {
for (Class c : classes) {
MyServlet ann = (MyServlet)c.getAnnotation(MyServlet.class) ;
ServletRegistration.Dynamic d = ctx.addServlet("hello", c) ;
d.addMapping(ann.path()) ;
}
}
The implementation needs to be in separate jar and included as a jar in the lib directory of the application war. WebContainerInitializer is annotated with @HandleTypes that takes MyServlet.class as parameter. When the application starts, the servlet container finds all classes that are annotated with MyServlet and passes them to the onStartup method. In the onStartup method, we go through each class found by the container, get the value of the path attribute from the annotation and register the servlet.
To make this work, we need one more thing, which is in the META-INF/services directory, a file whose name is javax.servlet.ServletContainerInitializer, which contains 1 line com.mj.WebContainerInitializer. If you are wondering why this is required, please see my this blog.
Step 4: Build and run the app
To build,
cd containerlib
mvn clean install
cd dynamichello
mvn clean install
This builds dynamichello/target/dynamichello.war that can be deployed to tomcat or any servlet container.
When the application starts, you will see the following messages in the log
Initializing container app .....
Found ...com.mj.servlets.HelloWorldServlet
path = /greeting
Point you browser to http://localhost:8080/hello/greeting.
The servlet will respond with a hello message.
In summary, this technique can be used to dynamically discover classes during application startup. This is typically used to implement libraries or containers such as JAX-RS implementation. This allows implementations to be provided by different developers. There is no hard wiring.
