vADC Docs

Writing Java Extensions - an introduction

by on ‎03-05-2013 05:19 AM - edited on ‎06-16-2015 04:29 PM by PaulWallace (2,155 Views)

Java Extensions may look complex, but they follow a very standard template that you can use as a basis for all of your code.

 

What is a Java Extension?

 

A Java Extension is a class derived from either the GenericServlet or HttpServlet class. HttpServlet-derived extensions are most common, so we'll focus on that class.

 

On its own, the abstract class implementation does not perform any useful functions.  When you derive an extension from the HttpServlet class, you provide your own implementation of its methods:

 

  • doGet() is called to service a GET request
  • doPost() is called to service a POST request
  • init() is called when the servlet is loaded (before it processes any requests) and can be used to perform initialization tasks

 

You then compile the extension to a Java class, upload it to Stingray's Java Extensions catalog, and configure Stingray to invoke the extension using the java.run() trafficscript function.  Stingray will then execute the code in the doGet() or doPost() methods against any transactions it processes.

 

An HttpServlet template

 

Every HTTP Servlet can start with the following template:

 

import java.io.IOException;  
  
import javax.servlet.ServletException;  
import javax.servlet.http.HttpServlet;  
import javax.servlet.http.HttpServletRequest;  
import javax.servlet.http.HttpServletResponse;  
  
// Insert additional imports here...  
  
public class Example extends HttpServlet {  
   private static final long serialVersionUID = 1L;  
  
   public void init() throws ServletException {  
      super.init();  
      // Add any initialization code here...  
   }  
  
   public void doGet( HttpServletRequest req, HttpServletResponse res )  
      throws ServletException, IOException  
   {  
      // Add the extension code here....  
   }  
  
   public void doPost( HttpServletRequest req, HttpServletResponse res )  
      throws ServletException, IOException  
   {  
      doGet( req, res ); // replace this to handle POSTs differently to GETs  
   }  
}  

 

Class names

 

Important note: The class name ('Example') and the source file name ('Example.java') must match, and together these will create a Java Extension named 'Example'.  If you want to refer to your extension by a different name, make sure to rename the class and the source file.

 

An example

 

To illustrate this, we'll use the eponymous 'Hello World' example.  HelloWorld does not require any explicit initialization (so we can omit the init() method) and because the class is named 'HelloWorld', make sure to save the source in the file HelloWorld.java:

 

import java.io.IOException;  
  
import javax.servlet.ServletException;  
import javax.servlet.http.HttpServlet;  
import javax.servlet.http.HttpServletRequest;  
import javax.servlet.http.HttpServletResponse;  
  
// Additional imports  
import java.io.PrintWriter;  
  
public class HelloWorld extends HttpServlet {  
   private static final long serialVersionUID = 1L;  
  
   public void doGet( HttpServletRequest req, HttpServletResponse res )  
      throws ServletException, IOException  
   {  
      // Implementation of the servlet action  
     
      res.setContentType( "text/html" );  
  
      PrintWriter out = res.getWriter();  
      out.println( "<h1>Hello, world!</h1>");  
   }  
  
   public void doPost( HttpServletRequest req, HttpServletResponse res )  
      throws ServletException, IOException  
   {  
      doGet( req, res );  
   }  
}  

 

Save as HelloWorld.java

 

Compilation

 

The servlet classes and the custom Stingray extensions are not part of the standard Java (J2SE) distribution.  Download the two files (Java Servlet API (servlet.jar) and Stingray Java Extension API (zxtm-servlet.jar)) from Stingray's Java Extensions Catalog as below:

 

javajars.png

Download the Java Servlet API and Stingray Java Extensions API files

 

With the two servlet jar files and your source file HelloWorld.java in the same directory, you can build your Java class as follows:

 

javac -cp servlet.jar:zxtm-servlet.jar HelloWorld.java

 

Invoking the servlet

 

Upload the Java Servlet to your Java Extensions catalog.  Stingray will register HelloWorld.class and also create a simple TrafficScript (RuleBuilder) rule named 'HelloWorld'.  Assign this rule to a Virtual Server:

 

  • If you run this from a request rule, all subsequent rules processing will terminate and the response will be sent directly back to the client.
  • If you run this from a response rule, it will modify the response data that was provided by the back-end server. Subsequent response rules will be run, and if they try to inspect the response data, they will see the response that was set by this code.

 

Additional Code Samples

 

Many of the code samples you will see here just provide the implementations for the service() or doGet() methods, and any anciliary methods required. You'll need to insert this code into the full class code (copy and paste from this page) and add the necessary import statements in order to create the full source file.  You can then compile it as above, or use your favourite IDE.

 

Most IDEs will help you insert the correct imports - Ctrl-Shift-O in Eclipse will do the trick for example.

 

Read more

 

Contributors