JBoss 4.0.5 应用服务器WEB应用开发参考

 

第一章 Tomcat服务

Tomcat 5.5支持Servlet2.4和JSP2.0规范，Tomcat作为一个可布署的服务jbossweb-tomcat-55.sar发布在deploy目录。因为采用展开目录的发布形式，很容易检查和更新嵌入的Tomcat实例的配置信息。

主要的服务文件是 META-INF/jboss-service.xml,用来配置org.jboss.web.tomcat.tc5.Tomcat5 MBean控制Tomcat，支持的可配置属性包括：

• DefaultSecurityDomain: 指定JASS安全域设置，当一个war包的jboss-web.xml文件没有提供显式的security-domain设置时使用此设置。

• Java2ClassLoadingCompliance: 缺省值为true，表示采用标准的java父类委托类加载机制，而不是使用servlet加载机制，首先从WAR文件中加载。从包含客户端jar文件的 WAR包中加载被EJB使用的类，可能导致类加载冲突。因此，如果使用Servlet加载机制，必须保证布署包中没有重复的类。

• UseJBossWebLoader: 缺省值为true，表示使用JBoss统一的类加载器作为WEB应用程序的类加载器。这意味着包含在WEB-INF/classes和WEB-INF /lib目录下的所有的类都被加载到缺省的共享类加载存储区，这允许类和资源在多个WEB应用程序间共享。如果这不是你期望的，可以禁用此选项。

• LenientEjbLink: 缺省值为true，表示在jboss-web.xml 文件中查找jndi-name时忽略ejb-link错误。

• ManagerClass: 设置用来复制WEB应用程序之间的被标记为可分布式的状态的会话管理器类。唯一提供的实现是org.jboss.web.tomcat.tc5.session.JBossCacheManager, 使用JBossCache来追踪可分布式的状态。

• SubjectAttributeName: If set, this represents the request attribute name under which the JAAS subject will be stored. There is no default value, meaning that the subject is not set in the request.

• SessionIdAlphabet: 用来设置创建会话ID,必须由65个不同的字符组成。

• SnapshotMode:用来设置在一个集群环境下的快照模式。可选值是instant或interval，instant模式下针对一个集群会话的任何改变都会立即进行广播。interval模式下针对一个集群会话的所有改变都根据SnapshotInterval设置的间隔值进行广播。

• SnapshotInterval: 设置interval快照模式下的快照间隔，单位为ms，缺省值是1000ms。

• UseLocalCache: 缺省值是true，表示是否优先使用本地HTTP会话值。当设置为ture时，将使用本地HTTP会话值，更新会被复制到其他节点，但是对其他节点的相同 会话的更新不会更新本地会话值，这种模式在failover时比较有用。当设置为false时，会话值将从分布式的缓存中获取，这种模式适用于负载平衡。

• UseJK: 缺省值为false,用来指定是否使用MOD_JK(2)，和JvmRoute组合起来用于负载平衡。如果设置为true，将插入一个 JvmRouteFilter拦截所有的请求，在检测到一个failover时，替换JvmRoute。此设置要求在Engine定义时设置 JvmRoute。

• Domain: 缺省域值为jboss.web,This is the JMX domain under which Tomcat will register additional MBeans.

• SecurityMangerService: 这是Tomcat使用的JASS安全管理器的引用，缺省值为Jboss.security:service=JaasSecurityManager.

第二章 SERVER.XML

jboss-service.xml文件用来控制Tomcat整合服务，Tomcat本身有一个文件jbossweb-tomcat55.sar/server.xml控制他自身的操作。

server.xml文件没有一个正式的DTD或模式定义，这里只讲述一些主要的可配置元素。顶层元素是Server，包含一个Service元素用来描述整个WEB子系统，支持的属性包括：

• name: 唯一标识符

• className: 提供服务实现的类全称。

Connector

Service可以包含一个或多个连接器元素。一个连接器用来配置允许客户端发送请求和接受响应的传输机制。连接器转发请求给引擎并返回响应结果给客户端，每个连接器通过Connector元素进行配置，连接器支持如下属性：

• className: 连接器实现的类全称，必须实现org.apache.catalina.Connector接口，缺省设置是 org.apache.catalina.connector.http.HttpConnector，表示HTTP传输机制。

• acceptCount:当所有的请求处理线程都可用时，可以接受的最大的请求数。当接受的请求数超过此数值时，所有的请求都会被拒绝。缺省值为10。

• address. 对于不止一个IP地址的服务器，此属性用来指定需要监听指定端口的IP，缺省情况这个端口将被服务器的所有地址使用。

• bufferSize: 用来指定连接器使用缓存输入流的缓存大小，缺省为2048字节。

• connectionTimeout:设置连接超时，单位为ms，缺省值为60000ms。

• debug: 设置连接器生成的日志消息的调试级别，值越大，日志越详细，缺省值为0。此值依赖于log4j的类别 org.jboss.web.tomcat.tc5.Tomcat5 的阀值。

• enableLookups: 缺省值为false,表示使用客户端主机名的DNS解析功能，被ServletRequest.getRemoteHost方法调用。

• maxThreads: 缺省值为200,设置并发的请求处理线程的最大数目。 that will be allowed to exist until the thread pool starts stopping the unnecessary threads. The default value is 50.

• minSpareThreads: 缺省值为4，设置当连接器启动时被创建的并发的请求处理线程，连接器保证任何时候都有不小于此数值的请求处理线程可用。

• port: 连接器会创建一个服务器端SOCKET用来等待连接请求，此属性用来设置TCP端口号。同时只能有一个服务器应用监听一个指定的IP地址的指定端口。

• proxyName:如果连接器使用在代理模式，此属性用来指定request.getServerName()方法调用返回的服务器. 名称。

• proxyPort: 如果连接器使用在代理模式，此属性用来指定request.getServerPort()方法调用返回的服务器端口号。

• redirectPort: 缺省值是标准的HTTPS端口号443，用来设置非SSL请求在接受到基于内容安全的请求时应该重定向的端口号。

• secure:设置ServletRequest.isSecure方法的值，表示是否需要保证传输管道的安全性，缺省值为false。

• scheme: 设置ServletRequest.getScheme方法返回的模式名称，缺省值为http。

• tcpNoDelay: 缺省值为true，此属性设置为true，将会设置服务器端SOCKET的TCP_NO_DELAY选项，在大多数情况下此选项可以提升性能。

详细的描述请参见： http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/http.html.

Engine

每一个Service必须有且仅有一个Engine配置。一个引擎处理经过配置的连接器提交到服务的所有请求，支持的子元素包括： Host, Logger, Valve 和Listener，支持的属性包括:

• className: org.apache.catalina.Engine接口的具体实现的类全称，如果不指定，缺省值为org.apache.catalina.core.StandardEngine.

• defaultHost: 用来处理主机名无法匹配Host配置的请求时使用的缺省Host配置。

• name:引擎的逻辑名称，用于日志记录。

详细的描述请参见：http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/engine.html.

Host

Host 元素表示一个虚拟主机配置，是基于一个特定的DNS主机名称的WEB应用程序的容器，支持的子元素包括： Alias, Valve 和Listener，支持的属性包括：:

• className: org.apache.catalina.Host 接口的具体实现的类全称，缺省值为 org.apache.catalina.core.StandardHost.

• name:虚拟主机的DNS名称，必须至少配置一个其名称值和Engine元素的defaultHost属性相同的HOST元素 。

• Alias 元素是Host元素的可选子元素，每个Alias指定Host一个可选的DNS名称。

详细的描述参见:http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/host.html.

Valve

 Valve 元素提供WEB容器的请求处理管道的一个钩子，必须实现org.apache.catalina.Valve 接口，只有一个必须的. There is only one required configuration attribute:

• className:org.apache.catalina.Valve 接口实现的类全称。

最通用的Valve实现是AccessLogValve, 用来记录HTTP访问日志，类全称为 org.jboss.web.catalina.valves.AccessLogValue，支持的属性包括：

• directory: 访问日志保存的路径。

• pattern: 定义日志消息的模式，缺省值为common。

• prefix: 缺省值为 access_log，设置日志文件名称前缀。

• suffix: 缺省值为空字符串，设置日志文件名称后缀。

详细描述参见：http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/valve.html.

第三章 CONTEXT.XML

context.xml配置系统内包含的所有WEB应用程序的缺省上下文。支持的属性包括：

• cookies: 缺省值为true，表示是否需要使用cookie跟踪会话。

• crossContext: 表示ServletContext.getContext(String path) 方法是否可以返回布署在虚拟主机内的其他WEB应用程序的上下文信息 。

详细描述参见：http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/context.html.

第四章 使用HTTPS

有几种方式配置Tomcat容器支持HPPT通过SSL，根据是否使用JBoss特定的连接器Socket工厂（允许从JBossSX安全域获取JSSE服务器认证信息，这要求使用org.jboss.security.plugins.JaasSecurityDomain MBean建立一个SecurityDomain。下面的server.xml文件描述了使用这种方式设置SSL连接器的配置。

xml 代码

1. <Server>  
2.     <Service name="jboss.web" className="org.jboss.web.tomcat.tc5.StandardService">  
3.   
4.         <Connector port="8080" address="${jboss.bind.address}" maxThreads="150"  
5.             minSpareThreads="25" maxSpareThreads="75" enableLookups="false"  
6.             redirectPort="443" acceptCount="100" connectionTimeout="20000"    
7.             disableUploadTimeout="true"/>  
8.   
9.         <Connector port="443" address="${jboss.bind.address}" maxThreads="100"  
10.             minSpareThreads="5" maxSpareThreads="15" scheme="https"  
11.             secure="true" clientAuth="false"  
12.             keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore"  
13.             keystorePass="rmi+ssl" sslProtocol="TLS"/>  
14.   
15.         <Engine name="jboss.web" defaultHost="localhost">  
16.             <Realm  
17.                 className="org.jboss.web.tomcat.security.JBossSecurityMgrRealm"    
18.                 certificatePrincipal="org.jboss.securia.Log4jLogger"  
19.                 verbosityLevel="WARNING" category="org.jboss.web.localhost.Engine"/>  
20.             <Host name="localhost" autoDeploy="false" deployOnStartup="false"    
21.                   deployXML="false">  
22.                 <DefaultContext cookies="true" crossContext="true" override="true"/>  
23.             </Host>  
24.         </Engine>  
25.     </Service>  
26.             </Server>  

上述的配置包含一个JaasSecurityDomain, 由于此描述文件不是作为一个SAR的一部分布署的，需要拷贝chap8.keystore 文件到 server/default/conf目录。可以通过访问https://localhost/jmx-console测试此配置。

注意：如果JBoss运行的系统对1023以下的端口要求特殊的权限，可能需要更改端口号，通常使用8443。

支持的可配置属性如下

• algorithm: 证书使用的编码算法，缺省使用SunX509.

• className: SSL服务器SOCKET工厂实现类全称，这里必须是org.apache.coyote.tomcat4.CoyoteServerSocketFactory。使用任何别的实现不会导致错误，但是服务器SOCKET不会使用SSL。

• clientAuth: 如果SSL堆栈在接受一个连接时需要从客户端获取一个有效的证书链，可以设置此属性为true。缺省值为false，除非客户端请求一个使用CLIENT-CERT认证的资源，将不需要获取一个有效的证书链。

• keystoreFile: 证书文件保存的路径名称，缺省情况路径名是保存在操作系统主目录下的.keystore文件。

• keystorePass: 缺省值是 changeit,用来设置访问证书文件中的服务器认证的密码。

• keystoreType: 证书文件的类型，缺省值为JKS。

• protocol: SSL协议的版本，如果没有指定缺省值为TLS.

注意：如果使用自签名的证书测试此配置，尝试通过HTTPS连接访问，浏览器将显示一个警告框如下：

第五章 使用DIGEST 认证

当使用BASIC和FORM认证时，用户密码使用明文发送。如上描述，可以使用HTTPS加密整个会话，使密码保持私密性。然而，这种方式还是要求密码以明文形式存在于服务器端，哪怕是临时存在于内存中。

Digest 使用询问-响应机制，服务器发送一个唯一的询问给客户，客户响应一个哈希值，服务器会将这个哈希值和服务器端的版本进行比较。

使用Digest认证的WEB应用程序通过在web.xml文件中设置auth-method 值为DIGEST ，下面的示例忽略应用程序特定的security-constraint 和security-role 声明。

1. <login-config>  
2.     <auth-method>DIGEST</auth-method>  
3.     <realm-name>My Aplication</realm-name>  
4. </login-config>  

xml 代码

要完成整个配置，我们还必须创建一个特定的安全域，并链接到这个应用太空船，比如我们在java:/jaas/digest下创建一个安全域，应用程序将在jboss-web.xml文件中链接此安全域：

xml 代码

1. <jboss-web>  
2.     <security-domain>java:/jaas/digest</security-domain>  
3. </jboss-web>   

    

现在我们需要创建安全域定义，这个例子中我们将使用UsersRolesLoginModule，虽然任何login模块都支持对密码进行哈希处理。下面的示例显示一个完整的配置：

xml 代码

1. <application-policy name="digest">  
2.     <authentication>  
3.         <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"  
4.                       flag="required">  
5.             <module-option name="usersProperties">digest-users.properties</module-option>  
6.             <module-option name="rolesProperties">digest-roles.properties</module-option>  
7.             <module-option name="hashAlgorithm">MD5</module-option>  
8.             <module-option name="hashEncoding">rfc2617</module-option>  
9.             <module-option name="hashUserPassword">false</module-option>  
10.             <module-option name="hashStorePassword">true</module-option>  
11.             <module-option name="passwordIsA1Hash">true</module-option>  
12.             <module-option name="storeDigestCallback">  
13.                 org.jboss.security.auth.spi.RFC2617Digest   
14.             </module-option>  
15.         </login-module>  
16.     </authentication>  
17. </application-policy>  

   

头两个模块选项配置用户和角色属性文件，剩余的六个选项配置digest认证。要使你的应用程序支持digest认证，拷贝这六个选项到你的login模块配置部分。

现在剩下的工作是必须创建密码的哈希值，并保存在你的用户存储中，在这个示例中是the digest-users.properties 文件。Digest使用用户名称，密码和realm名称进行哈希操作。realm来自于web.xml文件中，这里是  My Application.

JBoss 提供一个帮助类用来创建digest哈希值，这可以在bin目录中使用如下命令激活：

[bin]$ java -cp ../server/default/lib/jbosssx.jar /
org.jboss.security.auth.spi.RFC2617Digest username "My Application" password
RFC2617 A1 hash: 9b47ec6f03603dd49863e7d58c4c49ea

三个参数分别是用户名，realm名和密码，处理后的密码应该保存在用户存储中，在这个示例中，就是保存在digest-users.properties 文件中。

user=9b47ec6f03603dd49863e7d58c4c49ea

你还需要定义应用程序角色，并在login模块中进行配置.

第六章 设置WEB应用程序上下文

应用程序上下文决定Tomcat如何基于URL派发请求给应用程序。如果你的应用程序上下文是myapp,那么任何类似于/myapp 或 /myapp/* 的请求都将派发给你的应用程序，除非有一个更特定的上下文存在。如果还有一个应用程序的上下文是 myapp/help, 对 /myapp/help/help.jsp的请求将会派发给这个应用程序处理，而不是刚才那个。

如果应用程序上下文被设置为/，作为根上下文，当一个应用程序被设置为要上下文，它将处理所有不能被其他上下文处理的请求。

应用程序上下文根据如何布署来决定。当一个应用程序布署在EAR文件中时，上下文参数在application.xml 文件中使用 context-root 元素指定，如下示例中web-client.war的上下文为bank。

xml 代码

1. <application xmlns="http://java.sun.com/xml/ns/j2ee" version="1.4"  
2.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    
3.     xsi:schemaLocation="http://java.sun.com /xml/ns/j2ee    
4.                              http://java.sun.com/xml/ns/j2ee/application_1_4.xsd">  
5.     <display-name>JBossDukesBank</display-name>  
6.   
7.     <module>  
8.         <ejb>bank-ejb.jar</ejb>  
9.     </module>  
10.     <module>  
11.         <web>  
12.             <web-uri>web-client.war</web-uri>  
13.             <context-root>bank</context-root>  
14.         </web>  
15.     </module>  
16.   
17. </application>  

布署在EAR文件外部的应用程序，上下文可以通过两种方式指定，一种是在WEB-INF/jboss-web.xml文件中指定，示例如下：

   
   

    xml 代码
   
   

    
<jboss-web>  
    <context-root>bank</context-root>  
</jboss-web>  
   

最后如果没有指定上下文，那么上下文就是WAR文件的名称。比如 web-client.war, 缺省上下文将是web-client. 唯一的例外是 ROOT,JBoss已经在jbossweb-tomcat55.sar 目录中包含一个ROOT.war文件，所以如果需要使用自己的ROOT，必须重命名或移除这个ROOT。

第七章 设置虚拟主机

虚拟主机允许根据运行JBoss的机器中，JBoss知道的不同的DNS名称组织应用程序。考虑如下在server.xml文件中的虚拟主机配置。

xml 代码

    

     
<Server>  
   <Service name="jboss.web"  
      className="org.jboss.web.tomcat.tc5.StandardService">  
          
      <!-- A HTTP/1.1 Connector on port 8080 -->  
      <Connector port="8080" address="${jboss.bind.address}"  
                 maxThreads="150" minSpareThreads="25" maxSpareThreads="75"  
                 enableLookups="false" redirectPort="8443" acceptCount="100"  
                 connectionTimeout="20000" disableUploadTimeout="true"/>  
  
      <Engine name="jboss.web" defaultHost="vhost1">  
         <Realm className="org.jboss.web.tomcat.security.JBossSecurityMgrRealm"  
                certificatePrincipal="org.jboss.security.auth.certs.SubjectDNMapping"  
            />  
         <Logger className="org.jboss.web.tomcat.Log4jLogger"  
                 verbosityLevel="WARNING"  
                 category="org.jboss.web.localhost.Engine"/>  
  
            <Host name="vhost1" autoDeploy="false"  
                  deployOnStartup="false" deployXML="false">  
                <Alias>vhost1.mydot.com</Alias>  
                <Valve className="org.apache.catalina.valves.AccessLogValve"  
                       prefix="vhost1" suffix=".log" pattern="common"  
                       directory="${jboss.server.home.dir}/log"/>  
               
     
                <DefaultContext cookies="true" crossContext="true" override="true"/>  
            </Host>      
            <Host name="vhost2" autoDeploy="false"    
                  deployOnStartup="false" deployXML="false">  
                <Alias>vhost2.mydot.com</Alias>  
                <Alias>www.mydot.com</Alias>     
  
                <Valve className="org.apache.catalina.valves.AccessLogValve"  
                       prefix="vhost2" suffix=".log" pattern="common"    
                       directory="${jboss.server.home.dir}/log"/>  
  
                <DefaultContext cookies="true" crossContext="true" override="true"/>  
            </Host>  
      </Engine>  
   </Service>  
</Server>  
    

当布署一个WAR文件时，缺省关联的虚拟主机是在Engine引擎的 defaultHost属性中指定的。要布署一个应用程序到一个特定的虚拟主机，必须在jboss-web.xml文件中配置一个合适的virtual -host定义。下面的示例布署一个WAR文件到虚拟主机www.mydot.com。

xml 代码

1. <jboss-web>  
2.     <context-root>/</context-root>  
3.     <virtual-host>www.mydot.com</virtual-host>  
4. </jboss-web>  

第八章 静态内容

JBoss提供一个缺省的应用程序，在 jbossweb-tomcat55.sar 目录下的ROOT.war。可以通过添加内容到ROOT.war目录，提供静态文件服务，而不和任务其他的应用程序关联。比如如果你想有一个共享的图片文件目录 ，可以在ROOT.war目录下创建一个images子目录。你能通过如下路径访问myimage.jpg文件http://localhost:8080/images/myimage.jpg.