Configuring the Web Server
Most common technologies for creating web applications are JSPs and servlets, these are most commonly deployed in a Apache/Tomcat solution. Tomcat can double up and also be used as a web server serving static content, it can use use virtual hosts and CGI. One problem with Tomcat is that it is a lot slower that an dedicated web server such as Apache (which is the leader in web servers).
JBoss serves web applications using a new Red Hat product called JBoss Web Server, which combines the speed of Apache with the versatility of Apache/Tomcat. JBoss Web Server is built on top of Apache Tomcat 6.0 but is capable of using a native Apache library called Apache Portable Runtime (APR) to attain the speed of the Apache web server.
Some of what I am going to talk about has already been mentioned in my Tomcat section, I will point you in that direction on topics that I have already covered.
Java EE applications are packaged into a WAR (Web Archive) structure defined in the servlet specification. I will be using the below diagram to discuss what a web application structure looks like, this is a simple example but is common, the top-level folder defines the name of the package, this package is a Web Archive package which uses the .war extension, the package could be a single file or an exploded directory, you can place any static content in the top-level directory that your application requires, which may include HTML files, XML files, images, JSPs, etc. There are two important directories in this example WEB-INF and META-INF, both of the directories cannot be access via a URL and are private to the web application.
I have already discuss in detail the above directories in my Tomcat section.
All web applications must have at least the WEB-INF/web.xml deployment descriptor (also known as standard deployment descriptor), the configuration files that provides the server with the necessary information required when deploying an application. A web application can have a proprietary deployment descriptor which can be used to enforce security rules by defining the source of the security data and how that data should be compared to the restricted security role. JBoss has two proprietary deployment descriptors called jboss-web.xml and context.xml.
Each web application must have a web deployment descriptor file called web.xml located in the WEB-INF directory, this file holds standard configuration information for servlets and JSPs
| example web.xml | <web-app> <servlet> <servlet-name>Oracle Test</servlet-name> <servlet-class>OracleTest1</servlet-class> </servlet> <servlet-mapping> |
The next file is the jboss-web.xml also in the WEB-INF directory, this is the main proprietary deployment descriptor file, this file is optional and is normally scant, there are a number of elements that can be used in this file
jboss-web.xml elements |
|
| class-loading | Used to enable isolated class loading, use this if you want to change the class loading behavior for an application but not necessary the entire server |
| security-domain | Specifies which security domain the application uses for authentication and authorization |
| context-root | Defines the root URL mapped to this application when HTTP requests come in, use this if you want to change the URL context |
| virtual-host | Specifies which virtual host the application belongs to, this must match a virtual host that was defined in the Tomcat server.xml file. |
| use-session-cookies | A boolean flag that indicates whether or not the session should be kept in client cookies |
| replication-config | Specifies when to replicate the HTTP session state throughout a cluster |
| resource-env-ref | Maps the Enterprise Naming Context (ENC) name for a resource-env-ref defined in the web.xml file to the location in the global JNDI namespace, use this if you have defined a resource-env-ref in the web.xml file for an application |
| resource-ref | Maps the Enterprise Naming Context (ENC) name for a resource-ref defined in the web.xml file to the location in the global JNDI namespace, use this if you have defined a resource-ref in the web.xml file for an application |
| ejb-ref | Maps the Enterprise Naming Context (ENC) name for an ejb-ref defined in the web.xml file to the location in the global JNDI namespace. |
| ejb-local-ref | Maps the Enterprise Naming Context (ENC) name for an ejb-local-ref defined in the web.xml file to the location in the global JNDI namespace. |
| servlet | Used to specify servlet-=specific customizations in JBoss Web Server. |
Simple example (jboss-web.xml) |
|
| <jboss-web> <security-domain>java:/jaas/simple-security-domain</security-domain> </jboss-web> |
|
JBoss Web Server is built on top of Tomcat and its proprietary deployment descriptor called context.xml, the jboss-web.xml has overridden most of the configuration features making it unnecessary in most cases. The only time this is used is if you are going to be using application-level Tomcat Valves.
There are times when you want a configuration to apply to all web applications, JBoss has global versions of these files which are located in the deployers directory, below is a table detailing application-level and global-level configuration files
| Filename | Application-level configuration | Global-level configuration |
| web.xml | WEB-INF/web.xml | deployers/jbossweb.deployer/web.xml |
| context.xml | WEB-INF/context.xml | deploy/jbossweb.sar/context.xml |
| jboss-web.xml | WEB-INF/jboss-web.xml | None available |
JBoss has a number of key files and directories, that live under either deploy and deployers directories
| deploy/jbossweb.sar/server.xml | Primary server configuration files, used to configure virtual hosts, protocols, ports and request filters |
| deploy/jbossweb.sar/context.xml | Global version of the application-level file by the same name |
| deploy/jbossweb.sar/jsf-libs | Contains libraries necessary for JSF development |
| conf/web.xml | Global version of the application-level file that we discussed above |
| deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml | Microcontainer configuration file, used to initialize the WAR deployer, it also configures security, class loading and clustering |
The server.xml is very much like Tomcats server.xml file (I suggest you have a quick look at my Tomcat section to get up to speed) it comprises of the following elements
| Element | Description | When would you configure it? |
| Server | Represents the entire servlet container | likely never |
| Service | Container for multiple connectors that share a single engine | likely never |
| Connector | Binds to a particular port and listens for requests using a particular protocol | For any changes to the protocol or port that clients use to communicate with the web container |
| Engine | Receives and processes all requests from all connectors in the same service. | When you're setting up load-balanced JBoss Web Servers nodes |
| Realm | Defines how security information is handled | If you need to change the strategy for mapping X509 certificate chains to a user for authentication purposes |
| Host | Defines virtual hosts | You need to add or change the configuration for a domain or hostname mapped to your server |
| Alias | Specifies an alias for Host element that surrounds it | If you have multiple names for the same virtual host |
| Valve | Intercepts requests that come into the system and executes code before the request reaches the targeted web component | In order to add some sort of monitoring or logging capability to the web container or a particular web application |
Like Tomcat two connectors are configured by default a HTTP connector (port 8080) and a AJP connector (port 8009).
The WAR deployer configuration file war-deployers-jboss-beans.xml defines a bean called WarDeployer, the main deployer used for web applications. There are a number of properties at the end of the file that you may wish to change
| defaultSecurityDomain | The security domain used if you don't explicitly define one in your applications WEB-INF/jboss-web.xml, default is java:/jaas/jboss-web-policy |
| deleteWorkDirOnContextDestroy | Delete the server/xxx/work directory after the application context ends, default is false |
| java2ClassLoadingCompliance useJBossWebLoader filteredPackages |
These properties are used to configure class loading for web applications. |
I have already discussed virtual hosts in my Tomcat section, so pop over to get an ideal what it means, I am only going to show you a quick and dirty on what needs to be configured in JBoss to setup virtual hosting, you need to do the following
| Enable the connector to use virtual hosts | <Connector protocol="HTTP/1.1" port="8080" Note: this would be configured in the server.xml (this is identical to Tomcat) |
| Define the virtual host | <Engine name="jboss.web" defaultHost="localhost"> Note: you can add an alias to map multiple domain names to the same virtual host configuration |
| Bind an application to a virtual host | <jboss-web> <virtual-host>www.somehostname.com</virtual-host> </jboss-web> Note: this would be placed in the application WEB-INF/jboss-web.xml file |
The last web application aspect you might want to change is the context paths, here are some tips
| context-root path | <jboss-web> <context-root>/hello</context-root> </jboss-web> Note: change this in the jboss-web.xml file |
| context path of an Enterprise app | <application> <display-name>HelloWorldApp</display-name> <module> <web> <web-uri>helloworld.war</web-uri> <context-root>/hello</context-root> </web> </module> </application> |
There are two ways to configure JBoss
If you have decided to setup the JBoss web server most clients will connect via HTTP or HTTPS, if have are using JBoss as a servlet, JSP and EJB server only then you are probably going to use AJP. I have already discussed the three types of connectors in my Tomcat section section so pop over and take a look at HTTP/HTTPS and AJP to get up to speed.
I am only going to display the already configured setup in the server/xxx/deploy/jbossweb.sar/server.xml file and explain some of the attributes that you could change
Connector Attributes |
|
| maxThreads | This is used with the HTTP connector which is the maximum number of processing threads that can run concurrently, the default is 200. If the limit is reached the requests will be queued there a number of queuing attributes (see below), but the defaults are more than enough for most installations |
| minSpareThreads | The number of threads the web server tries to keep available above and beyond the number of currently in use, default is 4 |
| maxSpareThreads | if more threads than this are idle, then those threads are stopped and deallocated, default is 50 |
| acceptCount or backlog | Defines the length of the queue, once the queue is full all request are then refused, default is 10 acceptCount (HTTP) backlog(AJP) |
| connectionTimeouts | Use this if clients are responding slowly, HTTP connectors have a default of 60 seconds then AJP connector is 0 which means infinite |
| proxyName and proxyPort | Use these if you are going to be behind a proxy, they override values that are provided to your application when your code calls the request.getServerName() and request.getServerPort() servlet methods. |
Already configured Connectors |
|
Example |
<Connector protocol="HTTP/1.1" port="8080" address="${jboss.bind.address}" connectionTimeout="20000" redirectPort="8443" />
<Connector protocol="AJP/1.3" port="8009" address="${jboss.bind.address}" redirectPort="8443" /> |
Again I have already discussed valves in my Tomcat section, valves in JBoss are the same as the Tomcat ones, you can perform certain actions every time a request comes in to the server, you may want to log information, check an IP address, block IP addresses.
You can configure valves at the application-level using the WEB-INF/context.xml file or at the server-level as a sub-element of an engine or a host in the JBoss Web Servers server.xml file.
A valve element must have an attribute called className that points to a Java class, there are a number of Java classes you can use
| org.apache.catalina.valves.RequestDumperValve | Logs information about a request before and after its processed |
| org.apache.catalina.valves.AccessLogValve | Writes to a logfile that resembles a web server access log, you can customize the log information |
| org.apache.catalina.valves.FastCommonAccessLogValve | Same as above but faster with limited configuration |
| org.apache.catalina.valves.RemoteAddrValve | Allows filtering of requests based on the clients IP address |
| org.apache.catalina.valves.RemoteHostValve | Allows filtering of requests based on the clients hostname |
| org.apache.catalina.authenicator.SingleSignOn | When a user signs into a single application, this valve automatically signs them into all other applications associated with the virtual host for which the valve is defined |
| org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn | This is the same as the SingleSignOn valve but enables the single-sign-on feature to work across a cluster of JBoss servers |
| org.jboss.web.tomcat.service.jca.CachedConnectionValve | Automatically closes all JCA connections when the web request ends, in production you probably want to disable this. |