|
Evaluating Software Design Patterns — the "Gang of Four" patterns implemented in Java 6 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object dk.rode.thesis.meta.reflect.IdentifiedStackTraceElement dk.rode.thesis.meta.reflect.CallerClass dk.rode.thesis.meta.reflect.Caller
public class Caller
A caller represents one or more java.lang.reflect.Member
instances representing a specific calling
context.
The calling context can be either a static initialisation block,
an instance initialisation block, a constructor, or a method. The
caller thus represents a corresponding Member
instance,
if possible.
However, the member may not be able to identified uniquely based on the stack trace. It will not be possible to uniquely resolve a member in case the calling context represents an overloaded method; a constructor and/or instance initialisation block declared in a class that declares multiple constructors and/or initialisation blocks; or a static initialisation block declared in a class that declares several static initialisation blocks.
The calling context is stored in the callerMember
attribute,
while the member representing the immediate calling context is stored
in the calleeMember
attribute. The attributes are never null,
but may not be able to identify the unique member, as stated. They can,
however, still be used to test on the different types of members, and
list the possible candidates
as well.
Callers are immutable.
Example:
.. public class Goo { public void goo { // Calling context at depth 2... new Foo().foo(); } } .. public class Foo { public void foo { // Calling context at depth 1... new Bar().bar(); } } .. public class Bar { public void bar { // Immediate calling context is the callee, i.e. the // member at depth 0 (method bar)... Caller caller = newNotice that the no-arg constructor does not identify the immediate calling context as theCaller()
; // = 1 System.out.println(caller.callerMember
); // prints "foo" System.out.println(caller.calleeMember
); // prints "bar" caller = newCaller
(1); System.out.println(caller.callerMember
); // prints "foo" System.out.println(caller.calleeMember
); // prints "bar" caller = newCaller
(2); System.out.println(caller.callerMember
); // prints "goo" System.out.println(caller.calleeMember
); // prints "bar" } } ..
callerMember
, but the
calling context at stack depth 1. The immediate calling context
is always available via the calleeMember
method.
An offset
can be supplied
at construction
time to specify a stack
depth to identify the calling context. The offset is relative to
the immediate calling context.
Stack traces are local to the thread in question.
Nested Class Summary | |
---|---|
static class |
Caller.CallerType
A caller type identifies possible caller contexts a given caller represents. |
static class |
Caller.MemberContext
A member context represents a member in a given calling context, which may or may not be uniquely Caller.MemberContext.resolved . |
Nested classes/interfaces inherited from class dk.rode.thesis.meta.reflect.CallerClass |
---|
CallerClass.CallerIterator<C extends CallerClass> |
Field Summary | |
---|---|
Caller.MemberContext |
calleeMember
The callee member context represents the member that created this caller instance, i.e. the member representing the the immediate calling context. |
Caller.MemberContext |
callerMember
The caller member context represents the member of the calling context, relative to the offset supplied
at construction time. |
Fields inherited from class dk.rode.thesis.meta.reflect.CallerClass |
---|
calleeClass, callerClass |
Fields inherited from class dk.rode.thesis.meta.reflect.IdentifiedStackTraceElement |
---|
element, offset, stack, throwable |
Constructor Summary | |
---|---|
|
Caller()
No-arg constructor. |
|
Caller(Caller caller)
Copy constructor. |
protected |
Caller(Caller caller,
int offset)
Constructor, which creates this caller using an existing stack trace supplied from caller ,
but using a perhaps different offset supplied as
offset . |
|
Caller(int offset)
Constructor. |
protected |
Caller(int depth,
int offset)
Constructor. |
Method Summary | |
---|---|
Caller |
getAssignableCaller()
Returns the first caller in the call-stack where the class of the calling context
is assignable to the class representing
the immediate calling context. |
Caller |
getCaller()
Returns the caller representing the calling context of this caller, or null if no such caller exist. |
Caller |
getCaller(Caller.CallerType type)
Returns the first caller of this caller found in the call-stack matching the caller type supplied as type , if any. |
Iterator<Caller> |
getCallers()
Returns a new iterator to iterate over all preceding callers in the call-stack. |
Caller |
getClassCaller()
Returns the first caller in the call-stack where the class of the calling context
is identical to the class representing
the immediate calling context. |
protected static Member[] |
getMember(StackTraceElement element)
Returns the members associated with the stack trace element supplied as element . |
Caller |
getNonAssignableCaller()
Returns the first caller in the call-stack where the class of the calling context
is not assignable to the class representing
the immediate calling context. |
Caller |
getNonClassCaller()
Returns the first caller in the call-stack where the class of the calling context
is not identical to the class representing
the immediate calling context. |
Caller |
getNonSubClassCaller()
Returns the first caller in the call-stack where the class of the calling context
is a not a sub-class of the class representing
the immediate calling context. |
Caller |
getSubClassCaller()
Returns the first caller in the call-stack where the class of the calling context
is a sub-class of the class representing
the immediate calling context. |
boolean |
isConstructor()
Returns true if the member of the calling context
is a constructor or instance initialisation block, false if not. |
boolean |
isMemberInCallStack(Member... members)
Returns true if just one of the members supplied in members
is contained in the call-stack of this caller, false if not. |
boolean |
isMemberInCallStack(Object... objects)
Returns true if just one of the declared methods and constructors fetched from an object in objects is contained in the
call-stack of this caller, false if not. |
boolean |
isMethod()
Returns true if the member of the calling context
is a method, false if not. |
boolean |
isStatic()
Returns true if the member of the calling context
is a static initialiser block, false if not. |
Methods inherited from class dk.rode.thesis.meta.reflect.CallerClass |
---|
equals, getClass, hashCode, isAssignableToThisClass, isClassInCallStack, isNestedClass, isPackageInCallStack, isSubClass, isSuperClass, isThisClass, isThisPackage, iterator |
Methods inherited from class dk.rode.thesis.meta.reflect.IdentifiedStackTraceElement |
---|
getStackTrace, printStackTrace, toString |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public final Caller.MemberContext calleeMember
Never null.
CallerClass.calleeClass
public final Caller.MemberContext callerMember
offset
supplied
at construction time.
The member is the "other member" to test when methods
like isConstructor()
is invoked,
where calleeMember
represents "this class".
Never null.
CallerClass.callerClass
Constructor Detail |
---|
public Caller()
The caller member
is the member of the calling
context at stack depth 1 from the member
of
the immediate calling context, i.e. the calling context of the
immediate calling context.
Example:
.. public void foo { this.bar(); } public void bar { // Represents foo, *not* bar Caller caller = new Caller(); } ..
public Caller(Caller caller)
caller
- The caller to copy; cannot be null.
NullPointerException
- If caller
is null.protected Caller(Caller caller, int offset)
caller
,
but using a perhaps different offset supplied as
offset
.
caller
- The caller to supply the stack trace;
cannot be null.offset
- The stack offset; must be within bounds.
NullPointerException
- If caller
is null.
IndexOutOfBoundsException
- If offset
is illegal, i.e.,
does not represent a valid stack trace element.public Caller(int offset)
The caller member
is the member of the calling
context at stack depth offset
from the member
of the immediate calling context.
Invoking this constructor with a value of zero corresponds to invoking the no-arg constructor.
offset
- The stack offset; must be within bounds.
IndexOutOfBoundsException
- If offset
is illegal, i.e., does not
represent a valid stack trace element.protected Caller(int depth, int offset)
The caller member
is the member of the calling
context at stack depth offset
from the member
of the immediate calling context.
Invoking this constructor with zero values corresponds to invoking the no-arg constructor.
depth
- The increase in stack depth added by this class or
by sub-classes. The depth of this class is zero,
the depth of an immediate sub-class is one, and
so forth.offset
- The stack offset; must be within bounds.
IndexOutOfBoundsException
- If offset
is illegal, i.e., does not
represent a valid stack trace element.Method Detail |
---|
public Caller getAssignableCaller()
CallerClass
class
of the calling context
is assignable to the class
representing
the immediate calling context.
This may be the same class as the class
of the immediate calling context represented by this caller.
getAssignableCaller
in class CallerClass
CallerClass.getNonAssignableCaller()
public Caller getCaller()
CallerClass
The returned caller will represents the same immediate
calling context as this caller, i.e. the CallerClass.calleeClass
is equal to that of this caller.
getCaller
in class CallerClass
CallerClass.getCallers()
public Caller getCaller(Caller.CallerType type)
type
, if any.
type
- The caller type; cannot be null.
NullPointerException
- If type
is null.public Iterator<Caller> getCallers()
CallerClass
Each returned caller will represents the same immediate
calling context as this caller, i.e. the CallerClass.calleeClass
is equal to that of this caller.
The remove()
method of the returned iterator will
always throw an UnsupportedOperationException
.
getCallers
in class CallerClass
CallerClass.getCaller()
,
CallerClass.iterator()
public Caller getClassCaller()
CallerClass
class
of the calling context
is identical to the class
representing
the immediate calling context.
getClassCaller
in class CallerClass
CallerClass.getNonClassCaller()
protected static final Member[] getMember(StackTraceElement element)
element
. The members will always be
constructors or methods.
The order of the members is their declaration order in the
class represented by element
, and only members
from that class are considered, i.e. no inherited members.
element
- The stack trace element; cannot be null.
NullPointerException
- If element
is null.public Caller getNonAssignableCaller()
CallerClass
class
of the calling context
is not assignable to the class
representing
the immediate calling context.
getNonAssignableCaller
in class CallerClass
CallerClass.getAssignableCaller()
public Caller getNonClassCaller()
CallerClass
class
of the calling context
is not identical to the class
representing
the immediate calling context.
getNonClassCaller
in class CallerClass
CallerClass.getClassCaller()
public Caller getNonSubClassCaller()
CallerClass
class
of the calling context
is a not a sub-class of the class
representing
the immediate calling context.
getNonSubClassCaller
in class CallerClass
CallerClass.getSubClassCaller()
public Caller getSubClassCaller()
CallerClass
class
of the calling context
is a sub-class of the class
representing
the immediate calling context.
getSubClassCaller
in class CallerClass
CallerClass.getNonSubClassCaller()
public final boolean isConstructor()
member
of the calling context
is a constructor or instance initialisation block, false if not. Example:
class Foo { { bar(); } public Foo { bar(); } public static void bar { Caller caller = new Caller(); boolean isConstructor = caller.isConstructor(); // True, True... .. } .. }
isStatic()
,
isMethod()
public boolean isMemberInCallStack(Member... members)
members
is contained in the call-stack of this caller, false if not.
Only Method
or Constructor
members can ever
result in a match, while all other member types will cause
false to be returned.
members
- The members to test; cannot contain null entries.
members
is
contained in the call-stack, false if not.
NullPointerException
- If members
contains null entries.isMemberInCallStack(Object...)
public boolean isMemberInCallStack(Object... objects)
objects
is contained in the
call-stack of this caller, false if not.
objects
may contain Class
objects as well.
objects
- The objects delivering the methods and constructors to
test; cannot contain null entries.
objects
is contained in the call-stack,
false if not.
NullPointerException
- If objects
contains null entries.isMemberInCallStack(Member...)
public final boolean isMethod()
member
of the calling context
is a method, false if not. Example:
.. public void foo { this.bar(); } public void bar { Caller caller = new Caller(); boolean isMethod = caller.isMethod(); // True: foo is a method... .. } ..
isStatic()
,
isConstructor()
public final boolean isStatic()
member
of the calling context
is a static initialiser block, false if not. Example:
class Foo { static { bar(); } public void bar { Caller caller = new Caller(); boolean isStatic = caller.isStatic(); // True... .. } .. }To test if a given static method is the caller, use the
isMethod()
instead, and then test on method
modifiers.
isConstructor()
,
isMethod()
|
Gunni Rode / rode.dk | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |