ObMimic 1.0 Released

22 08 2014

Updated Feb 2018: OpenBrace Limited has closed down, and its ObMimic product is no longer supported.

Release 1.0 of ObMimic is now available from OpenBrace Limited.

ObMimic is a library of ready-made test-doubles for the Servlet API. It provides fully-configurable plain-Java implementations of Servlet API objects for use in out-of-container testing of any code that depends on the Servlet API (including, for example, JSF pages).

You can use ObMimic to write comprehensive, detailed tests for such code, using the same tools and techniques as for normal plain-Java code – without having to deploy and run your code inside a servlet container, and without having to write your own stubs or use general-purpose mocks that rely on your own assumptions about the Servlet API’s behaviour.

At its simplest, your tests can obtain fully-functional instances of Servlet API objects using plain no-argument constructors (e.g. “new HttpServletRequestMimic()” to create an HttpServletRequest).

The main changes in this release are:

  • First full release: ObMimic is no longer in “beta”.
  • Fix to session handling: A bug in session-handling during RequestDispatcher “forwards” and “includes” has been fixed (see 16Bugs Bug #5 for details).
  • HttpServletResponseMimic.setStatus(int): By default this no longer clears the response buffer as was specified incorrectly by the Javadoc of Servlet API versions prior to 3.0 (but a new ServletContainerBehaviour option has also been added to allow explicit control over this).

For a more complete list of changes, refer to the Changes in ObMimic 1.0.000 page.

As before, the free “Community Edition” and a free (but time-limited) licence-key file for evaluation of the “Professional Edition” facilities are available for download from the ObMimic website’s Downloads / Current Release page.

In addition, “Professional Edition” licence-key files and the “Enterprise Edition” can now be purchased via the website’s Buy ObMimic Licences page.

For full details and documentation please see the ObMimic website at www.openbrace.com.

For previous posts that describe ObMimic (including some example code), see:

ObMimic 1.0 Beta 10 Released

7 11 2013

Updated Feb 2018: OpenBrace Limited has closed down, and its ObMimic product is no longer supported.

Release 1.0-beta-10 of ObMimic is now available from OpenBrace Limited.

The main changes in this release are:

  • Testing of JSF pages: A “how to” guide has been added to cover testing of JSF pages, based on experiments that have demonstrated that ObMimic can be used for out-of-container testing of complete JSF pages (including full control over the ServletContext and ability to access the JSF FacesContext and API within tests).
  • Maven: A “how to” guide and “pom.xml” file have been added to aid in the use of ObMimic within Maven-based projects.
  • Listeners for Servlet API calls: Listeners can now be installed into Mimics to intercept, examine and optionally modify Servlet API calls and their results at the point where they occur, as described in an accompanying “how to” guide. In particular, this can be used as a last resort to work around any questionable Servlet API calls made by third-party code, or to overrule ObMimic’s built-in behaviour for a particular Servlet API call.

Additional changes include:

  • Any attempt to use a Java EE jar that is deliberately limited to “compile-time only” is now explicitly checked for and reported, and documentation has been updated accordingly.
  • Options have been added for configuring how the ServletContext “getResource” and “getResourceAsStream” methods behave when given “directory” paths.
  • Various minor fixes and documentation improvements.
  • ObMimic has been tested against some additional JDKs, including a JDK 8 early-access release.

For more complete details, refer to the Changes in ObMimic 1.0 Beta 10 page.

As before, the OpenBrace website provides a free download of ObMimic (including a free licence-key to unlock the “Professional Edition” features during the beta).

Note that our current intention is that this will be the last “beta” release, with the full 1.0 release to follow next.

ObMimic 1.0 Beta 9 Released

24 07 2013

Updated Feb 2018: OpenBrace Limited has closed down, and its ObMimic product is no longer supported.

Release 1.0-beta-9 of ObMimic is now available from OpenBrace Limited.

The main change from the previous 1.0-beta-8 release is compatibility with Servlet 3.1 and Java EE 7 libraries, so that ObMimic can be used with such libraries.

Whilst full support for Servlet 3.0 and 3.1 features is still pending (and intended for future releases), in the meantime this at least allows ObMimic to be used in the presence of Servlet 3.1 or Java EE 7 libraries (i.e. it can now be used with any Servlet 3.1 library as well as with any Servlet 2.4, 2.5 or 3.0 library as before). This also paves the way for the gradual introduction of Servlet 3.1 support in future releases.

In addition:

  • ObMimic’s Javadoc is now supplied in Java 7 style (but including an adjustment to work-around a problem in some versions of the Eclipse IDE that render Eclipse unable to parse such Javadoc).
  • Various minor fixes, revisions and improvements have been made to ObMimic’s documentation.

As before, the OpenBrace website provides a free download of ObMimic (including a free licence-key to unlock the “Professional Edition” features during the beta).

For previous posts that describe ObMimic and show some example code, see:

ObMimic Public Beta for Out-of-Container Servlet Testing

3 06 2013

Updated Feb 2018: OpenBrace Limited has closed down, and its ObMimic product is no longer supported.

ObMimic from OpenBrace Limited is a library of complete and fully-configurable plain-Java implementations of Servlet API objects for use as ready-made test-doubles in out-of-container testing of Servlet code. After a long development – and an even longer hiatus – it’s now available as a public beta release at www.openbrace.com.

You can use ObMimic to write comprehensive, detailed tests for your Servlet API code, using the same tools and techniques as for normal plain-Java code – without having to deploy and run your code inside a servlet container, and without having to write your own mocks or stubs and rely on your own assumptions about the Servlet API’s behaviour.

At its simplest, your tests can obtain fully-functional “mimic” instances of Servlet API objects using plain no-argument constructors — for example, you can create an HttpServletRequest with just:

new HttpServletRequestMimic();

Beyond that, you can configure and inspect the logical state of each such object as necessary for your tests. This includes control over details that would normally be “fixed” when running within a Servlet container (e.g. “init” parameters, Servlet API version, behaviours that are allowed to vary between containers, deliberate throwing of exceptions for testing of exception handling etc). There’s a detailed list of features on the website’s Features page.

If you want to test code that uses the Servlet API but find that detailed testing of such code is harder, more restrictive or slower than for normal Java code, ObMimic may be what you’re looking for.

The website provides a free download of ObMimic (including a free licence-key to unlock the “Professional Edition” features during the beta). The website also has a full copy of ObMimic’s documentation (including comprehensive Javadoc and a set of How To guides) and a set of discussion forums.

For some earlier posts that describe ObMimic and show some example code, see Experiments with out-of-container testing of Servlet code using ObMimic (Part 1) and First use of ObMimic for out-of-container testing of Servlets and Struts (Part 2).

Servlet 3.0 – A spaghetti API?

26 07 2010

The introduction in Servlet 3.0 of “web fragments” and both annotation-based and programmatic mechanisms for introducing components into a web-application are all very welcome.

However, combined with all the other new features, their configuration facilities, the relevant class/jar-finding mechanisms, and the interactions between everything, the overall complexity of the Servlet API seems to have increased horrendously.

To my mind, an awful lot of it is starting to look like a tangled mess of spaghetti – the API equivalent of spaghetti code.

Here’s just one relatively minor example (but please, please, please put me straight if I’ve missed the meaning of this and it’s all really simple and elegant).

Here goes…

The Javadoc of every “since 3.0” method in javax.servlet.ServletContext (for example, getEffectiveMajorVersion) includes a “throws” clause that says:

Throws: java.lang.UnsupportedOperationException – if this ServletContext was passed to the ServletContextListener#contextInitialized method of a ServletContextListener that was neither declared in web.xml or web-fragment.xml, nor annotated with WebListener

So the behaviour of a ServletContext, including things like whether or not you can determine which Servlet version it needs, thus depends on whether it “was passed to” a ServletContextListener to notify that listener of the context’s initialization – depending on which of various ways were used to create the listener.

For now let’s just gloss over the various minor questions and issues raised by this, such as:

  • What does “was passed to” actually mean? Has been passed to, at any time previously? Is currently being processed within a call to? Both? Something else?
  • Does or doesn’t this apply if the ServletContext “was passed to” multiple listeners of which some are of the specified type and some are not?
  • What is the actual purpose of this rule (i.e. why should being passed to a particular type of listener prevent the ServletContext from processing any of its “since 3.0” methods)?

Quite apart from all that, and far more fundamentally, isn’t it rather perverse for an object’s methods to depend directly on what other objects it “was passed to”? Especially where there doesn’t seem to be any immediately obvious reason for such a dependency?

And doesn’t it seem even more wrong that an object’s behaviour should depend on which other objects are “listening” for events on it? Isn’t that the tail wagging the dog?

Even assuming there’s some reasonable reason for this, and that there’s some sense in which it makes some kind of sense, is this really the kind of thing we want to see in an API?

Just in case this still seems too simple for you, the ServletContext also now includes a createListener method for creating listeners, and a number of overloaded addListener methods for adding listeners to itself (but only provided it has not already been initialized). The method for creating listeners does allow the creation of ServletContextListeners, but the methods for adding listeners only supports the addition of a ServletContextListener “If this ServletContext was passed to ServletContainerInitializer#onStartup” (which I’ll come to later).

Now both of these methods are subject to various conditions, including the “throws” clause described above. Listeners created and added in this way are, presumably, precisely the sort of listeners that such “throws” clauses are referring to (that is, not defined in web.xml or web-fragment.xml and potentially not annotated with WebListener). But what does it mean for methods that create and add such listeners to also have this “throws” clause themselves? Especially when they also require the ServletContext to have not yet have been initialized, in which case it presumably can’t have been passed to any ServletContextListeners yet anyway?

Is anyone else getting confused yet?

If even that still seems simple enough, ServletContextListeners are also no longer the only things listening for the application and/or context’s initialization. There is also now a ServletContainerInitializer interface, for classes that want to handle the application’s start-up (or does it really mean the container’s start-up, as its name would seem to imply?). Clearly, this is another route through which ServletContextListeners can be programmatically created and introduced, in particular by having the ServletContainerInitializer use the ServletContext’s “createListener” and/or “addListener” methods – with the “addListener” methods making specific allowance for this as described above, and requiring the ServletContext to know whether or not it “was passed to” a ServletContainerInitializer.

Of course, this ServletContainerInitializer interface has its own complexities and quirks. I won’t go into full detail on these here, but just to give a flavour:

  • It specifies naming conventions and mechanisms for how its implementing classes are found (and these mechanisms have their own quirks and ambiguities, for example the naming convention appears to require classes to be placed in the “javax.servlet” package, in violation of the usual rues and licence terms, and the class-level javadoc says that implementations must be within the application’s /WEB-INF/services directory but the relevant method’s javadoc talks about different behaviour depending on whether it is within /WEB-INF/lib or elsewhere);
  • It uses an annotation to specify what types of classes are to be passed to its sole method as arguments, together with rules for how the relevant classes are to be found, with this in turn including a requirement for the container to provide “a configuration option” to control whether failure to find such classes should be logged;
  • Its javadoc includes the quite wonderful statement “In either case, ServletContainerInitializer services from web fragment JAR files excluded from an absolute ordering must be ignored, and the order in which these services are discovered must follow the application’s classloading delegation model.”.

Am I alone in thinking this is all getting way out of hand? How many features like these (with their accompanying restrictions, exclusions and interactions) does it take before the API as a whole becomes incomprehensible?

At this point I was going to sarcastically sugguest some incredibly complex and convoluted fictional requirement for things I’d like to see added into the next version of the API. But I’m too afraid that someone might treat it as a serious feature request, and in any case it’s not easy to come up with anything that’s more convoluted than the existing features (at least, not without sounding completely silly).

So instead I’ll just say that, personally, I fear that the Servlet API may have already jumped the shark.

Forcing Glassfish V2 to reload an auto-deployed web-application

31 01 2009

If you auto-deploy a war archive on Glassfish V2, any changes to the deployed application’s JSP files are picked up automatically. However, if you make changes to the deployed application’s web.xml file or any other such configuration files, you need some way to make Glassfish “reload” the application using the updated files.

It isn’t immediately apparent how to trigger this. At any rate, it had me scratching my head yesterday when I found myself trying to install a third-party application. The installation instructions led me to auto-deploy its war archive and then edit the deployed files, but the changes didn’t take effect.

I couldn’t see anything in the Glassfish admin console to make it stop and re-load the application, and the command-line facilities that I found for this don’t seem to apply to auto-deployed applications.

The obvious solution was to shut-down and restart Glassfish, but even that seemed to leave the application still using its original configuration and ignoring the changes.

Apparently the trick is that you have to put a file named .reload into the root of the deployed application’s directory structure.

This file’s timestamp is then checked by Glassfish and used to trigger reloading of the application. So you can force a reload at any time by “touching” or otherwise updating this “.reload” file.

I can’t claim any detailed knowledge in this area, and have only had a quick look, but I get the impression that this “.reload” mechanism is used by Glassfish for the reloading of all “exploded” directory deployments. For applications that are explicitly deployed from a specified directory structure, you can use the deploydir command with a “–force=true” option to force re-deployment (there might be other ways to do this, but that’s the most obvious I’ve seen so far). But on Glassfish V2 that doesn’t appear possible for auto-deployed applications, so the answer for those is to manually maintain the “.reload” file yourself.

For some other descriptions and information about this, see:

Some notes:

  • Manually touching/updating a “.reload” file also works for exploded archives that have been deployed via “deploydir” (i.e. as an alternative to using the “deploydir” command to force reloading).
  • The content of the “.reload” file doesn’t matter, and it can even be empty. It just has to be named “.reload” and must be in the root directory of the deployed application (that is, alongside the WEB-INF directory, not inside it).
  • Because the “.reload” file is in the root of the web-application and outside of its WEB-INF, it’s accessible to browsers just like a normal JSP, HTML or other such file would be. So it’s not something you’d want to have present in a live system (or you might want to take other steps to prevent it being accessible).

I haven’t looked in detail at whether Glassfish V3 has any improved mechanism for this, but:

  • The V3 Prelude’s “Application Deployment Guide” does have a page “To Reload Code or Deployment Descriptor Changes” that shows the same solution still in place.
  • Glassfish V3 also seems to have a new redeploy command for redeploying applications, which appears to be equivalent to “deploydir” with “–force=true” but doesn’t require a directory path, so can presumably be used on any application, including auto-deployed applications.

As a personal opinion, I’m quite happy with using auto-deployment for most purposes, but in general I’m very much against the idea of editing the resulting “deployed” files. It just doesn’t seem right to me, and I can see all sorts of potential problems.

So even where a third-party product is delivered as a war archive and requires customisation of its files, I prefer to make the necessary changes to an unzipped copy. I can then use my normal processes to build a finished, already-customized archive that can be deployed without needing any further changes.

But there are still times when it’s handy to auto-deploy a web-application or other component by just dropping its archive into Glassfish, and then be able to play around with it “in place” – for example, when first evaluating a third-party product, or when doing some quick experiments just to try something.

So being able to force reloading of an auto-deployed application remains useful.

Private beta of ObMimic for out-of-container servlet testing

30 05 2008

Updated Feb 2018: OpenBrace Limited has closed down, and its ObMimic product is no longer supported.

The ObMimic library for out-of-container servlet testing is now being made available to a small number of users as a private “beta” release, in advance of a more public beta.

We’re ready for a few more people to start trying it out, so if you’re interested just let me know – either via this blog’s “contact me” page or via my company e-mail address of mike-at-openbrace-dot-com.

In outline, ObMimic provides a comprehensive set of fully-configurable test doubles for the Servlet API, so that you can use normal “plain java” tools and techniques to test servlets, filters, listeners and any other code that depends on the Servlet API. We call these test doubles “mimics”, because they “mimic” the behaviour of the real object.

We see this as the ultimate set of “test doubles” for this specific API: a set of plain Java objects that completely and accurately mimic the behaviour of the “real” Servlet API objects, whilst being fully configurable and inspectable and with additional instrumentation to support both “state-based” and “interaction-based” testing.

If you find servlet code harder to test than plain Java, ObMimic might be just what you’re looking for.

With ObMimic, you can create instances of any Servlet API interface or abstract class using plain no-argument constructors; configure and inspect all relevant details of their internal state as necessary; and pass them into your code wherever Servlet API objects are needed. This makes it easy to do detailed testing of servlets, filters, listeners and other code that depends on the Servlet API, without needing a servlet container and without any of the complexities and overheads of packaging, deployment, restarts/reloads, networking etc.

ObMimic includes facilities for:

  • Setting values that are “read-only” in the Servlet API (including full programmatic control over “deployment descriptor” values and other values that are normally fixed during packaging/deployment, or that have fixed values in each servlet container).
  • Examining values that are normally “write-only” in the Servlet API (such as a response’s body content).
  • Optionally recording and retrieving details of the Servlet API calls made to each object (with ability to turn this on and off on individual objects).
  • Controlling which version of the Servlet API is simulated, with versions 2.3, 2.4 and 2.5 currently supported (for example, you can programmatically repeat a test using different Servlet API versions).
  • Detecting and reporting any calls to Servlet API methods whose handling isn’t strictly defined by the API (e.g. passing null arguments to Servlet API methods whose Javadoc doesn’t specify whether nulls are permitted or how they are handled).
  • Controlling the simulation of container-specific behaviour (i.e. where the Servlet API allows variations or leaves this open).
  • Explicitly forcing Servlet API methods to throw a checked exception (e.g. so that you can test any code that handles such exceptions).
  • Handling JNDI look-ups using a built-in, in-memory JNDI simulation.

There are no dependencies on any particular testing framework or third-party libraries (other than Java SE 5 or higher and the Servlet API itself), so you can freely use ObMimic with JUnit, TestNG or any other testing framework or tool.

In contrast to traditional “mock” or “stub” objects, ObMimic provides complete, ready-made implementations of the Servlet API interfaces and abstract classes as defined by their Javadoc. As a result, your tests don’t have to depend on your own assumptions about the Servlet API’s behaviour, and both state-based and interaction-based tests can be supported. ObMimic can even handle complex sequences of Servlet API calls, such as for session-handling, request dispatching, incorporation of “POST” body content into request parameters, notification to listeners, and other such complex interactions between Servlet API objects. It can thus be used not only for testing individual components in isolation, but also for testing more complete paths through your code and third-party libraries.

With the appropriate configuration, it’s even possible to test code that uses other frameworks on top of the Servlet API. For example, we’ve been able to use ObMimic to test “Struts 1” code, and to run ZeroTurnaround’s JspWeaver on top of ObMimic to provide out-of-container testing of JSPs (as documented previously).

As a somewhat arbitrary example, the following code illustrates a very simple use of ObMimic to test a servlet (just to show the basics of how Servlet API objects can be created, configured and used):

import com.openbrace.obmimic.mimic.servlet.http.HttpServletRequestMimic;
import com.openbrace.obmimic.mimic.servlet.http.HttpServletResponseMimic;
import com.openbrace.obmimic.mimic.servlet.ServletConfigMimic;
import javax.servlet.Servlet;
import javax.servlet.ServletException;
import java.io.IOException;


/* Create a request and configure it as needed by the test. */    
HttpServletRequestMimic request = new HttpServletRequestMimic();
request.getMimicState().getRequestParameters().set("name", "foo");
request.getMimicState().getAttributes().set("bar", 123);
... further request set-up as desired ...

/* Create a response. */
HttpServletResponseMimic response = new HttpServletResponseMimic();

 * Create and initialize the servlet to be tested (assumed to be a
 * class called "MyHttpServlet"), using a dummy/minimal 
 * ServletConfig.
Servlet myServlet = new MyHttpServlet();
try {
    myServlet.init(new ServletConfigMimic());
} catch (ServletException e) {
    ... report that test failed with unexpected ServletException ...

/* Invoke the servlet to process the request and response. */
try {
    myServlet.service(request, response);
} catch (ServletException e) {
    ... report that test failed with unexpected ServletException ...
} catch (IOException e) {
    ... report that test failed with unexpected IOException ...

 * Retrieve the response's resulting status code and body content,
 * as examples of how the resulting state of the relevant mimic 
 * instances can be examined.
int statusCode 
    = response.getMimicState().getEffectiveHttpStatusCode();
String bodyContent
    = response.getMimicState().getBodyContentAsString();
... then check them as appropriate for the test ...

For further examples and details, refer to the previous posts “First experiments with out-of-container testing of Servlet code using ObMimic” part 1 and part 2, “Out-of-container JSP testing with ObMimic and JspWeaver”, and the related post “Mocking an API should be somebody else’s problem”.

There are also more extensive examples in ObMimic’s documentation.

ObMimic isn’t open-source, but it will have a zero-cost version (full API coverage but a few overall features disabled, such as the ability to configure the Servlet API version, control over how incorrect/ambiguous API calls are handled, and recording of API calls). There will also be a low-cost per-user “Professional” version with full functionality, and an “Enterprise” version that includes all of ObMimic’s source-code and internal tests (with an Ant build script) as well as a licence for up to 200 users.

At the moment there’s no web-site, discussion forums or bug-reporting mechanisms (all still being prepared), but ObMimic already comes with full documentation including both short and detailed “getting started” guides, “how to”s with example code, and extensive Javadoc – and for this private beta I’m providing direct support by e-mail.

Anyway, if you’d like to try out ObMimic, or have any questions or comments, or would like to be informed when there’s a more public release, just let me know via the “contact me” page or by e-mail.

%d bloggers like this: