Tech Per

In several projects I have been co-developing, we had a webapp as part of the system, which exposed a webservice API as integration end-point to the system. The sole content of that webapp is the webservice, and as such, the web.xml contained only the mount of the webservice servlet (like CXF or Axis) and not much more.

The Problem

If this webapp is hit on an URL that does not exist, the webservice servlet does not even get hit, and the container produces a 404 html page. If some internal server error happen before the webservice servlet is hit, the container generates a 500 html page. If the client calling the webservice does not produce proper authentication tokens, the container generates a 401 html page, again before the webservice servlet is reached.

In all these cases, the webservice engine, Axis, CXF or their cousins, won’t be able to produce a proper SOAP fault message. If the client program that calls the webservice, trigger any of the above described situations, the response cannot be parsed properly as a SOAP response. Because the response is html (or nothing/empty).

This is not very SOAP like. Luckily, the solution is simple.

The Solution

In web.xml, you can both map server response codes to specific response pages and map certain extensions to HTTP response content-type setting. Let’s solve the problem for the 401 situation, where authentication failed:

Step 1: Create a static SOAP response

For the 401 problem, we will create a file named 401.soap and place it inside the webapp in the /soap-error-responses directory. The file shall contain this static xml:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
	<env:Body>
		<env:Fault>
			<faultcode>env:Server</faultcode>
			<faultstring>401:Unauthorized</faultstring>
		</env:Fault>
	</env:Body>
</env:Envelope>

Step 2: Map the error-code to the static file

Inside web.xml, you add this mapping:

<error-page>
  <error-code>401</error-code>
  <location>/soap-error-responses/401.soap</location>
</error-page>

This will make the container return your static response in the case of a 401 response code.

Step 3: Map the .soap extension to a content-type

A SOAP response should be sent with HTTP content-type text/xml. To ensure this for the .soap files, you put the below mime-mapping element into your web.xml file:

<mime-mapping>
  <extension>soap</extension>
  <mime-type>text/xml</mime-type>
</mime-mapping>

And you are done.

One thing about this solution, as also mentioned in the beginning, is that it will be okay for a webapp which contains nothing but a webservice service. On the other hand, if the webapp also contains a regular web application with html and jsp files, it will be a problem that 401, 404, 500,… are mapped to SOAP fault codes. The browser will be disappointed

Another thing to note is, that there is nothing stopping you from using dynamically generated response files, like jsp files. One caveat though, the source of a response like 500 (internal server error), could be things like out-of-memory, out-of-disk-space or out-of-file-handles, all errors that most likely will prevent the container from processing a dynamic jsp files too. So, maybe better stay with the static ones.