AspectJS - Tutorial: Applying Wrappers - Part 4 of a Guide to Function Interception in JavaScript

Contents

Applying Wrappers
Symmetric Wrappers

Applying Wrappers

The application of a wrapper — where a function has both a prefix and a suffix — follows the same principle as AddPrefix and AddSuffix, but is a little more involved because it requires passing more parameters.

Example Seventeen illustrates the application of a wrapping intercept to a function. Here, the first two arguments describe the interceptee, as in the examples above. The next four describe the prefix completely, including its calling argument and execution limit (as in a full call to AddPrefix), and the remaining four parameters describe the suffix, as in a call to AddSuffix. The trailing argument provides diagnostic information.

These parameters set the prefix such that it will execute for every invocation of MyFunc, and is passed the value "Homer" every time it is called. Similarly, the suffix is passed the value "Beer", and is also set to execute on every invocation of MyFunc.

The string passed as the ClientCallPoint argument does not appear in the output because the call to AddWrapper is entirely legal (although it is shown here for demonstration purposes). If the call were incorrect, however, AJS would throw an Error object, the message property of which would contain that string.

Note that it is necessary to provide Arg and ExecMax parameters to the prefix-describing portion of the call, even if the prefix requires no calling argument, and must execute indefinitely. In the case of the suffix-describing parameters, the calling-argument and execution-limit parameters can be omitted, as long as no argument is required for the diagnostic information. If the affix functions do not require a calling argument then these parameters can be either null or an empty string.


 // Example 17

 function Prefix (Value) { alert ("Prefix executed - Value = " + Value); }
 function Suffix (Value) { alert ("Suffix executed - Value = " + Value); }

 function MyFunc ()      { alert ("MyFunc executed"); }


 AJS.AddWrapper (this,   "MyFunc",
                 Prefix, "Homer", Infinity,
                 Suffix, "Beer",  Infinity, "AddWrapper Example");

 MyFunc ();

 --------------------------------------

 Output:

 Prefix executed - Value = Homer
 MyFunc executed
 Suffix executed - Value = Beer

Symmetric Wrappers

Prefix and suffix functions that are attached to an interceptee can have the same identity. In other words, the same function can act as a prefix and a suffix for a given interceptee. Pressing a function into such double-duty can be effected by calling AddWrapper, wherein the suffix is specified by passing the same reference that is used to indicate the prefix. This is illustrated in Example Eighteen.


 // Example 18

 function WrapFix (Value) { alert ("WrapFix executed - Value = " + Value); }
 function MyFunc  ()      { alert ("MyFunc executed"); }

 AJS.AddWrapper (this, "MyFunc", WrapFix, "Homer", Infinity,
                                 WrapFix, "Beer");

 MyFunc ();

 --------------------------------------

 Output:

 WrapFix executed - Value = Homer
 MyFunc executed
 WrapFix executed - Value = Beer

Clearly, however, this is unwieldy, tedious and therefore error prone, as well as being a little inefficient. Given this, AspectJS supports a method called AddSymmetricWrapper, which takes a single set of arguments that describe both the prefix and the suffix.

Example Nineteen illustrates the use of this method, where the discrete Prefix and Suffix functions used in the example for AddWrapper have been replaced by a single function called 'WrapFix'.

Note that prefixes and suffixes that are set in this way operate in an identical fashion to those set using the methods explored above, with the exception that the same value is passed to both the prefix and suffix function. This is in order to simplify AddSymmetricWrapper's signature still further in comparison with AddWrapper.


 // Example 19

 function WrapFix (Value) { alert ("WrapFix executed - Value = " + Value); }
 function MyFunc  ()      { alert ("MyFunc executed"); }

 AJS.AddSymmetricWrapper (this, "MyFunc", WrapFix, "Marge");

 MyFunc ();

 --------------------------------------

 Output:

 WrapFix executed - Value = Marge
 MyFunc executed
 WrapFix executed - Value = Marge

Go forward to Part 5 of this tutorial.
Go back to Part 3 of this tutorial.