Recent Comments

    Introducing the ATG Servlet Programming Series

    If you’ve been doing JSP development on the ATG platform for any length of time you’ve come across ATG Servlet beans. These servlets (or droplets as some call them) provide a lot of the key functionality needed to take full advantage of the ATG Platform.  Some of the droplets that are provided out of the box include:

    • AnchorTag
    • Compare
    • DateTagConverter
    • ForEach
    • IsEmpty
    • Range
    • Tag
    • ValueIsHTMLTagConverter

    Goals of this series

    In this series we will be going through the servlet source code that Oracle provides with ATG. The goals are to utilize the provided source code to:

    1. Gain a better understanding of what is possible using ATG Servlets
    2. Understand the correct way to implement custom ATG servlets.
    3. Identify idioms, nomenclature, and patterns that we can leverage for future work.

    With these goals in mind we will start out with some of the simpler servlets and as we gain a better understanding we will move into the more complex ones. There is not a clear roadmap of the order for droplets but hopefully a sensible path through the codebase will present itself as we progress.

    What is an ATG Servlet?

    From chapter 5 of the ATG Programming Guide:

    “Most applications, however, require some way to generate JSP from a Java object. The dsp:droplet tag also lets you do this, by referring to a Nucleus component rather than another JSP file. In this case, the JSP generated by the Nucleus component is embedded into the JSP. A Nucleus component used in this way is called an ATG servlet bean.”

    Put more simply, an ATG Servlet:

    • Is just a java servlet,
    • Is passed a request and response object just like a regular java servlet
    • Extends the DynamoServlet class

    Using an ATG Servlet:

    The following example shows how to use a fictional servlet within a JSP:

    <dsp:droplet name=”com.atgdeveloper.joelhainley.droplet.series.examples.gotham.GothamCharacterLookupDroplet">
    <dsp:param name="param1" bean="story.getCurrentCharacter"/>
    	<dsp:oparam name="goodguy">
       		<p><h1>GOOD GUY</h1>
    		<dsp:valueof param="description"></dsp:valueof>
    	<dsp:oparam name="badguy">
       		<p><h1>BAD GUY</h1>
    		<dsp:valueof param="description"></dsp:valueof>
     	<dsp:oparam name="unknown">
    		<dsp:valueof param="description"></dsp:valueof>

    Examining the code above:

    Line 1: Line 1 starts off with a dsp:droplet tag which is what we use to specify that we are using an ATG Servlet on this page. The fact that all Servlets are included on JSP pages with the dsp:droplets tag is why you will often hear them referred to as “droplets”.  The name parameter specifies the package name for the droplet to be utilized.

    Line 2: More often than not you will be passing something to a droplet, either a property, or an object reference, or something. There are probably uses for droplets that take no parameters and just output information, but they most often not very interesting. There are different types of parameters that you can pass to a bean, I encourage you to read through the ATG documentation to become well versed in the details of passing parameters to beans.

    To pass arguments you use the dsp:param tag inside the bounds of the dsp:droplet tag, referencing the name and information that the servlet requires.

    Line 3: Now we come to the dsp:oparam tag, I tend to think of it as the “output parameter” and I suspect that’s actually what it stands for. If you look at lines x and lines Y you’ll notice that there are two dsp:oparam tags each with different names. The dsp:oparam on line X has a name of “good”. The dsp:oparam on line Y has a name of “bad”.

    Now you might be wondering how can it have two different outputs? Well the key to understanding this is realize that you will often want to execute different parts of JSP based upon something determined by the Servlet. So within the servlet what happens is that you actually specify which parameter should be serviced based upon the needs of your application.

    So if you passed in Batman to your servlet, the servlet might do some processing and then call the “good” oparam. Whereas if you passed in Joker, your servlet might choose to call the “bad” oparam. We will get into this concept a bit more as this series goes on, but it’s a standard idiom so if you want to understand it in more detail I suggest you refer to the ATG documentation.

    Programming Servlets/Droplets

    Now that you’ve seen the usage of an example servlet in a JSP page, let’s go through how we might go about creating the servlet itself by looking at some sample java code:

    package com.atgdeveloper.joelhainley.droplet.series.examples.gotham;
    import javax.servlet.ServletException;
    import atg.servlet.DynamoHttpServletRequest;
    import atg.servlet.DynamoHttpServletResponse;
    import atg.servlet.DynamoServlet;
    import org.apache.axis.utils.StringUtils;
    public class GothamCharacterLookupDroplet extends DynamoServlet {
    	private static final ParameterName INPARAM_CHARACTER= ParameterName
    	private static final String OPARAM_NAME_DESCRIPTION = "description";
    	private static final ParameterName OPARAM_OUTPUT_GOODGUY = ParameterName
    	private static final ParameterName OPARAM_OUTPUT_BADGUY = ParameterName
    	private static final ParameterName OPARAM_OUTPUT_UNKNOWN = ParameterName
    	public void service(DynamoHttpServletRequest pRequest,
    			DynamoHttpServletResponse pResponse) throws ServletException,
    			IOException {
    		String character = "";
    		// does the input param exist in the request?
    		if(pRequest.getObjectParameter(INPARAM_CHARACTER) == null){
    			throw new ServletException("Missing required parameter: [character]");
            // retrieve the value of the input parameter
    		String character = pRequest.getParameter(INPARAM_CHARACTER);
    		// inspect the contents of the input parameter
    		if(character==null || StringUtils.isEmpty(character)){
    			throw new ServletException("Parameter [character] : must contain a value.");			
    		//  inspect value and take appropriate action
    			pRequest.setParameter(OPARAM_NAME_DESCRIPTION, "The Caped Crusader");
    			pRequest.serviceLocalParameter(OPARAM_OUTPUT_GOODGUY, pRequest, pResponse);
    		else if ("riddler".equals(character)){
    			pRequest.setParameter(OPARAM_NAME_DESCRIPTION, "Riddle me this!");
    			pRequest.serviceLocalParameter(OPARAM_OUTPUT_BADGUY, pRequest, pResponse);			
    		else {
    			pRequest.setParameter(OPARAM_NAME_DESCRIPTION, "Unknown character, be wary.");
    			pRequest.serviceLocalParameter(OPARAM_OUTPUT_UNKNOWN pRequest, pResponse);			

    This is standard java code, so we’ll just go over the interesting parts below:

    Line 1: We  declare the package that the Servlet belongs to

    Line 10: defines the input parameterName that is passed in through the “character” param tag in the jsp

    Line 12: defines the output parameterName that we use to return a value later in the servlet

    Lines 13-18: define the three different output section ParameterNames that this droplet could call as part of it’s processing

    Line 20-23: is the definition of the service method that is called when the GothamCharacterLookupDroplet is invoked. Note that there are two parameters passed to this method (DynamoHttpServletRequest, and DynamoHttpServletResponse) and that it throws a ServletException. If you’ve done any sort of servlet programming this should all be familiar.

    Line 27-29: Verifies that the expected parameter “character” was passed to the servlet. Throwing an exception if it isn’t present. (note: there are some differing opinions on whether it’s better to utiilize an error output parameter, or simply throw an exception. We will be devoting an article to this issue later on in this series. For now, just know that this is one accepted approach to dealing with errors in your droplets)

    Line 31: We retrieve the value from the request and put it into a String object.

    Lines 34-36: Inspect the String object and throw an exception if it doesn’t meet our expectations.

    Lines 39-54: Depending on the value passed in the character param to the droplet, we service different oparams and provide an message back to the calling jsp.

    In conclusion

    We’ve laid out the premise for this series, given you an idea of some of the things that will be covered. We went over the basics of using, and creating an ATG servlet and generally have ourselves situated to dig into the source code and get to work. Check back soon for our next article where we start to dig into the actual source itself, it should be fun and rather educational!

    About the Author

    Joel Hainley is a founder and consultant at JWB Solutions Inc., a software development consulting firm based in the San Francisco Bay Area.



    Who am I?

    My name is Joel Hainley and I am a San Francisco Bay Area based ATG Consultant that has been doing ATG development for a couple of years. Lately, I’ve been focusing mostly on the front-end parts (from Form Handlers, Droplets, and JSPs to HTML, CSS, Javascript, AJAX, Flex, etc.)  I’ve also been heavily involved with J2EE application development, iOS/Objective-C, Mule ESB, and Ruby On Rails.

    Right, so what’s the point of this site?

    Lately, I’ve been diving deeper into ATG development and have chosen to document the things that I learn. There are three reasons for this:

    1. By learning with the intent of explaining what I’m learning, I will learn things more thoroughly,
    2. I will have a reference for the future,
    3. Having a journal of what I’ve learned will make it easier for me to refresh my memory from time to time.

    Additionally, I’ll also spend some time talking about various developments in the ATG world, talk about supporting technologies that I’m working with, etc. I’ll try to capture news stories, interesting blog posting from ATG developers, new releases, etc. Any and everything related to, or relevant to,  the building of e-commerce sites using ATG.

    In the coming weeks I’ll be introducing the first series of articles for this site, and tweaking and customizing the site itself. Stay tuned!