Child pages
  • AspectWerkz Pattern Language

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Wiki Markup
{HTMLcomment:hidden}
examples using tc config-file elements would be useful
{HTMLcomment}

h1. AspectWerkz Pattern Language

...


{toc

...

:maxLevel

...

=2

...

|minLevel

...

Join point selection pattern language

...

=2}

AspectWerkz supports a fine-grained pattern language for

...

 selecting join points

...

Table of Contents
minLevel3
indent20px
styledisc

Wildcards

You can utilize two types of wildcards when constructing your patterns:

* - which is used as a regular wildcard. Matches for example only one package level or one method parameter. When used to match a package name, matches at least one character. Else match zero or more character.

.. - used either to match any sequence of characters that start and end with a "." (so it can be used to pick out all types in any subpackage) or in method selectors to match as many parameters as possible.

For example org.codehaus..* will match all classes in all subpackages starting from org.codehaus.

...

. This is useful in Terracotta XML configuration elements in which a number of related abstractions must be selected. Instead of explicitly naming each member of the classes, methods, or fields required, an AspectWerkz pattern can be used in the configuration element to cover sets of related abstractions.

h3. Wildcards
You can utilize two types of wildcards when constructing your patterns: 

 {{*}} - which is used as a regular wildcard. Matches for example only one package level or one method parameter. When used to match a package name, matches at least one character. Else match zero or more character. 

 {{..}} - used either to match any sequence of characters that start and end with a "." (so it can be used to pick out all types in any subpackage) or in method selectors to match as many parameters as possible. 

For example {{org.codehaus..*}} will match all classes in all subpackages starting from {{org.codehaus}}.

 {{* method(..)}} will match all methods with any number of parameters. 
Note: you can only use the {{..}} wildcard as the "last" thing specified. I.e. this is not possible: {{foo.bar..test.MyClass}}, but this is: {{foo.bar..}}. The same thing holds for method parameters.

...

 

Another specific character to express inheritance based matching will be presented further. 

h3.

...

 Combining the patterns

...


The patterns normally consists of a combination of a class and a method pattern or a class and a field pattern.

...

 

Example of a full method pattern:

...

 

{{<annotations> <modifiers> <return_type_pattern> <package_and_class_pattern>.<method_name_pattern>(<parameter_type_patterns>)

...

}} 

Example of a full field pattern:

...

 

{{<annotations> <modifiers> <field_type_pattern> <package_and_class_pattern>.<field_name_pattern>

...

}}

Example of a full class pattern:

...

 

{{<annotations> <modifiers> <package_and_class_pattern>

...

Class selections

The classes are selected by specifying a pattern that consists of:

  • the annotations
  • the modifiers
  • the full name of the class

All class patterns must follow this structure:

<annotations> <modifiers> <full_class_name>

For the class selections specify the full package name of the class along with some wildcards.

Examples

foo.bar.*

...

}}

h3. Class selections
The classes are selected by specifying a pattern that consists of: 

* the annotations 
* the modifiers 
* the full name of the class 

All class patterns must follow this structure: 

{{<annotations> <modifiers> <full_class_name>}}

For the class selections specify the full package name of the class along with some wildcards. 

h4. Examples

{{foo.bar.*}} 
  - will match {{foo.bar.FooBar2}} 
  - as well as {{foo.bar.FooBear}} 
  - but not {{foo.bar.subpackage.FooMouse

...

}}

{{foo.*.FooBar

...

}} 
  - will match {{foo.bar.FooBar

...

}} 
  - as well as {{foo.bear.FooBar

...

}} 
  - but not {{foo.bear.FooBear

...

}} 

{{foo.\*.FooB

...

\*}} 
  - will match {{foo.bar.FooBar2

...

}} 
  - as well as {{foo.bear.FooBear

...

}} 
  - as well as {{foo.bear.FooB

...

}}

{{public foo.bar.*

...

}} 
  - will match {{public static final foo.bar.FooBar

...

}}
  - as well as {{public static foo.bar.FooBar

...

}} 
  - but not {{static foo.bar.FooBar}} or {{private foo.bar.FooBar

...

}}

{{@Session foo.bar.*

...

}}
 - will match {{@Session foo.bar.FooBar

...

}} 
 - but not {{foo.bar.FooBar}} or {{private foo.bar.FooBar

...

}}

{{foo..

...

  • will match all classes in all packages starting with foo

Method selections

The methods are selected by specifying a pattern that consists of:

  • the annotations
  • the modifiers
  • the return type
  • the full name of the method (including class and package)
  • the parameter types

All method patterns must follow this structure:

...

}} 
  - will match all classes in all packages starting with foo

h3. Method selections

The methods are selected by specifying a pattern that consists of: 

* the annotations 
* the modifiers 
* the return type 
* the full name of the method (including class and package) 
* the parameter types 

All method patterns must follow this structure: 

<annotations> <modifiers> <return_type> <full_method_name>(<parameter_types>)

...

Examples

...

 

h4. Examples 

{{int foo.*.Bar.method()

...

}} 
 - will match {{int method()

...

}}
 - but not {{int method(int i)

...

}}

{{int \*.method\(\*

...

\)}}
 - will match {{int Foo.method(int i)

...

}}
 - but not {{int Foo.method()

...

}} 
 - and not {{int apackage.Foo.method(int i)

...

}}

{{* method(..)

...

}} 
 - will match {{void Foo.method()

...

}}
 - as well as {{void apackage.Bar.method(int[] i)

...

}}

{{int foo.\*.\*.method(*,int)

...

}} 
 - will match {{int method(String s, int i)

...

}} 
 - as well as {{int method(int i1, int i2)

...

}}

{{int foo.*.Bar.method(..)

...

}} 
 - will match {{int method()

...

}}
 - as well as {{int method(String s, int i)

...

}} 
 - as well as {{int method(int i, double d, String s, Object o)

...

}}

{{int foo.*.Bar.method(int,..)

...

}} 
 - will match {{int method(int)

...

}}
 - as well as {{int method(int i, String s)

...

}} 
 - as well as {{int method(int i, double d, String s, Object o)

...

}}

{{int foo.\*.Bar.method(java.lang.\*)

...

}} 
 - will match {{int method(String s)

...

}} 
 - as well as {{int method(StringBuffer sb)

...

}}

{{int foo.\*.Bar.me\*o\*()

...

}} 
 - will match {{int method()

...

}} 
 - as well as {{int metamorphosis()}} and {{int meo()

...

}} 
 - but not {{int me()

...

}}

{{\* foo.\*.Bar.method()

...

}} 
 - will match {{int method()

...

}} 
 - as well as {{java.lang.String method()

...

}}

{{java.lang.\* foo.\*.Bar.method()

...

}} 
 - will match {{java.lang.String Bar.method()

...

}} 
 - as well as {{java.lang.StringBuffer Bar.method()

...

}}

{{static int foo.*.Bar.method()

...

}}
 - will match {{static int method()

...

}} 
 - but not {{int method(int i)

...

}}

{{@Transaction \* foo.\*.\*.\*(..)

...

}}
 - will match {{@Transaction int method()

...

}} 
 - but not {{void method(int i)

...

Constructor selections

The constructors are selected by specifying a pattern that consists of:

  • the annotations
  • the modifiers
  • the fully qualified name of the class (including package) plus the word 'new' as constructor name
  • the parameter types

All the patterns must follow this structure:

...

}}


h3. Constructor selections

The constructors are selected by specifying a pattern that consists of: 

* the annotations 
* the modifiers 
* the fully qualified name of the class (including package) plus the word 'new' as constructor name 
* the parameter types 

All the patterns must follow this structure: 

{{<annotations> <modifiers> <className>.new(<parameter_types>)

...

Note
DSO is not using constructor selectors and to match on constructors you should use method selector for __INIT__ method instead. So instead of
}}

{note}
DSO is not using constructor selectors and to match on constructors you should use method selector for {{\_\_INIT\_\_}} method instead. So instead of {{Foo.new(..)}} use {{\* Foo.\_\_INIT\_\_(..)

Examples

}}
{note}

h4. Examples 

{{foo.\*.Bar.new()

...

}} 
 - will match {{new Bar()

...


 - but not {{new Bar(int i)

...

}}

{{\* new(..)

...

}} 
 - will match {{new Foo()

...

}} 
 - as well as {{new apackage.Bar(int[] i)

...

}}

{{\*.new(String)

...

}} 
 - will match {{new Foo(String name)}} and {{new Bar(String name)

...

}} 
 - but not {{new Foo()

...

Field selections

Fields are selected by specifying a pattern that consists of:

  • the annotations
  • the modifiers
  • the field type
  • the full name of the field (including class and package)

All field patterns must follow this structure:

<annotations> <modifiers> <field_type> <full_field_name>

Note

Note that DSO currently doesn't support selection of excluded or transient fields based on annotations.

Examples

...

}}


h3. Field selections

Fields are selected by specifying a pattern that consists of: 

* the annotations 
* the modifiers 
* the field type 
* the full name of the field (including class and package) 

All field patterns must follow this structure: 

{{<annotations> <modifiers> <field_type> <full_field_name>}}

{note}
Note that DSO currently doesn't support selection of excluded or transient fields based on annotations.
{note}

h4. Examples 

{{int foo.\*.Bar.m_foo

...

  • will match int m_foo
  • but not int s_foo or long m_foo

* m_field

  • will match int Foo.m_field
  • as well as int[] apackage.Bar.field

...

}} 
 - will match {{int m\_foo}} 
 - but not {{int s\_foo}} or {{long m\_foo}}

{{\* m_field}} 
 - will match {{int Foo.m\_field}} 
 - as well as {{int[] apackage.Bar.field}}

{{\* foo.\*.Bar.m\_foo

...

}}
 - will match {{int m\_foo}} 
 - as well as {{java.lang.String m\_foo

...

}}

{{java.lang.\* foo.\*.Bar.m\_foo

...

}}
 - will match {{java.lang.String m\_foo

...

}} 
 - as well as {{java.lang.StringBuffer m\_foo

...

}}

{{int foo.\*.Bar.m_

...

\*}} 
 - will match {{int m_foo

...

}}
 - as well as {{int m_bar

...

}}

{{int foo.\*.Bar.m_\*oo

...

\*}}
 - will match {{int m_foo

...

}}
 - as well as {{int m_looser

...

}} 
 - as well as {{int m_oo

...

}}


{anchor:subtype-patterns

...

Subtype patterns

It is possible to pick out all subtypes of a type with the "+" wildcard. The "+" wildcard follows immediately a type name pattern. So, while

* foo.Bar.*(..)

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

* foo.Bar+.*(..)

picks out all method call join points where an instance of any subtype of Foo (including Foo itself) is constructed.

Note that in the previous sample, foo.Bar can be wether a class (a super class) or an interface.

Array type patterns

...

}
h3. Subtype patterns

It is possible to pick out all subtypes of a type with the "{{\+}}" wildcard. The "{{\+}}" wildcard follows immediately a type name pattern. So, while 

{{\* foo.Bar.\*(..)}}

picks out all method call join points where an instance of exactly type {{Foo}} is constructed, 

{{\* foo.Bar+.\*(..)}}

picks out all method call join points where an instance of any subtype of {{Foo}} (including {{Foo}} itself) is constructed. 

Note that in the previous sample, {{foo.Bar}} can be wether a class (a super class) or an interface. 

h3. 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 {{java.lang.Object[]}} is an array type pattern, and so is {{foo.bar.\*[][]

...

Abbreviations

...

}}. 

h3. Abbreviations

When picking out the return and parameter types it is possible to use predefined abbreviations for the classes in the {{java.lang.\*}} and {{java.util.\*}} packages. If you specify only the class name it will be mapped to the full class name for the class (you cannot use patterns in abbreviations).

...

 

Abbreviations are supported for array types as well, with a dimension less or equal to 2. {{String[][]}} will thus be resolved as {{java.lang.String[][]}} but {{String[][][]}} will not.

...

 

This is usefull when dealing with complex advice signature in the XML definition. 

h4.

...

 Examples

...

 

You can use:

...

 

* String instead of {{java.lang.String

...

}}
* List instead of {{java.util.List

...

}}
* but not {{String\*}} instead of {{java.lang.String}} or {{java.lang.StringBuffer

...

}} 
* and so on...

...

 

Apart from these abbreviations you always have to specify the fully qualified name of the class (along with the wildcards).