rough draft of initial documentation

[Jonathan Asbell]

pleas comment on this initial rough draft.  There is no color yet.

Title: Struts is simply a package of java classes (components) which you integrate with a java enabled server, and which acts as a �f

Literal explanation of Struts Struts is simply a package of java classes (components) which you integrate into a java enabled server and use for developing web applications.� It functions as a �framework� for building web applications and makes the following advantageous capabilities possible: �          Provides a central organizational structure for building, controlling, and extending web applications �          Enables clean separation between the code used for presentation and the code used for function �          Built-in internationalization (capability of input and display in multiple languages) �          Built-in and extensible authentication and validation �          Allows modular development and easy integration with new components (including enterprise components)   Struts is based on the java servlets and java server pages(jsp) technologies.� It uses a collection of its own �jsp tag� classes to create presentations centered around a unique servlet, the �ActionServlet�, which determines a course of action and a resulting presentation.� Specific requests coming from a user�s activity in the presentation layer trigger the servlet to call upon specific classes you have created to handle a desired activity.   Jump to requirements and installation Jump to Struts details   Struts aims to solve problems which developers continuously face in building, managing, changing, and extending web applications:   The lack of a central point of control and organization Adding new sections to a site means creating a lot of web pages and programming new functionality as well.� How will you link to the new section from the old sections, and how will you link between the areas of the new section?� Will you recreate each presentation page in its entirety from scratch? That�s a lot of copying and pasting. Wouldn�t it be nice to create the presentation(design) pages by re-using some common pieces you have already created (a template).� It would be a great advantage to create any new logic and be able to configure how all the pages in the site are connected all in one place.� When this capability can be accomplished changes can be made without needing to reprogram.� Presentation pages can be created and changed faster.� You will be able to make these changes at single points saving yourself from the wasted time and mistakes involved in copying and pasting the same code over and over and over.   Intermixing of presentation and programming code When a development team permits the mixing of the programmers functional code (java) and the designers presentation code (html etc.) within the same document, a precarious situation is created. In this scenario designers have to be concerned about the effects of the functional code affecting their designed page, and programmers have to spend time helping designers understand and prevent the altering of the functional code which has been mixed in with the design so as to prevent the potential breaking of functionality and presentation.� If these areas are separated then designers can focus on the presentation without worrying about effecting functionality, and programmers can focus on functionality without worrying about effecting presentation.   Difficulty in developing applications with multi-language support Your company has decided to serve users who are native speakers of Spanish, Japanese, and Portuguese.� Everything from the �Welcome� message to the instructions , error messages, money, and dates need to be displayed in the language and format of the user.� How will you handle all of this without extensive programming efforts?� What pieces will programmers have to create to make this an easy task for the designers to use, and for the programmers to change?� Having this capability is a requirement.� Making this capability easy to utilize and alter for your own needs is ideal.� Having all of this capability without having to actually create it translates into a lot of time saved on creation and programmatic management.� Giving designers and translators the ability to add languages and change displayable text and images without the intervention of programmers, means programmers don�t have to spend their time intervening, coding, and changing text at all on behalf of the designers. � Most applications don�t have a complete pre-existing means of Authentication and Validation Every application needs to be able to prevent unauthorized access to certain pages or resources.� Every application needs to validate what users enter, like phone numbers, e-mails, and credit cards.� Most developers end up programming this type of validation over and over, starting from scratch.� Some have developed basic validation packages if they have been involved in the same project for a long period of time.� Having this capability without having to design and program it is yet another time saver.� To then be able to add and extend this capability for your own special needs is something that few applications can claim to possess.   Most web applications are not modular and do not easily integrate with new components. The popularity of your web application is growing, and now thousands of users are viewing your site on a daily basis.� You need to move this particular web site of yours away from the other ones to another server box that has more memory. �You also decide to �distribute� the basic functional pieces of your site by using enterprise components located on yet a third server box with which the stuff on the first box communicates with.� This capability is an important option, but for it to be beneficial it must be simple as well.� It could cost you a lot of time should you need to do a lot of reprogramming.� If the web oriented programming can be neatly separated from the distributed functional programming, you will have the ability to move whole sites around without affecting code that has already been developed in both areas.   Jump to requirements and installation Jump to Struts details         Struts components   The ActionServlet Struts� function is centered around a very powerful servlet called �ActionServlet� which gets loaded when you start up the server that manages your application.� You configure it�s behavior in 2 specific xml files, �web.xml� and �struts-config.xml�, which are also both read upon startup.� Once the application is running, the servlet gets triggered when a specific String in a requested URI matches a specific String you configured the servlet to look for in the �web.xml� file.� Once triggered, it makes a series of calls to components you have created and defined associations for in the �struts-config.xml� file, where all associations between components are defined.� Want to change an association between an activity and an action to take on that activity? Just change the �struts-config.xml� file.   The Tag Classes The Struts package contains a series of �Tag� classes which designers will use to create displays (web pages).� Theses tags purposely have the appearance of html, but they do a lot more.� Their purpose is 2-fold: 1)       To allow designers to work with presentation code that looks familiar (looks like html tags) without them having see any programming code. 2)       To enable programmers to use a tags extra capabilities of passing around data and managing internationalization     How it all works   STEP 1 - Upon starting up your server: When you start up your server, it searches for web applications you have configured.� If the server was configured properly it will recognize the existence of the root directory of your particular web application and in turn will search for a specific directory under the root called �WEB-INF�.� In the WEB-INF directory you must have already created and configured an xml file called �web.xml� which contains default behavior and configurations for your application: behavior which you server reads� and uses (this is a standard behavior in servlet spec 2.2 section 9.4).� In the �web.xml� file you will have mentioned the Struts �ActionServlet� class and you will have configured it to load upon startup.   STEP-2 As the servlet loads: As the �ActionServlet� is loading it searches for another xml file called �struts-config.xml�.� This xml file contains the configuration information for the behavior of the servlet itself. The �struts-config.xml� file contains associations between Struts components.� As the �ActionServlet� reads �struts-config.xml�, it begins to create and register Struts based classes which you have both designed and mentioned in the file, and it places them in memory associated with a lookup name.� Now the servlet is ready to react to requests.   STEP-3 After the servlet has been loaded: A user now begins surfing around your site and clicks on a link which sends out a URI request such as� �http://www.yoursite.com/search.do� for your server to process.� The �ActionServlet� will have been configured by you to respond to any URI that matches a particular String, in this example it would be any URI that ends in �.do�.� The �ActionServlet� will first strip of the �.do�, leaving http://www.yoursite.com/search� and will try to look up and get a class registered by �ActionServlet� and associated with the String �search� (everything from the stripped off �.do� backwards to the first �/� encountered). The �ActionServlet� now uses this looked up class, an �Action� class,� to process the request.� A different request could call upon a different �Action� class to perform yet a different function.� Now this �Action� class does what it does, calls who it needs to call, and finally looks up and returns an �ActionForward� object.� This is merely an object you select which contains the destination URI for a particular outcome.� The user is now forwarded to the resulting destination.     Usage and installation requirements   Struts is based on the java servlets and java server pages(jsp) technologies.� Therefore, you will need this capability installed and configured properly on your computer for Struts to work.� Depending on your needs, Struts may require other separate packages as well.� Below are the requirements.   Required packages for using Struts: 1)       Java Development Kit(JDK) �          minimum version 1.2 �          recommended version atleast 1.3, (1.4 will be out soon) 2)       servlet and jsp capable engine which must support atleast servlet version 2.2 and jsp version 1.1. �          try java based server which has servlet capabilities (TOMCAT, JBOSS, WEBLOGIC etc.) a.        Bluestone Universal Business Server - Additional steps required. b.        Borland Application Server 4.5 -No additional steps required. c.        iPlanet Application Server - Service Pack 2 is recommended. Note that the database object in the Struts-Example application is not compatible with this container. d.        iPlanet Web Server - Additional steps required. e.        iPortal Application Server - Additional steps required. f.         Orion Application Server - Additional steps required. g.        Resin 2.1+ "standalone" - No additional steps required. h.        Silverstream - - Additional steps required. i.         Tomcat 3.1 and prior - Not recommended. Use Tomcat 3.2.1 or later. j.         Tomcat 3.2.1+ "standalone" - No additional steps required. k.        Tomcat 3.2.1 with Apache - Additional steps required. l.         Weblogic - Additional steps required. m.      WebLogic 6.0+ - No additional steps required. n.        WebSphere - Additional steps required. o.        WebSphere - Steps for the Example Application. �          or a non-java based server integrated by installling a separate java servlet enabled package(Allaire�s jrun). a.        JRUN - Additional steps required. 3)       xml parser package only if they are not already available from any of your previously installed packages, and must be compatible with the Java API for XML Parsing (JAXP) version 1.0 or later �          jdk 1.3 already has one included �          otherwise we recommend apache�s XERCES   Additionally required packages if you intend to recompile Struts from scratch from the source distribution: 1)       ANT package(used for building), minimum version 1.3 2)       SERVLET package only if they are not already included in the previously mentioned �JDK� or server you have installed. (It is not included in some versions of JDK1.2) 3)       XALAN xslt processor package version 1.2 (problems have been reported with current versions of Xalan 2.0), or use the version of Xalan included in the JAXP 1.1 release   Required packages if you will be using JDBC 2.0 capabilities: 1)   Installing the packages: