org.jwalk.core
Class ClassInspector

java.lang.Object
  extended by org.jwalk.JWalker
      extended by org.jwalk.core.ClassInspector
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
ProtocolWalker

public class ClassInspector
extends JWalker

ClassInspector detects the public method interface of the test class. A ClassInspector inspects a class and extracts all of the constructors and methods in its public interface. These include public methods inherited from all of its ancestors, back to the root Object class. By default, the built-in methods from Object are excluded; but they may be selectively included. The ClassInspector uses Java's reflection to extract lists of Constructor and Method objects.

Version:
1.0
Author:
Anthony Simons

Field Summary
protected  java.util.List<java.lang.Enum<?>> constants
          The list of inspected constants.
protected  java.util.List<java.lang.reflect.Constructor<?>> constructors
          The list of inspected constructors.
protected  java.util.List<java.lang.reflect.Method> methods
          The list of inspected methods.
protected  java.lang.Class<?> testClass
          The test class.
 
Fields inherited from class org.jwalk.JWalker
channels, settings
 
Constructor Summary
ClassInspector(Settings settings, Channels channels)
          Creates a ClassInspector using the settings and channels.
 
Method Summary
 boolean classIsAbstract()
          Reports if the test class is abstract.
 boolean classIsEnum()
          Reports if the test class is an enumerated type.
 boolean classIsInterface()
          Reports if the test class is an interface.
 boolean classNotPublic()
          Reports if the test class is not public.
 int countActiveEdges(int cycle)
          Counts the number of active edges on a given test cycle.
 int countConstants()
          Counts the number of enumerated constants.
 int countConstructors()
          Counts the number of Constructors.
 int countMethods()
          Counts the number of Methods.
 long countPermutations()
          Counts the number of TestSequence permutations.
 void execute()
          Executes this ClassInspector.
 java.util.List<java.lang.Enum<?>> getConstants()
          Returns the enumerated constants of the test class.
 java.util.List<java.lang.reflect.Constructor<?>> getConstructors()
          Returns the public constructors of the test class.
 java.util.List<java.lang.reflect.Method> getMethods()
          Returns the public methods of the test class.
 java.lang.Class<?> getTestClass()
          Returns the test class.
 void inspectProtocols()
          Inspects the public interface of the test class by introspection.
 
Methods inherited from class org.jwalk.JWalker
getChannels, getSettings, outOfMemory, run, userAborted
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

testClass

protected java.lang.Class<?> testClass
The test class. This is cached by each JWalker upon creation, because of the frequent need to refer to this class. It is obtained from the Settings known to this JWalker.


constants

protected java.util.List<java.lang.Enum<?>> constants
The list of inspected constants. This is initially null, and is created upon inspection by this ClassInspector, if the test class happens to be an enumerated type.


constructors

protected java.util.List<java.lang.reflect.Constructor<?>> constructors
The list of inspected constructors. This is initially null, and is created upon inspection by this ClassInspector, if the test class happens to be a standard class with public constructors.


methods

protected java.util.List<java.lang.reflect.Method> methods
The list of inspected methods. This is initially null, and is created upon inspection by this ClassInspector, if the test class has any public methods.

Constructor Detail

ClassInspector

public ClassInspector(Settings settings,
                      Channels channels)
Creates a ClassInspector using the settings and channels. Creates a ClassInspector that will extract method protocols in the manner specified in the settings and report back to the listeners specified in the channels.

Parameters:
settings - the test parameter settings to use.
channels - the callback channels to report on.
Method Detail

getTestClass

public java.lang.Class<?> getTestClass()
Returns the test class. Returns a cached local reference to the test class. Overrides the method in JWalker. In ClassInspector, the test class will have been set, unless the user entered an empty string for its name, in which case the test class is null.

Overrides:
getTestClass in class JWalker
Returns:
the testClass, or null.

classIsInterface

public boolean classIsInterface()
Reports if the test class is an interface. If so, then it is only possible to inspect the class; and it is an error to execute it.


classIsAbstract

public boolean classIsAbstract()
Reports if the test class is abstract. If so, then it is only possible to inspect the class; and it is an error to execute it.


classIsEnum

public boolean classIsEnum()
Reports if the test class is an enumerated type. If so, then it may not be possible to construct and exercise it in the usual way.


classNotPublic

public boolean classNotPublic()
Reports if the test class is not public. If so, then it is only possible to inspect the class; and it is an error to execute it.


getConstants

public java.util.List<java.lang.Enum<?>> getConstants()
Returns the enumerated constants of the test class. Only valid after this ClassInspector has inspected the test class.

Returns:
the list of enumerated constants, or null.

getConstructors

public java.util.List<java.lang.reflect.Constructor<?>> getConstructors()
Returns the public constructors of the test class. Only valid after this ClassInspector has inspected the test class.

Returns:
the list of public constructors, or null.

getMethods

public java.util.List<java.lang.reflect.Method> getMethods()
Returns the public methods of the test class. Only valid after this ClassInspector has inspected the test class.

Returns:
the list of public methods.

countConstants

public int countConstants()
Counts the number of enumerated constants. This will be greater than zero if the test class is an enumerated type. Only valid after this ClassInspector has inspected the test class.

Returns:
the number of enumerated constants.

countConstructors

public int countConstructors()
Counts the number of Constructors. This will be greater than zero if the test class has public constructors. Only valid after this ClassInspector has inspected the test class.

Returns:
the number of Constructors.

countMethods

public int countMethods()
Counts the number of Methods. This will be greater than zero if the test class has public methods. Only valid after this ClassInspector has inspected the test class.

Returns:
the number of Methods.

countPermutations

public long countPermutations()
Counts the number of TestSequence permutations. This is the maximum number of permutations of the test class's constructors and methods. The effectiveness of any test strategy may be judged by how many fewer paths were actually explored than this theoretical maximum. Only valid after this ClassInspector has inspected the test class.

Returns:
the number of TestSequence permutations.

countActiveEdges

public int countActiveEdges(int cycle)
Counts the number of active edges on a given test cycle. This is the maximum number of active edges that could be considered by the test strategy (before pruning is taken into account). The test cycle number is in the range 0..n, where 0 indicates the construction cycle. If the cycle parameter is given a value outside this range, returns 0. Only valid after this ClassInspector has inspected the test class.

Parameters:
cycle - the test cycle number, 0..n.
Returns:
the number of active edges on a given test cycle.

inspectProtocols

public void inspectProtocols()
                      throws PermissionException
Inspects the public interface of the test class by introspection. Extracts lists of Enum, Constructor and Method meta-objects from the test class. If the test class is an enumerated type, builds the list of enumerated constants. If the test class has public constructors, builds a list of these. If the test class has public methods, builds a list of these, including methods inherited from superclasses. The list of methods may, or may not, include the built-in methods of the root Object class, depending on the Convention specified in the Settings.

If the convention is STANDARD, no root methods are included. If the convention is CUSTOM, only the methods equals(), getClass(), hashCode() and toString() are included from Object. If the convention is COMPLETE, all of Object's methods are included. However, if the test class is in fact java.lang.Object, the COMPLETE Convention is automatically selected.

On completing the inspection, this ClassInspector dispatches a ProtocolReport to the listeners registered in the channels.

Throws:
PermissionException - if the test class refused permission to access either its constructors or methods.

execute

public void execute()
             throws PermissionException,
                    GeneratorException,
                    ExecutionException
Executes this ClassInspector. Invokes inspectProtocols() to extract the public Constructor and Method interface of the test class, according to the current settings. Descendants of ClassInspector will also execute the test class dynamically to infer its algebraic structure or high-level state space.

Overrides:
execute in class JWalker
Throws:
GeneratorException - if any constructor or method argument value could not be synthesised. A CustomGenerator must be provided that is capable of synthesising values of the argument type.
ExecutionException - if any constructor or method could not be invoked, for reasons of visibility, security or bad arguments, or if it is detected that a constructor or method behaves randomly.
PermissionException - if the loaded test class, or any custom generator, could not be instantiated, either for reasons of security, or visibility, or because it was abstract, or an interface.