blob: 2d8153906a2a2519fa80b0da08af0036d4bcfb4b [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +08001<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Catalina Functional Specifications (7.0.77) - Administrative Apps - Overall Requirements</title><meta name="author" content="Craig McClanahan"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
Hongqing Liufd5ee812014-05-10 16:32:51 +080080 Catalina Functional Specifications
刘洪青6266f992017-05-15 21:21:03 +080081 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Functional Specs</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>Administrative Apps</strong></p><ul><li><a href="fs-admin-apps.html">Overall Requirements</a></li><li><a href="mbean-names.html">Tomcat MBean Names</a></li><li><a href="fs-admin-objects.html">Administered Objects</a></li><li><a href="fs-admin-opers.html">Supported Operations</a></li></ul><p><strong>Internal Servlets</strong></p><ul><li><a href="fs-default.html">Default Servlet</a></li></ul><p><strong>Realm Implementations</strong></p><ul><li><a href="fs-jdbc-realm.html">JDBC Realm</a></li><li><a href="fs-jndi-realm.html">JNDI Realm</a></li><li><a href="fs-memory-realm.html">Memory Realm</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Administrative Apps - Overall Requirements</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
Hongqing Liufd5ee812014-05-10 16:32:51 +080082<ul><li><a href="#Overview">Overview</a><ol><li><a href="#Introduction">Introduction</a></li><li><a href="#External_Specifications">External Specifications</a></li><li><a href="#Implementation_Requirements">Implementation Requirements</a></li></ol></li><li><a href="#Dependencies">Dependencies</a><ol><li><a href="#Environmental_Dependencies">Environmental Dependencies</a></li><li><a href="#Container_Dependencies">Container Dependencies</a></li><li><a href="#External_Technologies">External Technologies</a></li></ol></li><li><a href="#Functionality">Functionality</a><ol><li><a href="#Properties_of_Administered_Objects">Properties of Administered Objects</a></li><li><a href="#Supported_Administrative_Operations">Supported Administrative Operations</a></li><li><a href="#Access_Method_Specific_Requirements">Access Method Specific Requirements</a></li></ol></li><li><a href="#Testable_Assertions">Testable Assertions</a></li></ul>
83</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
84
85
86 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
87
88 <p>The purpose of this specification is to define high level requirements
89 for administrative applications that can be used to manage the operation
刘洪青6266f992017-05-15 21:21:03 +080090 of a running Tomcat container. A variety of <em>Access Methods</em>
Hongqing Liufd5ee812014-05-10 16:32:51 +080091 to the supported administrative functionality shall be supported, to
92 meet varying requirements:</p>
93 <ul>
94 <li><em>As A Scriptable Web Application</em> - The existing
95 <code>Manager</code> web application provides a simple HTTP-based
96 interface for managing Tomcat through commands that are expressed
97 entirely through a request URI. This is useful in environments
98 where you wish to script administrative commands with tools that
99 can generate HTTP transactions.</li>
100 <li><em>As An HTML-Based Web Application</em> - Use an HTML presentation
101 to provide a GUI-like user interface for humans to interact with the
102 administrative capabilities.</li>
103 <li><em>As SOAP-Based Web Services</em> - The operational commands to
104 administer Tomcat are made available as web services that utilize
105 SOAP message formats.</li>
106 <li><em>As Java Management Extensions (JMX) Commands</em> - The operational
107 commands to administer Tomcat are made available through JMX APIs,
108 for integration into management consoles that utilize them.</li>
109 <li><em>Other Remote Access APIs</em> - Other remote access APIs, such
110 as JINI, RMI, and CORBA can also be utilized to access administrative
111 capabilities.</li>
112 </ul>
113
114 <p>Underlying all of the access methods described above, it is assumed
115 that the actual operations are performed either directly on the
116 corresponding Catalina components (such as calling the
117 <code>Deployer.deploy()</code> method to deploy a new web application),
118 or through a "business logic" layer that can be shared across all of the
119 access methods. This approach minimizes the cost of adding new
120 administrative capabilities later -- it is only necessary to add the
121 corresponding business logic function, and then write adapters to it for
122 all desired access methods.</p>
123
124 <p>The current status of this functional specification is
125 <strong>PROPOSED</strong>. It has not yet been discussed and
126 agreed to on the TOMCAT-DEV mailing list.</p>
127
128 </blockquote></td></tr></table>
129
130
131 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="External Specifications"><!--()--></a><a name="External_Specifications"><strong>External Specifications</strong></a></font></td></tr><tr><td><blockquote>
132
133 <p>The implementation of this functionality depends on the following
134 external specifications:</p>
135 <ul>
刘洪青6266f992017-05-15 21:21:03 +0800136 <li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/idl">
137 Java IDL</a> (for CORBA, included in the JDK)</li>
138 <li><a href="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800139 Java Management Extensions</a></li>
刘洪青6266f992017-05-15 21:21:03 +0800140 <li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/rmi">
141 Remote Method Invocation</a> (Included in the JDK)</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800142 </ul>
143
144 </blockquote></td></tr></table>
145
146
147 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Implementation Requirements"><!--()--></a><a name="Implementation_Requirements"><strong>Implementation Requirements</strong></a></font></td></tr><tr><td><blockquote>
148
149 <p>The implementation of this functionality shall conform to the
150 following requirements:</p>
151 <ul>
152 <li>To the maximum extent feasible, all administrative functions,
153 and the access methods that support them, shall run portably
刘洪青6266f992017-05-15 21:21:03 +0800154 on all platforms where Tomcat itself runs.</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800155 <li>In a default Tomcat distribution, all administrative capabilities
156 shall be disabled. It shall be necessary for a system
157 administrator to specifically enable the desired access methods
158 (such as by adding a username/password with a specific role to
159 the Tomcat user's database.</li>
160 <li>Administrative functions shall be realized as direct calls to
161 corresponding Catalina APIs, or through a business logic layer
162 that is independent of the access method used to initiate it.</li>
163 <li>The common business logic components shall be implemented in
164 package <code>org.apache.catalina.admin</code>.</li>
165 <li>The common business logic components shall be built as part of the
166 standard Catalina build process, and made visible in the
167 Catalina class loader.</li>
168 <li>The Java components required for each access method shall be
169 implemented in subpackages of <code>org.apache.catalina.admin</code>.
170 </li>
171 <li>The build scripts should treat each access method as optional,
172 so that it will be built only if the corresponding required
173 APIs are present at build time.</li>
174 <li>It shall be possible to save the configured state of the running
175 Tomcat container such that this state can be reproduced when the
176 container is shut down and restarted.</li>
177 <li>Administrative commands to start up and shut down the overall
178 Tomcat container are <strong>out of scope</strong> for the
179 purposes of these applications. It is assumed that other
180 (usually platform-specific) mechanisms will be used for container
181 startup and shutdown.</li>
182 </ul>
183
184 </blockquote></td></tr></table>
185
186
187</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Dependencies"><strong>Dependencies</strong></a></font></td></tr><tr><td><blockquote>
188
189
190 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Environmental Dependencies"><!--()--></a><a name="Environmental_Dependencies"><strong>Environmental Dependencies</strong></a></font></td></tr><tr><td><blockquote>
191
192 <p>The following environmental dependencies must be met in order for
193 administrative applications to operate correctly:</p>
194 <ul>
195 <li>For access methods that require creation of server sockets, the
196 appropriate ports must be configured and available.</li>
197 </ul>
198
199 </blockquote></td></tr></table>
200
201
202 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Container Dependencies"><!--()--></a><a name="Container_Dependencies"><strong>Container Dependencies</strong></a></font></td></tr><tr><td><blockquote>
203
204 <p>Correct operation of administrative applications depends on the
205 following specific features of the surrounding container:</p>
206 <ul>
207 <li>To the maximum extent feasible, Catalina components that offer
208 direct administrative APIs and property setters shall support
209 "live" changes to their operation, without requiring a container
210 restart.</li>
211 </ul>
212
213 </blockquote></td></tr></table>
214
215
216 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="External Technologies"><!--()--></a><a name="External_Technologies"><strong>External Technologies</strong></a></font></td></tr><tr><td><blockquote>
217
218 <p>The availability of the following technologies can be assumed
219 for the implementation and operation of the various access methods
刘洪青6266f992017-05-15 21:21:03 +0800220 and the corresponding administrative business logic:<br>
221 <strong>FIXME</strong> - This list below is totally outdated, but nobody
222 cares about the administrative app anymore. It is removed and unsupported
223 since Tomcat 6.0.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800224 <ul>
刘洪青6266f992017-05-15 21:21:03 +0800225 <li><a href="http://www.oracle.com/technetwork/java/javase/overview/index.html">
226 Java Standard Edition</a> (Version 1.2 or later)</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800227 <li><a href="http://www.jcp.org/jsr/detail/154.jsp">Servlet 2.4</a>
刘洪青6266f992017-05-15 21:21:03 +0800228 (supported natively by Tomcat 5)</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800229 <li><a href="http://www.jcp.org/jsr/detail/152.jsp">JavaServer Pages 2.0</a>
刘洪青6266f992017-05-15 21:21:03 +0800230 (supported natively by Tomcat 5)</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800231 <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>
232 <li><a href="http://struts.apache.org/">Struts Framework</a>
233 (Version 1.0) - MVC Framework for Web Applications</li>
234 <li><strong>TO BE DETERMINED</strong> - Application for hosting SOAP
235 based web services</li>
236 </ul>
237
238 </blockquote></td></tr></table>
239
240
241</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Functionality"><strong>Functionality</strong></a></font></td></tr><tr><td><blockquote>
242
243
244 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Properties of Administered Objects"><!--()--></a><a name="Properties_of_Administered_Objects"><strong>Properties of Administered Objects</strong></a></font></td></tr><tr><td><blockquote>
245
246 <p>Functional requirements for administrative applications are specified
247 in terms of <em>Administered Objects</em>, whose definitions and detailed
248 properties are listed <a href="fs-admin-objects.html">here</a>. In general,
249 Administered Objects correspond to components in the Catalina architecture,
250 but these objects are defined separately here for the following reasons:</p>
251 <ul>
252 <li>It is possible that the administrative applications do not expose
253 every possible configurable facet of the underlying components.</li>
254 <li>In some cases, an Administered Object (from the perspective of an
255 administrative operation) is realized by more than one Catalina
256 component, at a finer-grained level of detail.</li>
257 <li>It is necessary to represent the configuration information for a
258 component separately from the component itself (for instance, in
259 order to store that configuration information for later use).</li>
260 <li>It is necessary to represent configuration information (such as
261 a Default Context) when there is no corresponding component instance.
262 </li>
263 <li>Administered Objects, when realized as Java classes, will include
264 methods for administrative operations that have no correspondence
265 to operations performed by the corresponding actual components.</li>
266 </ul>
267
268 <p>It is assumed that the reader is familiar with the overall component
269 architecture of Catalina. For further information, see the corresponding
270 Developer Documentation. To distinguish names that are used as both
271 <em>Administered Objects</em> and <code>Components</code>, different
272 font presentations are utilized. Default values for many properties
273 are listed in [square brackets].</p>
274
275 </blockquote></td></tr></table>
276
277
278 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Supported Administrative Operations"><!--()--></a><a name="Supported_Administrative_Operations"><strong>Supported Administrative Operations</strong></a></font></td></tr><tr><td><blockquote>
279
280 <p>The administrative operations that are available are described in terms
281 of the corresponding Administered Objects (as defined above), in a manner
282 that is independent of the access method by which these operations are
283 requested. In general, such operations are relevant only in the context
284 of a particular Administered Object (and will most likely be realized as
285 method calls on the corresponding Administered Object classes), so they
286 are organized based on the currently "focused" administered object.
287 The available Supported Operations are documented
288 <a href="fs-admin-opers.html">here</a>.</p>
289
290 </blockquote></td></tr></table>
291
292
293 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Access Method Specific Requirements"><!--()--></a><a name="Access_Method_Specific_Requirements"><strong>Access Method Specific Requirements</strong></a></font></td></tr><tr><td><blockquote>
294
295 <h5>Scriptable Web Application</h5>
296
297 <p>An appropriate subset of the administrative operations described above
298 shall be implemented as commands that can be performed by the "Manager"
299 web application. <strong>FIXME</strong> - Enumerate them.</p>
300
301 <p>In addition, this web application shall conform to the following
302 requirements:</p>
303 <ul>
刘洪青6266f992017-05-15 21:21:03 +0800304 <li>All request URIs shall be protected by security constraints that
305 require a security role to be assigned for processing.</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800306 <li>The default user database shall <strong>not</strong> contain any
刘洪青6266f992017-05-15 21:21:03 +0800307 user that has been assigned a security role.</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800308 </ul>
309
310 <h5>HTML-Based Web Application</h5>
311
312 <p>The entire suite of administrative operations described above shall be
313 made available through a web application designed for human interaction.
314 In addition, this web application shall conform to the following
315 requirements:</p>
316 <ul>
317 <li>Must be implemented using servlet, JSP, and MVC framework technologies
318 described under "External Technologies", above.</li>
319 <li>Prompts and error messages must be internationalizable to multiple
320 languages.</li>
321 <li>Rendered HTML must be compatible with Netscape Navigator (version 4.7
322 or later) and Internet Explorer (version 5.0 or later).</li>
323 </ul>
324
325 </blockquote></td></tr></table>
326
327
328</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Testable Assertions"><!--()--></a><a name="Testable_Assertions"><strong>Testable Assertions</strong></a></font></td></tr><tr><td><blockquote>
329
330 <p><strong>FIXME</strong> - Complete this section.</p>
331
刘洪青6266f992017-05-15 21:21:03 +0800332</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
333 on improving documentation for Apache Tomcat.<br><br>
334 If you have trouble and need help, read
335 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
336 and ask your question on the tomcat-users
337 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
338 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
339 The Apache Comments System is explained <a href="../comments.html">here</a>.
340 Comments may be removed by our moderators if they are either
341 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
342 var comments_shortname = 'tomcat';
343 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/funcspecs/fs-admin-apps.html';
344 (function(w, d) {
345 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
346 d.write('<div id="comments_thread"><\/div>');
347 var s = d.createElement('script');
348 s.type = 'text/javascript';
349 s.async = true;
350 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
351 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
352 }
353 else {
354 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
355 }
356 })(window, document);
357 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
358 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800359 </em></font></div></td></tr></table></body></html>