Addition
-
Removal |
Name |
Member of |
Returns |
Description |
|
addPrefix
addSuffix
addWrapper
|
AJS
interceptee
AJS
interceptee
AJS
interceptee
|
Affix
Affix
Affix
Affix
Wrapper
Wrapper
|
addPrefix and addSuffix associate the execution of a function (an
'affix') with the execution of a given method (the 'interceptee')
of a given object. Calling addPrefix causes the affix to execute
before the interceptee, whereas calling addSuffix causes it to
execute afterwards.
Calling addWrapper associates both a prefix and suffix function
(which can be the same function) with the same interceptee, and
is a shorthand equivalent to calling addPrefix and addSuffix
separately. Where one or more of the arguments that describe the
suffix are omitted then the equivalent prefix-argument is used
as a default. It follows that if all suffix-descriptors are omitted
then all the arguments that describe the prefix are used, which
has the effect of wrapping the interceptee 'symmetrically'.
addPrefix and addSuffix return an 'Affix' object that corresponds
to the affix function that has been attached to the interceptee.
Similarly, addWrapper returns a 'Wrapper' object
that subsumes two affix objects that correspond respectively to
the prefix and suffix that have been attached.
A call to an intercepted method causes invocation of 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 operate as expected, as do calls to
user-defined constructors. It also means that the interceptee
operates as expected should client code use the 'apply' and
'call' methods that function objects support.
It is possible to intercept calls to constructors of native
types, but a quirk in the way that JavaScript interpreters
operate may cause such calls to return an object of the incorrect
type. This is with the known exception of the Array, Function and
RegExp constructors. As of September 2008, other Native/Built-In types have not been
tested.
The AJS implementations of these methods can be called whenever
the client wishes, but the interceptee implementations cannot be
called until the interceptee acquires an initial prefix
and/or suffix. Additionally, a given interceptee loses its
implementations of these methods once it loses its last affix.
|
addBefore
addAfter
|
Affix
Affix
|
Affix
Affix
|
These methods create and insert a new affix into an existing set
of affixes. addBefore inserts the new affix such that it executes
before the affix-function that corresponds to the Affix object on
which addBefore is called. Conversely, addAfter inserts the new
affix such that it executes after the affix-function that
corresponds to the Affix object on which addAfter is called.
Calling these methods on an Affix that has been removed from its
interceptee has no effect.
|
|
remove
|
Affix
Wrapper
|
undefined
undefined
|
When called on an Affix object, this method dissociates the
corresponding affix-function from its interceptee. When called on
a wrapper it dissociates both the prefix and suffix functions.
When called on a Wrapper, where one affix has already been
removed, it causes removal of the other affix.
Calling this function on an Affix that has already been removed,
or on a Wrapper where both the prefix and suffix have been
removed, has no effect.
As soon as an Affix is removed its methods are rendered safe,
such that calling them has no effect, and only safe
default-values are returned.
When all prefixes and suffixes have been removed, either
explicitly or automatically through reaching their execution
limit, the interception mechanism is dissociated from the
interceptee, and the relationship between the interceptee, its
parent object and the interceptee's callers returns to normal.
Attempts to remove an affix explicitly while the interception
mechanism is executing that affix and its siblings have no
effect.
|
|
Accession
-
Mutation |
Name |
Member of |
Returns |
Description |
|
getPfixTot
getSfixTot
getAffixTot
|
interceptee
interceptee
Affix
|
number
number
number
|
These methods return, respectively, the total number of prefixes
and suffixes that are associated with a given interceptee, and
the total number of affixes in a given set.
|
|
getFirstPfix
getLastPfix
getFirstSfix
getLastSfix
|
interceptee
interceptee
interceptee
interceptee
|
Affix
Affix
Affix
Affix
|
These methods return, respectively, the first and last prefixes
and suffixes in a given interceptee's set. They return null if
the interceptee has no affixes of the type indicated.
|
getFirstSib
getLastSib
|
Affix
Affix
|
Affix
Affix
|
These methods return, respectively, the first and last Affixes in
a set of prefixes or suffixes for a given member of that set.
They return null if, respectively, the interceptee has no
prefixes or suffixes.
|
getPrev
getNext
|
Affix
Affix
|
Affix
Affix
|
These methods return, respectively, the previous and next Affix
objects for the Affix in question. Calling getPrev
on the first Affix in a set, or getNext on the last Affix in a
set returns that Affix, meaning
that iteration beyond the end of a set of Affixes is impossible.
|
getPrefix
getSuffix
|
Wrapper
Wrapper
|
Affix
Affix
|
These methods return, respectively, the prefix and suffix objects
that are subsumed by the Wrapper object on which they are called.
|
|
getFunc
setFunc
|
Affix
Affix
Wrapper
|
function
undefined
undefined
|
These methods, respectively, get and set the reference to the
affix function(s) that correspond(s) to the Affix/Wrapper
in question.
|
|
getArg
setArg
|
Affix
Affix
Wrapper
|
*
undefined
undefined
|
These methods, respectively, get and set the argument that is passed, on invocation, to the
affix function(s) that correspond(s) to the Affix/Wrapper object
on which they are called.
|
|
getExecs
setExecs
|
Affix
Affix
Wrapper
|
number
undefined
undefined
|
These methods, respectively, get and set the number of times that
the affix on which they are called will execute before it is
detached automatically. When called on a Wrapper this sets the
execution limit for both the prefix and suffix that are subsumed
by the Wrapper object on which this function is called.
Calling setExecs on an Affix that has been removed has no effect.
|
|
isAttached
|
Affix
Wrapper
|
boolean
boolean
|
Indicates whether or not an affix has been removed from its
interceptee. It returns true if the affix in question is still
attached to its interceptee, and false if it has been removed.
When called on a Wrapper, this method returns true if either the
Prefix or Suffix, or both, are still attached to the interceptee,
and returns false only if both have been removed.
|
|
getSuspensions
|
Affix
|
number
|
Returns the degree to which the Affix in question is suspended, as
an integer value. The size of the number indicates the number of
times that resume must be called on the Affix in order to
reinstate its operation.
|
|
Suspension
-
Resumption |
Name |
Member of |
Returns |
Description |
|
enable
|
AJS_Logger
|
undefined
|
This method initialises logging behaviour, such that logging instrumentation is
applied to all methods of the AJS object, along with the methods of all Affix and Wrapper
objects created after a call to enable. It also applies instrumentation to the methods that
interceptees gain as soon as they acquire an initial prefix and/or suffix. There is no
corresponding disable method.
|
|
suspend
resume
|
Affix
Wrapper
AJS_Logger
Affix
Wrapper
AJS_Logger
|
undefined
undefined
undefined
undefined
undefined
undefined
|
When called on an Affix or Wrapper object, these methods, respectively,
suppress and re-instate the execution of
a given affix-function (or the prefix and suffix functions that
correspond to a Wrapper object), while leaving it attached to its
interceptee.
When called on AJS_Logger, these methods, respectively, suppress and
re-instate logging output. They have no effect prior to a call to the
enable method of the AJS_Logger object.
They have stack-like behaviour with all three types, in that a given number
of successive calls to suspend requires the same number of successive calls
to resume to reinstate the activity of the object in question.
Calling these methods on an Affix/Wrapper that has been removed
has no effect. Similarly, calling these methods on a AJS_Logger
before that object's enable method has been called has no effect.
|
|
suspendAll
resumeAll
|
Affix
Wrapper
Affix
Wrapper
|
undefined
undefined
undefined
undefined
|
These methods, respectively, suspend and resume all prefixes or
all suffixes that are attached to a given interceptee (or both
if called on a Wrapper object). The stack-like behaviour of the
suspend and resume methods of the underlying Affix objects is preserved.
Calling these methods on an Affix/Wrapper that has been removed has no effect.
|
|
Promotion
-
Demotion |
Name |
Member of |
Returns |
Description |
|
promote
demote
|
Affix
Wrapper
Affix
Wrapper
|
boolean
boolean
boolean
boolean
|
When called on an Affix object, and where the associated
affix-function is a member of a set of prefixes or suffixes,
these methods change the point in the execution order at which
the corresponding affix-function is invoked.
Where the Affix object represents a prefix, promoting it will cause its execution
to follow the prefix whose execution it
preceded previously, whereas promoting a suffix will cause the
suffix function to precede the suffix whose execution it
followed previously.
Conversely, demoting a prefix will cause it to execute before the
prefix that it followed previously, whereas demoting a suffix
will cause it to execute after the suffix whose execution it
preceded previously.
These methods return true if the Affix-execution order was
changed, and returns false if it was not. They have no effect if
there is no Affix over which the Affix in question can be
promoted/demoted.
When called on a Wrapper these methods promote/demote both the
prefix and suffix that it subsumes, and return true if either or both
the prefix and the suffix could be promoted/demoted, otherwise
they return false.
Attempts to promote or demote a given affix while the execution
mechanism is executing it and its siblings has no effect.
Calling these methods on an Affix/Wrapper that has been removed has no effect.
|
|
| Validation |
Name |
Member of |
Returns |
Description |
|
getVersion
|
AJS
|
string
|
Returns the version identifier for the AJS object as a string
containing "AspectJS Version 1.1".
|
|
aJS_DbC
|
Global
|
undefined
|
This function enables rigorous argument checking for all relevant
methods of AspectJS types and objects, such that passing an
incorrect type or value for a given argument, or omitting an
essential argument generates an exception. It is intended for
development and debugging purposes.
Calling this function also causes invocation of an optional,
user-defined, call-back function, whenever calls are made to an
affix or wrapper object that has been detached from a given
interceptee. Given this, it provides a way to eliminate redundant
(and therefore inefficient) calls to AspectJS methods, and
provides a way to eliminate the redundant consumption of storage
on the platform in question.
If used, this function should be called as soon as possible
following the import of the AspectJS library into the execution
environment. There is no need to call this function more than
once, and an exception is generated should this happen. Once
called, there is no way to disable argument checking without
removing the call to aJS_DbC and reinitialising the application.
|
|
User
Decides |
Name |
Member of |
Returns |
Description |
|
interceptee
|
*
|
*
|
An interceptee is an object method to which prefix and/or suffix
function(s) are applied. An interceptee executes after the
execution of its prefix(es), if is has any, and before the
execution of its suffix(es), if it has any.
Interceptees may do
anything they wish, and execute in ignorance of their affixes.
On losing the last of its affixes,
the interception mechanism that sits between an interceptee's owner-object and its
function-object disappears, as do the additional methods that the
function-object acquired when its initial affix(es) was/were applied.
This means that the relationship between it and the rest of the application
returns to normal.
|
|
onInterceptionRemoval
|
interceptee-
property
|
undefined
|
onInterceptionRemoval denotes an optional user-defined function that
is a method of any member of an interceptee (because functions can have members),
including its prototype. When an interceptee loses its last affix,
the relationship between it and its owner-object are returned to normal, such that
it retains any members that it acquired whilst it possessed affixes,
and retains any changes made to existing members during that period, including
changes to its prototype object.
However, if an interceptee-property implements 'onInterceptionRemoval',
that method will be called automatically during the interceptee's return to a
non-intercepted state. If the method returns false then the object of which it
is a member will NOT be copied back to the original interceptee.
This is an arcane feature that is necessary for AJS_DbC and AJS_Logger to
operate correctly, and may be of no use to other applications of the AJS object.
|
|
prefix
|
*
|
*
|
A prefix is a function that is defined by the user or platform
and which may be a method of an object or an inner function.
Prefixes are called before the interceptee with which they are
associated, and may do whatever they wish, except
remove/promote/demote themselves and other prefixes from/within
the set of which they may be a member. Any exception thrown by a
prefix emerges at the scope of the interceptee's caller, and
precludes execution of the interceptee.
Prefixes may be object-methods, inner functions, or an inner
function that is returned by calls to an outer function (in which
case the prefix will form part of a closure).
When invoked, prefixes receive the arguments that the
interceptee's caller passes (as a JavaScript 'arguments' array).
They are also passed a 'static' argument that is stipulated
optionally when the prefix was applied. If the prefix is one of a
set, it is also passed the value that execution of its previous
sibling returned (if it has one).
Prefix-function signatures differ from suffix-function signatures
in that they are NOT passed the result of the call to the
interceptee because the interceptee (obviously) has not yet been
called at the time the prefix function is invoked.
|
|
suffix
|
*
|
*
|
A suffix is a function that is defined by the user or platform
and which may be a method of an object or an inner function.
Suffixes are called before the interceptee with which they are
associated, and may do what ever they wish, except
remove/promote/demote themselves and other Suffixes from/within
the set of which they may be a member. Any exception thrown by a
suffix emerges at the scope of the interceptee's caller.
Suffixes may be object-methods, inner functions, or an inner
function that is returned by calls to an outer function (in which
case the suffix will form part of a closure),
When invoked, suffixes receive the arguments that the
interceptee's caller passes (as a JavaScript 'arguments' array).
They are also passed a 'static' argument that is stipulated
optionally when the suffix was applied. If the suffix is one of a
set, it is also passed the value that execution of its previous
sibling returned (if it has one).
Suffix-function signatures differ from prefix-function signatures
in that they ARE passed the result of the call to the interceptee
because the interceptee has already been called at the time the
suffix function is invoked. This gives suffixes an opportunity to
examine both what was passed into the interceptee, and what came
out.
|
|
onRedundantCall
|
*
|
undefined
|
onRedundantCall denotes a user-defined call-back function that
may be an object-method or an inner function.
Calling such a function 'onRedundantCall' is not mandatory.
onRedundantCall has meaning only if aJS_DbC is called. If provided to
that function, onRedundantCall is invoked whenever client code makes
a call to a method of an Affix or Wrapper object that has been detached from
its interceptee (although a very few methods are exempt).
It is intended to aid in profiling, debugging and tuning.
|
|
onMCall
|
*
|
undefined
|
onMCall denotes a user-defined call-back function that
may be an object-method or an inner function.
Calling such a function 'onMCall' is not mandatory.
onMCall is invoked by AJS_Logger whenever a method of the AJS object, an Affix or Wrapper object, or
an interceptee method is called, and is passed all available information regarding that call.
|
|
onMRtn
|
*
|
undefined
|
onMRtn denotes a user-defined call-back function that
may be an object-method or an inner function.
Calling such a function 'onMRtn' is not mandatory.
onMRtn is invoked by AJS_Logger whenever a method of the AJS object, an Affix or Wrapper object, or
an interceptee method returns, and is passed all available information regarding that call, including the
return value/object.
|
