| <?xml version="1.0"?> |
| <document url="introduction.html"> |
| |
| <properties> |
| <title>The Struts User's Guide - Introduction</title> |
| </properties> |
| |
| <body> |
| |
| <section name="1. Introduction" href="introduction"/> |
| |
| <section name="1.1 Forward into the Past! (or a brief history of Struts)" href="history"> |
| |
| <p> |
| When Java servlets were first invented, many programmers quickly realized that they were a |
| Good Thing. They were faster and more powerful that standard CGI, portable, and infinitely |
| extensible. |
| </p> |
| |
| <p> |
| But writing HTML to send to the browser in endless <code>println()</code> statements was tiresome and |
| problematic. The answer to that was |
| <a href="http://java.sun.com/products/jsp/product.html">JavaServer Pages</a>, |
| which turned |
| <a href="http://java.sun.com/products/jsp/product.html">Servlet</a> writing inside-out. |
| Now developers could easily mix HTML with Java code, and have all the advantages of servlets. |
| The sky was the limit! |
| </p> |
| |
| <p> |
| Java web applications quickly became "JSP-centric". This in-and-of itself was not a Bad |
| Thing, but it did little to resolve flow control issues and other problems endemic to web |
| applications. |
| </p> |
| |
| <p>Another model was clearly needed ...</p> |
| |
| <p> |
| Many clever developers realized that JavaServer Pages AND servlets could be used <strong> |
| together</strong> to deploy web applications. The servlets could help with the control-flow, and the |
| JSPs could focus on the nasty business of writing HTML. In due course, using JSPs and servlets |
| together became known as |
| <a href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html">Model 2</a> |
| (meaning, presumably, that using JSPs alone was Model 1). |
| </p> |
| |
| <p> |
| Of course, there is nothing new under the Sun ... and many have been quick to point out that |
| JSP's Model 2 follows the classic |
| <a href="http://java.sun.com/blueprints/patterns/j2ee_patterns/model_view_controller/">Model-View-Controller</a> |
| design pattern abstracted from the venerable |
| <a href="http://st-www.cs.uiuc.edu/users/smarch/st-docs/mvc.html">Smalltalk MVC framework</a>. |
| Java Web developers now tend to use the terms Model 2 and MVC interchangeably. In this guide, we use |
| the MVC paradigm to describe the Struts architecture, which might be best termed a Model 2/MVC |
| design. |
| </p> |
| |
| <p> |
| The Struts project was launched in May 2000 by Craig R. McClanahan to provide a standard MVC |
| framework to the Java community. In July 2001, Struts 1.0 was released, and IOHO, Java |
| Model 2 development will never be quite the same. |
| </p> |
| |
| </section> |
| |
| <section name="1.2 The Model-View-Controller ('MVC') Design Pattern" href="mvc"> |
| |
| <p> |
| In the MVC design pattern, application flow is mediated by a |
| central Controller. The Controller delegates requests - in our |
| case, HTTP requests - to an appropriate handler. The handlers |
| are tied to a Model, and each handler acts as an adapter |
| between the request and the Model. The Model represents, or |
| encapsulates, an application's business logic or |
| state. Control is usually then forwarded back through the |
| Controller to the appropriate View. The forwarding can be |
| determined by consulting a set of mappings, usually loaded |
| from a database or configuration file. This provides a loose |
| coupling between the View and Model, which can make |
| applications significantly easier to create and maintain. |
| </p> |
| |
| </section> |
| |
| <section name="1.2.1 The Model: System State and Business Logic JavaBeans" href="modelConcepts"> |
| |
| <p> |
| The <em>Model</em> portion of an MVC-based system can be often be divided into |
| two major subsystems -- the <strong>internal state</strong> of the system |
| and the <strong>actions</strong> that can be taken to change that state. |
| </p> |
| |
| <p>In grammatical terms, we might think about |
| state information as <strong>nouns</strong> (things) and actions as <strong>verbs</strong> |
| (changes to the state of those things). |
| </p> |
| |
| <p> |
| Many applications represent the internal state of the |
| system as a set of one or more JavaBeans. The bean properties represent |
| the details of the system' state. Depending on your application's complexity, |
| these beans may be self contained (and know how to persist their own state), |
| or they may be facades that know how to retrieve the system's state from another |
| component. This component may be a database, a search engine, an Entity Enterprise |
| JavaBean, a LDAP server, or something else entirely. |
| </p> |
| |
| <p> |
| Large-scale applications will often represent the set of possible |
| business operations as methods that can be called on the bean or beans |
| maintaining the state information. For example, you might have a shopping |
| cart bean, stored in session scope for each current user, with properties |
| that represent the current set of items that the user has decided to |
| purchase. This bean might also have a <code>checkOut()</code> method |
| that authorizes the user's credit card and sends the order to the |
| warehouse to be picked and shipped. Other systems will represent the |
| available operations separately, perhaps as Session Enterprise JavaBeans |
| (Session EJBs). |
| </p> |
| |
| <p> |
| In a smaller scale application, on the other hand, the available |
| operations might be embedded within the <code>Action</code> classes that are |
| part of the Struts control layer. This can be useful when the logic is very |
| simple or where reuse of the business logic in other environments is not |
| contemplated. |
| </p> |
| |
| <p> |
| The Struts framework architecture is flexible enough to support most any |
| approach to accessing the Model, but we <strong>strongly</strong> recommend that you |
| separate the business logic ("how it's done") from the role that |
| <code>Action</code> classes play ("what to do"). 'nuff said. |
| </p> |
| |
| <p> |
| For more about adapting your application's Model to Struts, see the |
| <a href="building_model.html">Building Model Components</a> chapter. |
| </p> |
| |
| </section> |
| |
| <section name="1.2.2 The View: JSP Pages and Presentation Components" href="presentationConcepts"> |
| |
| <p> |
| The <em>View</em> portion of a Struts-based application is most often |
| constructed using JavaServer Pages (JSP) technology. JSP pages can |
| contain static HTML (or XML) text called "template text", plus the |
| ability to insert dynamic content based on the interpretation (at page |
| request time) of special action tags. The JSP environment includes a |
| set of standard action tags, such as <code><jsp:useBean></code> |
| whose purpose is described in the <a href="http://java.sun.com/products/jsp/download.html">JavaServer Pages Specification</a>. |
| In addition to the built-in actions, there is a standard facility to |
| define your own tags, which are organized into "custom tag libraries." |
| </p> |
| |
| <p> |
| Struts includes a set of custom tag libraries that facilitate |
| creating user interfaces that are fully internationalized, and that |
| interact gracefully with <code>ActionForm</code> beans that are part |
| of the <em>Model</em> portion of the system. |
| </p> |
| |
| <p> |
| For more about the Struts taglibs and using presentation pages |
| with the framework, see the |
| "<a href="building_view.html">Building View Components</a>" chapter. |
| Additional documentation regarding the taglibs is also available in |
| the Developer Guides (see menu). |
| </p> |
| </section> |
| |
| <section name="1.2.3 The Controller: ActionServlet and ActionMapping" href="controllerConcepts"> |
| |
| <p> |
| The <em>Controller</em> portion of the application is focused on receiving |
| requests from the client (typically a user running a web browser), deciding |
| what business logic function is to be performed, and then delegating |
| responsibility for producing the next phase of the user interface to |
| an appropriate View component. In Struts, the primary component of the |
| Controller is a servlet of class <code>ActionServlet</code>. This servlet |
| is configured by defining a set of <code>ActionMappings</code>. |
| An ActionMapping defines a <code>path</code> that is matched against the |
| request URI of the incoming request, and usually specifies the |
| fully qualified class name of an Action class. All Actions |
| are subclassed from <code>org.apache.struts.action.Action</code>. Actions |
| encapsulate the business logic, interpret the outcome, and ultimately dispatch |
| control to the appropriate View component to create the response. |
| </p> |
| |
| <p> |
| Struts also supports the ability to use <code>ActionMapping</code> |
| classes that have additional properties beyond the standard ones required |
| to operate the framework. This allows you to store additional information |
| specific to your application, but still utilize the remaining features of |
| the framework. In addition, Struts lets you define logical "names" to which |
| control should be forwarded so that an action method can ask for the |
| "Main Menu" page (for example), without knowing what the actual name of the |
| corresponding JSP page is. These features greatly assist you in separating |
| the control logic (what to do) with the view logic (how it's rendered). |
| </p> |
| |
| <p> |
| For more about the Struts control layer, see the |
| <a href="building_controller.html">Building Controller Components</a> chapter. |
| </p> |
| |
| </section> |
| |
| <section name="1.3 Struts Control Flow" href="flow"> |
| |
| <p> |
| The Struts framework provides several components that make up the <strong>Control</strong> |
| layer of a MVC-style application. These include a controller servlet, |
| developer-defined request handlers, and several supporting objects. |
| </p> |
| |
| <p> |
| The Struts custom tag libraries provide direct support for the <strong>View</strong> layer |
| of a MVC application. Some of these access the control-layer objects. |
| Others are generic tags found convenient when writing applications. Other |
| taglibs, including |
| <a href="http://java.sun.com/products/jsp/jstl/index.html">JSTL</a>, |
| can also be used with Struts. Other presentation technologies, like |
| <a href="http://jakarta.apache.org/velocity/index.html">Velocity Templates</a> and |
| <a href="http://www.w3.org/TR/xslt">XSLT</a> |
| can also be used with Struts. |
| </p> |
| |
| <p> |
| The <strong>Model</strong> layer in a MVC application is often project-specific. Struts is |
| designed to make it easy to access the business-end of your application, |
| but leaves that part of the programming to other products, like |
| <a href="http://java.sun.com/products/jdbc/index.html">JDBC</a>, |
| <a href="http://java.sun.com/products/ejb/index.html">Enterprise Java Beans</a>, |
| <a href="http://jakarta.apache.org/ojb/">Object Relational Bridge</a>, or |
| <a href="http://netmeme.org/simper/">Simper</a>, |
| to name a few. |
| </p> |
| |
| <p> |
| Let's step through how this all fits together. |
| </p> |
| |
| <p> |
| When initialized, the controller parses a configuration |
| file (<code>struts-config.xml</code>) and uses it to deploy other control layer objects. |
| Together, these objects form the <strong>Struts Configuration</strong>. The Struts Configuration |
| defines (among other things) the |
| <a href="../api/org/apache/struts/action/ActionMappings.html">ActionMappings</a> |
| [<code>org.apache.struts.action.ActionMappings</code>] for an application. |
| </p> |
| |
| <p> |
| The Struts controller servlet consults the ActionMappings as it routes HTTP |
| requests to other components in the framework. Requests may be forwarded to JavaServer Pages or |
| <a href="../api/org/apache/struts/action/Action.html">Action</a> |
| [<code>org.apache.struts.action.Action</code>] subclasses provided by the |
| Struts developer. Often, a request is first forwarded to an Action and then to a JSP |
| (or other presentation page). The mappings help the controller turn HTTP requests into application |
| actions. |
| </p> |
| |
| <p> |
| An individual |
| <a href="../api/org/apache/struts/action/ActionMapping.html">ActionMapping</a> |
| [<code>org.apache.struts.action.ActionMapping</code>] |
| will usually contain a number of properties including:</p> |
| <ul> |
| <li>a <strong>request path</strong> (or "URI"),</li> |
| <li>the <strong>object type</strong> (Action subclass) to act upon the request, and</li> |
| <li>other properties as needed. </li> |
| </ul> |
| <p> |
| The Action object can handle the request and respond to the client (usually a Web |
| browser) or indicate that control should be forwarded elsewhere. For example, if |
| a login succeeds, a login action may wish to forward the request onto the |
| mainMenu page. |
| </p> |
| |
| <p> |
| Action objects have access to the application's controller servlet, and so have access |
| to that servlet's methods. When forwarding control, an Action object can indirectly |
| forward one or more shared objects, including |
| <a href="http://java.sun.com/products/javabeans/">JavaBeans</a>, by placing them in one |
| of the standard contexts shared by Java Servlets. |
| </p> |
| |
| <p> |
| For example, an Action object can create a shopping cart bean, add an item to the |
| cart, place the bean in the session context, and then forward control to |
| another mapping. That mapping may use a JavaServer Page to display the contents of the user's cart. |
| Since each client has their own session, they will each also have their own |
| shopping cart. </p> |
| <p> |
| In a Struts application, most of the business logic can be |
| represented using JavaBeans. An Action can call the properties of a JavaBean |
| without knowing how it actually works. This encapsulates the business logic, |
| so that the Action can focus on error handling and where to forward control. |
| </p> |
| |
| <p> |
| JavaBeans can also be used to manage input forms. A key problem in designing |
| Web applications is retaining and validating what a user has entered between |
| requests. With Struts, you can define your own set of input bean classes, by |
| subclassing |
| <a href="../api/org/apache/struts/action/ActionForm.html">ActionForm</a> |
| [<code>org.apache.struts.action.ActionForm</code>]. The ActionForm class makes it |
| easy to store <strong>and validate</strong> the data for your application's input forms. |
| The ActionForm bean is automatically saved in one of the standard, shared context |
| collections, so that it can be used by other objects, like an Action object or |
| another JSP. |
| </p> |
| |
| <p> |
| The form bean can be used by a JSP to collect data from the user ... by an |
| Action object to validate the user-entered data ... and then by the JSP again to |
| re-populate the form fields. In the case of validation errors, Struts has a |
| shared mechanism for raising and displaying error messages. |
| </p> |
| |
| <p> |
| Another element of the Struts Configuration are the |
| <a href="../api/org/apache/struts/action/ActionFormBeans.html">ActionFormBeans</a> |
| [<code>org.apache.struts.action.ActionFormBeans</code>]. |
| This is a collection of |
| <a href="../api/org/apache/struts/action/ActionFormBean.html">descriptor objects</a> |
| that are used to create instances of the ActionForm objects at runtime. |
| When a mapping needs an ActionForm, the servlet looks up the form-bean descriptor by name and uses |
| it to create an ActionForm instance of the specified type. |
| </p> |
| <p> |
| Here is the sequence of events that occur when a request calls for an mapping that uses an ActionForm: |
| </p> |
| |
| <ul> |
| <li>The controller servlet either retrieves or creates the ActionForm bean instance.</li> |
| <li>The controller servlet passes the bean to the Action object.</li> |
| <li>If the request is being used to submit an input page, the Action object |
| can examine the data. If necessary, the data can be sent back to the input |
| form along with a list of messages to display on the page. Otherwise the data can |
| be passed along to the business tier.</li> |
| <li>If the request is being used to create an input page, the Action object can |
| populate the bean with any data that the input page might need. </li> |
| </ul> |
| |
| <p> |
| The Struts framework includes custom tags that can automatically populate |
| fields from a JavaBean. All most JavaServer Pages really need to know |
| about the rest of the framework is the field names to use and where to submit |
| the form. |
| </p> |
| <p> |
| Other Struts tags can automatically output messages queued by an Action |
| or ActionForm and simply need to be integrated into the page's markup. |
| The messages are designed for |
| <a href="http://developer.java.sun.com/developer/technicalArticles/Intl/IntlIntro/">localization</a> |
| and will render the best available message for a user's locale. |
| </p> |
| |
| <p> |
| The Struts framework and its custom tag libraries were designed from the ground-up |
| to support the internationalization features built into the Java platform. All the field labels |
| and messages can be retrieved from a |
| <a href="../api/org/apache/struts/util/MessageResources.html">message resource</a>. |
| To provide messages for another language, simply add another file to the resource bundle. |
| </p> |
| |
| <p> |
| Internationalism aside, other benefits to the message resources approach are consistent labeling |
| between forms, and the ability to review all labels and messages from a central |
| location. |
| </p> |
| |
| <p> |
| For the simplest applications, an Action object may sometimes handle the business logic |
| associated with a request. <strong>However, in most cases, an Action object should |
| invoke another object, usually a JavaBean, to perform the actual business logic.</strong> |
| This lets the Action focus on error handling and control flow, rather than |
| business logic. To allow reuse on other platforms, business-logic JavaBeans should not refer to any Web |
| application objects. The Action object should translate needed details from the |
| HTTP request and pass those along to the business-logic beans as regular Java |
| variables. |
| </p> |
| |
| <p> |
| In a database application, for example: |
| </p> |
| |
| <ul> |
| <li>A business-logic bean will connect to and query the database,</li> |
| <li>The business-logic bean returns the result to the Action,</li> |
| <li>The Action stores the result in a form bean in the request,</li> |
| <li>The JavaServer Page displays the result in a HTML form.</li> |
| </ul> |
| |
| <p>Neither the Action nor the JSP need to know (or care) from where |
| the result comes. They just need to know how to package and display it. |
| </p> |
| |
| <p> |
| <a href="index.html">Other chapters</a> in this document cover the |
| various Struts components in greater detail. The Struts release also |
| includes several Developer Guides covering various aspects of the |
| frameworks, along with sample applications, the standard Javadoc API, |
| and, of course, the complete source code! |
| </p> |
| |
| <p> |
| Struts is distributed under the Apache Software Foundation license. The code |
| is copyrighted, but is free to use in any application. See the |
| <a href="http://www.apache.org/LICENSE-1.1">ASF license</a> for specifics. |
| </p> |
| |
| </section> |
| |
| <section> |
| <p class="right"> |
| Next: <a href="building_model.html">Building Model Components</a> |
| </p> |
| </section> |
| |
| |
| </body> |
| </document> |