Building a Servlet Capsule

The goals for this section include:

• Learning some background information about servlets
• Gaining familiarity with AppComposer's interface
• Creating a servlet capsule that sends HTML output to a browser
• Learning how actors and behaviors interact

Servlets are programs that run on a web server and interact with the user over the Internet. Servlets are written in Java, which means they use a platform-independent protocol to interact with the web servers needed to deploy them. This makes deployment and component-building simpler. It also saves developers from having to learn proprietary languages for specific web platforms, and enables them to create easily customizable servlets that can be adapted for different web applications or deployed into different environments. AppComposer is an excellent tool for creating or customizing servlets and for assembling servlets and other resources into portable, Java-compliant, web applications.

Servlets also free the developer from writing a complete front-end user interface, since users interact with servlets through browsers. Another benefit of Java servlets is that, unlike an applet, a web server executes all of a servlet's code, so the developer does not need to worry about client-side compatibility or security issues. This diagram shows how a servlet web application connects all of its parts.

As you can see outlined in the diagram, the servlet:

• interprets requests from the client browser
• processes any information from the browser
• retrieves information from back-end databases or legacy applications
• sends HTTP output back to the client browser

For more detailed information about servlets, see:

• Java Servlet Technology Whitepaper
• Fundamentals of Java Servlets
• Sun's Servlets Tutorial

This exercise explores AppComposer's servlet editing capabilities by building a very simple servlet which displays HTML text. In later lessons, you will build on that servlet so that it can accept input from a user and use the input to personalize the message it outputs.

Create a Servlet Capsule

Start AppComposer.

• Project pane
  AppComposer's project pane, in the upper left corner of the window, provides multiple file and directory management for your web applications. Here you can view all the resources used in your project, such as outside images, files or other resources. Projects also provide automated tools to package and deploy servlet projects. These tasks can be difficult and tedious to perform by hand, even for a simple web application.
• Console pane
  If you do not see a Console in the lower right of your window, open the View menu from the tool bar, and select Console. The Console displays any errors or output messages from AppComposer. If you have configured AppComposer to start its database, EJB server, or web server on startup, the Console window also includes tabs for these applications. Depending on what applications you run in conjunction with AppComposer, your tabs may differ from those shown.
• Palette
  This pane, in the lower left of your window, gives you shortcuts for items on the Insert menu in the tool bar. You can drag behaviors into the capsule from the Palette, or click to add them as a child of the current selection.
• Details pane
  As the name implies, the details pane shows the details of whatever your current selection is. You use this pane to edit and create unique behaviors and actors. Depending on the type of item you have selected, the fields in the details pane will vary.

Capsules

In this tutorial you will learn about AppComposer by building a Java servlet capsule. AppComposer uses the metaphor of capsules to describe the building blocks of applications. Most of the work you do in AppComposer is in the context of a capsule. Capsules are a means of organizing an application into modules. A capsule itself is a component that can be contained in other capsules. AppComposer shows the contents of capsules in a hierarchical outline form. Behind the scenes, AppComposer translates capsules from the graphical interface you see into Java-compliant components.

Capsules use .zac as their file type suffix. To save projects, use the suffix .zap.

To create a servlet capsule:

1. Open a new capsule of type Servlet.
   File -> New Capsule -> Servlet
   An untitled capsule outline appears.
   
2. From the File menu, select Save.
3. Save your capsule as hello.zac anywhere within the AppComposer directory.

To add a capsule to a project:

1. Click inside the Projects pane to enable the Project menu.
2. From the Project menu, select Project -> Add.
3. In the Add dialog, browse to where you saved your capsule.
4. Select hello.zac.
5. Click Add.
   AppComposer adds hello.zac to your untitled project.
6. From the File menu, select Save As.
7. Name your project hello.zap and save it in the same directory as your capsule.

Creating HTML Output

Now you have an empty servlet capsule named hello.zac. You need to give it some actors and behaviors so that it can send output to a browser.

When you use a Java component in AppComposer, the instance of that component is called an actor. AppComposer provides many built-in components that you can use as actors in your capsule, and you can import compliant Java components and beans and use them as actors in AppComposer.

You can assign behaviors to an actor. As the name implies, behaviors give the actor the ability to do something. It might print output, respond to an event, evaluate a conditional statement, interact with a resource outside of the servlet, or any other kind of action that it is possible to create using Java.

For this example, you will give the hello.zac capsule some actors that represent HTML output, and insert a behavior that instructs an actor to send output to a browser on request. AppComposer includes a library of components that correspond to HTML tags so it is easy for your servlets to generate browser-ready output.

 To add HTML actors to the servlet:

1. Select the capsule from the outline.
2. From the Palette, click the triangle next to Html to open the Html menu.
3. Select HTMLDocument. You can drag it or click it to insert it into the capsule.
   
   An HTMLDocument actor appears below the capsule in the outline.
4. Click on the text of HTMLDocument to select its name.
5. Type HelloDocument to rename the actor.
   Always name your actors with unique names that give a sense of their function.
6. With HelloDocument selected, insert an HTML Text actor.
   Scroll down the list of HTML actors in the Palette to HTMLText.
7. Name the HTMLText actor GreetingText.

Notice how GreetingText is indented in the outline as compared to HelloDocument. This is because when you have an actor selected in the outline, and then insert a new actor or behavior, AppComposer inserts it as a child of the actor or behavior that was selected. Notice also that HelloDocument now has a down pointing wedge next to its icon. Wedges show that the actor has a child or behavior associated with it. When the wedge points down, the outline displays the child actors or behaviors. If you click on the wedge, it faces right , and the outline no longer shows the actor's child elements.

So far you have inserted and named some HTML elements, but they are generic, that is, they do not contain any specific properties. AppComposer's HTML actors include properties that correspond to any option you can configure within the matching HTML tags. For instance, an HTML document might contain a title or a background color, and a text element needs some actual content within the text tags. You need to edit these actors so they output more than just generic, empty HTML tags.

To edit actor properties:

1. Select HelloDocument in the outline.
2. Look in the Details pane in the upper right corner of your window.You may need to resize or scroll the pane to see all of the fields for HelloDocument.
   
   
3. Give the document a title.
   Enter hello in the Title field.
4. Enter a comment.
   Comments don't have any functionality in terms of what the capsule does, but they become very important in large projects or ones you have not looked at for a while. This is your chance to note important features of an actor, what its purpose in the project is, or anything else you may want to know later.
5. Select GreetingText in the outline.
6. Look in the Details pane for GreetingText.
   
7. Enter Hello, World! in the Text field.
   
   This sets "Hello, World!" as the content within the HTML tags. This content is what the user actually sees.
   
8. Save your capsule.

Now your capsule contains some actors that hold content for an HTML document. But so far the servlet has no behaviors to associate with this content. It needs to be able to respond to a browser that requests this document, and to be able to send the content out to the browser. To do this, you need to give HelloDocument a behavior.

Adding a behavior to an actor

AppComposer includes several different kinds of behaviors. You can also create new behaviors, edit existing ones, and combine behaviors together into groups. You can then save, rename and reuse common behaviors or actors as often as you wish. AppComposer calls behaviors and actors that you create and save Saved Groups. AppComposer makes these behaviors available from the Insert -> Saved Group menu on the tool bar, or from the Palette in the Saved Groups menu..

AppComposer provides a predefined saved group that is useful for this servlet. It instructs its actor to accept GET requests from a browser, and return output to it. This behavior is called ServletGet.

To add a ServletGet behavior:

1. Select HelloDocument in the outline.
   You want HelloDocument to be able to output itself to a browser, so have it selected as you insert the behavior. This makes the behavior a child of HelloDocument.
   
2. Insert -> Saved Group -> ServletGet
   AppComposer inserts ServletGet as a child of HelloDocument.
3. Save your capsule.
4. Click on ServletGet's outline marker to see what ServletGet contains.

ServletGet is an action group behavior. You can see that by its icon and because it has two behaviors as its children. Like actors, each behavior has an editor so you can define or modify it. AppComposer also provides tools in the outline editor so that you can see what triggers behaviors, and what they in turn affect. These tools give you a better idea of how this action group works.

• Click on the activation events icon to see what triggers the behaviors in the capsule.
• Click on the action targets icon to see what each of the behaviors affects.
  
  

By following the blue arrows, you can see that the servlet capsule activates ServletGet. In turn, ServletGet activates both of its child actions. Look at the details of the child actions to get a better idea of what each does.

1. Select setContent in the outline.
2. The fields in the Details pane show you a little bit about this behavior:
   

• The Stimulus area shows what activates the behavior. In this case, it activates when its parent does. Remember that ServletGet is the parent action of this one.
• The Action area defines what the behavior does when activated. In this case, it tells the capsule that its output is type HTML.

Select sendDocument in the outline and look at its details.

The sendDocument behavior also activates when its parent behavior, ServletGet, activates. Instead of sending a message to the servlet capsule, sendDocument sends a message to its actor. If you look at the capsule outline, you can see that sendDocument belongs to the actor HelloDocument. So this behavior uses Java methods to tell HelloDocument to send its output.

Together, the actions that make up ServletGet respond to a GET request from a browser by sending the HTML content you created.

You can try this for yourself.

To test your servlet output:

Make sure you have set up the debugging web server.
1. Open a browser and go to the http://localhost/ site.
   If you located your web server at a different port, be sure to include that in the URL.
2. Click on the link that says hello.
   You should see a page that looks like this:

The result of the servlet capsule you created may seem humble, but you can build upon the ideas you used to create this to make servlets of far greater complexity and utility.

In the next lesson you will add some interaction with a user. Instead of static output like the Hello, world! example, you will modify the servlet capsule so that it asks for the user's name, and uses it to greet them.