1  All Editions

All editions of ObMimic, including the free “Community Edition”, provide the following features:

Feature

Explanation

Mimics for 26 Servlet API interfaces and abstract classes

ObMimic provides complete, ready‑made, plain Java™ out‑of‑container test‑doubles (“mimics”) for all of the following Servlet API interfaces and abstract classes:

  • javax.servlet.FilterChain, FilterConfig, Filter, GenericServlet, RequestDispatcher, ServletConfig, ServletContextAttributeListener, ServletContextListener, ServletContext, ServletInputStream, Servlet, ServletOutputStream, ServletRequestAttributeListener, ServletRequestListener, ServletRequest, ServletResponse and SingleThreadModel.
  • javax.servlet.http.HttpServletMimic, HttpServletRequest, HttpServletResponse, HttpSessionActivationListener, HttpSessionAttributeListener, HttpSessionBindingListener, HttpSessionContext, HttpSessionListener and HttpSession.

Additional mimics are provided for:

  • GenericServlet, Servlet and HttpServlet combined with SingleThreadModel.
  • Selected JDK classes, namely: java.security.Principal (for explicit control over the instance returned by HttpServletRequest.getUserPrincipal).

Mimics are plain Java objects

Each mimic is a plain Java object that can be used outside of servlet containers and that has no dependencies on any particular servlet container’s internal implementation.

Similarly, ObMimic is not tied to any particular testing framework or web‑application framework or toolkit, so you can use it in JUnit or TestNG tests (or in any other Java‑based tests), and independently of any other frameworks, tools or libraries you may be using.

Simple no‑argument constructors

Each mimic includes a simple no‑argument constructor. In particular, if all you need is a “dummy” instance of some Servlet API object, ObMimic provides the simplest possible way to achieve this (for example, “new HttpServletRequestMimic()” to create an HttpServletRequest).

In addition, for each mimic class there is also a corresponding “Factory” class through which instances can be created with given values for various key properties.

All Servlet API methods have complete and accurate implementations

Each mimic provides a complete and accurate implementation of all of the corresponding Servlet API methods and behaviour as defined by the Servlet API’s Javadoc. There are no “unsupported” methods, nor are any methods limited to only catering for the most common uses.

All mimic implementations include:

  • Appropriate handling of all of the various interactions between Servlet API methods.
  • Ensuring and maintaining consistency between Servlet API methods that depend on the same underlying data or affect each other, as described below.

All mimics are fully configurable and examinable

Each mimic includes a “mimicState” object that encapsulates the logical state of the Servlet API object that the mimic represents. This “mimicState” provides methods for explicitly configuring and examining everything that affects the behaviour and return values of the mimic’s Servlet API methods, even for values that would be fixed, read‑only or write‑only when running within a servlet container.

Your tests can therefore programmatically:

  • Control everything that affects how each mimic’s Servlet API methods behave and respond.
  • Examine the effect of each test on the state of the mimicked Servlet API objects, even where the Servlet API itself does not support this (for example, you can examine the content that has been written to an HttpServletResponse’s output, retrieve the entries that have been written to a ServletContext’s log etc).

Consistency between related Servlet API methods

Because the “MimicState” classes are modelled on the logical state of each Servlet API object as a whole (rather than the particular arguments and return values of each individual Servlet API method), they can maintain and ensure consistency between Servlet API calls that operate on shared or related data or that otherwise affect each other.

Control over application‑specific configuration

The “mimicState” objects used for ServletContext mimics include sub‑components that represent the application’s deployment‑descriptor and static resources, and through which relevant details of these can be programmatically configured and controlled.

This includes, for example, being able to programmatically configure context parameters; definitions and mappings for servlets, filters and listeners; and the location and content of static resources.

Control over container‑specific and environment‑specific behaviour

The “mimicState” objects used for ServletContext mimics include sub‑components representing the relevant details of the servlet container that is being simulated and its underlying environment, and through which these details can be programmatically configured and controlled.

This includes, for example, being able to programmatically configure the servlet container’s default response buffer size; the value to be returned by the ServletContext “getServerInfo” method; whether cross‑context request dispatching is supported or not; whether access to request headers using the HttpServletRequest “getHeaders” method is supported or always returns null; what file‑separator string the Servlet API methods should use; and many other such details.

Additional facilities are also provided through which the current date/time and environment variables as seen by ObMimic can be explicitly controlled.

MimicStates all support “clear”, “copyFrom” and “equals” methods

All “MimicState” classes and their sub‑components support:

  • A “clear” method to clear/reset the instance back to its initial state (with suitable default values for everything).
  • A “copyFrom” method for populating the instance’s entire state by copying it from any other instance of the same type.
  • An “equals” implementation for logical comparison of the instance’s entire state against that of any other instance of the same type.

Together these facilities enable you, for example, to use local MimicState variables as re‑usable initial values for multiple tests; as “expected results” for checking the outcome of a test; and as “snapshot” copies of a mimic’s state as at some particular point.

Detection of ambiguous API calls

All calls to a mimic’s Servlet API methods are checked for whether the Servlet API’s Javadoc is sufficiently complete and precise to unambiguously specify how the call should be handled (for example, that the given argument values are definitely permitted, that any other restrictions on calling the method are met, and exactly how such a call with those particular argument values should be processed). Any call for which the Servlet API is considered incomplete or ambiguous is treated as an “API ambiguity”.

For the Community edition of ObMimic, all such API ambiguities are handled by throwing an unchecked “APIAmbiguityException” to report the ambiguous call. You can thus detect whether the code you are testing is making any unwarranted assumptions about the Servlet API’s behaviour. (This is also the default handling of all API ambiguities in the Professional and Enterprise editions of ObMimic, but as described below these also allow you to select other options for how to handle individual API ambiguities or sets of API ambiguities).

Explicit control over Servlet API object lifecycles

ObMimic allows you to explicitly manage the lifecycle of a mimic where this is relevant to the Servlet API’s behaviour but is not directly controllable through its Servlet API methods (for example, for “initializing” and “destroying” a ServletContext, including appropriate invocations of any relevant listeners).

Explicit control over the throwing of Servlet API exceptions

Where Servlet API methods can potentially throw various exceptions, ObMimic supports explicit control over the throwing of those exceptions. This allows you to test code for handling such exceptions even where the exception cannot normally be made to occur on demand (for example, you can force a write to a ServletOutputStream mimic to fail with an example IOException; or force a call to a RequestDispatcher mimic’s “forward” method to fail with an example ServletException).

Interoperability with other test‑doubles

Where a mimic references a related Servlet API object (for example, the ServletContext for its application), the related object will normally be another ObMimic mimic. However, the use of any other implementation of the related Servlet API object is also permitted. Where necessary you can thus combine the use of ObMimic mimics with the use of other stubs, mocks and test‑doubles (for example, to introduce the use of one or more mimics into an existing test that is already using some other type of stub or mock).

Although some ObMimic features and some specific aspects of the Servlet API’s behaviour do intrinsically require internal cooperation between the objects involved (and therefore cannot be supported when combining an ObMimic mimic with some other implementation), where this is the case ObMimic degrades gracefully in the presence of non‑mimic objects, and its Javadoc explicitly documents how this affects each mimic’s behaviour.

Explicit support for POSTs from HTML forms, including file-uploads

ObMimic's ServletRequest mimic includes specific support to assist in populating the request with appropriate content for the submission of data from an HTML form, including:

  • Population of the request with “application/x-www-form-urlencoded” content to simulate a normal POST from an HTML form (including the merger of the submitted form data with any request parameters supplied by the request’s URL).
  • Population of the request with “multipart/form-data” content to simulate a POST that is uploading one or more files to the server (and more generally for populating the request with other such multi-part MIME content).

In-memory JNDI simulation

ObMimic includes an in‑memory JNDI simulation that you can populate programmatically to support any explicit or implied JNDI look‑ups from the code you are testing (in particular, for the application’s “Environment Naming Context” and any other “java:”‑prefixed JNDI contexts).

Additional features for testing of Servlet API code

ObMimic includes a number of additional classes and facilities that may be of use when testing Servlet API code, such as:

  • A wide variety of general utility classes and methods that are used internally within ObMimic but may also be of wider use (for example, for interpreting URL‑encoded request parameters and other strings).
  • A “StaticResourceServlet” that simply writes to its response some fixed content as supplied to it on construction.
  • A number of other ready‑made example servlets, servlet filters and Servlet API listeners. In general these simply track and report how many times they are invoked, and can optionally also delegate each call onwards to some other instance — but this is often adequate if you simply need an arbitrary object to act as the target for a “forward” or “include”, or are only interested in how many times a test causes a particular servlet, filter or listener to be invoked.

Configuration facilities

ObMimic supports a variety of configuration options, with all of these being identified by string names and specified using string values and with appropriate initial/default values. These configuration options can be set via any or all of the following mechanisms (in order of increasing precedence):

  • A Java properties file: By default the /config/config.properties file within the ObMimic installation is used (although the file to be used can itself be specified via a configuration setting if necessary). Note that the /config/config.properties file supplied with ObMimic includes full documentation of all configuration options and their names and permitted values, and sets all options to their default values.
  • System properties: In particular, configuration options can be specified as “‑D” command‑line arguments when running your tests.
  • Programmatically: Your test‑case code can programmatically set individual configuration options, and can also clear/reset all such programmatically‑set configuration options and determine the current value of any configuration option.

In addition, ObMimic provides enumerations and other named constants for the various configuration option values, and where the names of configuration options are composed from various elements (for example, to specify a particular set of “API ambiguities”), ObMimic provides methods, enumerations and named constants for type‑safe and correct construction of such names from their constituent elements.

Note, however, that for many of ObMimic’s configuration options the Community Edition only permits the use of the default value, with support for other values being limited to the additional facilities provided by the Professional and Enterprise editions of ObMimic, as described below.

Servlet API versions: 2.5

All editions of ObMimic support the simulation of version 2.5 of the Servlet API. (Note that, as described below, the Professional and Enterprise editions of ObMimic can also simulate other versions of the Servlet API).

Single jar archive with minimal dependencies

ObMimic’s classes are all supplied in a single jar with no dependencies on any third-party libraries (other than needing any run-time compatible Java EE or Servlet API library for Servlet 2.4 or higher and any JRE for Java SE 6.0 or higher), making it easy to add ObMimic to your projects.

Detailed Javadoc

ObMimic provides extensive, detailed Javadoc that includes details of:

  • Precisely how each Servlet API method’s Javadoc has been interpreted.
  • Precisely how each Servlet API method’s implementation interacts with its mimic’s “mimicState” and any other relevant ObMimic configuration or state.
  • Any “API ambiguities” in the Servlet API’s Javadoc and how each of these are handled (including the options available for handling each API ambiguity when using the Professional or Enterprise edition, as described below).
  • Any restrictions on the argument values that can be passed to each ObMimic method and any other restrictions on calls to the method, and the exceptions that result from any violation of such restrictions.

Additional documentation

In addition to its extensive Javadoc, ObMimic’s documentation also includes:

  • A README document that includes installation instructions, details of ObMimic’s system requirements, and details of an ObMimic installation’s directories and files.
  • A “Getting Started” guide (in both a short version and a longer, more extensive version that includes additional details and explanations).
  • A set of How‑To guides, including code examples where appropriate.
  • A summary of the properties and methods of each mimic class’s MimicState, to provide an overview of these MimicStates and aid you in finding the relevant properties and methods for configuring and examining mimic instances as necessary for your tests.

Detailed error messages

Any invalid calls to ObMimic methods and any other failures that occur within ObMimic code produce exceptions with suitably detailed and explanatory error messages, to help you identify exactly why the call has failed.

Discussion Forums

Discussion forums are provided for reporting possible bugs, requesting additional features, and for general help and support in using ObMimic. In particular, ObMimic’s developers participate directly in these forums, and these forums are recommended as the most effective means of obtaining support for ObMimic.

2  Additional Professional Edition Features

When used with a “Professional Edition” licence, ObMimic provides all of the above “Community Edition” features plus the following additional features:

Feature

Notes

Control over Servlet API version

The version of the Servlet API that is simulated by ObMimic can be explicitly configured, with all mimics then behaving as appropriate for that version of the Servlet API (and with the ObMimic Javadoc fully specifying any differences in behaviour between Servlet API versions).

This can be configured via any of ObMimic’s normal configuration mechanisms as described above. In particular:

  • It can be controlled programmatically within your tests (for example, to test the behaviour of some code on different versions of the Servlet API).
  • It can also be configured globally for the ObMimic installation as a whole (for example, if you are only concerned with one particular version of the Servlet API).
  • It can also be set via command-line arguments for the whole of a test run (for example, to run an entire set of tests against a specified version of the Servlet API).

Servlet API versions: 2.3, 2.4, 2.5 (with 3.0 and 3.1 to follow)

This release of ObMimic can be configured to simulate versions 2.3, 2.4 and 2.5 of the Servlet API.

Support for versions 3.0 and 3.1 of the Servlet API is currently being developed and will be introduced progressively into future releases of ObMimic.

Configurable API ambiguity handling

By default, any API ambiguity that is detected is reported by throwing an unchecked “ApiAmbiguityException”, as described above. However, the Professional edition of ObMimic also supports other options for how each API ambiguity should be handled. The options provided for each API ambiguity depend on the precise nature of that particular API ambiguity, but typically include throwing various types of unchecked exceptions; ignoring the method call that encountered the ambiguity; or ignoring the ambiguity and proceeding with a “best guess” of the appropriate processing.

Configuration settings are supported for specifying the option to be used for an individual API ambiguity or for a range of API ambiguities (for example, all ambiguities of a particular type, all ambiguities within a particular Servlet API class, all ambiguities within a particular Servlet API method etc). These can be set using any of ObMimic’s normal configuration mechanisms as described above.

ObMimic’s Javadoc for each Servlet API method’s implementation specifies precisely what API ambiguities the method can give rise to (including any details necessary to identify each ambiguity when configuring it); the precise circumstances under which each ambiguity occurs; the options that are available for handling each ambiguity; and the precise effects of each such option.

History of Servlet API method calls

Each mimic includes a “MimicHistory” object that can optionally record the details of Servlet API method calls processed by the mimic, and through which these details can be retrieved for examination. For each individual mimic, the recording of API calls can be turned on and off and can be cleared/reset programmatically, so that you can selectively record and inspect the API calls to particular mimics during particular tests.

The details recorded for each API call include the the method called; immutable representations of the call’s arguments; whether the call completed successfully or failed with an exception; an immutable representation of the call’s return value or its resulting exception; and timestamps for the call and its completion. A unique (per JVM) sequence number is also included so that the overall sequence of calls to multiple mimics can be determined (for example, to check whether a call to a listener occurred before or after some other API call, or to merge calls to multiple mimics into a single sequence for inspection).

Listeners for Servlet API method calls

Each mimic includes a “MimicListeners” object into which listeners can optionally be installed to be notified of each Servlet API method call to the mimic and the result of each such call. This allows such listeners to intercept and examine the details of each call and its outcome. These listeners can also optionally modify the arguments being passed to the Servlet API method and the result of the call.

As well as providing a dynamic alternative to using the “MimicHistory” facilities to examine the Servlet API calls issued during a test, this also provides a way to work‑around any incorrect or questionable use of the Servlet API by any third‑party framework or library code used within your code — or to completely replace ObMimic’s built‑in behaviour for a particular Servlet API call if this ever proves necessary.

Configurable handling of absent and deprecated Servlet API elements

Depending on which version of the Servlet API is being simulated and the Servlet API class library being used, calls may be physically possible to Servlet API classes and methods that are deprecated or entirely removed in the Servlet API version that is currently being simulated, or that post‑date it (that is, are not present in that version of the Servlet API due to only being introduced in later versions).

Whilst the Community Edition of ObMimic is limited to the default behaviour of always processing calls to deprecated API elements but throwing an unchecked exception to report any calls to methods that do not exist in the relevant Servlet API version, the Professional edition of ObMimic provides configuration options through which you can control which such calls are processed as normal and which fail with a suitable unchecked exception.

Perpetual licence

Licence‑key files for ObMimic are valid in perpetuity for the version of ObMimic for which they were obtained. In addition, each licence‑key file also covers:

  • All earlier versions of ObMimic.
  • All “minor” updates and patches/fixes for the “major” version covered by the licence‑key file (that is, all versions of ObMimic for which the first element of the version number is the same as that specified by the licence‑key file).
  • Any and all individual versions of ObMimic that are released within a year of the licence‑key file’s “start” date (even where these are for a higher “major” version).

Discounts on future versions

Upgrades/replacements for licence‑key files for future versions of ObMimic will be offered at a discount of 50% of their full price (for example, when purchasing a licence‑key file for a version 2.x.x of ObMimic to replace an existing licence‑key file for a version 1.x.x).

3  Additional Enterprise Edition Features

The “Enterprise Edition” of ObMimic includes a built-in copy of the “Professional Edition” and also provides the following additional features:

Feature

Notes

Licence for 100 users

Each Enterprise Edition purchase provides a licence‑key file for up to 100 users to make use of the Professional and Enterprise Edition features (and for larger numbers of users, you can purchase additional copies or licence‑key files as necessary — or contact us for volume discounts).

Full source code

The Enterprise Edition of ObMimic includes a copy of all of ObMimic’s source code for your own internal use. This allows you to customize or extend ObMimic for your own needs, reduces any potential dependency on OpenBrace, and may also be helpful during debugging whilst running your tests.

Ant build script

The Enterprise Edition of ObMimic includes a ready‑to‑run Ant script for building the Professional Edition of ObMimic (or your own customized variant of it) from the supplied source code. A properties file is used to control many aspects of the build, and both the Ant script and the properties file include documentation that explains the build and its configuration.

Note that even if you want to use other build tools or write your own build scripts, the supplied Ant script and its accompanying properties file and documentation gives you a relatively simple starting point for this (for example, by showing where all the necessary files are, any particular compile options that are required etc).

Comprehensive JUnit tests

Comprehensive JUnit tests are included that provide extensive, detailed and precise testing of all of ObMimic’s code.

Priority support

OpenBrace will prioritize support for Enterprise Edition customers (and in addition a separate discussion forum is provided for issues relating to the Enterprise Edition).

4  What’s Missing?

An outline of the additional features that we are currently hoping to introduce in future versions of ObMimic can be found on the Future Plans page.

If there are any particular features that you need and would like us to consider for future versions of ObMimic, please let us know via the ObMimic Feature Requests discussion forum.