Summary

  • Major new feature: Professional/Enterprise Editions now support a set of listeners on each Mimic instance (accessed via a new getMimicListeners method on each Mimic) that are notified of all calls to mimicked Servlet API methods and their results. These can be used to examine the details and results of such calls as each call occurs, and can optionally also modify the call’s arguments and results. Note that this is in addition to the existing “history” facilities, which in contrast capture an overall history of the calls using immutable representations of each call’s details for subsequent examination.
  • “How To” guide and pom.xml file added to aid in the use of ObMimic within Maven-based projects.
  • “How To” guide added for out-of-container testing of JSF pages.
  • ObMimic now checks for and explicitly reports any attempt to use a Java EE API jar that is unsuitable for use with ObMimic due to being deliberately restricted to compile-time use only, and documentation has been updated to explain this.
  • Minor adjustments to some test cases as a result of testing on IBM Java SE 6 and IBM Java SE 7 on Linux (and in particular to cater for a presumed bug in IBM Java SE 6 on Linux), and similarly minor adjustments to the Enterprise Edition’s build script as a result of testing this against IBM Java SE 7 on Linux.
  • Initial testing on Oracle JDK 8 (build b99), and general fixes to Javadoc problems found by the stricter checking of Javadoc HTML on this JDK (plus one minor fix/work-around for a source-code problem encountered on this particular JDK 8 build, and one source-code work-around for a Javadoc bug in this particular JDK 8 build).
  • The ServletContextMimic getResource and getResourceAsStream implementations have been revised to explicitly cater for the ambiguities and container-dependent behavior of these methods when given paths that end with “/” or that otherwise correspond to a “directory” rather than an individual resource. The getResourceAsStream method’s validation, ambiguity handling and exception throwing have also made consistent with those of the getResource method.
  • The RequestParameters class now supports a set of listeners that are notified of any changes to its request parameters.
  • Other minor improvements and corrections to documentation.

Listeners for Mimicked API Method Calls and Results

  • com.openbrace.obcommon.lang: New classes MethodInvocationDetails, MethodResultDetails, MethodInvokedEvent, MethodExitedEvent, MethodInvocationListener, MethodExitListener, MethodInvocationListenerAdapter and MethodExitListenerAdapter added to support the capture, and optionally modification, of method invocation details and results, and to provide corresponding event and listener classes for method invocation and exit.
  • com.openbrace.obmimic.core: New class MimicListeners added to provide each Mimic instance with a separate sub-component into which listeners for API method invocations and results can be installed, and through which these listeners can be notified of relevant events.
  • com.openbrace.obmimic.core: New getMimicListeners method added to the Mimic interface to provide access to the mimic’s MimicListeners (but with use of this restricted to “Professional” and “Enterprise” editions only), and correspondingly implemented in the AbstractMimicForInterface class that acts as the base class for most Mimic classes.
  • com.openbrace.obmimic.mimic.servlet and com.openbrace.obmimic.mimic.servlet.http: Implementation of the Mimic interface’s new getMimicListeners method added to all Mimic classes that are not based on the AbstractMimicForInterface class (namely GenericServletMimic, ServletInputStreamMimic, ServletOutputStreamMimic and HttpServletMimic).
  • com.openbrace.obmimic.core.MimicImpl: Updated to maintain a MimicListeners object for each instance (with this being supplied on construction) and to implement the Mimic interface’s new getMimicListeners method to return this MimicListeners object.
  • com.openbrace.obmimic.core.MimicInvocationHandler: Updated to support the changes to the Mimic interface and its MimicImpl implementation by maintaining a MimicListeners object for each Mimic and supplying this to the Mimic’s MimicImpl.
  • com.openbrace.obmimic.core.MimicInvocationHandler: Enhanced so that, for “Professional” and “Enterprise” editions, each call to a mimicked API method issues the appropriate notifications to any listeners currently installed into the Mimic’s MimicListeners prior to the call and on return from the call. Such listeners can then examine and optionally modify the call’s method arguments and result. Note that these listener notifications precede any corresponding recording of the call details into the mimic’s “history”, so that the history reflects any modifications made by such listeners to the call’s method arguments and results).
  • com.openbrace.obmimic.config.ProFeature: New enumeration value MIMIC_LISTENERS added for the ability to access and use each Mimic’s MimicListeners.
  • Following the introduction of the new com.openbrace.obcommon.util.AbstractListeners class, the unrelated com.openbrace.obmimic.substate.servlet package’s AbstractListeners class has been renamed to AbstractMimicStateListeners to avoid having two such classes with the same simple class name.
  • ObMimic documentation updated to reflect the new support for these listeners: README.html, GettingStartedShort.html and GettingStartedDetailed.html updated to mention these listeners; DesignPrinciples.html updated to explain these listeners and contrast them with the “history” facilities; FAQ entry “What Facilities are Provided by ObMimic’s mimics?” updated to cover these listeners; Title of the History.html “How To” revised and references to this in the “How To” index and in the JSP.html “How To” guide revised to use its new title; “How To” guides JSP.html, ExamineMimicState.html and ConfigureMimicState.html revised to mention the listeners alongside any existing mention of “history” facilities where relevant; Support for these listeners mentioned within the History.html “How To” guide; and new “How To” guide Listeners.html added to explain how to use the new MimicListeners feature.

Handling of Unsuitable Java EE API Jars

  • com.openbrace.obmimic.api.ServletApiVersionEnum: Method checkServletJarAcceptable added to detect when the Servlet API is being supplied via an unsuitable “compile-time only” jar that cannot be used at run-time, (such as the “official” javaee-api-*.jar and javaee-web-api-*.jar libraries from the java.net website, or the copies of these in various Maven™ repositories), with this throwing an UnacceptableApiJarException if such a jar is being used so as to clearly and explicitly report this.
  • com.openbrace.obmimic.api.UnacceptableApiJarException: Added for use when the Servlet API is being supplied via an unsuitable “compile-time only” jar, as above.
  • com.openbrace.obmimic.mimic.servlet.AbstractMimicForServletInterface: Added as a subclass of com.openbrace.obmimic.core.AbstractMimicForInterface for use in all Mimics that are for the Servlet API. This adds a call to the new checkServletJarAcceptable method at the start of the Mimic’s construction so as to immediately report if the Servlet API jar being used is unsuitable. All Mimics for the Servlet API now either subclass this new AbstractMimicForServletInterface (instead of the original and still underlying AbstractMimicForInterface) or (for the few Mimics that are outside of this inheritance hierarchy) provide a similar check in their own constructor. All Mimics for Servlet API classes will thus throw an UnacceptableApiJarException during construction if an unsuitable Servlet API jar is being used (prior to any use of the Servlet API that might result in a more cryptic exception from within the Servlet API code).
  • com.openbrace.obmimic.state.servlet.AbstractServletMimicState: Similarly to AbstractMimicForServletInterface, this has been added as a subclass of com.openbrace.obmimic.core.AbstractMimicState for use in all MimicStates that are for the Servlet API. This adds a call to the new checkServletJarAcceptable method at the start of the MimicState’s construction. All MimicStates for the Servlet API now subclass this new AbstractServletMimicState (instead of the original and still underlying AbstractMimicState).
  • FAQ.html: Entries added for “Why do I get an UnacceptableApiJarException” and “Why do I get an ExceptionInInitializerError?”, to explain why ObMimic checks for unsuitable Java EE API jars, the possible exceptions that can result, and how to resolve such problems.
  • README.html, GettingStartedShort.html, GettingStartedDetailed.html: Details of which Servlet API libraries can be used have been updated to reflect the unsuitability of some Java EE API jars due to being deliberately restricted to compile-time use only, with explanations and links to the relevant FAQ entry where appropriate.

Support for Maven-based Projects

  • obmimic.jar: Added META-INF/maven/com.openbrace/obmimic/pom.xml within this jar archive to provide a Maven POM that can be used by the Maven “install” plug-in from version 2.5 onwards to install the obmimic.jar library into a local Maven repository.
  • /etc/obmimic.pom.xml: Added to provide a copy of the obmimic.jar’s built-in pom.xml (as above) for use with Maven “install” plug-in versions prior to 2.5 (which are unable to automatically obtain this from within the obmimic.jar).
  • AddToMavenProject.html: Added this new “How To” guide to explain how ObMimic can be installed into a local Maven repository and used within Maven-based projects.
  • README.html, GettingStartedShort.html, GettingStartedDetailed.html: Updated to reflect the above changes (i.e. the presence of the /etc/obmimic.pom.xml file and the pom.xml file within obmimic.jar, their use in installing obmimic.jar into a local Maven repository, and references to the corresponding “How To” guide).

Directory Paths in getResource and getResourceAsStream

  • com.openbrace.obmimic.mimic.servlet.ServletContextMimic: Javadoc and implementations for the getResource and getResourceAsStream methods have been revised to more explicitly cater for the ambiguities and container-dependent behaviour of these methods for paths that end with “/” or that otherwise correspond to a “directory” rather than an individual resource. Specifically, the previous InvalidCompleteRelativePathAmbiguity has been replaced by an InvalidRelativePathAmbiguity that no longer covers paths that end with “/”; Such paths are now instead covered by a separate InvalidCompleteRelativePathAmbiguity; and after dealing with any such ambiguities, any paths that either end with “/” or correspond to a “directory” within the resources are now handled as specified by newly-introduced properties of the ServletContext’s mimicState.container.behaviour — with options to either indicate that the resource is “not found” by returning null or to reject the path as invalid by throwing an exception. In addition, for getResourceAsStream the previous validation and ambiguity handling has been replaced by validation and ambiguity handling that matches that of getResource, except that any resulting MalformedURLException is wrapped in an IllegalArgumentException to permit getResourceAsStream to throw it.
  • com.openbrace.obmimic.support.servlet.PartialResourcePathBehaviourEnum: This new enumeration has been added to specify the supported options for how the ServletContext getResource and getResourceAsStream methods should treat “directory” paths.
  • com.openbrace.obmimic.substate.servlet.ServletContainerBehaviour: Properties servletContextGetResourcePartialPathBehaviour and servletContextGetResourceAsStreamPartialPathBehaviour to control how the ServletContext getResource and getResourceAsStream methods should treat “directory” paths.
  • com.openbrace.obmimic.substate.servlet.WebAppResources: Method isDirectory has been added to indicate whether a given relative path corresponds to a “partial” path (effectively, a “directory”) that exists within the web-application’s resources.

Listener support added to RequestParameters

  • com.openbrace.obmimic.substate.servlet.RequestParameters: Support added for maintaining a set of listeners and notifying them of any changes to the request parameters.
  • com.openbrace.obmimic.support.servlet.RequestParametersListener, RequestParametersListenerAdapter, RequestParametersChangedEvent: Added to provide the listener and event classes for listening to changes to RequestParameters.

Other Documentation Changes

  • “How To” guide TestingJSFPages.html added to cover out-of-container testing of JSF pages, and a note added to the start of the more general “How To” guide TestingFrameworks.html to explain that more specific guides may be available for particular frameworks.
  • “How To” guide History.html revised to give a more precise explanation of which method calls are and are not subject to recording in a mimic’s MimicHistory (explaining that this covers precisely those API methods that are “mimicked” by ObMimic, but not any methods where the mimic directly inherits a default concrete implementation provided by the underlying API object itself or from the relevant JDK base class, for which the underlying implementation is called directly with no intervention by ObMimic).
  • “How To” guide PopulatePostContent.html page’s initial “please note” paragraph change to be styled as an “alert” block for greater clarity and separation from the rest of the text.
  • “How To” guide JSP.html now explains that the Java EE specification now recommends JSF as the view technology for Java EE, and the need for explicit JSP support is therefore perhaps of declining importance.
  • “How To” guides for testing Servlet API filters and listeners renamed from TestingFilters.html to TestingServletFilters.html and from TestingListeners.html to TestingServletListeners.html, and their titles also changed to explictly state “servlet filters” and “servlet API listeners” respectively, for improved clarity and to distinguish these from any other types of filter and listener.
  • “How To Index” re-organised to separate the guides for Servlet API components and the guides for frameworks, and the JSP.html guide moved from the “Other APIs&rduo; into the “frameworks&rduo; section.
  • FAQ: Added new item “Which JDKs has ObMimic been tested against?” to explicitly list the JDKs that the ObMimic deliverables and the Enterprise Edition’s build script are tested against.
  • FAQ: Added new item “What can I do if I need different Servlet API behaviour?”, in particular to explicitly the use of the new MimicListener facilities as the recommended way to override/supplement ObMimic’s Servlet API behaviour.
  • Support.html: Divided into separate sections with suitable headings, and a section added to cover website issues (in particular to better cater for anyone that reaches the website copy of this page whilst trying to report a problem in the website copy of the ObMimic documentation).
  • README.html: Links for downloading Servlet API 3.1 jars updated to include Tomcat 8, now that downloads of Tomcat 8 are available.
  • MimicStateSummary.html: Updated to include the com.openbrace.obmimic.substate.servlet.ServletContainerBehaviour’s new servletContextGetResourcePartialPathBehaviour and servletContextGetResourceAsStreamPartialPathBehaviour properties.
  • MimicStateSummary.html: Updated to include the com.openbrace.obmimic.substate.servlet.RequestParameters’s new methods for supporting a set of listeners for changes to the request parameters.
  • Various Javadoc syntax problems fixed so that all of the Javadoc now passes the stricter HTML validation of the Oracle JDK 8 Javadoc tool (as of its “early-access” build b99). In particular, all ampersand, “<” and “>” characters within the Javadoc text are now suitably encoded, and various incorrect HTML opening and closing tags have been fixed.
  • Reduced the previously rather widespread use of “and/or” within the ObMimic documentation pages.

Other Changes to Built-In ObCommon Packages

  • Version updated to ObCommon 1.0-beta-10.
  • com.openbrace.obcommon.io.IOUtilities: The getInputStreamContent method now gives a more explicit IllegalArgumentException with a specific error message and the underlying IllegalArgumentException as its cause if the given charset name is invalid or does not exist in the underlying JVM (as the underlying exception tends to differ significantly across JVMs, and in some cases does not give adequate information or any underlying cause).
  • com.openbrace.obcommon.security.SecurityUtilities: The getPrivateKeyFromKeyStore method now throws a KeyStoreException if the requested entry is present and is successfully read but is not of the required PrivateKeyEntry type (with any underlying exception as its cause). Note that on many JVMs it’s not possible for this to occur (with any entry of incorrect type being rejected at some other, earlier stage), but on the few where it is possible this method previously failed with a ClassCastException if this occurred. The new approach makes the resulting exception more consistent with other possible problems and gives it a more meaningful error message.
  • com.openbrace.obcommon.text.TextUtilities: New wrapWithQuotesIfString method added to help with the display within text messages of objects that might or might not be strings.
  • com.openbrace.obcommon.util.AbstractListeners: Added to provide a general base class for sets of event listeners. (Note, however, that although this is used as the base class for ObMimic’s new MimicListeners class, ObMimic’s various other existing sets of event listeners within its MimicStates remain entirely unrelated and independent of this, as they instead need to be subclasses of AbstractMimicState).
  • com.openbrace.obcommon.test.ExampleEventListener: Added to provide an example arbitrary EventListener class for use in tests (and com.openbrace.obmimic.substate.servlet.EventListenerStub removed and replaced by this new class within ObMimic’s test cases).

Enterprise Edition Changes

  • Various test-case classes added and updated to match all of the changes documented above.
  • com.openbrace.obmimic.core.MimicInvocationHandler: Substantial revision to the internal implementation of the callApiMethodImplementation method to support the newly-introduced listeners for method invocation and exit, and integration of this with the implementation’s exception handling and “history” support.
  • com.openbrace.obmimic.mimic.* test classes for Mimic classes: testListenerFunctionality methods added to test classes for all Mimic classes that have any mimicked methods, to provide a basic check that the Mimic’s support for listeners is present and appears to be usable.
  • com.openbrace.obmimic.core.ExampleMethodInvocationListener, ExampleMethodExitListener: Added to assist in testing of code that issues notifications to MethodInvocationListener and MethodExitListener instances.
  • com.openbrace.obmimic.core.ExampleApiInterface, ExampleApiInterfaceMimic, ExampleApiInterfaceBody: Method exampleStringToStringMethod added for use in the testing of notifications to MethodInvocationListener and MethodExitListener listeners (in conjunction with the ExampleMethodInvocationListener and ExampleMethodExitListener classes and their ability to configurably modify a method call’s first argument and returned value where these are strings).
  • com.openbrace.obmimic.examples.howto.TestingJSFPagesTest: Added to include and check/test the example code shown in the Listeners.html “How To&rduo; guide.
  • com.openbrace.obmimic.examples.howto.ListenersTest: Added to include and check/test the example code shown in the TestingJSFPages.html “How To&rduo; guide (but with all actual use of JSF removed/replaced, to avoid any ObMimic dependency on JSF).
  • README.html, build.xml, build.properties: Details of which Servlet API libraries can be used updated to reflect the unsuitability of some Java EE API jars due to being deliberately restricted to compile-time use only.
  • README.html: Links for downloading Servlet API 3.1 jars updated to include Tomcat 8, now that downloads of Tomcat 8 are available.
  • README.html: Updated to reflect the introduction of the /etc/obmimic.pom.xml file and the pom.xml within obmimic.jar.
  • The Enterprise Edition build script is now tested against IBM JDK for Java SE 7 on Linux (as well as the Oracle JDK for Java SE 7 on both MS Windows and Linux as before).
  • build.xml: Updated to incorporate the new /etc/obmimic.pom.xml file into the resulting ObMimic deliverable and as META-INF/maven/com.openbrace/obmimic/pom.xml within its obmimic.jar archive, and new section 4.13 added into the build.xml file’s heading comments to explain these files and their use.
  • build.xml, build.properties and corresponding comments within README.html: The “bootclasspath” is no longer specified for the build script’s javac and javadoc runs, as doing so causes problems for at least some versions of the IBM JDK for Java SE 7 (or at best would require use of a different “bootclasspath” and “classpath” for that JDK). This does result in a compiler warning from each javac run, but this can be safely ignored. A full explanation and alternatives have been added to the comments within the build script.
  • com.openbrace.obmimic.body.servlet.ServletContextBodyPre30: Implementations of getResource and getResourceAsStream methods revised to implement the revised validation, ambiguity handling and behaviour specifed by the updated com.openbrace.obmimic.mimic.servlet.ServletContextMimic Javadoc.
  • com.openbrace.obcommon.logging.ReadableLogHandlerTest: The testReadableLogHandlerFindParameterizedMessage tests are skipped when running on IBM Java SE 6 as there appears to be a bug in this particular JDK/JRE (at least on some versions of this on Linux) whereby its Logger.log method doesn’t seem able to lookup message keys in resource bundles and produce the translated message with parameter substitutions, and instead just writes the message key itself into the log. This works OK on IBM Java SE 5 and IBM Java SE 7, so the problem seems limited to IBM Java SE 6. At present this is understood to be a bug in that particular JDK/JRE, with no known work-around, and with any users of that JDK/JRE simply stuck with that limitation and shortcoming for any log messages that are written. Given this, ignoring the failures of this test that would arise on that particular JDK/JRE is currently considered acceptable and the best that can be done.
  • com.openbrace.obmimic.taglet.ApiAmbigiuityTagletTest: The testRegister method now uses an anonymous inner class to provide an example Taglet class rather than LiteralTaglet, as for some reason at least one of the Oracle JDK 8 “early-access” releases (build b99) seems to not recognise that LiteralTaglet implements Taglet.
  • com.openbrace.obcommon.core.TestUtilities: Revised the source code of the allowTestingOfSpecifiedThrowable method to work-around an apparent bug in the Javadoc of Oracle JDK 8 early-access build b99, which seem to fail to recognise the method’s “@throws X” clause as referring to a generic parameter type and instead tries to look for an actual class named X. The work-around consists of defining a package-private runtime exception class named X and including code into the method that can potentially throw such an X. This allows the Javadoc processing to see the “@throws X” as referring to a valid exception type regardless of whether it correctly treats it as being the generic parameter type X or incorrectly treats it as being an class with a name of X. Within the method, the generic parameter name X hides the class name X, so an “@SuppressWarnings” for this is needed and the reference to class X has to use its fully qualified name. Even with this, the JDK 8 Javadoc tool still seems to give a warning that the method’s “throws X” clause does not have a matching Javadoc tag, but at least this is just a warning rather than an error. Test cases have also been added just to ensure that this dummy X class can actually be constructed and the code within the method that potentially uses it does work, though in practice none of this should ever be used at run-time and class X and the code that uses it exist purely as a source-code work-around for this specific Javadoc bug. It is hoped that this kludge and the class X can be removed in due course, but for the moment it’s the best work-around found so far for this presumed Javadoc bug.
  • com.openbrace.obmimic.substate.servlet.EventListenerStub: Removed from the test cases (replaced by the new but equivalent com.openbrace.obcommon.test.ExampleEventListener class).