source: nutchez-0.1/tomcat/webapps/docs/funcspecs/printer/fs-admin-apps.html

Last change on this file was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 15.2 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications - Administrative Apps - Overall Requirements</title><meta value="Craig McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      Catalina Functional Specifications
3    " align="right" src="../../../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="../../../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Catalina Functional Specifications</h1><h2>Administrative Apps - Overall Requirements</h2></td><td nowrap="true" valign="top" align="right"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../../images/void.gif"></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
4
5
6  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
7
8    <p>The purpose of this specification is to define high level requirements
9    for administrative applications that can be used to manage the operation
10    of a running Tomcat 6 container.  A variety of <em>Access Methods</em>
11    to the supported administrative functionality shall be supported, to
12    meet varying requirements:</p>
13    <ul>
14    <li><em>As A Scriptable Web Application</em> - The existing
15        <code>Manager</code> web application provides a simple HTTP-based
16        interface for managing Tomcat through commands that are expressed
17        entirely through a request URI.  This is useful in environments
18        where you wish to script administrative commands with tools that
19        can generate HTTP transactions.</li>
20    <li><em>As An HTML-Based Web Application</em> - Use an HTML presentation
21        to provide a GUI-like user interface for humans to interact with the
22        administrative capabilities.</li>
23    <li><em>As SOAP-Based Web Services</em> - The operational commands to
24        administer Tomcat are made available as web services that utilize
25        SOAP message formats.</li>
26    <li><em>As Java Management Extensions (JMX) Commands</em> - The operational
27        commands to administer Tomcat are made available through JMX APIs,
28        for integration into management consoles that utilize them.</li>
29    <li><em>Other Remote Access APIs</em> - Other remote access APIs, such
30        as JINI, RMI, and CORBA can also be utilized to access administrative
31        capabilities.</li>
32    </ul>
33
34    <p>Underlying all of the access methods described above, it is assumed
35    that the actual operations are performed either directly on the
36    corresponding Catalina components (such as calling the
37    <code>Deployer.deploy()</code> method to deploy a new web application),
38    or through a "business logic" layer that can be shared across all of the
39    access methods.  This approach minimizes the cost of adding new
40    administrative capabilities later -- it is only necessary to add the
41    corresponding business logic function, and then write adapters to it for
42    all desired access methods.</p>
43
44    <p>The current status of this functional specification is
45    <strong>PROPOSED</strong>.  It has not yet been discussed and
46    agreed to on the TOMCAT-DEV mailing list.</p>
47
48  </blockquote></td></tr></table>
49
50
51  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote>
52
53    <p>The implementation of this functionality depends on the following
54    external specifications:</p>
55    <ul>
56    <li><a href="http://java.sun.com/products/jdk/idl/index.html">Java
57        IDL</a> (for CORBA, included in the JDK)</li>
58    <li><a href="http://java.sun.com/products/JavaManagement/index.html">
59        Java Management Extensions</a></li>
60    <li><a href="http://java.sun.com/products/rmi/index.html">Remote
61        Method Invocation</a> (Included in the JDK)</li>
62    </ul>
63
64  </blockquote></td></tr></table>
65
66
67  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Implementation Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>
68
69    <p>The implementation of this functionality shall conform to the
70    following requirements:</p>
71    <ul>
72    <li>To the maximum extent feasible, all administrative functions,
73        and the access methods that support them, shall run portably
74        on all platforms where Tomcat 6 itself runs.</li>
75    <li>In a default Tomcat distribution, all administrative capabilities
76        shall be disabled.  It shall be necessary for a system
77        administrator to specifically enable the desired access methods
78        (such as by adding a username/password with a specific role to
79        the Tomcat user's database.</li>
80    <li>Administrative functions shall be realized as direct calls to
81        corresponding Catalina APIs, or through a business logic layer
82        that is independent of the access method used to initiate it.</li>
83    <li>The common business logic components shall be implemented in
84        package <code>org.apache.catalina.admin</code>.</li>
85    <li>The common business logic components shall be built as part of the
86        standard Catalina build process, and made visible in the
87        Catalina class loader.</li>
88    <li>The Java components required for each access method shall be
89        implemented in subpackages of <code>org.apache.catalina.admin</code>.
90        </li>
91    <li>The build scripts should treat each access method as optional,
92        so that it will be built only if the corresponding required
93        APIs are present at build time.</li>
94    <li>It shall be possible to save the configured state of the running
95        Tomcat container such that this state can be reproduced when the
96        container is shut down and restarted.</li>
97    <li>Adminstrative commands to start up and shut down the overall
98        Tomcat container are <strong>out of scope</strong> for the
99        purposes of these applications.  It is assumed that other
100        (usually platform-specific) mechanisms will be used for container
101        startup and shutdown.</li>
102    </ul>
103
104  </blockquote></td></tr></table>
105
106
107</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>
108
109
110  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Environmental Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>
111
112    <p>The following environmental dependencies must be met in order for
113    administrative applications to operate correctly:</p>
114    <ul>
115    <li>For access methods that require creation of server sockets, the
116        appropriate ports must be configured and available.</li>
117    </ul>
118
119  </blockquote></td></tr></table>
120
121
122  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Container Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>
123
124    <p>Correct operation of administrative applications depends on the
125       following specific features of the surrounding container:</p>
126    <ul>
127    <li>To the maximum extent feasible, Catalina components that offer
128        direct administrative APIs and property setters shall support
129        "live" changes to their operation, without requiring a container
130        restart.</li>
131    </ul>
132
133  </blockquote></td></tr></table>
134
135
136  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="External Technologies"><strong>External Technologies</strong></a></font></td></tr><tr><td><blockquote>
137
138    <p>The availability of the following technologies can be assumed
139    for the implementation and operation of the various access methods
140    and the corresponding administrative business logic:</p>
141    <ul>
142    <li><a href="http://java.sun.com/j2se/">Java 2 Standard Edition</a>
143        (Version 1.2 or later)</li>
144    <li><a href="http://www.jcp.org/jsr/detail/154.jsp">Servlet 2.4</a>
145        (supported natively by Tomcat 6)</li>
146    <li><a href="http://www.jcp.org/jsr/detail/152.jsp">JavaServer Pages 2.0</a>
147        (supported natively by Tomcat 6)</li>
148    <li><a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">JavaServer Pages Standard Tag Library 1.0 (Jakarta Taglibs-Standard 1.0.3)</a></li>
149    <li><a href="http://jakarta.apache.org/struts/">Struts Framework</a>
150        (Version 1.0) - MVC Framework for Web Applications</li>
151    <li><strong>TO BE DETERMINED</strong> - Application for hosting SOAP
152        based web services</li>
153    </ul>
154
155  </blockquote></td></tr></table>
156
157
158</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>
159
160
161  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Properties of Administered Objects"><strong>Properties of Administered Objects</strong></a></font></td></tr><tr><td><blockquote>
162
163  <p>Functional requirements for administrative applications are specified
164  in terms of <em>Administered Objects</em>, whose definitions and detailed
165  properties are listed <a href="fs-admin-objects.html">here</a>.  In general,
166  Administered Objects correspond to components in the Catalina architecture,
167  but these objects are defined separately here for the following reasons:</p>
168  <ul>
169  <li>It is possible that the administrative applications do not expose
170      every possible configurable facet of the underlying components.</li>
171  <li>In some cases, an Administered Object (from the perspective of an
172      administrative operation) is realized by more than one Catalina
173      component, at a finer-grained level of detail.</li>
174  <li>It is necessary to represent the configuration information for a
175      component separately from the component itself (for instance, in
176      order to store that configuration information for later use).</li>
177  <li>It is necessary to represent configuration information (such as
178      a Default Context) when there is no corresponding component instance.
179      </li>
180  <li>Administered Objects, when realized as Java classes, will include
181      methods for administrative operations that have no correspondence
182      to operations performed by the corresponding actual components.</li>
183  </ul>
184
185  <p>It is assumed that the reader is familiar with the overall component
186  architecture of Catalina.  For further information, see the corresponding
187  Developer Documentation.  To distinguish names that are used as both
188  <em>Administered Objects</em> and <code>Components</code>, different
189  font presentations are utilized.  Default values for many properties
190  are listed in [square brackets].</p>
191
192  </blockquote></td></tr></table>
193
194
195  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Supported Administrative Operations"><strong>Supported Administrative Operations</strong></a></font></td></tr><tr><td><blockquote>
196
197  <p>The administrative operations that are available are described in terms
198  of the corresponding Administered Objects (as defined above), in a manner
199  that is independent of the access method by which these operations are
200  requested.  In general, such operations are relevant only in the context
201  of a particular Administered Object (and will most likely be realized as
202  method calls on the corresponding Administered Object classes), so they
203  are organized based on the currently "focused" administered object.
204  The available Supported Operations are documented
205  <a href="fs-admin-opers.html">here</a>.</p>
206
207  </blockquote></td></tr></table>
208
209
210  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Access Method Specific Requirements"><strong>Access Method Specific Requirements</strong></a></font></td></tr><tr><td><blockquote>
211
212  <h5>Scriptable Web Application</h5>
213
214  <p>An appropriate subset of the administrative operations described above
215  shall be implemented as commands that can be performed by the "Manager"
216  web application.  <strong>FIXME</strong> - Enumerate them.</p>
217
218  <p>In addition, this web application shall conform to the following
219  requirements:</p>
220  <ul>
221  <li>All request URIs shall be protected by a security constraint that
222      requires security role <code>manager</code> for processing.</li>
223  <li>The default user database shall <strong>not</strong> contain any
224      user that has been assigned the role <code>manager</code>.</li>
225  </ul>
226
227  <h5>HTML-Based Web Application</h5>
228
229  <p>The entire suite of administrative operations described above shall be
230  made available through a web application designed for human interaction.
231  In addition, this web application shall conform to the following
232  requirements:</p>
233  <ul>
234  <li>Must be implemented using servlet, JSP, and MVC framework technologies
235      described under "External Technologies", above.</li>
236  <li>Prompts and error messages must be internationalizable to multiple
237      languages.</li>
238  <li>Rendered HTML must be compatible with Netscape Navigator (verson 4.7
239      or later) and Internet Explorer (version 5.0 or later).</li>
240  </ul>
241
242  </blockquote></td></tr></table>
243
244
245</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Testable Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>
246
247  <p><strong>FIXME</strong> - Complete this section.</p>
248
249</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
250        Copyright &copy; 1999-2008, Apache Software Foundation
251        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.