InsertableServlet interface extends PipelineableServlet interface (which we studied in previous article). It is used for the same purpose - to insert a servlet in the DAF pipeline.
The question is, when PipelineableServlet (or PipelineableServletImpl) can be used to insert a servlet in pipeline, why do we need InsertableServlet?We will know "WHY" in a moment.
In the previous article, when we needed to insert a ServletMid between already existing ServletA and ServletB, we had to first create ServletMid, and then we had to point the ServletA's "nextServlet" property to ServletMid.
InsertableServlet is used when we don't want to modify ServletA. We just create and define ServletMid and define some properties so that it automatically inserts between ServletA and ServletB without having to modify the properties of either of these servlets.
Before we jump into how we use it, let us understand the class structure of InsertableServlet. ATG also provides the implementation of InsertableServlet called InsertableServletImpl which can be extended, so that we just have to override its service() method.
The InsertableServlet interface has getInsertAfterServlet() and setInsertAfterServlet() methods, which are implemented by InsertableServletImpl along with the capabilities of PipelineableServletImpl. These two methods allow us to define a property "insertAfterServlet" in any component whose class extends InsertableServletImpl. This is the magic property in which you define the config-path of the previous servlet (in our case, we will set the insertAfterServlet property of ServletMid to the config-path of ServletA). Once this property is defined, ATG does all the magic and inserts this servlet in the right place.
To conclude, we use InsertableServlet instead of PipelineableServlet in cases where we don't want to modify any other servlet, except for the one we are inserting.
Steps to Insert an InsertableServlet
1. Create a class ServletMid which extends InsertableServletImpl
2. Override the service() method and write your own code
3. Create a properties file ServletMid in your ATG config path and set the $class and $scope variables with fully qualified class name and global scope respectively
4. Now that your component and classes are created, set the "insertAfterServlet" property of ServletMid to the config path of ServletA. (Because you want to insert ServletMid after ServletA)
5. Add this new servlet to Initial.properties for server time initialization. For more details on Initial.properties, read ART#105 - Nucleus and ATG.
Using insertAfterServlet property, we did not have to modify any other servlet as opposed to previous article.
How it Works?
1. Firstly, ServletA's nextServlet Points to ServletB.
2. We set ServletMid's insertAfterServlet to ServletA.
3. It takes the ServletA's nextServlet property (which contains ServletB) and makes it its own nextServlet. This means that ServletB now becomes ServletMid's nextServlet.
4. Next, it makes the ServletA's nextServlet property point to its own. This means that ServletA's nextServlet now becomes ServletMid.
5. Finally, this is how the pipeline becomes.
InsertableServlet and InsertableServletImpl implement PipelinebleServlet (see class diagram on top of the page). Therefore, the attribute nextServlet also becomes a part of InsertableServlet.
If you are using an InsertableServlet, and specify both; insertAfterServlet property and nextServlet property, which starts a secondary pipeline, then after the execution of secondary pipeline, the control returns to the first pipeline's next servlet.
For example, you have inserted ServletMid between ServletA and ServletB. You have set the insertAfterServlet property of ServletMid to config path of ServletA, and you also specify nextServlet property which starts a secondary pipeline, then after the secondary pipeline completes execution, the control returns back to ServletB, which was the next servlet after ServletMid in the primary pipeline.
When overriding the service method in your custom InsertableServlet, don't forget to call the passRequest(request, response) method. This method passes the request to next servlet in chain.This is it for InsertableServlet implementation. Hang on for more....