AspectSharp/docs/languageref.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta content="text/html;charset=ISO-8859-1" http-equiv="content-type">
   5 <meta content="en" http-equiv="content-language">
   6 <meta name="robots" content="index, follow/">
   7 <meta name="keywords" content="AOP, Aspect, Aspect Oriented Programming, .NET, DotNet, C#, Aspect .Net, Aspect Sharp, AspectSharp, Aspect #, Aspect#, AOP .Net, Aspect Oriented Programming .NET " />
   8 <meta name="description" content="A .NET AOP Framework, it uses Dynamic Proxies and XML configuration files as basis." />
   9 <title>Aspect# Language Documentation</title>
  10 <style type="text/css">
  11                         <!--
  12                                 body
  13                                 {
  14                                         font-family: verdana;
  15                                         font-size:x-small;
  16                                 }
  17                                 a
  18                                 {
  19                                         color: navy;
  20                                 }
  21                                 a:hover
  22                                 {
  23                                         color: blue;
  24                                 }
  25                                 h1
  26                                 {
  27                                         color:green;
  28                                 }
  29                                 table
  30                                 {
  31                                         font-size:x-small;
  32                                 }
  33                                 .code
  34                                 {
  35         font-family:"Lucida Console", "Courier New", Courier;
  36         font-size:small;
  37         background-color: #DDDDDD;
  38         width: 100%;
  39         border: 2px dashed #000000;
  40         margin: 2pt;
  41         padding: 2pt;
  42                                 }
  43                         -->
  44                 </style>
  45 </head>
  46
  47
  48 <body>
  49 <table border="1" cellspacing="0" bordercolor="black" width="100%">
  50                         <tr>
  51                                 <td>Aspect# - An AOP framework for the .NET</td>
  52                         </tr>
  53                 </table>
  54
  55                 <h1><img src="http://aspectsharp.sourceforge.net/logo.gif" alt="Aspect# Logo. By Ricardo Aloise." /></h1>
  56
  57                 <p></p>
  58
  59
  60 <h3>Aspect# Language Documentation</h3>
  61
  62 <p> The purpose of Aspect# language is to offer you a cleaner way to configure,
  63   describe and document your aspects configuration without have to rely on creepy
  64   xml syntax to do so.</p>
  65 <h4>&nbsp;</h4>
  66 <h4>Basic definitions</h4>
  67 <p>You must obey to a few rules to use the Aspect# language, and the first rule
  68   is that order matters. So you declarations must obey this sequence:</p>
  69 <pre class="code">
  70 [Imports]
  71
  72 [Global Interceptor map]
  73
  74 [Global Mixin map]
  75
  76 Aspects definitions
  77 </pre>
  78 <h4>&nbsp;</h4>
  79 <h4>Imports</h4>
  80 <p>The imports section helps you to keep a clean code and helps the language to
  81   resolve the types.</p>
  82 <pre class="code">Import Namespace.Name [in AssemblyName]</pre>
  83 <p>Examples:</p>
  84 <pre class="code">Import System.Collections in System</pre><br/>
  85 <pre class="code">Import AspectSharp.Core</pre>
  86
  87 <h4>&nbsp;</h4>
  88 <h4>Global Interceptors</h4>
  89 <p>In the case that you have an interceptor that is going to be used in more than
  90   one aspect - or even more than one pointcut, you can define it in an global
  91   interceptor section:</p>
  92 <pre class="code">
  93 interceptors [
  94   &quot;key&quot; : InterceptorType ;
  95   &quot;key2&quot; : InterceptorType2
  96 ]</pre>
  97 <p>Examples</p>
  98 <pre class="code">
  99 interceptors [
 100   "logger" : DigitalGravity.Interceptors.Logger in DigitalGravity.XProject
 101 ]
 102 </pre><br/>
 103 <pre class="code">
 104 Import DigitalGravity.Interceptors in DigitalGravity.XProject
 105
 106 interceptors [
 107   "logger" : Logger
 108 ]
 109 </pre>
 110 <p>Once you've done it, you can refer to them in an aspect declaration by their
 111   keys:</p>
 112 <pre class="code">
 113 aspect Test for MyClass
 114
 115   pointcut method(*)
 116     advice("key")
 117   end
 118
 119   pointcut property(*)
 120     advice("key2")
 121   end
 122
 123 end
 124 </pre>
 125
 126 <h4>&nbsp;</h4>
 127 <h4>Global Mixins</h4>
 128 <p>For the same reason there is also a mixin global section:</p>
 129 <pre class="code">
 130 mixins [
 131   &quot;key&quot; : MixinType ;
 132   &quot;key2&quot; : MixinType2
 133 ]</pre>
 134 <p>Examples</p>
 135 <pre class="code">
 136 mixins [
 137   "security" : DigitalGravity.Mixins.SecurityMixin in DigitalGravity.XProject
 138 ]
 139 </pre><br/>
 140 <pre class="code">
 141 Import DigitalGravity.Mixins in DigitalGravity.XProject
 142
 143 interceptors [
 144   "security" : SecurityMixin
 145 ]
 146 </pre>
 147 <p>Once you've done it, you can refer to them in an aspect declaration by their
 148   keys:</p>
 149 <pre class="code">
 150 aspect Test for MyClass
 151
 152   include("security")
 153
 154 end
 155 </pre>
 156
 157 <h4>&nbsp;</h4>
 158 <h4>Aspects</h4>
 159 <p>An aspect section defines which mixins and which pointcuts will be applied to a type or a set of types:</p>
 160 <pre class="code">
 161 aspect Name for Type
 162   [include]
 163   [pointcuts]
 164 end
 165 </pre>
 166 <p>Examples</p>
 167 <pre class="code">
 168 aspect MyAspect for Customer
 169 end
 170 </pre>
 171 <br/>
 172 <pre class="code">
 173 aspect MyAspect for [ My.Namespace.Classes excludes(Customer,Author) ]
 174 end
 175 </pre>
 176 <br/>
 177 <pre class="code">
 178 aspect MyAspect for [ assignableFrom(Customer) ]
 179 end
 180 </pre>
 181 <br/>
 182 <pre class="code">
 183 aspect MyAspect for [ customMatcher(MyAspectMatcher) ]
 184 end
 185 </pre>
 186 <p>
 187 When you invoke the AspectEngine.Wrap method on an instance, basically Aspect# will try to match
 188 the aspects for that particular instance. If more than one are matched, a new aspect is created from
 189 the union and will be used as the aspect definition.
 190 </p>
 191 <p>
 192 If you need a more specific semantic to match aspects, you can provide your own using the
 193 customMatcher keyword (as the example above). Your class must implement the IClassMatcher interface
 194 and perform its logic returning true if the instance is eligible for that aspect.
 195 </p>
 196 <h4>&nbsp;</h4>
 197 <h4>Includes</h4>
 198 <p>You use one or more include to add mixins to the resulting type in an aspect definition.</p>
 199 <p>Examples</p>
 200 <pre class="code">
 201 aspect MyAspect for Customer
 202   include DigitalGravity.Mixins.Security in DigitalGravity.XProject
 203   include System.Collections.ArrayList in System
 204 end
 205 </pre>
 206 <h4>&nbsp;</h4>
 207 <p><h4>Pointcuts</h4></p>
 208 <p>The purpose of pointcuts is to define an expression that must be true (matched) in order
 209 to introduce advices.</p>
 210 <pre class="code">
 211 pointcut [target][method signature]
 212   advice(type)
 213   advice("key")
 214 end
 215 </pre>
 216 <p>The possible targets are:</p>
 217 <un>
 218 <li>method</li>
 219 <li>property</li>
 220 <li>propertyread</li>
 221 <li>propertywrite</li>
 222 </un>
 223 <p>You can also combine them if you want, provided that they make sense</p>
 224 <pre class="code">
 225 pointcut method|property(*)
 226 end
 227
 228 pointcut method|propertyread(*)
 229 end
 230
 231 pointcut propertywrite(*)
 232 end
 233 </pre>
 234 <p>Using property|propertywrite for instance is meaningless, and you'll get an error.</p>
 235 <p>The method signature can be simple as a (*) meaning everything, or (System.IList Create(int, *)) meaning
 236 methods named Create that returns System.IList and have at least the first argument of the type int.
 237 <b>Please note that return types and argument types here are not resolved, so you have to use
 238 the full type name.</b>
 239 </p>
 240 <p>Regular expressions are not fully supported. In fact, you can use only .* to match something
 241 in the rest of an name like (Str.* Create(int, string)) that will match Create methods with two
 242 arguments (the first an int and the second a String) and returning a type which the name starts with
 243 Str, like String, Strange, Stripissimo and so on.</p>
 244 <p>Examples</p>
 245 <pre class="code">
 246 // All read and write property named Name
 247 pointcut property(* Name)
 248 end
 249
 250 // All read and write property named
 251 // C****Name like CustomerName
 252 pointcut property(string C.*Name)
 253 end
 254
 255 // The method Perform returning void with no arguments
 256 pointcut method(void Perform)
 257 end
 258
 259 // The method Perform with the first argument as String
 260 // and we don't care about the other arguments
 261 pointcut method(void Perform(string, *))
 262 end
 263 </pre>
 264 <h4>&nbsp;</h4>
 265 <p><h4>Advices</h4></p>
 266 <p>Advices are the pieces of code that will be associated with a given joinpoint.
 267 Aspect# only supports MethodInterceptors advices.
 268 </p>
 269 <p><b>Please note that we use lazy instantiation of interceptors and
 270 only one instance of an interceptor will exist per Wrap(). In other words, proxies
 271 will not share interceptors.</b>
 272 </p>
 273 <p>Examples</p>
 274 <pre class="code">
 275 aspect MyAspect for Customer
 276   pointcut method(*)
 277     advice(DigitalGravity.Interceptors.LogInvocationInterceptor in DigitalGravity.XProject)
 278   end
 279 end
 280 </pre>
 281 <p></p>
 282 <hr noshade>
 283 <p>20-09-04 - The Aspect# Team
 284 </p>
 285
 286
 287 </body>
 288 </html>
 289