path: root/docs/progguide/semantics.adoc

[[semantics]]
= Language Semantics

[[semantics-intro]]
== Introduction

AspectJ extends Java by overlaying a concept of join points onto the
existing Java semantics and adding a few new program elements to Java:

A join point is a well-defined point in the execution of a program.
These include method and constructor calls, field accesses and others
described below.

A pointcut picks out join points, and exposes some of the values in the
execution context of those join points. There are several primitive
pointcut designators, and others can be named and defined by the
`pointcut` declaration.

A piece of advice is code that executes at each join point in a
pointcut. Advice has access to the values exposed by the pointcut.
Advice is defined by `before`, `after`, and `around` declarations.

Inter-type declarations form AspectJ's static crosscutting features,
that is, is code that may change the type structure of a program, by
adding to or extending interfaces and classes with new fields,
constructors, or methods. Some inter-type declarations are defined
through an extension of usual method, field, and constructor
declarations, and other declarations are made with a new `declare`
keyword.

An aspect is a crosscutting type that encapsulates pointcuts, advice,
and static crosscutting features. By type, we mean Java's notion: a
modular unit of code, with a well-defined interface, about which it is
possible to do reasoning at compile time. Aspects are defined by the
`aspect` declaration.

[[semantics-joinPoints]]
== Join Points

While aspects define types that crosscut, the AspectJ system does not
allow completely arbitrary crosscutting. Rather, aspects define types
that cut across principled points in a program's execution. These
principled points are called join points.

A join point is a well-defined point in the execution of a program. The
join points defined by AspectJ are:

Method call::
  When a method is called, not including super calls of non-static
  methods.
Method execution::
  When the body of code for an actual method executes.
Constructor call::
  When an object is built and that object's initial constructor is
  called (i.e., not for `super` or `this` constructor calls). The object
  being constructed is returned at a constructor call join point, so its
  return type is considered to be the type of the object, and the object
  itself may be accessed with `after returning` advice.
Constructor execution::
  When the body of code for an actual constructor executes, after its
  this or super constructor call. The object being constructed is the
  currently executing object, and so may be accessed with the `this()` pointcut.
  The constructor execution join point for a constructor that
  calls a super constructor also includes any non-static initializers of
  enclosing class. No value is returned from a constructor execution
  join point, so its return type is considered to be `void`.
Static initializer execution::
  When the static initializer for a class executes. No value is returned
  from a static initializer execution join point, so its return type is
  considered to be `void`.
Object pre-initialization::
  Before the object initialization code for a particular class runs.
  This encompasses the time between the start of its first called
  constructor and the start of its parent's constructor. Thus, the
  execution of these join points encompass the join points of the
  evaluation of the arguments of `this()` and `super()` constructor calls.
  No value is returned from an object pre-initialization join point, so its
  return type is considered to be `void`.
Object initialization::
  When the object initialization code for a particular class runs. This
  encompasses the time between the return of its parent's constructor
  and the return of its first called constructor. It includes all the
  dynamic initializers and constructors used to create the object. The
  object being constructed is the currently executing object, and so may
  be accessed with the `this()` pointcut. No value is returned from a constructor
  execution join point, so its return type is considered to be `void`.
Field reference::
  When a non-constant field is referenced. [Note that references to
  constant fields (static final fields bound to a constant string object
  or primitive value) are not join points, since Java requires them to
  be inlined.]
Field set::
  When a field is assigned to. Field set join points are considered to
  have one argument, the value the field is being set to. No value is
  returned from a field set join point, so its return type is considered
  to be void. [Note that the initializations of constant fields (`static final`
  fields where the initializer is a constant string object or
  primitive value) are not join points, since Java requires their
  references to be inlined.]
Handler execution::
  When an exception handler executes. Handler execution join points are
  considered to have one argument, the exception being handled. No value
  is returned from a field set join point, so its return type is
  considered to be void.
Advice execution::
  When the body of code for a piece of advice executes.

Each join point potentially has three pieces of state associated with
it: the currently executing object, the target object, and an object
array of arguments. These are exposed by the three state-exposing
pointcuts, `this`, `target`, and `args`, respectively.

Informally, the currently executing object is the object that a `this`
expression would pick out at the join point. The target object is where
control or attention is transferred to by the join point. The arguments
are those values passed for that transfer of control or attention.

[cols=",,,",options="header",]
|===
|*Join Point* |*Current Object* |*Target Object* |*Arguments*
|Method Call |executing object* |target object** |method arguments

|Method Execution |executing object* |executing object* |method
arguments

|Constructor Call |executing object* |None |constructor arguments

|Constructor Execution |executing object |executing object |constructor
arguments

|Static initializer execution |None |None |None

|Object pre-initialization |None |None |constructor arguments

|Object initialization |executing object |executing object |constructor
arguments

|Field reference |executing object* |target object** |None

|Field assignment |executing object* |target object** |assigned value

|Handler execution |executing object* |executing object* |caught
exception

|Advice execution |executing aspect |executing aspect |advice arguments
|===

+++*+++ There is no executing object in static contexts such as static method
bodies or static initializers.

+++**+++ There is no target object for join points associated with static
methods or fields.

[[semantics-pointcuts]]
== Pointcuts

A pointcut is a program element that picks out join points and exposes
data from the execution context of those join points. Pointcuts are used
primarily by advice. They can be composed with boolean operators to
build up other pointcuts. The primitive pointcuts and combinators
provided by the language are:

`call(MethodPattern)`::
  Picks out each method call join point whose signature matches `_MethodPattern_`.
`execution(MethodPattern)`::
  Picks out each method execution join point whose signature matches `_MethodPattern_`.
`get(FieldPattern)`::
  Picks out each field reference join point whose signature matches `_FieldPattern_`. [Note that references to constant fields (static final fields bound
  to a constant string object or primitive value) are not join points,
  since Java requires them to be inlined.]
`set(FieldPattern)`::
  Picks out each field set join point whose signature matches `_FieldPattern_`. [Note that the initializations of constant fields (static final
  fields where the initializer is a constant string object or primitive
  value) are not join points, since Java requires their references to be
  inlined.]
`call(ConstructorPattern)`::
  Picks out each constructor call join point whose signature matches `_ConstructorPattern_`.
`execution(ConstructorPattern)`::
  Picks out each constructor execution join point whose signature
  matches `_ConstructorPattern_`.
`initialization(ConstructorPattern)`::
  Picks out each object initialization join point whose signature
  matches `_ConstructorPattern_`.
`preinitialization(ConstructorPattern)`::
  Picks out each object pre-initialization join point whose signature
  matches `_ConstructorPattern_`.
`staticinitialization(TypePattern)`::
  Picks out each static initializer execution join point whose signature
  matches `_TypePattern_`.
`handler(TypePattern)`::
  Picks out each exception handler join point whose signature matches `_TypePattern_`.
`adviceexecution()`::
  Picks out all advice execution join points.
`within(TypePattern)`::
  Picks out each join point where the executing code is defined in a
  type matched by `_TypePattern_`.
`withincode(MethodPattern)`::
  Picks out each join point where the executing code is defined in a
  method whose signature matches `_MethodPattern_`.
`withincode(ConstructorPattern)`::
  Picks out each join point where the executing code is defined in a
  constructor whose signature matches `_ConstructorPattern_`.
`cflow(Pointcut)`::
  Picks out each join point in the control flow of any join point `_P_` picked out by `_Pointcut_` , including `_P_` itself.
`cflowbelow(Pointcut)`::
  Picks out each join point in the control flow of any join point `_P_` picked out by `_Pointcut_`, but not `_P_` itself.
`this(Type or Id)`::
  Picks out each join point where the currently executing object (the
  object bound to `_this_`) is an instance of `_Type_` , or of the type of the identifier `_Id_` (which must be bound in the enclosing advice or pointcut definition).
  Will not match any join points from static contexts.
`target(Type or Id)`::
  Picks out each join point where the target object (the object on which
  a call or field operation is applied to) is an instance of `_Type_` , or of the type of the identifier `_Id_` (which must be bound in the enclosing advice or pointcut definition).
  Will not match any calls, gets, or sets of static members.
`args(Type or Id, ...)`::
  Picks out each join point where the arguments are instances of the
  appropriate type (or type of the identifier if using that form). A `_null_` argument is matched iff the static type of the argument (declared
  parameter type or field type) is the same as, or a subtype of, the
  specified args type.
`PointcutId(TypePattern or Id, ...)`::
  Picks out each join point that is picked out by the user-defined
  pointcut designator named by `_PointcutId_` .
`if(BooleanExpression)`::
  Picks out each join point where the boolean expression evaluates to `_true_` . The boolean expression used can only access static members,
  parameters exposed by the enclosing pointcut or advice, and `_thisJoinPoint_` forms. In particular, it cannot call non-static methods on the aspect
  or use return values or exceptions exposed by after advice.
`! Pointcut`::
  Picks out each join point that is not picked out by `_Pointcut_` .
`Pointcut0 && Pointcut1`::
  Picks out each join points that is picked out by both `_Pointcut0_` and `_Pointcut1_` .
`Pointcut0 || Pointcut1`::
  Picks out each join point that is picked out by either pointcuts. `_Pointcut0_` or `_Pointcut1_` .
`( Pointcut )`::
  Picks out each join points picked out by `_Pointcut_` .

=== Pointcut definition

Pointcuts are defined and named by the programmer with the `pointcut`
declaration.

[source, java]
....
pointcut publicIntCall(int i):
  call(public * *(int)) && args(i);
....

A named pointcut may be defined in either a class or aspect, and is
treated as a member of the class or aspect where it is found. As a
member, it may have an access modifier such as `public` or `private`.

[source, java]
....
class C {
  pointcut publicCall(int i):
    call(public * *(int)) && args(i);
}

class D {
  pointcut myPublicCall(int i):
    C.publicCall(i) && within(SomeType);
}
....

Pointcuts that are not final may be declared abstract, and defined
without a body. Abstract pointcuts may only be declared within abstract
aspects.

[source, java]
....
abstract aspect A {
  abstract pointcut publicCall(int i);
}
....

In such a case, an extending aspect may override the abstract pointcut.

[source, java]
....
aspect B extends A {
  pointcut publicCall(int i): call(public Foo.m(int)) && args(i);
}
....

For completeness, a pointcut with a declaration may be declared `final`.

Though named pointcut declarations appear somewhat like method
declarations, and can be overridden in subaspects, they cannot be
overloaded. It is an error for two pointcuts to be named with the same
name in the same class or aspect declaration.

The scope of a named pointcut is the enclosing class declaration. This
is different than the scope of other members; the scope of other members
is the enclosing class _body_. This means that the following code is
legal:

[source, java]
....
aspect B percflow(publicCall()) {
  pointcut publicCall(): call(public Foo.m(int));
}
....

=== Context exposure

Pointcuts have an interface; they expose some parts of the execution
context of the join points they pick out. For example, the PublicIntCall
above exposes the first argument from the receptions of all public unary
integer methods. This context is exposed by providing typed formal
parameters to named pointcuts and advice, like the formal parameters of
a Java method. These formal parameters are bound by name matching.

On the right-hand side of advice or pointcut declarations, in certain
pointcut designators, a Java identifier is allowed in place of a type or
collection of types. The pointcut designators that allow this are
`this`, `target`, and `args`. In all such cases, using an identifier
rather than a type does two things. First, it selects join points as
based on the type of the formal parameter. So the pointcut

[source, java]
....
pointcut intArg(int i): args(i);
....

picks out join points where an `int` (or a `byte`, `short`, or `char`;
anything assignable to an `int`) is being passed as an argument. Second,
though, it makes the value of that argument available to the enclosing
advice or pointcut.

Values can be exposed from named pointcuts as well, so

[source, java]
....
pointcut publicCall(int x): call(public *.*(int)) && intArg(x);
pointcut intArg(int i): args(i);
....

is a legal way to pick out all calls to public methods accepting an int
argument, and exposing that argument.

There is one special case for this kind of exposure. Exposing an
argument of type Object will also match primitive typed arguments, and
expose a "boxed" version of the primitive. So,

[source, java]
....
pointcut publicCall(): call(public *.*(..)) && args(Object);
....

will pick out all unary methods that take, as their only argument,
subtypes of Object (i.e., not primitive types like `int`), but

[source, java]
....
pointcut publicCall(Object o): call(public *.*(..)) && args(o);
....

will pick out all unary methods that take any argument: And if the
argument was an `int`, then the value passed to advice will be of type
`java.lang.Integer`.

The "boxing" of the primitive value is based on the _original_ primitive
type. So in the following program

[source, java]
....
public class InstanceOf {
  public static void main(String[] args) {
    doInt(5);
  }

  static void doInt(int i) {  }
}

aspect IntToLong {
  pointcut el(long l) :
    execution(* doInt(..)) && args(l);

  before(Object o) : el(o) {
    System.out.println(o.getClass());
  }
}
....

The pointcut will match and expose the integer argument, but it will
expose it as an `Integer`, not a `Long`.

=== Primitive pointcuts

==== Method-related pointcuts

AspectJ provides two primitive pointcut designators designed to capture
method call and execution join points.

* `call( MethodPattern )`
* `execution( MethodPattern )`

==== Field-related pointcuts

AspectJ provides two primitive pointcut designators designed to capture
field reference and set join points:

* `get( FieldPattern )`
* `set( FieldPattern )`

All set join points are treated as having one argument, the value the
field is being set to, so at a set join point, that value can be
accessed with an `args` pointcut. So an aspect guarding a static integer
variable x declared in type T might be written as

[source, java]
....
aspect GuardedX {
  static final int MAX_CHANGE = 100;

  before(int newval): set(static int T.x) && args(newval) {
    if (Math.abs(newval - T.x) > MAX_CHANGE)
      throw new RuntimeException();
  }
}
....

==== Object creation-related pointcuts

AspectJ provides primitive pointcut designators designed to capture the
initializer execution join points of objects.

* `call( ConstructorPattern )`
* `execution( ConstructorPattern )`
* `initialization( ConstructorPattern )`
* `preinitialization( ConstructorPattern )`

==== Class initialization-related pointcuts

AspectJ provides one primitive pointcut designator to pick out static
initializer execution join points.

* `staticinitialization( TypePattern )`

==== Exception handler execution-related pointcuts

AspectJ provides one primitive pointcut designator to capture execution
of exception handlers:

* `handler( TypePattern )`

All handler join points are treated as having one argument, the value of
the exception being handled. That value can be accessed with an `args`
pointcut. So an aspect used to put `FooException` objects into some
normal form before they are handled could be written as

[source, java]
....
aspect NormalizeFooException {
  before(FooException e): handler(FooException) && args(e) {
    e.normalize();
  }
}
....

==== Advice execution-related pointcuts

AspectJ provides one primitive pointcut designator to capture execution
of advice

* `adviceexecution()`

This can be used, for example, to filter out any join point in the
control flow of advice from a particular aspect.

[source, java]
....
aspect TraceStuff {
  pointcut myAdvice(): adviceexecution() && within(TraceStuff);

  before(): call(* *(..)) && !cflow(myAdvice) {
    // do something
  }
}
....

==== State-based pointcuts

Many concerns cut across the dynamic times when an object of a
particular type is executing, being operated on, or being passed around.
AspectJ provides primitive pointcuts that capture join points at these
times. These pointcuts use the dynamic types of their objects to pick
out join points. They may also be used to expose the objects used for
discrimination.

* `this( Type or Id )`
* `target( Type or Id )`

The `this` pointcut picks out each join point where the currently
executing object (the object bound to `this`) is an instance of a
particular type. The `target` pointcut picks out each join point where
the target object (the object on which a method is called or a field is
accessed) is an instance of a particular type. Note that `target` should
be understood to be the object the current join point is transfering
control to. This means that the target object is the same as the current
object at a method execution join point, for example, but may be
different at a method call join point.

* `args( Type or Id or "..", ...)`

The args pointcut picks out each join point where the arguments are
instances of some types. Each element in the comma-separated list is one
of four things. If it is a type name, then the argument in that position
must be an instance of that type. If it is an identifier, then that
identifier must be bound in the enclosing advice or pointcut
declaration, and so the argument in that position must be an instance of
the type of the identifier (or of any type if the identifier is typed to
Object). If it is the `*` wildcard, then any argument will match, and if
it is the special wildcard `..`, then any number of arguments will
match, just like in signature patterns. So the pointcut

[source, java]
....
args(int, .., String)
....

will pick out all join points where the first argument is an `int` and
the last is a `String`.

==== Control flow-based pointcuts

Some concerns cut across the control flow of the program. The `cflow`
and `cflowbelow` primitive pointcut designators capture join points
based on control flow.

* `cflow( Pointcut )`
* `cflowbelow( Pointcut )`

The `cflow` pointcut picks out all join points that occur between entry
and exit of each join point `P` picked out by `Pointcut`, including `P`
itself. Hence, it picks out the join points _in_ the control flow of the
join points picked out by `Pointcut`.

The `cflowbelow` pointcut picks out all join points that occur between
entry and exit of each join point `P` picked out by `Pointcut`, but not
including `P` itself. Hence, it picks out the join points _below_ the
control flow of the join points picked out by `Pointcut`.

===== Context exposure from control flows

The `cflow` and `cflowbelow` pointcuts may expose context state through
enclosed `this`, `target`, and `args` pointcuts.

Anytime such state is accessed, it is accessed through the _most recent_
control flow that matched. So the "current arg" that would be printed by
the following program is zero, even though it is in many control flows.

[source, java]
....
class Test {
  public static void main(String[] args) {
    fact(5);
  }
  static int fact(int x) {
    if (x == 0) {
      System.err.println("bottoming out");
      return 1;
    }
    else return x * fact(x - 1);
  }
}

aspect A {
  pointcut entry(int i): call(int fact(int)) && args(i);
  pointcut writing(): call(void println(String)) && ! within(A);

  before(int i): writing() && cflow(entry(i)) {
    System.err.println("Current arg is " + i);
  }
}
....

It is an error to expose such state through _negated_ control flow
pointcuts, such as within `!cflowbelow(P)`.

==== Program text-based pointcuts

While many concerns cut across the runtime structure of the program,
some must deal with the lexical structure. AspectJ allows aspects to
pick out join points based on where their associated code is defined.

* `within( TypePattern )`
* `withincode( MethodPattern )`
* `withincode( ConstructorPattern )`

The `within` pointcut picks out each join point where the code executing
is defined in the declaration of one of the types in `TypePattern`. This
includes the class initialization, object initialization, and method and
constructor execution join points for the type, as well as any join
points associated with the statements and expressions of the type. It
also includes any join points that are associated with code in a type's
nested types, and that type's default constructor, if there is one.

The `withincode` pointcuts picks out each join point where the code
executing is defined in the declaration of a particular method or
constructor. This includes the method or constructor execution join
point as well as any join points associated with the statements and
expressions of the method or constructor. It also includes any join
points that are associated with code in a method or constructor's local
or anonymous types.

==== Expression-based pointcuts

* `if( BooleanExpression )`

The if pointcut picks out join points based on a dynamic property. its
syntax takes an expression, which must evaluate to a boolean true or
false. Within this expression, the `thisJoinPoint` object is available.
So one (extremely inefficient) way of picking out all call join points
would be to use the pointcut

[source, java]
....
if(thisJoinPoint.getKind().equals("call"))
....

Note that the order of evaluation for pointcut expression components at
a join point is undefined. Writing `if` pointcuts that have side-effects
is considered bad style and may also lead to potentially confusing or
even changing behavior with regard to when or if the test code will run.

=== Signatures

One very important property of a join point is its signature, which is
used by many of AspectJ's pointcut designators to select particular join
points.

==== Methods

Join points associated with methods typically have method signatures,
consisting of a method name, parameter types, return type, the types of
the declared (checked) exceptions, and some type that the method could
be called on (below called the "qualifying type").

At a method call join point, the signature is a method signature whose
qualifying type is the static type used to _access_ the method. This
means that the signature for the join point created from the call
`((Integer)i).toString()` is different than that for the call
`((Object)i).toString()`, even if `i` is the same variable.

At a method execution join point, the signature is a method signature
whose qualifying type is the declaring type of the method.

==== Fields

Join points associated with fields typically have field signatures,
consisting of a field name and a field type. A field reference join
point has such a signature, and no parameters. A field set join point
has such a signature, but has a has a single parameter whose type is the
same as the field type.

==== Constructors

Join points associated with constructors typically have constructor
signatures, consisting of a parameter types, the types of the declared
(checked) exceptions, and the declaring type.

At a constructor call join point, the signature is the constructor
signature of the called constructor. At a constructor execution join
point, the signature is the constructor signature of the currently
executing constructor.

At object initialization and pre-initialization join points, the
signature is the constructor signature for the constructor that started
this initialization: the first constructor entered during this type's
initialization of this object.

==== Others

At a handler execution join point, the signature is composed of the
exception type that the handler handles.

At an advice execution join point, the signature is composed of the
aspect type, the parameter types of the advice, the return type (void
for all but around advice) and the types of the declared (checked)
exceptions.

=== Matching

The `withincode`, `call`, `execution`, `get`, and `set` primitive
pointcut designators all use signature patterns to determine the join
points they describe. A signature pattern is an abstract description of
one or more join-point signatures. Signature patterns are intended to
match very closely the same kind of things one would write when
declaring individual members and constructors.

Method declarations in Java include method names, method parameters,
return types, modifiers like static or private, and throws clauses,
while constructor declarations omit the return type and replace the
method name with the class name. The start of a particular method
declaration, in class `Test`, for example, might be

[source, java]
....
class C {
  public final void foo() throws ArrayOutOfBoundsException { ... }
}
....

In AspectJ, method signature patterns have all these, but most elements
can be replaced by wildcards. So

[source, java]
....
call(public final void C.foo() throws ArrayOutOfBoundsException)
....

picks out call join points to that method, and the pointcut

[source, java]
....
call(public final void *.*() throws ArrayOutOfBoundsException)
....

picks out all call join points to methods, regardless of their name name
or which class they are defined on, so long as they take no arguments,
return no value, are both `public` and `final`, and are declared to
throw ``ArrayOutOfBoundsException``s.

The defining type name, if not present, defaults to *, so another way of
writing that pointcut would be

[source, java]
....
call(public final void *() throws ArrayOutOfBoundsException)
....

The wildcard `..` indicates zero or more parameters, so

[source, java]
....
execution(void m(..))
....

picks out execution join points for void methods named `m`, of any
number of arguments, while

[source, java]
....
execution(void m(.., int))
....

picks out execution join points for void methods named `m` whose last
parameter is of type `int`.

The modifiers also form part of the signature pattern. If an AspectJ
signature pattern should match methods without a particular modifier,
such as all non-public methods, the appropriate modifier should be
negated with the `!` operator. So,

[source, java]
....
withincode(!public void foo())
....

picks out all join points associated with code in null non-public void
methods named `foo`, while

[source, java]
....
withincode(void foo())
....

picks out all join points associated with code in null void methods
named `foo`, regardless of access modifier.

Method names may contain the * wildcard, indicating any number of
characters in the method name. So

[source, java]
....
call(int *())
....

picks out all call join points to `int` methods regardless of name, but

[source, java]
....
call(int get*())
....

picks out all call join points to `int` methods where the method name
starts with the characters "get".

AspectJ uses the `new` keyword for constructor signature patterns rather
than using a particular class name. So the execution join points of
private null constructor of a class `C` defined to throw an
`ArithmeticException` can be picked out with

[source, java]
....
execution(private C.new() throws ArithmeticException)
....

==== Matching based on the declaring type

The signature-matching pointcuts all specify a declaring type, but the
meaning varies slightly for each join point signature, in line with Java
semantics.

When matching for pointcuts `withincode`, `get`, and `set`, the
declaring type is the class that contains the declaration.

When matching method-call join points, the declaring type is the static
type used to access the method. A common mistake is to specify a
declaring type for the `call` pointcut that is a subtype of the
originally-declaring type. For example, given the class

[source, java]
....
class Service implements Runnable {
  public void run() { ... }
}
....

the following pointcut

[source, java]
....
call(void Service.run())
....

would fail to pick out the join point for the code

[source, java]
....
((Runnable) new Service()).run();
....

Specifying the originally-declaring type is correct, but would pick out
any such call (here, calls to the `run()` method of any `Runnable`). In
this situation, consider instead picking out the target type:

[source, java]
....
call(void run()) && target(Service)
....

When matching method-execution join points, if the execution pointcut
method signature specifies a declaring type, the pointcut will only
match methods declared in that type, or methods that override methods
declared in or inherited by that type. So the pointcut

[source, java]
....
execution(public void Middle.*())
....

picks out all method executions for public methods returning void and
having no arguments that are either declared in, or inherited by,
`Middle`, even if those methods are overridden in a subclass of `Middle`. So
the pointcut would pick out the method-execution join point for `Sub.m()`
in this code:

[source, java]
....
class Super {
  protected void m() { /*...*/ }
}

class Middle extends Super {}

class Sub extends Middle {
  public void m() { /*...*/ }
}
....

==== Matching based on the `throws` clause

Type patterns may be used to pick out methods and constructors based on
their `throws` clauses. This allows the following two kinds of extremely
wildcarded pointcuts:

[source, java]
....
pointcut throwsMathlike():
  // each call to a method with a throws clause containing at least
  // one exception exception with "Math" in its name.
  call(* *(..) throws *..*Math*);

pointcut doesNotThrowMathlike():
  // each call to a method with a throws clause containing no
  // exceptions with "Math" in its name.
  call(* *(..) throws !*..*Math*);
....

A `ThrowsClausePattern` is a comma-separated list of ``ThrowsClausePatternItem``s, where

[source, text]
....
ThrowsClausePatternItem := [ ! ] TypeNamePattern
....

A `ThrowsClausePattern` matches the `throws` clause of any code member
signature. To match, each `ThrowsClausePatternItem` must match the
`throws` clause of the member in question. If any item doesn't match, then
the whole pattern doesn't match.

If a `ThrowsClausePatternItem` begins with `!`, then it matches a
particular `throws` clause if and only if _none_ of the types named in the
`throws` clause is matched by the `TypeNamePattern`.

If a `ThrowsClausePatternItem` does not begin with `!`, then it matches
a throws clause if and only if _any_ of the types named in the `throws`
clause is matched by the `TypeNamePattern`.

The rule for `!` matching has one potentially surprising property, in
that these two pointcuts

. `call(* *(..) throws !IOException)`
. `call(* *(..) throws (!IOException))`

will match differently on calls to

[source, java]
....
void m() throws RuntimeException, IOException {}
....

[1] will *not* match the method `m()`, because ``m``'s throws clause
declares that it `throws IOException`.

[2] *will* match the method `m()`, because ``m``'s throws clause declares that
it throws some exception which does not match `IOException`, i.e. `RuntimeException`.

=== Type patterns

Type patterns are a way to pick out collections of types and use them in
places where you would otherwise use only one type. The rules for using
type patterns are simple.

==== Exact type pattern

First, all type names are also type patterns. So `Object`,
`java.util.HashMap`, `Map.Entry`, `int` are all type patterns.

If a type pattern is an exact type - if it doesn't include a wildcard -
then the matching works just like normal type lookup in Java:

* Patterns that have the same names as primitive types (like `int`) match those
  primitive types.
* Patterns that are qualified by package names (like `java.util.HashMap`) match
  types in other packages.
* Patterns that are not qualified (like `HashMap`) match types that are resolved
  by Java's normal scope rules. So, for example, `HashMap` might match a package-level
  type in the same package or a type that have been imported with Java's `import`
  form. But it would not match `java.util.HashMap` unless the aspect were in `java.util`
  or the type had been imported.

So exact type patterns match based on usual Java scope rules.

==== Type name patterns

There is a special type name, `\*`, which is also a type pattern. `*` picks
out all types, including primitive types. So

[source, java]
....
call(void foo(*))
....

picks out all call join points to void methods named foo, taking one
argument of any type.

Type names that contain the two wildcards `\*` and `..` are also type
patterns. The `*` wildcard matches zero or more characters characters
except for `.`, so it can be used when types have a certain naming
convention. So

[source, java]
....
handler(java.util.*Map)
....

picks out the types `java.util.Map` and `java.util.java.util.HashMap`, among
others, and

[source, java]
....
handler(java.util.*)
....

picks out all types that start with `java.util.` and don't have any
more ``.``s, that is, the types in the `java.util` package, but not inner
types (such as `java.util.Map.Entry`).

The `..` wildcard matches any sequence of characters that start and
end with a `.`, so it can be used to pick out all types in any
subpackage, or all inner types. So

[source, java]
....
within(com.xerox..*)
....

picks out all join points where the code is in any declaration of a type
whose name begins with `com.xerox.`.

Type patterns with wildcards do not depend on Java's usual scope rules -
they match against all types available to the weaver, not just those
that are imported into an Aspect's declaring file.

==== Subtype patterns

It is possible to pick out all subtypes of a type (or a collection of
types) with the `+` wildcard. The `+` wildcard follows immediately a
type name pattern. So, while

[source, java]
....
call(Foo.new())
....

picks out all constructor call join points where an instance of exactly
type `Foo` is constructed,

[source, java]
....
call(Foo+.new())
....

picks out all constructor call join points where an instance of any
subtype of `Foo` (including `Foo` itself) is constructed, and the unlikely

[source, java]
....
call(*Handler+.new())
....

picks out all constructor call join points where an instance of any
subtype of any type whose name ends in `Handler` is constructed.

==== Array type patterns

A type name pattern or subtype pattern can be followed by one or more
sets of square brackets to make array type patterns. So `Object[]` is an
array type pattern, and so is `com.xerox..*[][]`, and so is `Object+[]`.

==== Type patterns

Type patterns are built up out of type name patterns, subtype patterns,
and array type patterns, and constructed with boolean operators `&&`,
`||`, and `!`. So

[source, java]
....
staticinitialization(Foo || Bar)
....

picks out the static initializer execution join points of either `Foo` or
`Bar`, and

[source, java]
....
call((Foo+ && ! Foo).new(..))
....

picks out the constructor call join points when a subtype of `Foo`, but
not `Foo` itself, is constructed.

=== Pattern Summary

Here is a summary of the pattern syntax used in AspectJ:

[source, text]
....
MethodPattern =
    [ModifiersPattern] TypePattern
    [TypePattern . ] IdPattern (TypePattern | ".." , ... )
    [ throws ThrowsPattern ]
ConstructorPattern =
    [ModifiersPattern ]
    [TypePattern . ] new (TypePattern | ".." , ...)
    [ throws ThrowsPattern ]
FieldPattern =
    [ModifiersPattern] TypePattern [TypePattern . ] IdPattern
ThrowsPattern =
    [ ! ] TypePattern , ...
TypePattern =
    IdPattern [ + ] [ [] ... ]
    | ! TypePattern
    | TypePattern && TypePattern
    | TypePattern || TypePattern
    | ( TypePattern )
IdPattern =
    Sequence of characters, possibly with special * and .. wildcards
ModifiersPattern =
    [ ! ] JavaModifier  ...
....

[[semantics-advice]]
== Advice

Each piece of advice is of the form

[source, text]
....
[ strictfp ] AdviceSpec [ throws TypeList ] : Pointcut { Body }
....

where `AdviceSpec` is one of

* `before( Formals )`
* `after( Formals ) returning [ ( Formal ) ]`
* `after( Formals ) throwing [ ( Formal ) ]`
* `after( Formals )`
* `Type around( Formals )`

and where `Formal` refers to a variable binding like those used for
method parameters, of the form `Type` `Variable-Name`, and `Formals`
refers to a comma-delimited list of `Formal`.

Advice defines crosscutting behavior. It is defined in terms of
pointcuts. The code of a piece of advice runs at every join point picked
out by its pointcut. Exactly how the code runs depends on the kind of
advice.

AspectJ supports three kinds of advice. The kind of advice determines
how it interacts with the join points it is defined over. Thus AspectJ
divides advice into that which runs *before* its join points, that which
runs *after* its join points, and that which runs *in place of (or
"around")* its join points.

While `before` advice is relatively unproblematic, there can be three
interpretations of `after` advice: After the execution of a join point
completes normally, after it throws an exception, or after it does
either one. AspectJ allows `after` advice for any of these situations:

[source, java]
....
aspect A {
  pointcut publicCall(): call(public Object *(..));

  after() returning (Object o): publicCall() {
    System.out.println("Returned normally with " + o);
  }

  after() throwing (Exception e): publicCall() {
    System.out.println("Threw an exception: " + e);
  }

  after(): publicCall(){
    System.out.println("Returned or threw an Exception");
  }
}
....

`after returning` advice may not care about its returned object, in which
case it may be written

[source, java]
....
after() returning: call(public Object *(..)) {
  System.out.println("Returned normally");
}
....

If `after returning` does expose its returned object, then the type of the
parameter is considered to be an `instanceof`-like constraint on the
advice: it will run only when the return value is of the appropriate
type.

A value is of the appropriate type if it would be assignable to a
variable of that type, in the Java sense. That is, a `byte` value is
assignable to a `short` parameter but not vice-versa, an `int` is
assignable to a `float` parameter, `boolean` values are only assignable
to `boolean` parameters, and reference types work by `instanceof`.

There are two special cases: If the exposed value is typed to `Object`,
then the advice is not constrained by that type: the actual return value
is converted to an object type for the body of the advice: `int` values
are represented as `java.lang.Integer` objects, etc, and no value (from
`void` methods, for example) is represented as `null`.

Secondly, the `null` value is assignable to a parameter `T` if the join
point _could_ return something of type `T`.

`around` advice runs in place of the join point it operates over, rather
than before or after it. Because `around` is allowed to return a value, it
must be declared with a return type, like a method.

Thus, a simple use of `around` advice is to make a particular method
constant:

[source, java]
....
aspect A {
  int around(): call(int C.foo()) {
    return 3;
  }
}
....

Within the body of `around` advice, though, the computation of the
original join point can be executed with the special syntax

[source, java]
....
proceed( ... )
....

The `proceed` form takes as arguments the context exposed by the around's
pointcut, and returns whatever the around is declared to return. So the
following around advice will double the second argument to `foo`
whenever it is called, and then halve its result:

[source, java]
....
aspect A {
  int around(int i): call(int C.foo(Object, int)) && args(i) {
    int newi = proceed(i*2)
    return newi/2;
  }
}
....

If the return value of `around` advice is typed to `Object`, then the
result of proceed is converted to an object representation, even if it
is originally a primitive value. And when the advice returns an `Object`
value, that value is converted back to whatever representation it was
originally. So another way to write the doubling and halving advice is:

[source, java]
....
aspect A {
  Object around(int i): call(int C.foo(Object, int)) && args(i) {
    Integer newi = (Integer) proceed(i*2)
    return new Integer(newi.intValue() / 2);
  }
}
....

Any occurence of `proceed(..)` within the body of around advice is
treated as the special `proceed` form (even if the aspect defines a method
named `proceed`), unless a target other than the aspect instance is
specified as the recipient of the call. For example, in the following
program the first call to `proceed` will be treated as a method call to
the `ICanProceed` instance, whereas the second call to `proceed` is
treated as the special `proceed` form.

[source, java]
....
aspect A {
  Object around(ICanProceed canProceed) : execution(* *(..)) && this(canProceed) {
    canProceed.proceed();        // a method call
    return proceed(canProceed);  // the special proceed form
  }

  private Object proceed(ICanProceed canProceed) {
    // this method cannot be called from inside the body of around advice
    // in the aspect
  }
}
....

In all kinds of advice, the parameters of the advice behave exactly like
method parameters. In particular, assigning to any parameter affects
only the value of the parameter, not the value that it came from. This
means that

[source, java]
....
aspect A {
  after() returning (int i): call(int C.foo()) {
    i = i * 2;
  }
}
....

will _not_ double the returned value of the advice. Rather, it will
double the local parameter. Changing the values of parameters or return
values of join points can be done by using `around` advice.

With `proceed(..)` it is possible to change the values used by
less-precedent advice and the underlying join point by supplying
different values for the variables. For example, this aspect replaces
the string bound to `s` in the named pointcut `privateData`:

[source, java]
....
aspect A {
  Object around(String s): MyPointcuts.privateData(s) {
    return proceed("private data");
  }
}
....

If you replace an argument to `proceed(..)`, you can cause a
`ClassCastException` at runtime when the argument refers to a supertype
of the actual type and you do not supply a reference of the actual type.
In the following aspect, the around advice replaces the declared target
`List` with an `ArrayList`. This is valid code at compile-time since the
types match.

[source, java]
....
import java.util.*;

aspect A {
  Object around(List list): call(* List+.*()) && target(list) {
    return proceed(new ArrayList());
  }
}
....

But imagine a simple program where the actual target is `LinkedList`. In
this case, the advice would cause a `ClassCastException` at runtime, and
`peek()` is not declared in `ArrayList`.

[source, java]
....
public class Test {
  public static void main(String[] args) {
    new LinkedList().peek();
  }
}
....

The `ClassCastException` can occur even in situations where it appears
to be unnecessary, e.g., if the program is changed to call `size()`,
declared in `List`:

[source, java]
....
public class Test {
  public static void main(String[] args) {
    new LinkedList().size();
  }
}
....

There will still be a `ClassCastException` because it is impossible to
prove that there won't be a runtime binary-compatible change in the
hierarchy of `LinkedList` or some other advice on the join point that
requires a `LinkedList`.

=== Advice modifiers

The `strictfp` modifier is the only modifier allowed on advice, and it
has the effect of making all floating-point expressions within the
advice be FP-strict.

=== Advice and checked exceptions

An advice declaration must include a `throws` clause listing the checked
exceptions the body may throw. This list of checked exceptions must be
compatible with each target join point of the advice, or an error is
signalled by the compiler.

For example, in the following declarations:

[source, java]
....
import java.io.FileNotFoundException;

class C {
  int i;
  int getI() { return i; }
}

aspect A {
  before(): get(int C.i) {
    throw new FileNotFoundException();
  }

  before() throws FileNotFoundException: get(int C.i) {
    throw new FileNotFoundException();
  }
}
....

both pieces of advice are illegal. The first because the body throws an
undeclared checked exception, and the second because field get join
points cannot throw ``FileNotFoundException``s.

The exceptions that each kind of join point in AspectJ may throw are:

method call and execution::
  the checked exceptions declared by the target method's `throws` clause.
constructor call and execution::
  the checked exceptions declared by the target constructor's `throws` clause.
field get and set::
  no checked exceptions can be thrown from these join points.
exception handler execution::
  the exceptions that can be thrown by the target exception handler.
static initializer execution::
  no checked exceptions can be thrown from these join points.
pre-initialization and initialization::
  any exception that is in the `throws` clause of all constructors of the initialized class.
advice execution::
  any exception that is in the `throws` clause of the advice.

=== Advice precedence

Multiple pieces of advice may apply to the same join point. In such
cases, the resolution order of the advice is based on advice precedence.

==== Determining precedence

There are a number of rules that determine whether a particular piece of
advice has precedence over another when they advise the same join point.

If the two pieces of advice are defined in different aspects, then there
are three cases:

* If aspect `A` is matched earlier than aspect `B` in some `declare precedence`
  form, then all advice in concrete aspect `A` has precedence over all
  advice in concrete aspect `B` when they are on the same join point.
* Otherwise, if aspect `A` is a subaspect of aspect `B`, then all advice
  defined in `A` has precedence over all advice defined in `B`. So, unless
  otherwise specified with `declare precedence`, advice in a subaspect has
  precedence over advice in a superaspect.
* Otherwise, if two pieces of advice are defined in two different
  aspects, it is undefined which one has precedence.

If the two pieces of advice are defined in the same aspect, then there
are two cases:

* If either are `after` advice, then the one that appears later in the aspect has precedence
  over the one that appears earlier.
* Otherwise, then the one that appears earlier in the aspect has
  precedence over the one that appears later.

These rules can lead to circularity, such as

[source, java]
....
aspect A {
  before(): execution(void main(String[] args)) {}
  after():  execution(void main(String[] args)) {}
  before(): execution(void main(String[] args)) {}
}
....

such circularities will result in errors signalled by the compiler.

==== Effects of precedence

At a particular join point, advice is ordered by precedence.

A piece of `around` advice controls whether advice of lower precedence
will run by calling `proceed`. The call to `proceed` will run the advice
with next precedence, or the computation under the join point if there
is no further advice.

A piece of `before` advice can prevent advice of lower precedence from
running by throwing an exception. If it returns normally, however, then
the advice of the next precedence, or the computation under the join
pint if there is no further advice, will run.

Running `after returning` advice will run the advice of next precedence,
or the computation under the join point if there is no further advice.
Then, if that computation returned normally, the body of the advice will
run.

Running `after throwing` advice will run the advice of next precedence,
or the computation under the join point if there is no further advice.
Then, if that computation threw an exception of an appropriate type, the
body of the advice will run.

Running `after` advice will run the advice of next precedence, or the
computation under the join point if there is no further advice. Then the
body of the advice will run.

=== Reflective access to the join point

Three special variables are visible within bodies of advice and within
`if()` pointcut expressions: `thisJoinPoint`, `thisJoinPointStaticPart`,
and `thisEnclosingJoinPointStaticPart`. Each is bound to an object that
encapsulates some of the context of the advice's current or enclosing
join point. These variables exist because some pointcuts may pick out
very large collections of join points. For example, the pointcut

[source, java]
....
pointcut publicCall(): call(public * *(..));
....

picks out calls to many methods. Yet the body of advice over this
pointcut may wish to have access to the method name or parameters of a
particular join point.

* `thisJoinPoint` is bound to a complete join point object.

* `thisJoinPointStaticPart` is bound to a part of the join point object
  that includes less information, but for which no memory allocation is
  required on each execution of the advice. It is equivalent to
  `thisJoinPoint.getStaticPart()`.

* `thisEnclosingJoinPointStaticPart` is bound to the static part of the
  join point enclosing the current join point. Only the static part of
  this enclosing join point is available through this mechanism.

Standard Java reflection uses objects from the `java.lang.reflect`
hierarchy to build up its reflective objects. Similarly, AspectJ join
point objects have types in a type hierarchy. The type of objects bound
to `thisJoinPoint` is `org.aspectj.lang.JoinPoint`, while
`thisStaticJoinPoint` is bound to objects of interface type
`org.aspectj.lang.JoinPoint.StaticPart`.

[[semantics-declare]]
== Static crosscutting

Advice declarations change the behavior of classes they crosscut, but do
not change their static type structure. For crosscutting concerns that
do operate over the static structure of type hierarchies, AspectJ
provides inter-type member declarations and other `declare` forms.

=== Inter-type member declarations

AspectJ allows the declaration of members by aspects that are associated
with other types.

An inter-type method declaration looks like

* `[ Modifiers ] Type OnType . Id ( Formals ) [ ThrowsClause ] { Body }`
* `abstract [ Modifiers ] Type OnType . Id ( Formals ) [ ThrowsClause ] ;`

The effect of such a declaration is to make `OnType` support the new
method. Even if `OnType` is an interface. Even if the method is neither
public nor abstract. So the following is legal AspectJ code:

[source, java]
....
interface Iface {}

aspect A {
  private void Iface.m() {
    System.err.println("I'm a private method on an interface");
  }

  void worksOnI(Iface iface) {
    // calling a private method on an interface
    iface.m();
  }
}
....

An inter-type constructor declaration looks like

* `[ Modifiers ] OnType . new ( Formals ) [ ThrowsClause ] { Body }`

The effect of such a declaration is to make `OnType` support the new
constructor. It is an error for `OnType` to be an interface.

Inter-type declared constructors cannot be used to assign a value to a
final variable declared in `OnType`. This limitation significantly
increases the ability to both understand and compile the `OnType` class
and the declaring aspect separately.

Note that in the Java language, classes that define no constructors have
an implicit no-argument constructor that just calls `super()`. This
means that attempting to declare a no-argument inter-type constructor on
such a class may result in a conflict, even though it _looks_ like no
constructor is defined.

An inter-type field declaration looks like one of

* `[ Modifiers ] Type OnType . Id = Expression ;`
* `[ Modifiers ] Type OnType . Id ;`

The effect of such a declaration is to make `OnType` support the new
field. Even if `OnType` is an interface. Even if the field is neither
public, nor static, nor final.

The initializer, if any, of an inter-type field declaration runs before
the class-local initializers defined in its target class.

Any occurrence of the identifier `this` in the body of an inter-type
constructor or method declaration, or in the initializer of an
inter-type field declaration, refers to the `OnType` object rather than
to the aspect type; it is an error to access `this` in such a position
from a `static` inter-type member declaration.

=== Access modifiers

Inter-type member declarations may be `public` or `private`, or have default
(package-protected) visibility. AspectJ does not provide protected
inter-type members.

The access modifier applies in relation to the aspect, not in relation
to the target type. So a private inter-type member is visible only from
code that is defined within the declaring aspect. A default-visibility
inter-type member is visible only from code that is defined within the
declaring aspect's package.

Note that a declaring a private inter-type method (which AspectJ
supports) is very different from inserting a private method declaration
into another class. The former allows access only from the declaring
aspect, while the latter would allow access only from the target type.
Java serialization, for example, uses the presense of a private method
`void writeObject(ObjectOutputStream)` for the implementation of
`java.io.Serializable`. A private inter-type declaration of that method
would not fulfill this requirement, since it would be private to the
aspect, not private to the target type.

The access modifier of abstract inter-type methods has one constraint:
It is illegal to declare an abstract non-public inter-type method on a
public interface. This is illegal because it would say that a public
interface has a constraint that only non-public implementors must
fulfill. This would not be compatible with Java's type system.

=== Conflicts

Inter-type declarations raise the possibility of conflicts among locally
declared members and inter-type members. For example, assuming
`otherPackage` is not the package containing the aspect `A`, the code

[source, java]
....
aspect A {
  private Registry otherPackage.onType.r;

  public void otherPackage.onType.register(Registry r) {
    r.register(this);
    this.r = r;
  }
}
....

declares that `onType` in `otherPackage` has a field `r`. This field,
however, is only accessible from the code inside of aspect `A`. The
aspect also declares that `onType` has a method "`register`", but makes
this method accessible from everywhere.

If `onType` already defines a private or package-protected field `r`,
there is no conflict: The aspect cannot see such a field, and no code in
`otherPackage` can see the inter-type `r`.

If `onType` defines a public field `r`, there is a conflict: The
expression

[source, java]
....
this.r = r
....

is an error, since it is ambiguous whether the private inter-type `r`
or the public locally-defined `r` should be used.

If `onType` defines a method `register(Registry)` there is a conflict,
since it would be ambiguous to any code that could see such a defined
method which `register(Registry)` method was applicable.

Conflicts are resolved as much as possible as per Java's conflict
resolution rules:

* A subclass can inherit multiple fields from its superclasses, all with the
  same name and type. However, it is an error to have an ambiguous reference
  to a field.
* A subclass can only inherit multiple methods with the same name and argument
  types from its superclasses if only zero or one of them is concrete (i.e., all
  but one is abstract, or all are abstract).

Given a potential conflict between inter-type member declarations in
different aspects, if one aspect has precedence over the other its
declaration will take effect without any conflict notice from compiler.
This is true both when the precedence is declared explicitly with
`declare precedence` as well as when when sub-aspects implicitly have
precedence over their super-aspect.

=== Extension and Implementation

An aspect may change the inheritance hierarchy of a system by changing
the superclass of a type or adding a superinterface onto a type, with
the `declare parents` form.

* `declare parents: TypePattern extends Type ;`
* `declare parents: TypePattern implements TypeList ;`

For example, if an aspect wished to make a particular class runnable, it
might define appropriate inter-type `void
        run()` method, but it should also declare that the class
fulfills the `Runnable` interface. In order to implement the methods in
the `Runnable` interface, the inter-type `run()` method must be public:

[source, java]
....
aspect A {
  declare parents: SomeClass implements Runnable;

  public void SomeClass.run() { ... }
}
....

=== Interfaces with members

Through the use of inter-type members, interfaces may now carry
(non-public-static-final) fields and (non-public-abstract) methods that
classes can inherit. Conflicts may occur from ambiguously inheriting
members from a superclass and multiple superinterfaces.

Because interfaces may carry non-static initializers, each interface
behaves as if it has a zero-argument constructor containing its
initializers. The order of super-interface instantiation is observable.
We fix this order with the following properties: A supertype is
initialized before a subtype, initialized code runs only once, and the
initializers for a type's superclass are run before the initializers for
its superinterfaces. Consider the following hierarchy where {`Object`,
`C`, `D`, `E`} are classes, {`M`, `N`, `O`, `P`, `Q`} are interfaces.

[source, text]
....
Object  M   O
     \ / \ /
      C   N   Q
       \ /   /
        D   P
         \ /
          E
....

when a new `E` is instantiated, the initializers run in this order:

[source, text]
....
Object M C O N D Q P E
....

=== Warnings and Errors

An aspect may specify that a particular join point should never be
reached.

* `declare error: Pointcut : String ;`
* `declare warning: Pointcut : String ;`

If the compiler determines that a join point in `Pointcut` could
possibly be reached, then it will signal either an error or warning, as
declared, using the `String` for its message.

=== Softened exceptions

An aspect may specify that a particular kind of exception, if thrown at
a join point, should bypass Java's usual static exception checking
system and instead be thrown as a `org.aspectj.lang.SoftException`,
which is subtype of `RuntimeException` and thus does not need to be
declared.

* `declare soft: Type : Pointcut ;`

For example, the aspect

[source, java]
....
aspect A {
  declare soft: Exception: execution(void main(String[] args));
}
....

Would, at the execution join point, catch any `Exception` and rethrow a
`org.aspectj.lang.SoftException` containing original exception.

This is similar to what the following advice would do

[source, java]
....
aspect A {
  void around() execution(void main(String[] args)) {
    try { proceed(); }
    catch (Exception e) {
      throw new org.aspectj.lang.SoftException(e);
    }
  }
}
....

except, in addition to wrapping the exception, it also affects Java's
static exception checking mechanism.

Like advice, the declare soft form has no effect in an abstract aspect
that is not extended by a concreate aspect. So the following code will
not compile unless it is compiled with an extending concrete aspect:

[source, java]
....
abstract aspect A {
  abstract pointcut softeningPC();

  before() : softeningPC() {
    Class.forName("FooClass"); // error:  uncaught ClassNotFoundException
  }

  declare soft : ClassNotFoundException : call(* Class.*(..));
}
....

[[advice-precedence-cross]]
=== Advice Precedence

An aspect may declare a precedence relationship between concrete aspects
with the `declare precedence` form:

* `declare precedence : TypePatternList ;`

This signifies that if any join point has advice from two concrete
aspects matched by some pattern in `TypePatternList`, then the
precedence of the advice will be the order of in the list.

In `TypePatternList`, the wildcard `*` can appear at most once, and it
means "any type not matched by any other pattern in the list".

For example, the constraints that (1) aspects that have Security as part
of their name should have precedence over all other aspects, and (2) the
Logging aspect (and any aspect that extends it) should have precedence
over all non-security aspects, can be expressed by:

[source, java]
....
declare precedence: *..*Security*, Logging+, *;
....

For another example, the `CountEntry` aspect might want to count the entry
to methods in the current package accepting a Type object as its first
argument. However, it should count all entries, even those that the
aspect `DisallowNulls` causes to throw exceptions. This can be
accomplished by stating that `CountEntry` has precedence over
`DisallowNulls`. This declaration could be in either aspect, or in
another, ordering aspect:

[source, java]
....
aspect Ordering {
  declare precedence: CountEntry, DisallowNulls;
}

aspect DisallowNulls {
  pointcut allTypeMethods(Type obj): call(* *(..)) && args(obj, ..);
  before(Type obj):  allTypeMethods(obj) {
    if (obj == null) throw new RuntimeException();
  }
}

aspect CountEntry {
  pointcut allTypeMethods(Type obj): call(* *(..)) && args(obj, ..);
  static int count = 0;
  before():  allTypeMethods(Type) {
    count++;
  }
}
....

==== Various cycles

It is an error for any aspect to be matched by more than one TypePattern
in a single decare precedence, so:

[source, java]
....
declare precedence:  A, B, A ;  // error
....

However, multiple declare precedence forms may legally have this kind of
circularity. For example, each of these declare precedence is perfectly
legal:

[source, java]
....
declare precedence: B, A;
declare precedence: A, B;
....

And a system in which both constraints are active may also be legal, so
long as advice from `A` and `B` don't share a join point. So this is an
idiom that can be used to enforce that `A` and `B` are strongly independent.

==== Applies to concrete aspects

Consider the following library aspects:

[source, java]
....
abstract aspect Logging {
  abstract pointcut logged();

  before(): logged() {
    System.err.println("thisJoinPoint: " + thisJoinPoint);
  }
}

abstract aspect MyProfiling {
  abstract pointcut profiled();

  Object around(): profiled() {
    long beforeTime = System.currentTimeMillis();
    try {
      return proceed();
    } finally {
      long afterTime = System.currentTimeMillis();
      addToProfile(thisJoinPointStaticPart, afterTime - beforeTime);
    }
  }

  abstract void addToProfile(
    org.aspectj.JoinPoint.StaticPart jp,
    long elapsed
  );
}
....

In order to use either aspect, they must be extended with concrete
aspects, say, MyLogging and MyProfiling. Because advice only applies
from concrete aspects, the declare precedence form only matters when
declaring precedence with concrete aspects. So

[source, java]
....
declare precedence: Logging, Profiling;
....

has no effect, but both

[source, java]
....
declare precedence: MyLogging, MyProfiling;
declare precedence: Logging+, Profiling+;
....

are meaningful.

=== Statically determinable pointcuts

Pointcuts that appear inside of `declare` forms have certain
restrictions. Like other pointcuts, these pick out join points, but they
do so in a way that is statically determinable.

Consequently, such pointcuts may not include, directly or indirectly
(through user-defined pointcut declarations) pointcuts that discriminate
based on dynamic (runtime) context. Therefore, such pointcuts may not be
defined in terms of

* `cflow`
* `cflowbelow`
* `this`
* `target`
* `args`
* `if`

all of which can discriminate on runtime information.

[[semantics-aspects]]
== Aspects

An aspect is a crosscutting type defined by the `aspect` declaration.

=== Aspect Declaration

The `aspect` declaration is similar to the `class` declaration in that
it defines a type and an implementation for that type. It differs in a
number of ways:

==== Aspect implementation can cut across other types

In addition to normal Java class declarations such as methods and
fields, aspect declarations can include AspectJ declarations such as
advice, pointcuts, and inter-type declarations. Thus, aspects contain
implementation declarations that can can cut across other types
(including those defined by other aspect declarations).

==== Aspects are not directly instantiated

Aspects are not directly instantiated with a new expression, with
cloning, or with serialization. Aspects may have one constructor
definition, but if so it must be of a constructor taking no arguments
and throwing no checked exceptions.

==== Nested aspects must be `static`

Aspects may be defined either at the package level, or as a `static`
nested aspect -- that is, a `static` member of a class, interface, or
aspect. If it is not at the package level, the aspect _must_ be defined
with the `static` keyword. Local and anonymous aspects are not allowed.

=== Aspect Extension

To support abstraction and composition of crosscutting concerns, aspects
can be extended in much the same way that classes can. Aspect extension
adds some new rules, though.

==== Aspects may extend classes and implement interfaces

An aspect, abstract or concrete, may extend a class and may implement a
set of interfaces. Extending a class does not provide the ability to
instantiate the aspect with a new expression: The aspect may still only
define a null constructor.

==== Classes may not extend aspects

It is an error for a class to extend or implement an aspect.

==== Aspects extending aspects

Aspects may extend other aspects, in which case not only are fields and
methods inherited but so are pointcuts. However, aspects may only extend
abstract aspects. It is an error for a concrete aspect to extend another
concrete aspect.

=== Aspect instantiation

Unlike class expressions, aspects are not instantiated with `new`
expressions. Rather, aspect instances are automatically created to cut
across programs. A program can get a reference to an aspect instance
using the static method `aspectOf(..)`.

Because advice only runs in the context of an aspect instance, aspect
instantiation indirectly controls when advice runs.

The criteria used to determine how an aspect is instantiated is
inherited from its parent aspect. If the aspect has no parent aspect,
then by default the aspect is a singleton aspect. How an aspect is
instantiated controls the form of the `aspectOf(..)` method defined on
the concrete aspect class.

==== Singleton Aspects

* `aspect Id { ... }`
* `aspect Id issingleton() { ... }`

By default (or by using the modifier `issingleton()`) an aspect has
exactly one instance that cuts across the entire program. That instance
is available at any time during program execution from the static method
`aspectOf()` automatically defined on all concrete aspects -- so, in the
above examples, `A.aspectOf()` will return ``A``'s instance. This aspect
instance is created as the aspect's classfile is loaded.

Because the an instance of the aspect exists at all join points in the
running of a program (once its class is loaded), its advice will have a
chance to run at all such join points.

(In actuality, one instance of the aspect `A` is made for each version of
the aspect `A`, so there will be one instantiation for each time `A` is
loaded by a different classloader.)

==== Per-object aspects

* `aspect Id perthis( Pointcut ) { ... }`
* `aspect Id pertarget( Pointcut ) { ... }`

If an aspect `A` is defined `perthis(Pointcut)`, then one object of type `A`
is created for every object that is the executing object (i.e., `this`)
at any of the join points picked out by `Pointcut`. The advice defined
in `A` will run only at a join point where the currently executing object
has been associated with an instance of `A`.

Similarly, if an aspect `A` is defined `pertarget(Pointcut)`, then one
object of type `A` is created for every object that is the target object
of the join points picked out by `Pointcut`. The advice defined in `A`
will run only at a join point where the target object has been
associated with an instance of `A`.

In either case, the static method call `A.aspectOf(Object)` can be used
to get the aspect instance (of type `A`) registered with the object. Each
aspect instance is created as early as possible, but not before reaching
a join point picked out by `Pointcut` where there is no associated
aspect of type `A`.

Both `perthis` and `pertarget` aspects may be affected by code the
AspectJ compiler controls, as discussed in the xref:implementation.adoc#implementation[Implementation Notes]
appendix.

==== Per-control-flow aspects

* `aspect Id percflow( Pointcut ) { ... }`
* `aspect Id percflowbelow( Pointcut ) { ... }`

If an aspect `A` is defined `percflow(Pointcut)` or
`percflowbelow(Pointcut)`, then one object of type `A` is created for each
flow of control of the join points picked out by `Pointcut`, either as
the flow of control is entered, or below the flow of control,
respectively. The advice defined in `A` may run at any join point in or
under that control flow. During each such flow of control, the static
method `A.aspectOf()` will return an object of type `A`. An instance of
the aspect is created upon entry into each such control flow.

==== Aspect instantiation and advice

All advice runs in the context of an aspect instance, but it is possible
to write a piece of advice with a pointcut that picks out a join point
that must occur before asopect instantiation. For example:

[source, java]
....
public class Client
{
  public static void main(String[] args) {
    Client c = new Client();
  }
}

aspect Watchcall {
  pointcut myConstructor(): execution(new(..));

  before(): myConstructor() {
    System.err.println("Entering Constructor");
  }
}
....

The before advice should run before the execution of all constructors in
the system. It must run in the context of an instance of the Watchcall
aspect. The only way to get such an instance is to have Watchcall's
default constructor execute. But before that executes, we need to run
the before advice...

There is no general way to detect these kinds of circularities at
compile time. If advice runs before its aspect is instantiated, AspectJ
will throw a
xref:../runtime-api/org/aspectj/lang/NoAspectBoundException.html[`org.aspectj.lang.NoAspectBoundException`].

=== Aspect privilege

* `privileged aspect Id { ... }`

Code written in aspects is subject to the same access control rules as
Java code when referring to members of classes or aspects. So, for
example, code written in an aspect may not refer to members with default
(package-protected) visibility unless the aspect is defined in the same
package.

While these restrictions are suitable for many aspects, there may be
some aspects in which advice or inter-type members needs to access
private or protected resources of other types. To allow this, aspects
may be declared `privileged`. Code in priviliged aspects has access to
all members, even private ones.

[source, java]
....
class C {
  private int i = 0;
  void incI(int x) { i = i+x; }
}

privileged aspect A {
  static final int MAX = 1000;

  before(int x, C c): call(void C.incI(int)) && target(c) && args(x) {
    if (c.i+x > MAX) throw new RuntimeException();
  }
}
....

In this case, if `A` had not been declared `privileged`, the field reference
`c.i` would have resulted in an error signaled by the compiler.

If a privileged aspect can access multiple versions of a particular
member, then those that it could see if it were not privileged take
precedence. For example, in the code

[source, java]
....
class C {
  private int i = 0;
  void foo() { }
}

privileged aspect A {
  private int C.i = 999;

  before(C c): call(void C.foo()) target(c) {
    System.out.println(c.i);
  }
}
....

``A``'s private inter-type field `C.i`, initially bound to 999, will be
referenced in the body of the advice in preference to ``C``'s privately
declared field, since `A` would have access to its own inter-type
fields even if it were not privileged.

Note that a privileged aspect can access private inter-type declarations
made by other aspects, since they are simply considered private members
of that other aspect.