AJS[ _HP].AddPrefix
Implementation : Function
Description : Associates the execution of a function (the Prefix) with the
execution of another function (the Interceptee), such that
calling the interceptee causes the Prefix to execute first.
Signature : AddPrefix (IntercepteeOwner, Interceptee,
PrefixFunc[ , PrefixArg [, ExecMax[, ClientCallPoint]]])
Parameters : IntercepteeOwner - Reference indicating the object of which the
interceptee is a member. Must not be null.
Interceptee - String containing the name of the function to
which the prefix is applied. Must not be
null. Must be a member of the object referred
to by IntercepteeOwner.
PrefixFunc - Reference to the function that is to be
executed before the interceptee.
PrefixArg - Optional parameter, which is passed to the
prefix function when it is executed. Can be of
any type, and any value, and can be null.
ExecMax - Optional integer, denoting the number of times
the prefix will execute before it is removed
automatically. A null or non-existent value
for this parameter will cause the prefix to
execute for every execution of the
interceptee, unless it is removed explicitly.
Any value provided must be greater than 0.
ClientCallPoint - Optional string, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that AspectJS
methods can throw. Can have any value but,
ideally, should denote the point in the
application's code where the call to AddPrefix
was made.
Returns : Reference to an Affix object.
Throws : Error object, if - 'this' does not refer to the AJS or AJS_HP object
IntercepteeOwner is undefined
IntercepteeOwner is null
IntercepteeOwner does not refer to an object
Interceptee is undefined
Interceptee is null
Interceptee does not refer to a function
The interceptee has existing prefixes and/or suffixes
PrefixFunc is undefined
PrefixFunc is null
PrefixFunc does not refer to a function
ExecMax is non-numeric
ExecMax is less than 1
Notes : The Affix object returned corresponds to the prefix that has
been applied.
This function can be called on a method that already has
prefixes and or suffixes.
A value must be provided for ExecMax if a value for
ClientCallPoint is supplied. If the Prefix must remain attached
to the interceptee indefinitely then the caller should pass
either the Infinity member of the Global object, or the
POSITIVE_INFINITY member of the Number type.
The AJS_HP version of this function ignores the ClientCallPoint
argument, and the Prefix and Suffix members of the Intercept
object returned do NOT permit new prefixes and suffixes to be
applied (the methods of those objects either do nothing when
called, or return a safe value). The AJS_HP version also performs
no argument checking, and only throws an exception if the
interceptee has an existing intercept.
Following application of a prefix, a call to the interceptee
by client code causes the interception mechanism to invoke the
interceptee such that the 'this' reference is the same as that
set by the call from client code. This means that normal
client-code calls will operate as expected, as well as
constructor calls. It also means that use of the 'apply' and
'call' methods of function objects when client code invokes the
interceptee will operate as expected.
AJS[ _HP].AddSuffix
Implementation : Function
Description : Associates the execution of a function (the Suffix) with the
execution of another function (the Interceptee), such that
calling the interceptee causes the suffix to execute afterwards.
Signature : AddSuffix (IntercepteeOwner, Interceptee,
SuffixFunc[ , SuffixArg[, ExecMax[, ClientCallPoint]]])
Parameters : IntercepteeOwner - Reference indicating the object of which the
interceptee is a member. Must not be null.
Interceptee - String containing the name of the function to
which the suffix is applied. Must not be
null. Must be a member of the object referred
to by IntercepteeOwner.
SuffixFunc - Reference to the function that is to be
executed before the interceptee.
SuffixArg - Optional parameter, which is passed to the
suffix function when it is executed. Can be of
any type, and can be null.
ExecMax - Optional integer, denoting the number of times
the suffix will execute before it is removed
automatically. A null or non-existent value
for this parameter will cause the suffix to
execute for every execution of the
interceptee, unless it is removed explicitly.
Any value provided must be greater than 0.
ClientCallPoint - Optional string, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that AspectJS
methods can throw. Can have any value but,
ideally, should denote the point in the
application's code where the call to AddSuffix
was made.
Returns : Reference to an Affix object.
Throws : Error object, if - 'this' does not refer to the AJS or AJS_HP object
IntercepteeOwner is undefined
IntercepteeOwner is null
IntercepteeOwner does not refer to an object
Interceptee is undefined
Interceptee is null
Interceptee does not refer to a function
The interceptee has existing prefixes and/or suffixes
SuffixFunc is undefined
SuffixFunc is null
SuffixFunc does not refer to a function
ExecMax is non-numeric
ExecMax is less than 1
Notes : The Affix object returned corresponds to the prefix that has
been applied.
This function can be called on a method that already has
prefixes and or suffixes.
A value must be provided for ExecMax if a value for
ClientCallPoint is supplied. If the Prefix must remain attached
to the interceptee indefinitely then the caller should pass
either the Infinity member of the Global object, or the
POSITIVE_INFINITY member of the Number type.
The AJS_HP version of this function ignores the ClientCallPoint
argument, and the Prefix and Suffix members of the Intercept
object returned do NOT permit new prefixes and suffixes to be
applied (the methods of those objects either do nothing when
called, or return a safe value). The AJS_HP version also performs
no argument checking, and only throws an exception if the
interceptee has an existing intercept.
Following application of a suffix, a call to the interceptee
by client code causes the interception mechanism to invoke the
interceptee such that the 'this' reference is the same as that
set by the call from client code. This means that normal
client-code calls will operate as expected, as well as
constructor calls. It also means that use of the 'apply' and
'call' methods of function objects when client code invokes the
interceptee will operate as expected.
AJS[ _HP].AddWrapper
Implementation : Function
Description : Associates two functions (the Prefix and Suffix) with the
execution of another function (the Interceptee), such that
calling the interceptee causes the Prefix to execute before the
Interceptee, and the Suffix to execute afterwards.
Signature : AddWrapper (IntercepteeOwner, Interceptee, PrefixFunc, PrefixArg, PrefixExecMax,
SuffixFunc[, SuffixArg[, SuffixExecMax[,
ClientCallPoint]]])
Parameters : IntercepteeOwner - Reference indicating the object of which the
interceptee is a member. Must not be null.
Interceptee - String containing the name of the function to
which the prefix is applied. Must not be
null. Must be a member of the object referred
to by IntercepteeOwner.
PrefixFunc - Reference to the function that is to be
executed before the interceptee.
PrefixArg - Parameter passed to the prefix function when
it is executed. Can be of any type, and any value.
Cannot be null.
PrefixExecMax - Integer, denoting the number of times
the prefix will execute before it is removed
automatically. Cannot be null, value must be
greater than 1.
SuffixFunc - Reference to the function that is to be
executed before the interceptee.
SuffixArg - Optional parameter, passed to the suffix
function when it is executed. Can be of any
type, and any value.
SuffixExecMax - Optional integer, denoting the number of times
the suffix will execute before it is removed
automatically. Any value provided must be
greater than 1.
ClientCallPoint - Optional string, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that AspectJS
methods can throw. Can have any value but,
ideally, should denote the point in the
application's code where the call to
AddWrapper was made.
Returns : Reference to a Wrapper object.
Throws : Error object, if - 'this' does not refer to the AJS or AJS_HP object
IntercepteeOwner is undefined
IntercepteeOwner is null
IntercepteeOwner does not refer to an object
Interceptee is undefined
Interceptee is null
Interceptee does not refer to a function
The interceptee has existing prefixes and/or suffixes
PrefixFunc is undefined
PrefixFunc is null
PrefixFunc does not refer to a function
PrefixExecMax is non-numeric
PrefixExecMax is less than 1
SuffixFunc is undefined
SuffixFunc is null
SuffixFunc does not refer to a function
SuffixExecMax is non-numeric
SuffixExecMax is less than 1
Notes : Like AddSymmetricWrapper, the Wrapper object returned subsumes
two Affix objects that correspond to the prefix and suffix that
have been applied to the interceptee.
This function can be called on a method that already has
prefixes and/or suffixes.
A value must be provided for PrefixExecMax. If it must remain
attached to the interceptee indefinitely then the caller should
pass either the Infinity member of the Global object, or
the POSITIVE_INFINITY member of the Number type.
A value must be provided for SuffixExecMax if a value for
ClientCallPoint is supplied. If the suffix must remain attached
to the interceptee indefinitely then the caller should pass
either the Infinity member of the Global object, or the
POSITIVE_INFINITY member of the Number type.
The AJS_HP version of this function ignores the ClientCallPoint
argument, and the Prefix and Suffix members of the Intercept
object returned do NOT permit new prefixes and suffixes to be
applied (the methods of those objects either do nothing when
called, or return a safe value). The AJS_HP version also
performs no argument checking, and only throws an exception if
the interceptee has an existing intercept.
Following application of a wrapper, a call to the interceptee
by client code causes the interception mechanism to invoke the
interceptee such that the 'this' reference is the same as that
set by the call from client code. This means that normal
client-code calls will operate as expected, as well as
constructor calls. It also means that use of the 'apply' and
'call' methods of function objects when client code invokes the
interceptee will operate as expected.
AJS[ _HP].AddSymmetricWrapper
Implementation : Function
Description : Associates a function (the 'wrapper function') with the
execution of another function (the 'interceptee'), such that
calling the interceptee causes the wrapper function to execute both
before and after the interceptee executes.
Signature : AddSymmetricWrapper (IntercepteeOwner, Interceptee,
WrapperFunc[ , WrapperArg[, ExecMax[, ClientCallPoint]]])
Parameters : IntercepteeOwner - Reference indicating the object of which the
interceptee is a member. Must not be null.
Interceptee - String containing the name of the function to
which the wrapper is applied. Must not be
null.
WrapperFunc - Reference to the function that is to be
executed before and after the interceptee.
WrapperArg - Optional parameter passed to the wrapper
function when it is executed. Can be of any
type, and any value.
ExecMax - Optional integer, denoting the number of times
the wrapper will execute before it is removed
automatically. Any value must be
greater than 1.
ClientCallPoint - Optional string, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that AspectJS
methods can throw. Can have any value but,
ideally, should denote the point in the
application's code where the call to
AddSymmetricWrapper was made.
Returns : Reference to a Wrapper object.
Throws : Error object, if - 'this' does not refer to the AJS or AJS_HP object
IntercepteeOwner is undefined
IntercepteeOwner is null
IntercepteeOwner does not refer to an object
Interceptee is undefined
Interceptee is null
Interceptee does not refer to a function
The interceptee has existing prefixes and/or suffixes
WrapperFunc is undefined
WrapperFunc is null
WrapperFunc does not refer to a function
ExecMax is non-numeric
ExecMax is less than 1
Notes : In essence, this method is functionally equivalent to the
AddWrapper method, as it simply provides a shorthand way of
repeating the suffix parameters that AddWrapper accepts, thus
making it more convenient to use in client code. The one
difference is that the argument passed to the prefix is the same as
the argument passed to the suffix.
Like AddWrapper, the Wrapper object returned subsumes two Affix
objects that correspond to the prefix and suffix that have been
applied to the interceptee.
The prefix and suffix applied by this function are independent of
each other. Even though they both refer to the same function.
This means that they can be removed individually, and can be
given different ExecMax values using the SetExecMax method of the
Affix type.
If a value for ClientCallPoint is supplied then a value must be
provided for WrapperExecMax. If the prefix and suffix must remain
attached to the interceptee indefinitely then the caller should
pass either the Infinity member of the Global object, or the
POSITIVE_INFINITY member of the Number type.
The AJS_HP version of this function ignores the ClientCallPoint
argument, and the Prefix and Suffix members of the Intercept
object returned do NOT permit new prefixes and suffixes to be
applied (the methods of those objects either do nothing when
called, or return a safe value). The AJS_HP version also performs
no argument checking, and only throws an exception if the
interceptee has an existing intercept.
Following application of a wrapper, a call to the interceptee
by client code causes the interception mechanism to invoke the
interceptee such the 'this' reference is the same as that set by
the call from client code. This means that normal client-code
calls will operate as expected, as well as constructor calls.
It also means that use of the 'apply' and 'call' methods of
function objects when client code invokes the interceptee will
operate as expected.
AJS[ _HP].NullFuncCount
Implementation : Attribute
Description : In the context of AJS, this object holds the number of times
that AJS.NullFunc has been called. In the context of AJS_HP
it always has the value of zero.
Type : Integer variable.
Notes : This (possibly useful diagnostic) property represents the number
of times that client code has called the AddBefore,
AddAfter, Remove and SetExecMax methods of an affix object
that has already been dissociated (removed) from an interceptee.
While calling these methods in such a circumstance is harmless,
such calls are redundant. Developers can therefore use this
attribute when attempting to root out such inefficiencies in their
applications.
This attribute may be set to an arbitrary value by client code,
as it has no effect on the operation of AJS or AJS_HP.
Even though AJS_HP makes no use of this attribute, it supports
it in order to preserve symmetry (i.e. 'type substitutability')
with AJS.