| $Id: INSTALL,v 1.6.2.1 2001/07/21 06:18:33 martinc Exp $ |
| |
| Struts |
| ====== |
| |
| This document contains notes that have been accumulated on getting the Struts |
| applications (documentation and example) running in a variety of servlet |
| container environments. |
| |
| For most containers, you need only to: |
| |
| * Copy the WAR files in your Struts < /webapp > directory to your containers |
| < webapps > directory. |
| |
| * In some cases, you may need to restart your container if it is running. |
| |
| Status of various containers -- as reported by volunteers on the Struts-User list. |
| |
| * Tomcat 3.1+ Standalone - No additonal steps required. |
| * Resin 1.2+ Standalone - No additional steps required. |
| * WebLogic 6.0+ - No additional steps required. |
| |
| * Bluestone Universal Business Server - Additional steps provided below. |
| * JRUN - Additional steps provided below. |
| * Orion Application Server - Additional steps provided below. |
| * Tomcat 3.1+ with Apache - Additional steps provided below. |
| * Weblogic 5.1 (sp8) - Additional steps provided below. |
| |
| * Websphere - Determination pending. |
| |
| |
| BLUESTONE UNIVERSAL BUSINESS SERVER |
| ----------------------------------- |
| |
| * You need UBS version 7.2 to run war file applications. The UBS 7.2.2 |
| evaluation is located here: |
| |
| http://www.bluestone.com/SaISAPI.dll/SaServletEngine.class/products/downloads.jsp |
| |
| * If you're using version 7.2.1, you need to download the WAR file patch, |
| located in the product enhancement section of Bluestone's website: |
| |
| http://www.bluestone.com/SaISAPI.dll/SaServletEngine.class/products/wfe.jsp |
| |
| * After installation of the correct version and/or patch of UBS 7.2, you |
| need to modify your apserver.txt file to point to the correct directory |
| for your war file applications. Look for the section that says something |
| similar to the following: |
| |
| [SaServletEngine.class] |
| session_affinity=1 |
| type=1 |
| program=/SaServletEngine.class |
| file_path=f:\webapps |
| host=localhost:20000 |
| |
| * Use the directory specified by the "file_path" variable, or modify it |
| to point to your own custom webapp directory. Copy the |
| "struts-documention.war" and "struts-example.war" files into that |
| webapp directory, and start the UBS (read documentation distributed |
| with UBS for information on how to start it if necessary). Your webapps |
| are now accessible from the following URL's: |
| |
| http://localhost/<PLUGIN>/SaServletEngine.class/struts-example/ |
| http://localhost/<PLUGIN>/SaServletEngine.class/struts-documentation/ |
| |
| |
| * "<PLUGIN>" represents the plugin you are using for your specific |
| webserver. For apache on Windows, it might be "cgi-bin/SaCGI.exe", |
| for IIS on Windows, it might be "scripts/SaCGI.exe" or "scripts/ISAPI.dll". |
| Consult the UBS documentation for more information. |
| |
| |
| JRUN 3.0 SP2A, VERSION 3.02A.11614 |
| ---------------------------------- |
| Tested with: Microsoft IIS 5.0, Windows 2000 |
| |
| |
| Important Note: |
| =============== |
| |
| At the moment, JRun is not fully compliant with the JSP 1.1/1.2 |
| specification. |
| |
| Specifically, the automatic type conversions for custom tag parameters |
| specified in "Issue 7" of the JSP 1.1 Errata and in the JSP 1.2 Proposed |
| Final Draft have not yet been implemented. |
| |
| As it stands, JSP pages that make use of Struts taglibs whose parameters |
| require conversion (such as booleans) will not compile under JRun. This |
| includes the Struts Example Application. Attempting to run the example |
| application will result in an exception similar to the following being |
| thrown: |
| |
| /struts-example/index.jsp: |
| |
| javax.servlet.ServletException: Compilation error occured: |
| |
| allaire.jrun.scripting.DefaultCFE: |
| |
| Errors reported by compiler: |
| c:/JRun/servers/default/Struts Example/WEB-INF/jsp/jrun__index2ejspa.java:41:1:41:27: |
| Error: No match was found for method "setLocale(java.lang.String)". |
| |
| (For more details refer to: |
| |
| < http://www.mail-archive.com/struts-user@jakarta.apache.org/msg01860.html >) |
| |
| The following instructions describe how to install the Struts Example |
| Application under JRun. A subsequent section describes how the Struts Example |
| Application can be patched to work with Struts |
| |
| |
| The following instructions assume the following: |
| |
| * JRun has been installed and integrated with the web server of choice |
| |
| * $APP_SERVER_NAME is the name of the application server used to host the |
| application. (When JRun is first installed, it creates an application |
| server called JRun Default Server) |
| |
| * $APP_SERVER_DIR is the directory used to hold applications hosted by |
| $APP_SERVER_NAME. For the JRun Default Server, the directory is |
| $JRUN_HOME/servers/default where $JRUN_HOME is the directory where |
| JRun is installed. |
| |
| Installing The Struts Example Application |
| ----------------------------------------- |
| |
| * Login to the JRun Management Console. |
| |
| * On the left pane, select $APP_SERVER_NAME. A page showing the |
| current server status will be shown on the right pane. |
| |
| * On the right pane, click on the WAR Deployment link. A page |
| containing a list of the currently deployed web applications will be |
| shown. |
| |
| * On the right pane, click on Deploy an Application. Complete the Web |
| Application Information form as follows: |
| |
| o Servlet War File or Directory: Enter the full path where |
| struts-example.war is found or click on Browse to select |
| the path. |
| o JRun Server Name: $APP_SERVER_NAME |
| o Application Name: Struts Example |
| o Application Hosts: All Hosts |
| o Application URL: /struts-example |
| o Application Deploy Directory: will default to |
| $APP_SERVER_NAME/Struts Example (or the name as specified for |
| Application Name) |
| |
| * Once the form is complete, click on the Deploy button. |
| |
| * If deployment is successful, restart the application server by |
| clicking on $APP_SERVER_NAME on the left pane. A page showing the |
| current server status will be shown on the right pane. Click the |
| Restart Server button to restart the application server. |
| |
| * Test the sample application by using the following URL in the |
| browser: |
| http://hostname/struts-example/index.jsp |
| |
| The struts-documentation.war can be installed using the same |
| procedure. |
| |
| |
| Installing Unpacked Web Applications |
| ------------------------------------ |
| |
| The above steps should be followed for applications deployed as *.war files. |
| |
| For unpacked web applications, configuration involves the following steps: |
| |
| * From the JRun Management Console, select $APP_SERVER_NAME (on the |
| left pane) and click on WAR Deployment (on the right pane) |
| |
| * On the right pane, click on Create an Application and complete the |
| Web Application Information form as follows: |
| |
| * JRun Server Name: $APP_SERVER_NAME |
| |
| o Application Name: myApplication |
| o Application Hosts: All Hosts |
| o Application URL: /myApplication |
| o Application Deploy Directory: will default to |
| $APP_SERVER_NAME/myApplication |
| |
| * Click on Create to submit the form. |
| |
| * Once the web application is created, install and configure the struts |
| components (struts.jar, struts*.tld, etc) for the web application under |
| $APP_SERVER_NAME/myApplication/WEB-INF |
| |
| * Install the remaining components of the application: .class files, |
| JSP pages,.properties files etc as required. |
| |
| * To configure the extension mapping of the request URI (ie *.do) to |
| the action servlet, expand $APP_SERVER_NAME on the left pane, expand |
| the Web Applications branch and click on myApplication. The right pane |
| will display the configuration options for myApplication. Click on |
| Servlet URL Mappings. A list of existing mappings will be shown. Click |
| the Edit button and create the following entry: |
| |
| o Virtual Path/Extension: *.do |
| o Servlet Invoked: action |
| |
| * Click on the Update button to save the changes. |
| * Restart the application server. |
| * The application should now be accessible from the browser. |
| |
| The JRun application server will need to be restarted each time one of the |
| following changes are made to the web application: |
| |
| * .class or .jar files are modified |
| |
| * .properties files are modified |
| |
| * .xml files are modified |
| |
| |
| Patching The Struts Example Application |
| --------------------------------------- |
| |
| As mentioned at the beginning of these notes, the Struts Example Application |
| will not run under JRun without modification. The following changes will need |
| to be made: |
| |
| * index.jsp, logon.jsp: Change <html:html locale="true"> to |
| <html:html locale=<%= true %>> |
| |
| * registration.jsp, subscription.jsp: Change all instances of |
| filter="true" to filter=<%= true %> |
| |
| |
| ORION APPLICATION SERVER |
| ------------------------ |
| |
| * In the steps below, $ORION_HOME refers to the directory in which you |
| have installed Orion, and $STRUTS_HOME is the directory in which you |
| unpacked the Struts binary distribution. |
| |
| * Modify the file "$ORION_HOME/config/application.xml" to define the two |
| new applications, by adding the following declarations, immediately |
| following the <web-module> directive for the default web application: |
| |
| <web-module id="strutsDoc" |
| path="$STRUTS_HOME/webapps/struts-documentation.war"/> |
| |
| <web-module id="strutsExample" |
| path="$STRUTS_HOME/webapps/struts-example.war"/> |
| |
| * Modify the file "$ORION_HOME/config/default-web-site.xml" (or the |
| configuration file for any other Orion web site) to include the following |
| declarations, after the declaration for the <default-web-app> if any: |
| |
| <web-app application="default" name="strutsDoc" |
| root="/struts-documentation"/> |
| |
| <web-app application="default" name="strutsExample" |
| root="/struts-example"/> |
| |
| * After you start Orion, you should now be able to access these applications |
| (assuming you haven't changed the port number from the default of 80) at: |
| |
| http://localhost/struts-documentation |
| |
| http://localhost/struts-example |
| |
| * Versions of Orion up to at least 1.0.3 have a bug related to |
| ServletContext.getResource() calls that prevent the Struts example |
| application from working out of the box. This manifests itself as a |
| JSP error when you try to access the example application, with the |
| following message: |
| |
| javax.servlet.jsp.JspException: Missing resources attribute |
| org.apache.struts.action.MESSAGE |
| |
| followed by an error traceback. There will also be an initialization |
| error message in the "$ORION_HOME/log/global-application.log" log file. |
| To work around this problem, you can take the following steps: |
| |
| - Go to the "$STRUTS_HOME/webapps" directory, where you will note that |
| Orion has automatically expanded each web application into an |
| unpacked directory structure. |
| |
| - Go to the "$STRUTS_HOME/webapps/struts-example/WEB-INF" directory, |
| and copy the file "struts-config.xml" one directory up (that is, into |
| "$STRUTS_HOME/webapps/struts-example". |
| |
| - Modify the "$STRUTS_HOME/webapps/struts-example/WEB-INF/web.xml" file, |
| changing the value of the "config" initialization parameter (for the |
| action servlet) from "/WEB-INF/struts-config.xml" to "/struts-config.xml". |
| |
| - Restart Orion, and you should be able to access the example application. |
| |
| Note that this workaround has a negative security-related side effect: |
| your "struts-config.xml" file can now be retrieved by remote clients at the |
| following URL: |
| |
| http://localhost/struts-example/struts-config.xml |
| |
| Therefore, you should be sure you do not store sensitive information |
| (such as database passwords) in this file. |
| |
| |
| SILVERSTREAM APPLICATION SERVER 3.7.1 AND LATER |
| ----------------------------------------------- |
| |
| Start the SilverStream application server. |
| |
| Create an XML deployment plan for the "struts-example.war" application. |
| |
| Call the file "struts-example-depl-plan.xml". You can use the following |
| contents for the file |
| |
| ----- cut here ----- |
| |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE warJarOptions PUBLIC |
| "-//SilverStream Software, Inc.//DTD J2EE WAR Deployment Plan//EN" |
| "deploy_war.dtd"> |
| <warJarOptions> |
| <warJar> |
| <warJarName>struts-example.war</warJarName> |
| <isEnabled>true</isEnabled> |
| <urls><el>struts-example</el></urls> |
| </warJar> |
| </warJarOptions> |
| |
| ----- cut here ----- |
| |
| Create an XML deployment plan for the "struts-documentation.war" |
| application. |
| |
| Call the file "struts-documentation-depl-plan.xml". You can use the |
| following contents for the file: |
| |
| ----- cut here ----- |
| |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE warJarOptions PUBLIC |
| "-//SilverStream Software, Inc.//DTD J2EE WAR Deployment Plan//EN" |
| "deploy_war.dtd"> |
| <warJarOptions> |
| <warJar> |
| <warJarName>struts-documentation.war</warJarName> |
| <isEnabled>true</isEnabled> |
| <urls><el>struts-documentation</el></urls> |
| </warJar> |
| </warJarOptions> |
| |
| ----- cut here ----- |
| |
| Run the following "SilverCmd DeployWAR" commands to deploy the applications. |
| You can change 'localhost' to whatever server you are deploying to. You can |
| change 'Silvermaster' to whatever database you are deploying to. |
| |
| SilverCmd DeployWar localhost Silvermaster struts-example.war |
| -f struts-example-depl-plan.xml |
| SilverCmd DeployWar localhost Silvermaster struts-documentation.war |
| -f struts-documentation-depl-plan.xml |
| |
| |
| TOMCAT 3.1 (OR LATER) WITH APACHE |
| --------------------------------- |
| |
| * These instructions assume you have successfully integrated |
| Tomcat with Apache according to the Tomcat documentation. |
| |
| * Copy "struts-documentation.war" and "struts-example.war" |
| to your $TOMCAT_HOME/webapps directory |
| |
| * Restart Tomcat if it is already running |
| |
| * Tomcat will generate a file "$TOMCAT_HOME/conf/tomcat-apache.conf" |
| that will be used by Apache. This file is regenerated every time |
| you start Tomcat, so copy this file to a safe place (such as |
| your Apache configuration directory; on Unix systems this is usually |
| "/usr/local/apache/conf". |
| |
| * If you are running Tomcat 3.1, Tomcat will not have generated the |
| entries for your new applications. Add the following lines to the |
| "tomcat-apache.conf" file that you have saved, replacing |
| $TOMCAT_HOME with the path to your Tomcat home directory: |
| |
| Alias /struts-documentation "$TOMCAT_HOME/webapps/struts-documentation" |
| <Directory "$TOMCAT_HOME/webapps/struts-documentation> |
| Options Indexes FollowSymLinks |
| </Directory> |
| ApJServMount /struts-documentation/servlet /struts-documentation |
| <Location "/struts-documentation/WEB-INF/"> |
| AllowOverride None |
| deny from all |
| </Location> |
| |
| Alias /struts-example "$TOMCAT_HOME/webapps/struts-example" |
| <Directory "$TOMCAT_HOME/webapps/struts-example> |
| Options Indexes FollowSymLinks |
| </Directory> |
| ApJServMount /struts-example/servlet /struts-example |
| <Location "/struts-example/WEB-INF/"> |
| AllowOverride None |
| deny from all |
| </Location> |
| |
| * On all versions of Tomcat, the generated file above does not |
| know anything about extension mappings defined in a web.xml file, |
| so the "*.do" URIs that go to the controller servlet will not be |
| recognized. To fix this, add the following line to the saved |
| version of "tomcat-apache.conf", after the corresponding line |
| for the .jsp extension: |
| |
| AddHandler jserv-servlet .do |
| |
| * Ensure that the saved version of "tomcat-apache.conf" is referenced |
| in your Apache "httpd.conf" configuration file. A typical use would |
| have the following line at the bottom of "httpd.conf": |
| |
| Include /usr/local/apache/conf/tomcat-apache.conf |
| |
| * In order to recognize "index.jsp" as a default page for web |
| applications, search in your "httpd.conf" for a "DirectoryIndex" |
| directive. If you have one, add "index.jsp" to the end of the |
| list, so that it might look like this: |
| |
| DirectoryIndex index.html index.jsp |
| |
| If you do not have such an entry, add one like this: |
| |
| DirectoryIndex index.jsp |
| |
| * Restart Apache to make it aware of the new applications. You should |
| now be able to access the applications from a browser like this: |
| |
| http://localhost/struts-documentation |
| http://localhost/struts-example |
| |
| |
| WEBLOGIC 5.1 (service pack 8) |
| ----------------------------- |
| |
| * Obtain and install the Xerces XML parser (problems have been reported |
| with the Sun reference implementation). Put xerces.jar in your WebLogic system |
| path. |
| |
| * Obtain and unpack the Struts binary distribution (this procedure assumes |
| it was extracted to C:\jakarta-struts). |
| |
| * Add an entry to weblogic.properties for each of the Struts web |
| applications that you would like to configure. For example, to make the |
| struts-example application available, add the following line to |
| weblogic.properties: |
| |
| weblogic.httpd.webApp.strutsexample=c:/jakarta-struts/webapps/struts-example.war |
| |
| * You do not need to include struts.jar or any of the application specific |
| classes in the WebLogic classpath, since this will be done automatically |
| (unless deploying an unpacked web archive- see below). |
| |
| * Start WebLogic server and point your web browser to the struts |
| application. For example, to connect to the example application added in |
| step 3: |
| |
| http://localhost:7001/strutsexample |
| |
| * This example application depends on the Struts specific resource file |
| ApplicationResources.properties to be present on the classpath. However, |
| WebLogic only extracts *.class files from the archive so this file will not |
| be found, resulting in an error the first time it is needed- something |
| similar to: javax.servlet.ServletException: runtime failure in custom tag |
| 'message'. Steps 6 & 7 will need to be performed for this application, and |
| any other that relies on ApplicationResources.properties. |
| |
| * Extract ApplicationResources.properties from the *.war file, and |
| manually copy it to the respective package in the _tmp_war_ directory |
| WebLogic created for this application. Again referring to the struts-example |
| application, this would be: |
| |
| c:\jakarta-struts\webapps\WEB-INF\_tmp_war_strutsexample |
| |
| * Restart WebLogic. You will now be able to run the application: |
| |
| http://localhost:7001/strutsexample |
| |
| * The above steps should be followed for applications deployed as *.war |
| files. For unpacked web applications, configuration involves adding both |
| struts.jar and /WEB-INF/classes to the WebLogic classpath. For this reason, |
| I would suggest deploying applications as war files to WebLogic. However, |
| the same example application can be successfully deployed in extracted |
| format by modifying weblogic.properties (assuming the war was extracted to |
| directory webapps/struts-example): |
| |
| weblogic.httpd.webApp.strutsexample=c:/jakarta-struts/webapps/struts-example/ |
| |
| And starting WebLogic with the updated WebLogic classpath. For example: |
| |
| c:\jdk1.3\bin\java -ms16m -mx64m |
| -classpath c:\weblogic\lib\weblogic510sp8boot.jar; |
| c:\weblogic\classes\boot; |
| c:\xerces\xerces.jar -Dweblogic.class.path=c:\weblogic\lib\weblogic510sp8.jar; |
| c:\weblogic\license; |
| c:\weblogic\classes; |
| c:\weblogic\myserver\serverclasses; |
| c:\weblogic\lib\weblogicaux.jar; |
| c:\jakarta-struts\lib\struts.jar; |
| c:\jakarta-struts\webapps\struts-example\WEB-INF\classes |
| -Dweblogic.system.home=c:\weblogic-Djava.security.manager |
| -Djava.security.policy=c:\weblogic\weblogic.policyweblogic.Server |