{div9:id=documentationcolumn}
include:HeaderBasic}
{HTMLcomment:hidden}
examples using tc config-file elements would be useful
{HTMLcomment} |
h1. AspectWerkz Pattern Language
{:=|=}
AspectWerkz supports a fine-grained pattern language for selecting join points. 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.
h2. 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: {{WildcardsYou 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.
h2. 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> Combining the patternsThe 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> }}
h2. 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 {{Class selectionsThe 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. Examplesfoo.bar.*
- will match
foo.bar.FooBar2 - as well as
foo.bar.FooBear - but not
foo.bar.subpackage.FooMouse }}
{{foo.*.FooBar }}
- will match {{- will match
foo.bar.FooBar }}
- as well as {{- as well as
foo.bear.FooBar }}
- but not {{}}
{{foo. \*.FooB \*}}
- will match {{*
- will match
foo.bar.FooBar2 }}
- as well as {{- as well as
foo.bear.FooBear }}
- as well as {{}}
{{public public foo.bar.* }}
- will match {{public static final - will match
public static final foo.bar.FooBar }}
- as well as {{public static - as well as
public static foo.bar.FooBar }}
- but not {{static - but not
static foo.bar.FooBar }} {{ }}
{{@Session @Session foo.bar.* }}
- will match {{@Session - will match
@Session foo.bar.FooBar }}
- but not {{}} {{ }}
{{foo.. }}
- will match all classes in all packages starting with foo
h2. 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> - will match all classes in all packages starting with foo
Method selectionsThe 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>)
h4. Examples
{{int Examples int foo.*.Bar.method() }}
- will match {{int }}
- but not {{int }}
{{int \int *.method \( \* \)}}
- will match {{int )
- will match
int Foo.method(int }}
- but not {{int }}
- and not {{int - and not
int apackage.Foo.method(int }}
{{* * method(..) }}
- will match {{void - will match
void Foo.method() }}
- as well as {{void - as well as
void apackage.Bar.method(int[] }}
{{int int foo. \*. \*.method(*,int) }}
- will match {{int - will match
int method(String }}
- as well as {{int - as well as
int method(int }}
{{int int foo.*.Bar.method(..) }}
- will match {{int }}
- as well as {{int - as well as
int method(String }}
- as well as {{int - as well as
int method(int }}
{{int int foo.*.Bar.method(int,..) }}
- will match {{int - will match
int method(int) }}
- as well as {{int - as well as
int method(int }}
- as well as {{int - as well as
int method(int }}
{{int int foo. \*.Bar.method(java.lang. \*) }}
- will match {{int - will match
int method(String }}
- as well as {{int - as well as
int method(StringBuffer }}
{{int int foo. \*.Bar.me \*o \*() }}
- will match {{int }}
- as well as {{int - as well as
int metamorphosis() }} {{ }}
- but not {{int }}
{{\* * foo. \*.Bar.method() }}
- will match {{int }}
- as well as {{- as well as
java.lang.String }}
{{java.lang. \* foo. \*.Bar.method() }}
- will match {{- will match
java.lang.String }}
- as well as {{- as well as
java.lang.StringBuffer }}
{{static int static int foo.*.Bar.method() }}
- will match {{static int - will match
static int method() }}
- but not {{int }}
{{@Transaction \* @Transaction * foo. \*. \*. \*(..) }}
- will match {{@Transaction int - will match
@Transaction int method() }}
- but not {{void }}
h2. 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> Constructor selectionsThe 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}
Terracotta is not using constructor selectors and to match on constructors you should use method selector for {{\_\_INIT\_\_}} method instead. So instead of {{ Note |
---|
Terracotta is not using constructor selectors and to match on constructors you should use method selector for __INIT__ method instead. So instead of Foo.new(..) | }} {{\ \\\\}}
{note}
h4. Examples
{{Examples foo. \*.Bar.new() }}
- will match
- {{ }}
{{\* * new(..) }}
- will match {{new }}
- as well as {{new - as well as
new apackage.Bar(int[] }}
{{\*.new(String) }}
- will match {{new - will match
new Foo(String }} {{ }}
- but not {{new }}
h2. 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 Terracotta currently doesn't support selection of excluded or transient fields based on annotations.
{note}
h4. Examples
{{int foo.\Field selectionsFields 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 Terracotta currently doesn't support selection of excluded or transient fields based on annotations. |
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}}
{{\* 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
* foo.*.Bar.m \_foo }}
- will match {{int m\_foo}}
- as well as {{- will match
int m_foo - as well as
java.lang.String \}}
{{java.lang. \* foo. \*.Bar.m \_foo }}
- will match {{- will match
java.lang.String \}}
- as well as {{- as well as
java.lang.StringBuffer \}}
{{int int foo. \*.Bar.m_ \*}}
- will match {{int * }}
- as well as {{int }}
{{int int foo. \*.Bar.m_ \*oo \*}}
- will match {{int * }}
- as well as {{int }}
- as well as {{int }}
{anchor: Anchor |
---|
| subtype-patterns |
---|
| subtype-patterns |
---|
| }
h2. Subtype patterns
It is possible to pick out all subtypes of a type with the " {{\+ }}" wildcard. The " {{\+ }}" wildcard immediately follows a type name pattern.
The following picks out all method-call join points where an instance of exactly type {{Bar }} is constructed:
{{\* * foo.Bar. \*(..) }}
The following picks out all method-call join points where an instance of _any subtype of _ {{Bar }} (including {{Bar }} itself) is constructed:
{{\* foo.Bar+. \*(..) }}
Note that {{foo.Bar }} can be a class (including a super class) or an interface.
h2. 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 {{Array type patternsA 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. \*[][] }}.
h2. Abbreviations
When picking out the return and parameter types it is possible to use predefined abbreviations for the classes in the {{. AbbreviationsWhen 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 {{Examples You can use: - String instead of
java.lang.String }}
* {{}}
* {{\}} {{}} {{}}
* and so
Apart from these abbreviations you always have to specify the fully qualified name of the class (along with the wildcards).
{div9} |