org.apache.aries.unittest.mocks
Class Skeleton

java.lang.Object
  org.apache.aries.unittest.mocks.Skeleton

All Implemented Interfaces:

InvocationHandler

public final class Skeleton
extends Object
implements InvocationHandler

The Skeleton class is an implementation of the java.lang.reflect.InvocationHandler that can be used for dynamic mock objects.

1. The static newMock methods can be used to create completely new mock objects backed by an entirely new skeleton.
2. The static getSkeleton method can be used to obtain the skeleton backing a given mock.
3. The createMock methods can be used to create a new mock object based on the skeleton that is invoked.
4. The registerMethodCallHandler method can be used to register a handler that will be invoked when a method is called.
5. The registerReturnTypeHandler method can be used to register a handler that will be invoked when a method with a specific return type is invoked. It should be noted that registered ReturnTypeHandlers will be invoked only if a method call handler has not been registered for the method that was invoked.
6. The setReturnValue method can be used to set a value that will be returned when a method is invoked.
7. The checkCalls methods can be used to determine if the methods in the list should have been called. They return a boolean to indicate if the expected calls occurred.
8. The assertCalls method performs the same operation as the checkCalls, but throws an junit.framework.AssertionFailedError if the calls don't match. This intended for use within the junit test framework
9. If no method call or return type handlers have been registered for a call then if the return type is an interface then a mock that implements that interface will be returned, otherwise null will be returned.

Method Summary

void	assertCalled(List<MethodCall> calls, boolean allCalls) This method checks that the MethodCalls objects in the given list were made and throws an AssertionFailedError if they were not.
void	assertCalled(MethodCall call) This does the same as checkCall, but throws an junit.framework.AssertionFailedError if the call did not occur.
void	assertCalledExactNumberOfTimes(MethodCall call, int numberOfCalls) This method asserts that the method specified in the call parameter has been called the number of times specified by numberOfCalls.
void	assertNotCalled(MethodCall call) This method throws an junit.framework.AssertionFailedError if the specified call was invoked on the skeleton.
void	assertSkeletonNotCalled() This method throws an junit.framework.AssertionFailedError if the skeleton has had any methods invoked on it.
boolean	checkCall(MethodCall call) Checks that the specified method has been called on this skeleton
boolean	checkCalls(List<MethodCall> calls, boolean allCalls) This method checks that the calls in the list occurred.
void	clearMethodCalls() This method clears the method calls list for the skeleton
Object	createMock(Class<?>... interfaceClasses) Creates a new Mock using this skeleton backing it.
<T> T	createMock(Class<T> interfaceClass) Creates a new Mock using this skeleton backing it.
void	deRegisterMethodCallHandler(MethodCall call) This method removes a registered MethodCallHandler for the specified MethodCall.
void	deRegisterReturnTypeHandler(Class<?> clazz) This method removes a registration for a ReturnTypeHandler for the specified class.
Object	getParameter(String key) This method allows a parameter to be retrieved.
static Skeleton	getSkeleton(Object mock) This method returns the Skeleton backing the supplied mock object.
Object	getTemplateObject()
Object	invoke(Object targetObject, Method calledMethod, Object[] arguments) This method is invoked by the mock objects.
Object	invokeReturnTypeHandlers(Class<?> type) This method invokes the return type proxy for the specified class.
static boolean	isSkeleton(Object mock) This method returns true if and only the provided object is backed by a Skeleton.
static Object	newMock(Class<?>... interfaceClazzes) This method returns a completely new mock object backed by a new skeleton object.
static <T> T	newMock(Class<T> interfaceClazz) This method returns a completely new mock object backed by a new skeleton object.
static <T> T	newMock(Object template, Class<T> interfaceClazz) It is often the case that only a subset of methods on an interface are needed, but those methods that are needed are quite complex.
void	registerExceptionListener(Class<?> throwableType, ExceptionListener listener) This method registers an ExceptionListener when the specified Exception is thrown.
void	registerMethodCallHandler(MethodCall call, MethodCallHandler handler) This method registers a MethodCallHandler for the specified MethodCall.
void	registerReturnTypeHandler(Class<?> clazz, ReturnTypeHandler handler) This method registers a ReturnTypeHandler for the specified class.
void	reset() This method resets the skeleton to the state it was in prior just after it was constructed.
void	setDefaultHandler(DefaultInvocationHandler defaultHandler)
void	setParameter(String key, Object value) This method allows a parameter to be set.
void	setReturnValue(MethodCall call, Object value) This is a convenience method for registering a method call handler where a specific value should be returned when a method is called, rather than some logic needs to be applied.
void	setThrows(MethodCall call, Error thingToThrow) This is a convenience method for registering a method call handler where a specific exception should be thrown when the method is called, rather than some logic needs to be applied.
void	setThrows(MethodCall call, Exception thingToThrow) This is a convenience method for registering a method call handler where a specific exception should be thrown when the method is called, rather than some logic needs to be applied.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newMock

public static final Object newMock(Class<?>... interfaceClazzes)

This method returns a completely new mock object backed by a new skeleton object. It is equivalent to new Skeleton().createMock(interfaceClazzes)

Parameters:

interfaceClazzes - the classes the mock should implement

Returns:

the new mock object.

newMock

public static final <T> T newMock(Class<T> interfaceClazz)

This method returns a completely new mock object backed by a new skeleton object. It is equivalent to new Skeleton().createMock(interfaceClazzes)

Type Parameters:

T - The object type.

Parameters:

interfaceClazz - the classes the mock should implement

Returns:

the new mock object.

newMock

public static final <T> T newMock(Object template,
                                  Class<T> interfaceClazz)

It is often the case that only a subset of methods on an interface are needed, but those methods that are needed are quite complex. In this case a static mock forces you into implementing lots of methods you do not need, and produces problems when new methods are added to the interface being implemented. This method can essentially be used to complete the interface implementation. The object passed in is an instance of a class that implements a subset of the methods on the supplied interface. It does not need to implement the interface itself. The returned object will implement the full interface and delegate to the methods on the templateObject where necessary.

Type Parameters:

T - The object type.

Parameters:

template - The template object for the mock

interfaceClazz - The interface to implement

Returns:

An implementation of the interface that delegates (where appropraite) onto the template.

getSkeleton

public static final Skeleton getSkeleton(Object mock)
                                  throws IllegalArgumentException

This method returns the Skeleton backing the supplied mock object. If the supplied object is not a mock an IllegalArgumentException will be thrown.

Parameters:

mock - the mock object

Returns:

the skeleton backing the mock object

Throws:

IllegalArgumentException - thrown if the object is not a mock.

isSkeleton

public static final boolean isSkeleton(Object mock)

This method returns true if and only the provided object is backed by a Skeleton. Another way to think about this is if it returns true then a call to getSkeleton will not result in an IllegalArgumentException, and is guaranteed to return a Skeleton.

Parameters:

mock - the mock to test.

Returns:

true if it is backed by a skeleton.

invoke

public Object invoke(Object targetObject,
                     Method calledMethod,
                     Object[] arguments)
              throws Throwable

This method is invoked by the mock objects. It constructs a MethodCall object representing the call and adds it to the list of calls that were made. (It should be noted that if the method is toString, hashCode or equals then they are not added to the list.) It then calls a registered MethodCallHandler, if a MethodCallHandler is not registered then a ReturnTypeHandler is invoked. If a ReturnTypeHandler is not invoked then the registered default InvocationHandler is called. By default the Skeleton is constructed with a DefaultInvocationHandler. If the invoked method has an interface as a return type then the DefaultInvocationHandler will return a new mock implementing that interface. If the return type is a class null will be returned.

Specified by:

invoke in interface InvocationHandler

Parameters:

targetObject - The mock object that was invoked.

calledMethod - The method that was called.

arguments - The arguments that were passed.

Returns:

The return of the method invoked.

Throws:

Throwable - Any exception thrown.

registerMethodCallHandler

public void registerMethodCallHandler(MethodCall call,
                                      MethodCallHandler handler)

This method registers a MethodCallHandler for the specified MethodCall.

Parameters:

call - The method that was called.

handler - The MethodCallHandler.

deRegisterMethodCallHandler

public void deRegisterMethodCallHandler(MethodCall call)

This method removes a registered MethodCallHandler for the specified MethodCall.

Parameters:

call - the specified MethodCall

reset

public void reset()

This method resets the skeleton to the state it was in prior just after it was constructed.

clearMethodCalls

public void clearMethodCalls()

This method clears the method calls list for the skeleton

setReturnValue

public void setReturnValue(MethodCall call,
                           Object value)

This is a convenience method for registering a method call handler where a specific value should be returned when a method is called, rather than some logic needs to be applied. The value should be an object or the object version of the primitive for the methods return type, so if the method returns short the value must be an instance of java.lang.Short, not java.lang.Integer.

Parameters:

call - the method being called.

value - the value to be returned when that method is called.

setThrows

public void setThrows(MethodCall call,
                      Exception thingToThrow)

This is a convenience method for registering a method call handler where a specific exception should be thrown when the method is called, rather than some logic needs to be applied.

Parameters:

call - the method being called

thingToThrow - the exception to throw.

setThrows

public void setThrows(MethodCall call,
                      Error thingToThrow)

This is a convenience method for registering a method call handler where a specific exception should be thrown when the method is called, rather than some logic needs to be applied.

Parameters:

call - the method being called

thingToThrow - the exception to throw.

registerReturnTypeHandler

public void registerReturnTypeHandler(Class<?> clazz,
                                      ReturnTypeHandler handler)

This method registers a ReturnTypeHandler for the specified class.

Parameters:

clazz - The class to be handled.

handler - The ReturnTypeHandler

deRegisterReturnTypeHandler

public void deRegisterReturnTypeHandler(Class<?> clazz)

This method removes a registration for a ReturnTypeHandler for the specified class.

Parameters:

clazz - The class to deregister the handler for.

registerExceptionListener

public void registerExceptionListener(Class<?> throwableType,
                                      ExceptionListener listener)

This method registers an ExceptionListener when the specified Exception is thrown.

Parameters:

throwableType - The type of the Throwable

listener - The listener.

setParameter

public void setParameter(String key,
                         Object value)

This method allows a parameter to be set. It is intended to be used by MethodCallHandlers and ReturnTypeHandlers.

Parameters:

key - The key

value - The value

getParameter

public Object getParameter(String key)

This method allows a parameter to be retrieved.

Parameters:

key - the key the parameter was set using

Returns:

the parameter

getTemplateObject

public Object getTemplateObject()

Returns:

the template object, if one was used when initializing this skeleton.

setDefaultHandler

public void setDefaultHandler(DefaultInvocationHandler defaultHandler)

Parameters:

defaultHandler - The defaultHandler to set.

checkCalls

public boolean checkCalls(List<MethodCall> calls,
                          boolean allCalls)

This method checks that the calls in the list occurred. If the addCalls boolean is true then their must be an exact match. If the allCalls boolean is false then the calls in the list must occur in that order, but other calls can be in between.

Parameters:

calls - The expected calls list

allCalls - true if an exact match comparison should be performed

Returns:

true if they the expected calls match.

checkCall

public boolean checkCall(MethodCall call)

Checks that the specified method has been called on this skeleton

Parameters:

call - the call that should have been called.

Returns:

true if the MethodCall occurs in the list.

assertCalled

public void assertCalled(List<MethodCall> calls,
                         boolean allCalls)
                  throws junit.framework.AssertionFailedError

This method checks that the MethodCalls objects in the given list were made and throws an AssertionFailedError if they were not. If allCalls is true the given list and the calls list must be identical. If allCalls is false other calls could have been made on the skeleton in between ones specified in the list.

Parameters:

calls - the list of calls

allCalls - whether an exact match between the lists is required

Throws:

junit.framework.AssertionFailedError - if a failure has occurred.

assertCalled

public void assertCalled(MethodCall call)

This does the same as checkCall, but throws an junit.framework.AssertionFailedError if the call did not occur.

Parameters:

call - the call that was expected

assertCalledExactNumberOfTimes

public void assertCalledExactNumberOfTimes(MethodCall call,
                                           int numberOfCalls)

This method asserts that the method specified in the call parameter has been called the number of times specified by numberOfCalls. If numberOfCalls is zero this method is equivalent to assertNotCalled.

Parameters:

call - The call that was made.

numberOfCalls - The number of times the call should have been made.

assertNotCalled

public void assertNotCalled(MethodCall call)

This method throws an junit.framework.AssertionFailedError if the specified call was invoked on the skeleton.

Parameters:

call - the call to check.

assertSkeletonNotCalled

public void assertSkeletonNotCalled()

This method throws an junit.framework.AssertionFailedError if the skeleton has had any methods invoked on it.

createMock

public Object createMock(Class<?>... interfaceClasses)

Creates a new Mock using this skeleton backing it.

Parameters:

interfaceClasses - an array of interface the mock should implement.

Returns:

the mock

createMock

public <T> T createMock(Class<T> interfaceClass)

Creates a new Mock using this skeleton backing it.

Type Parameters:

T - The object type

Parameters:

interfaceClass - an array of interface the mock should implement.

Returns:

the mock

invokeReturnTypeHandlers

public Object invokeReturnTypeHandlers(Class<?> type)
                                throws Exception

This method invokes the return type proxy for the specified class. If a ReturnTypeHandler for that type has not been registered then if the class represents an interface a new mock will be returned, backed by this skeleton, otherwise null will be returned.

Parameters:

type - the type to be invoked.

Returns:

the returned object.

Throws:

Exception - if an error occurs when invoking the return type handler.