← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libstruts1.2-java/trusty-proposed

« back to all changes in this revision

Viewing changes to xdocs/userGuide/installation.xml

  • Committer: Bazaar Package Importer
  • Author(s): Arnaud Vandyck
  • Date: 2004-11-19 15:35:25 UTC
  • Revision ID: james.westby@ubuntu.com-20041119153525-mdu08a76z4zo67xt
Tags: upstream-1.2.4
Import upstream version 1.2.4

Show diffs side-by-side

added added

removed removed

Lines of Context:
xdocs/userGuide/installation.xml
 
1
<?xml version="1.0"?>
 
2
<document url="installation.html">
 
3
 
 
4
  <properties>
 
5
    <author>Craig R. McClanahan</author>
 
6
    <author>Mike Schachter</author>
 
7
    <author>Ted Husted</author>
 
8
    <author>Martin Cooper</author>
 
9
    <author>Chris Assenza</author>
 
10
    <author>dIon Gillard</author>
 
11
    <author>Eric Wu</author>
 
12
    <author>John Rousseau</author>
 
13
    <author>John Ueltzhoeffer</author>
 
14
    <author>Mark Budai</author>
 
15
    <author>Paul Runyan</author>
 
16
    <author>Robert Hayden</author>
 
17
    <author>Stanley Santiago</author>
 
18
    <author>Wong Kok Kai</author>
 
19
    <author>Rob Leland</author>
 
20
    <author>John Berry</author>
 
21
    <title>The Struts Framework Project - Installation (1.1)</title>
 
22
  </properties>
 
23
 
 
24
  <body>
 
25
  <section name="6.2 Installation" href="installation"/>
 
26
  <section name="Prerequisite Software" href="Prerequisites">
 
27
 
 
28
  <p>The Struts binary distribution needs three other software packages installed to
 
29
  operate. You may already have these installed on your system. To build Struts from
 
30
  source you may need to acquire and install several others. The complete list is as
 
31
  follows:</p>
 
32
 
 
33
  <ul>
 
34
  <li><strong>Java Development Kit</strong> - You <strong>must</strong> download and install
 
35
      a Java2 (version 1.2 or later) Java Development Kit implementation for
 
36
      your operating system platform.
 
37
      A good starting point for locating Java Development Kit distributions is
 
38
      <a href="http://java.sun.com/j2se">http://java.sun.com/j2se</a>.
 
39
      To build Struts, Java 1.4.2 or later is suggested. </li>
 
40
 
 
41
  <li><strong>Servlet Container</strong> - You <strong>must</strong> download and install a
 
42
      servlet container that is compatible with the Servlet API Specification,
 
43
      version 2.2 or later, and the JavaServer Pages (JSP) Specification,
 
44
      version 1.1 or later.  One popular choice is to download Apache's
 
45
      <a href="http://jakarta.apache.org/tomcat">Tomcat</a> (version 3.1
 
46
      or later required, version 3.3 or later recommended).</li>
 
47
 
 
48
  <li><strong>XML Parser</strong> - Struts <strong>requires</strong> the presence of an XML
 
49
      parser that is compatible with the Java API for XML Parsing (JAXP)
 
50
      specification, 1.1 or later. This is bundled with J2SE 1.4 and later.
 
51
      (For earlier versions of Java, the easiest way to obtain JAXP is
 
52
      probably by downloading the Web Services Developers Kit
 
53
      (1.1 or later!). See the <a href="http://java.sun.com/xml/jaxp/faq.html#jaxp-ri-latest">
 
54
      Sun JAXP FAQ</a> for more information.)
 
55
      In Struts-based web applications, you may replace the reference
 
56
      implementation classes with any other JAXP compliant parser, such as
 
57
      <a href="http://xml.apache.org/xerces-j">Xerces</a>.  See detailed
 
58
      instructions related to the parser in the instructions for
 
59
      <a href="#Building">building</a> and <a href="#Installing">installing</a>
 
60
      Struts, below.</li>
 
61
 
 
62
  <li><strong>Ant Build System</strong> - If you are building Struts from the
 
63
      source distribution, you must download and install version 1.5.4 (or later)
 
64
      of the <a href="http://jakarta.apache.org/ant">Ant</a> build system.
 
65
      This package is also strongly recommended for use in developing your
 
66
      own web applications based on Struts.
 
67
      <ul>
 
68
      <li>Make sure that the "ant" and "ant.bat" scripts are executable, by
 
69
          adding the $ANT_HOME/bin directory to your PATH environment
 
70
          variable.</li>
 
71
      </ul></li>
 
72
 
 
73
  <li><strong>Servlet API Classes</strong> - In order to compile Struts itself,
 
74
      or applications that use Struts, you will need a <code>servlet.jar</code>
 
75
      file containing the Servlet and JSP API classes.  Most servlet containers
 
76
      include this JAR file.  Otherwise, you can get the Servlet API classes
 
77
      distribution from
 
78
      <a href="http://jakarta.apache.org/builds/jakarta-servletapi">here</a>.
 
79
      </li>
 
80
 
 
81
  <li><strong>JDBC 2.0 Optional Package Classes</strong> - Struts supports
 
82
      an optional implementation of <code>javax.sql.DataSource</code>, so it
 
83
      requires the API classes to be compiled.  They can be downloaded from
 
84
      <a href="http://java.sun.com/products/jdbc/download.html">http://java.sun.com/products/jdbc/download.html</a>.</li>
 
85
 
 
86
  <li>
 
87
      <strong>Jakarta Commons Packages</strong> - Struts utilizes several
 
88
      packages from the <a href="http://jakarta.apache.org/commons/">Jakarta
 
89
      Commons Project</a>.
 
90
      These are the packages which must be available if you wish to
 
91
      build Struts from source:
 
92
      <ul>
 
93
      <li><em>Beanutils</em> (Version 1.6.1 or later)</li>
 
94
      <li><em>Collections</em> (Version 2.1 or later)</li>
 
95
      <li><em>Digester</em> (Version 1.5 or later)</li>
 
96
      <li><em>FileUpload</em> (Version 1.0 or later)</li>
 
97
      <li><em>Lang</em> (Version 1.0.1 or later)</li>
 
98
      <li><em>Logging</em> (Version 1.0.3 or later when it is available)</li>
 
99
      <li><em>Struts-Legacy</em> (Version 1.0 or later)</li>
 
100
      <li><em>Validator</em> (Version 1.0.2 or later) </li>
 
101
      </ul>
 
102
      For your convenience, the requisite JARs are provided as a single
 
103
      download under the <code>lib</code> sub-directory with each release
 
104
      and beta distribution.
 
105
      Please note that the minimum requirements may change between releases
 
106
      and betas, and some JARs may need to be updated to use the latest
 
107
      Nightly Build.
 
108
  </li>
 
109
 
 
110
  <li><strong>Jakarta ORO</strong> -
 
111
  <a href="http://jakarta.apache.org/oro/index.html">Apache Jakarta ORO</a>
 
112
  version 2.0.6 (or later) is  required to build Struts from source.</li>
 
113
 
 
114
  <li><strong>Xalan XSLT Processor</strong> - If you are building Struts from
 
115
      the source distribution, you will need a version of Xalan to perform
 
116
      XSLT transformations. If you are using the JAXP/1.1 XML parser, you
 
117
      should use the version of <code>xalan.jar</code> shipped with it.
 
118
      Otherwise, download and install version 1.2 of Xalan from
 
119
      <a href="http://xml.apache.org/xalan">here</a>.
 
120
  </li>
 
121
 
 
122
  <li><strong>Cactus Testing</strong> - If you plan on testing the Struts applications
 
123
      in this distribution, you must download and install version 1.3
 
124
      of the <a href="http://jakarta.apache.org/cactus">Cactus</a> test framework.
 
125
      This package is also recommended for use in developing your
 
126
      own unit tests for your web applications based on Struts.
 
127
  </li>
 
128
 
 
129
  </ul>
 
130
 
 
131
  </section>
 
132
 
 
133
  <section name="Install A Struts Binary Distribution" href="Installing">
 
134
 
 
135
    <p>First, download a binary distribution of Struts by following the
 
136
    instructions <a href="../acquiring.html">here</a>.  Then, make sure
 
137
    you have downloaded and installed the
 
138
    <a href="#Prerequisites">prerequisite</a> software packages described
 
139
    above.</p>
 
140
 
 
141
    <p>Unpack the Struts binary distribution into a convenient directory.
 
142
    (If you <a href="#Building">build Struts from the source distribution</a>,
 
143
    the result of the build will already be an unpacked binary distribution
 
144
    for you). The distribution consists of the following contents:</p>
 
145
 
 
146
    <ul>
 
147
    <li><strong>lib/commons-*.jar</strong> - These JAR files contain packages
 
148
        from the Jakarta Commons project that are utilized within Struts
 
149
        itself.  When you assemble a Struts-based application, you will need
 
150
        to copy these files to the <code>WEB-INF/lib</code> directory.</li>
 
151
    <li><strong>lib/jdbc2_0-stdext.jar</strong> - The JDBC 2.0 Optional Package
 
152
        API classes.  You will need to copy this file to your
 
153
        <code>WEB-INF/lib</code> directory if you are utilizing the data
 
154
        sources support provided by Struts.</li>
 
155
    <li><strong>lib/struts.jar</strong> - This JAR file contains all of the
 
156
        Java classes included in Struts.  It should be copied into the
 
157
        <code>WEB-INF/lib</code> directory of your web application.
 
158
        <em>WARNING</em> - If you are going to be hosting multiple Struts
 
159
        based applications on the same servlet container, you will be tempted
 
160
        to place the <code>struts.jar</code> file into the shared repository
 
161
        supported by your container.  Be advised that this will like cause you
 
162
        to encounter ClassNotFoundException problems unless <em>all</em> of
 
163
        your application classes are stored in the shared repository.</li>
 
164
    <li><strong>lib/struts-*.tld</strong> - These are the "tag library
 
165
        descriptor" files that describe the custom tags in the various Struts
 
166
        tag libraries. They should be copied into the <code>WEB-INF</code>
 
167
        directory of your web application. (Servlet 2.3 can omit this step
 
168
        if the <a href="configuration.html#dd_config_taglib_23">standard uri</a>
 
169
        is referenced.)</li>
 
170
    <li><strong>webapps/struts-blank.war</strong> - This is a simple "web
 
171
        application archive" file containing a basic starting point for
 
172
        building your own Struts-based applications.</li>
 
173
    <li><strong>webapps/struts-documentation.war</strong> - This is a
 
174
        "web application archive" file containing all of the Struts
 
175
        documentation found on the
 
176
        <a href="http://jakarta.apache.org/struts">Struts web site</a>
 
177
        (including these pages).  You can install this web application
 
178
        on any servlet container compatible with Servlet API 2.2 or later.</li>
 
179
    <li><strong>webapps/struts-example.war</strong> - This is an example
 
180
        web application that uses a large percentage of Struts features.
 
181
        You can install this web application on any servlet container
 
182
        compatible with the Servlet 2.2 (or later) and JSP 1.1 (or later)
 
183
        specifications.  If an XML parser is not made available to web
 
184
        applications by your container, you will need to add one to the
 
185
        WEB-INF/lib directory of this web application.</li>
 
186
    <li><strong>webapps/struts-exercise-taglib.war</strong> - This web
 
187
        application contains test pages for the various custom tags supported
 
188
        by Struts.  It is primarily of use to developers who are enhancing the
 
189
        Struts custom tag libraries, but may also be useful as simple examples
 
190
        of the usage of various Struts tags.</li>
 
191
    <li><strong>webapps/struts-upload.war</strong> - This web application
 
192
        is a quick example of uploading files using the Struts framework.
 
193
    </li>
 
194
    <li><strong>webapps/struts-validator.war</strong> - This web application
 
195
        is an example of using the validator framework, using both the
 
196
        server-side and optional client-side validation.
 
197
    </li>
 
198
        <li><strong>webapps/tiles-documentation.war</strong> - This web
 
199
        application documents how to use tiles, and was developed using tiles.</li>
 
200
    </ul>
 
201
 
 
202
    <p>To use Struts in your own application, you will need to follow
 
203
    these steps:</p>
 
204
    <ul>
 
205
    <li>Copy the files <code>lib/commons-*.jar</code> from the Struts
 
206
        distribution into the <code>WEB-INF/lib</code> directory of your
 
207
        web application.</li>
 
208
    <li>Copy the file <code>lib/struts.jar</code> from the Struts distribution
 
209
        into the <code>WEB-INF/lib</code> directory of your web application.
 
210
        </li>
 
211
    <li>Copy the all of the files that match <code>lib/struts-*.tld</code>
 
212
        from the Struts distribution into the <code>WEB-INF</code> directory
 
213
        of your web application.</li>
 
214
    <li>Modify the <code>WEB-INF/web.xml</code> file for your web application
 
215
        to include a <code>&lt;servlet&gt;</code> element to define the
 
216
        controller servlet, and a <code>&lt;servlet-mapping&gt;</code> element
 
217
        to establish which request URIs are mapped to this servlet. Use the
 
218
        <code>WEB-INF/web.xml</code> file from the Struts example application
 
219
        for a detailed example of the required syntax.</li>
 
220
    <li>Modify the <code>WEB-INF/web.xml</code> file of your web application
 
221
        to include the following tag library declarations (Servlet 2.3 can omit
 
222
        this step if the <a href="configuration.html#dd_config_taglib_23">standard uri</a>
 
223
        is referenced):</li>
 
224
    </ul>
 
225
 
 
226
<pre>&lt;taglib&gt;
 
227
  &lt;taglib-uri&gt;/WEB-INF/struts-bean.tld&lt;/taglib-uri&gt;
 
228
  &lt;taglib-location&gt;/WEB-INF/struts-bean.tld&lt;/taglib-location&gt;
 
229
&lt;/taglib&gt;
 
230
 
 
231
&lt;taglib&gt;
 
232
  &lt;taglib-uri&gt;/WEB-INF/struts-html.tld&lt;/taglib-uri&gt;
 
233
  &lt;taglib-location&gt;/WEB-INF/struts-html.tld&lt;/taglib-location&gt;
 
234
&lt;/taglib&gt;
 
235
 
 
236
&lt;taglib&gt;
 
237
  &lt;taglib-uri&gt;/WEB-INF/struts-logic.tld&lt;/taglib-uri&gt;
 
238
  &lt;taglib-location&gt;/WEB-INF/struts-logic.tld&lt;/taglib-location&gt;
 
239
&lt;/taglib&gt;
 
240
</pre>
 
241
 
 
242
    <ul>
 
243
    <li>Create a file <code>WEB-INF/struts-config.xml</code> that defines the
 
244
        action mappings and other characteristics of your specific application.
 
245
        You can use the <code>struts-config.xml</code> file from the Struts
 
246
        example application for a detailed example of the required syntax.</li>
 
247
    <li>At the top of each JSP page that will use the Struts custom tags,
 
248
        add line(s) declaring the Struts custom tag libraries used on
 
249
        this particular page, like this:</li>
 
250
    </ul>
 
251
 
 
252
<pre>&lt;%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %&gt;
 
253
&lt;%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %&gt;
 
254
&lt;%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %&gt;
 
255
</pre>
 
256
 
 
257
    <ul>
 
258
    <li>When compiling the Java classes that comprise your application, be sure
 
259
        to include the <code>struts.jar</code> and
 
260
        <code>commons-*.jar</code> files (copied earlier) on the
 
261
        CLASSPATH that is submitted to the compiler.</li>
 
262
    </ul>
 
263
</section> <section name="Installing Struts With Your Servlet Container" href="Containers">
 
264
 
 
265
<p>For most containers, you need only to: </p>
 
266
<ul>
 
267
  <li>Copy the WAR files in your Struts <code>/webapp</code> directory to your
 
268
    containers <code>webapps</code> directory. </li>
 
269
  <li>In some cases, you may need to restart your container if it is running.</li>
 
270
</ul>
 
271
 
 
272
<h4>Running Struts Applications Under A Security Manager</h4>
 
273
 
 
274
<p>Many application servers execute web applications under the control of a
 
275
Java security manager, with restricted permissions on what classes in the web
 
276
application can do.  If you utilize form beans with mapped properties, you may
 
277
encounter security exceptions unless you add the following permission to the
 
278
set of permissions granted to your Struts application's codebase:</p>
 
279
<pre>
 
280
  permission java.lang.RuntimePermission "accessDeclaredMembers";
 
281
</pre>
 
282
 
 
283
<p>Consult the documentation on your application server for more information
 
284
about how to configure additional security manager permissions.</p>
 
285
 
 
286
<h4>Installing Struts on Various Containers</h4>
 
287
<ul>
 
288
  <li>Bluestone Universal Business Server 7.2 - <a href="installation-ubs72.html">Additional
 
289
    steps required.</a></li>
 
290
  <li>Borland Application Server 4.5 -No additional
 
291
    steps required.</li>
 
292
  <li>iPlanet Application Server - Service Pack 2 is recommended. Note that the database
 
293
  object in the Struts-Example application is not compatible with this container.</li>
 
294
  <li>iPlanet Web Server - <a href="installation-ip.html">Additional steps required.</a></li>
 
295
  <li>iPortal Application Server - <a href="installation-ipas.html">Additional steps required.</a></li>
 
296
  <li>Jetty - <a href="installation-jetty.html">Additional steps required.</a></li>
 
297
  <li>JRun - <a href="installation-jr30.html">Additional steps required.</a></li>
 
298
  <li>Novell ExteNd Application Server 4.0+ -
 
299
      <a href="installation-novell.html">Additional steps required.</a></li>
 
300
  <li>Orion Application Server - <a href="installation-oas.html">Additional steps
 
301
    required.</a></li>
 
302
  <li>Resin 1.2+ "standalone" - No additional steps required.</li>
 
303
  <li>RexIP - No additional steps required.</li>
 
304
  <li>SilverStream 3.7.1 and later - <a href="installation-sas.html">Additional steps required.</a></li>
 
305
  <li>Tomcat 3.1 and prior - Not recommended. Use Tomcat 3.2.1 or later.</li>
 
306
  <li>Tomcat 3.2.1 with Apache - <a href="installation-tc.html">Additional steps
 
307
    required.</a></li>
 
308
  <li>Tomcat 3.2.1+ "standalone" - No additional steps required.</li>
 
309
  <li>Tomcat 4.0 - No additional steps required.</li>
 
310
  <li>Weblogic 5.1 sp8 - <a href="installation-wls5.html">Additional steps required.</a></li>
 
311
  <li>WebLogic 6.0+ - No additional steps required.</li>
 
312
  <li>WebSphere - <a href="installation-was352.html">Additional steps required.</a></li>
 
313
  <li>WebSphere - <a href="installation-was352-x.html">Steps for the Example Application.</a></li></ul>
 
314
</section>
 
315
 
 
316
<section name="Building Struts From Source" href="Building">
 
317
 
 
318
    <p>First, download a source distribution of Struts by following the
 
319
    instructions <a href="../acquiring.html">here</a>.  Then, make sure
 
320
    you have downloaded and installed <strong>all</strong> of the
 
321
    <a href="#Prerequisites">prerequisite</a> software packages described
 
322
    above.</p>
 
323
 
 
324
    <p>To build Struts, you will need to customize the build process to the
 
325
    details of your development environment as follows:</p>
 
326
    <ul>
 
327
    <li>The Struts source distribution uses a file named
 
328
        <code>build.properties</code> (in the top-level directory of the
 
329
        distribution) to identify the location of external components
 
330
        that Struts depends on.</li>
 
331
    <li>There is no <code>build.properties</code> file included with the
 
332
        source distribution.  However, there is an example file named
 
333
        <code>build.properties.example</code> that you can copy to
 
334
        <code>build.properties</code> and then customize.</li>
 
335
    <li>The properties you must configure in <code>build.properties</code> are:
 
336
        <ul>
 
337
        <li><strong>catalina.home</strong> - Pathname to the directory of your
 
338
            binary distribution of Tomcat 4.0 (required only if you wish to
 
339
            use the <code>deploy.catalina</code> target).</li>
 
340
        <li><strong>commons-beanutils.jar</strong> - Pathname of the BeanUtils
 
341
            package JAR file from the Jakarta Commons project.</li>
 
342
        <li><strong>commons-collections.jar</strong> - Pathname of the
 
343
            Collections package JAR file from the Jakarta Commons project.</li>
 
344
        <li><strong>commons-digester.jar</strong> - Pathname of the
 
345
            Digester package JAR file from the Jakarta Commons project.</li>
 
346
        <li><strong>commons-fileupload.jar</strong> - Pathname of the
 
347
            Fileupload package JAR file from the Jakarta Commons project.</li>
 
348
        <li><strong>commons-lang.jar</strong> - Pathname of the
 
349
            Lang package JAR file from the Jakarta Commons project.</li>
 
350
        <li><strong>commons-logging.jar</strong> - Pathname of the
 
351
            Logging package JAR file from the Jakarta Commons project.</li>
 
352
        <li><strong>commons-validator.jar</strong> - Pathname of the
 
353
            Validator package JAR file from the Jakarta Commons project.</li>
 
354
        <li><strong>servletapi.home</strong> - Pathname to the directory of
 
355
            your binary distribution of the Servlet API classes.</li>
 
356
        <li><strong>tomcat.home</strong> - Pathname to the directory of your
 
357
            binary distribution of Tomcat 3.2 (required only if you wish to
 
358
            use the <code>deploy.tomcat</code> target).</li>
 
359
        <li><strong>xerces.home</strong> - Pathname to the directory of your
 
360
            binary distribution of the Xerces parser, version 1.2 or 1.3
 
361
            (required only if you wish to use the <code>deploy.catalina</code>
 
362
            target).</li>
 
363
        </ul></li>
 
364
 
 
365
 
 
366
   <li>If you are a Struts developer with write access to the CVS repository,
 
367
        be sure that you do <strong>NOT</strong> check in a copy of the
 
368
        <code>build.properties</code> file, since it will be different for
 
369
        each individual developer.</li>
 
370
    </ul>
 
371
 
 
372
    <p>To build a "distribution" version of Struts, first change your current
 
373
    directory to the directory in which you have unpacked the Struts
 
374
    source distribution, and (if necessary) create or customize the
 
375
    <code>build.properties</code> file as described above.  Then, type:</p>
 
376
<pre>
 
377
        ant dist
 
378
</pre>
 
379
 
 
380
    <p>This command will create a binary distribution of Struts, in a
 
381
    directory named <code>dist</code> (relative to where you
 
382
    are compiling from).  This directory contains an exact replica of the
 
383
    files included in a binary distribution of Struts, as described
 
384
    in the <a href="#Installing">preceding section</a>.</p>
 
385
 
 
386
    <p>IMPORTANT NOTE: The <code>struts.jar</code>, as well as the JAR files
 
387
    from the Jakarta Commons project, must be in your classpath when
 
388
    compiling Struts. The <code>build.xml</code> provided does this
 
389
    automatically.  If you use your development machine to test Struts
 
390
    application locally, be sure that the <code>struts.jar</code> is
 
391
    <strong>NOT</strong> on your classpath when your container is running.
 
392
    </p>
 
393
 
 
394
  </section>
 
395
 
 
396
<section>
 
397
    <p class="right">
 
398
    Next: <a href="../faqs/index.html">FAQs and HowTos</a>
 
399
    </p>
 
400
</section>
 
401
 
 
402
  
 
403
</body>
 
404
</document>