You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

joinpointsignatures.xml 19KB

19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
19 vuotta sitten
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536
  1. <chapter id="jpsigs" xreflabel="Join Point Signatures">
  2. <title>Join Point Signatures</title>
  3. <para>
  4. Many of the extensions to the AspectJ language to address the new features of
  5. Java 5 are derived from a simple set of principles for join point
  6. matching. In this section, we outline these principles as a foundation
  7. for understanding the matching rules in the presence of annotations,
  8. generics, covariance, varargs, and autoboxing.
  9. </para>
  10. <sect1 id="join-point-matching">
  11. <title>Join Point Matching</title>
  12. <para>AspectJ supports 11 different kinds of join points. These are
  13. the <literal>method call, method execution, constructor call,
  14. constructor execution, field get, field set, pre-initialization,
  15. initialization, static initialization, handler,</literal> and
  16. <literal>advice execution</literal> join points.</para>
  17. <para>The <emphasis>kinded</emphasis> pointcut designators match
  18. based on the kind of a join point. These are the <literal>call,
  19. execution, get, set, preinitialization, initialization,
  20. staticinitialization, handler,</literal> and <literal>adviceexecution</literal>
  21. designators.</para>
  22. <para>A kinded pointcut is written using patterns, some of which
  23. match based on <emphasis>signature</emphasis>, and some of which
  24. match based on <emphasis>modifiers</emphasis>. For example, in
  25. the <literal>call</literal> pointcut designator:</para>
  26. <programlisting><![CDATA[
  27. call(ModifierPattern TypePattern TypePattern.IdPattern(TypePatternList) ThrowsPattern)
  28. ]]></programlisting>
  29. <para>the modifiers matching patterns are <literal>ModifierPattern</literal>
  30. and <literal>ThrowsPattern</literal>, and the signature matching patterns
  31. are <literal>TypePattern TypePattern.IdPattern(TypePatternList)</literal>.
  32. </para>
  33. <para>
  34. A join point has potentially multiple signatures, but only one set of
  35. modifiers. <emphasis>A kinded primitive pointcut matches a particular join point
  36. if and only if</emphasis>:
  37. </para>
  38. <orderedlist>
  39. <listitem>They are of the same kind</listitem>
  40. <listitem>The signature pattern (exactly) matches at least one
  41. signature of the join point</listitem>
  42. <listitem>The modifiers pattern matches the modifiers of the
  43. subject of the join point</listitem>
  44. </orderedlist>
  45. <para>These rules make it very easily to quickly determine whether a
  46. given pointcut matches a given join point. In the next two sections,
  47. we describe what the signature(s) of a join point are, and what the
  48. subjects of join points are.</para>
  49. </sect1>
  50. <sect1 id="join-point-signatures">
  51. <title>Join Point Signatures</title>
  52. <para>Call, execution, get, and set join points may potentially have multiple
  53. signatures. All other join points have exactly one signature. The
  54. following table summarizes the constituent parts of a join point
  55. signature for the different kinds of join point.</para>
  56. <informaltable>
  57. <tgroup cols="7">
  58. <thead>
  59. <row>
  60. <entry>Join Point Kind</entry>
  61. <entry>Return Type</entry>
  62. <entry>Declaring Type</entry>
  63. <entry>Id</entry>
  64. <entry>Parameter Types</entry>
  65. <entry>Field Type</entry>
  66. <entry>Exception Type</entry>
  67. </row>
  68. </thead>
  69. <tbody>
  70. <row>
  71. <entry>Method call</entry>
  72. <entry>+</entry>
  73. <entry>+</entry>
  74. <entry>+</entry>
  75. <entry>+</entry>
  76. <entry></entry>
  77. <entry></entry>
  78. </row>
  79. <row>
  80. <entry>Method execution</entry>
  81. <entry>+</entry>
  82. <entry>+</entry>
  83. <entry>+</entry>
  84. <entry>+</entry>
  85. <entry></entry>
  86. <entry></entry>
  87. </row>
  88. <row>
  89. <entry>Constructor call</entry>
  90. <entry></entry>
  91. <entry>+</entry>
  92. <entry></entry>
  93. <entry>+</entry>
  94. <entry></entry>
  95. <entry></entry>
  96. </row>
  97. <row>
  98. <entry>Constructor execution</entry>
  99. <entry></entry>
  100. <entry>+</entry>
  101. <entry></entry>
  102. <entry>+</entry>
  103. <entry></entry>
  104. <entry></entry>
  105. </row>
  106. <row>
  107. <entry>Field get</entry>
  108. <entry></entry>
  109. <entry>+</entry>
  110. <entry>+</entry>
  111. <entry></entry>
  112. <entry>+</entry>
  113. <entry></entry>
  114. </row>
  115. <row>
  116. <entry>Field set</entry>
  117. <entry></entry>
  118. <entry>+</entry>
  119. <entry>+</entry>
  120. <entry></entry>
  121. <entry>+</entry>
  122. <entry></entry>
  123. </row>
  124. <row>
  125. <entry>Pre-initialization</entry>
  126. <entry></entry>
  127. <entry>+</entry>
  128. <entry></entry>
  129. <entry>+</entry>
  130. <entry></entry>
  131. <entry></entry>
  132. </row>
  133. <row>
  134. <entry>Initialization</entry>
  135. <entry></entry>
  136. <entry>+</entry>
  137. <entry></entry>
  138. <entry>+</entry>
  139. <entry></entry>
  140. <entry></entry>
  141. </row>
  142. <row>
  143. <entry>Static initialization</entry>
  144. <entry></entry>
  145. <entry>+</entry>
  146. <entry></entry>
  147. <entry></entry>
  148. <entry></entry>
  149. <entry></entry>
  150. </row>
  151. <row>
  152. <entry>Handler</entry>
  153. <entry></entry>
  154. <entry></entry>
  155. <entry></entry>
  156. <entry></entry>
  157. <entry></entry>
  158. <entry>+</entry>
  159. </row>
  160. <row>
  161. <entry>Advice execution</entry>
  162. <entry></entry>
  163. <entry>+</entry>
  164. <entry></entry>
  165. <entry>+</entry>
  166. <entry></entry>
  167. <entry></entry>
  168. </row>
  169. </tbody>
  170. </tgroup>
  171. </informaltable>
  172. <para>Note that whilst an advice execution join point has a
  173. signature comprising the declaring type of the advice and the
  174. advice parameter types, the <literal>adviceexecution</literal>
  175. pointcut designator does not support matching based on this
  176. signature.</para>
  177. <para>The signatures for most of the join point kinds should be
  178. self-explanatory, except for field get and set, and method call and execution
  179. join points, which can have multiple signatures. Each signature of
  180. a method call or execution join point has the same id and parameter
  181. types, but the declaring type and return type (with covariance) may vary.
  182. Each signature of a field get or set join point has the same id and field
  183. type, but the declaring type may vary.
  184. </para>
  185. <para>The following sections examine signatures for these join points
  186. in more detail.</para>
  187. <sect2 id="method-call-join-point-signatures" xreflabel="method-call-join-point-signatures">
  188. <title>Method call join point signatures</title>
  189. <para>
  190. For a call join point where a call is made to a method
  191. <literal>m(parameter_types)</literal> on a target type <literal>T</literal> (where
  192. <literal>T</literal> is the static type of the target):
  193. </para>
  194. <programlisting><![CDATA[
  195. T t = new T();
  196. t.m("hello"); <= call join point occurs when this line is executed
  197. ]]></programlisting>
  198. <para>
  199. Then the signature <literal>R(T) T.m(parameter_types)</literal> is a signature
  200. of the call join point, where <literal>R(T)</literal> is the return
  201. type of <literal>m</literal> in <literal>T</literal>, and
  202. <literal>parameter_types</literal> are the parameter types of
  203. <literal>m</literal>. If <literal>T</literal> itself does not
  204. declare a definition of <literal>m(parameter_types)</literal>, then
  205. <literal>R(T)</literal> is the return type in the definition of
  206. <literal>m</literal> that <literal>T</literal> inherits. Given the
  207. call above, and the definition of <literal>T.m</literal>:
  208. </para>
  209. <programlisting><![CDATA[
  210. interface Q {
  211. R m(String s);
  212. }
  213. class P implements Q {
  214. R m(String s) {...}
  215. }
  216. class S extends P {
  217. R' m(String s) {...}
  218. }
  219. class T extends S {}
  220. ]]></programlisting>
  221. <para>Then <literal>R' T.m(String)</literal> is a signature of the
  222. call join point for <literal>t.m("hello")</literal>.</para>
  223. <para>
  224. For each ancestor (super-type) <literal>A</literal> of <literal>T</literal>,
  225. if <literal>m(parameter_types)</literal> is defined for that super-type, then
  226. <literal>R(A) A.m(parameter_types)</literal> is a signature of the call join
  227. point, where <literal>R(A)</literal> is the return type of <literal>
  228. m(parameter_types)</literal> as defined in <literal>A</literal>, or as inherited
  229. by <literal>A</literal> if <literal>A</literal> itself does not
  230. provide a definition of <literal>m(parameter_types)</literal>.
  231. </para>
  232. <para>
  233. Continuing the example from above,we can deduce that
  234. </para>
  235. <programlisting><![CDATA[
  236. R' S.m(String)
  237. R P.m(String)
  238. R Q.m(String)
  239. ]]></programlisting>
  240. <para>are all additional signatures for the call join point arising
  241. from the call <literal>t.m("hello")</literal>. Thus this call
  242. join point has four signatures in total. Every signature has the same
  243. id and parameter types, and a different declaring type.</para>
  244. </sect2>
  245. <sect2 id="method-execution-join-point-signatures" xreflabel="method-execution-join-point-signatures">
  246. <title>Method execution join point signatures</title>
  247. <para>Join point signatures for execution join points are defined
  248. in a similar manner to signatures for call join points. Given the
  249. hierarchy:
  250. </para>
  251. <programlisting><![CDATA[
  252. interface Q {
  253. R m(String s);
  254. }
  255. class P implements Q {
  256. R m(String s) {...}
  257. }
  258. class S extends P {
  259. R' m(String s) {...}
  260. }
  261. class T extends S { }
  262. class U extends T {
  263. R' m(String s) {...}
  264. }
  265. ]]></programlisting>
  266. <para>Then the execution join point signatures arising as a result
  267. of the call to <literal>u.m("hello")</literal> are: </para>
  268. <programlisting><![CDATA[
  269. R' U.m(String)
  270. R' S.m(String)
  271. R P.m(String)
  272. R Q.m(String)
  273. ]]></programlisting>
  274. <para>Each signature has the same id and parameter types, and a
  275. different declaring type. There is one signature for each type
  276. that provides its own declaration of the method. Hence in this
  277. example there is no signature <literal>R' T.m(String)</literal>
  278. as <literal>T</literal> does not provide its own declaration of
  279. the method.</para>
  280. </sect2>
  281. <sect2 id="field-get-and-set-join-point-signatures" xreflabel="field-get-and-set-join-point-signatures">
  282. <title>Field get and set join point signatures</title>
  283. <para>
  284. For a field get join point where an access is made to a field
  285. <literal>f</literal> of type <literal>F</literal>
  286. on a object with declared type <literal>T</literal>, then
  287. <literal>F T.f</literal> is a signature of the get join point.
  288. </para>
  289. <para>
  290. If <literal>T</literal> does not directly declare a member
  291. <literal>f</literal>, then for each super type <literal>S</literal>
  292. of <literal>T</literal>, up to and including the most specific
  293. super type of <literal>T</literal> that does declare the member
  294. <literal>f</literal>, <literal>F S.f</literal> is a signature
  295. of the join point. For example, given the hierarchy:
  296. </para>
  297. <programlisting><![CDATA[
  298. class P {
  299. F f;
  300. }
  301. class S extends P {
  302. F f;
  303. }
  304. class T extends S { }
  305. ]]></programlisting>
  306. <para>
  307. Then the join point signatures for a field get join point of
  308. the field <literal>f</literal> on an object with declared type
  309. <literal>T</literal> are:
  310. </para>
  311. <programlisting><![CDATA[
  312. F S.f
  313. F T.f
  314. ]]></programlisting>
  315. <para>The signatures for a field set join point are derived in an
  316. identical manner.</para>
  317. </sect2>
  318. </sect1>
  319. <sect1 id="join-point-modifiers">
  320. <title>Join Point Modifiers</title>
  321. <para>Every join point has a single set of modifiers - these include
  322. the standard Java modifiers such as <literal>public, private,
  323. static, abstract</literal> etc., any annotations, and the throws
  324. clauses of methods and constructors. These modifiers are the
  325. modifiers of the <emphasis>subject</emphasis> of the join point.</para>
  326. <para>
  327. The following table defines the join point subject for each kind
  328. of join point.
  329. </para>
  330. <informaltable>
  331. <tgroup cols="2">
  332. <thead>
  333. <row>
  334. <entry>Join Point Kind</entry>
  335. <entry>Subject</entry>
  336. </row>
  337. </thead>
  338. <tbody>
  339. <row>
  340. <entry>Method call</entry>
  341. <entry>The method picked out by Java as
  342. the static target of the method call.</entry>
  343. </row>
  344. <row>
  345. <entry>Method execution</entry>
  346. <entry>The method that is executing.</entry>
  347. </row>
  348. <row>
  349. <entry>Constructor call</entry>
  350. <entry>The constructor being called.</entry>
  351. </row>
  352. <row>
  353. <entry>Constructor execution</entry>
  354. <entry>The constructor executing.</entry>
  355. </row>
  356. <row>
  357. <entry>Field get</entry>
  358. <entry>The field being accessed.</entry>
  359. </row>
  360. <row>
  361. <entry>Field set</entry>
  362. <entry>The field being set.</entry>
  363. </row>
  364. <row>
  365. <entry>Pre-initialization</entry>
  366. <entry>The first constructor executing in
  367. this constructor chain.</entry>
  368. </row>
  369. <row>
  370. <entry>Initialization</entry>
  371. <entry>The first constructor executing in
  372. this constructor chain.</entry>
  373. </row>
  374. <row>
  375. <entry>Static initialization</entry>
  376. <entry>The type being initialized.</entry>
  377. </row>
  378. <row>
  379. <entry>Handler</entry>
  380. <entry>The declared type of the
  381. exception being handled.</entry>
  382. </row>
  383. <row>
  384. <entry>Advice execution</entry>
  385. <entry>The advice being executed.</entry>
  386. </row>
  387. </tbody>
  388. </tgroup>
  389. </informaltable>
  390. <para>For example, given the following types</para>
  391. <programlisting><![CDATA[
  392. public class X {
  393. @Foo
  394. protected void doIt() {...}
  395. }
  396. public class Y extends X {
  397. public void doIt() {...}
  398. }
  399. ]]></programlisting>
  400. <para>Then the modifiers for a call to <literal>(Y y) y.doIt()</literal>
  401. are simply <literal>{public}</literal>. The modifiers for a call to
  402. <literal>(X x) x.doIt()</literal> are <literal>{@Foo,protected}</literal>.
  403. </para>
  404. </sect1>
  405. <sect1 id="join-point-matching-summary">
  406. <title>Summary of Join Point Matching</title>
  407. <para>
  408. A join point has potentially multiple signatures, but only one set of
  409. modifiers. <emphasis>A kinded primitive pointcut matches a particular join point
  410. if and only if</emphasis>:
  411. </para>
  412. <orderedlist>
  413. <listitem>They are of the same kind</listitem>
  414. <listitem>The signature pattern (exactly) matches at least one
  415. signature of the join point</listitem>
  416. <listitem>The modifiers pattern matches the modifiers of the
  417. subject of the join point</listitem>
  418. </orderedlist>
  419. <para>Given the hierarchy</para>
  420. <programlisting><![CDATA[
  421. interface Q {
  422. R m(String s);
  423. }
  424. class P implements Q {
  425. @Foo
  426. public R m(String s) {...}
  427. }
  428. class S extends P {
  429. @Bar
  430. public R' m(String s) {...}
  431. }
  432. class T extends S {}
  433. ]]></programlisting>
  434. <para>and the program fragment:</para>
  435. <programlisting><![CDATA[
  436. P p = new P();
  437. S s = new S();
  438. T t = new T();
  439. ...
  440. p.m("hello");
  441. s.m("hello");
  442. t.m("hello");
  443. ]]></programlisting>
  444. <para>
  445. The the pointcut <literal>call(@Foo R P.m(String))</literal> matches the
  446. call <literal>p.m("hello")</literal> since both the signature and the
  447. modifiers match. It does not match the call <literal>s.m("hello")</literal>
  448. because even though the signature pattern matches one of the signatures
  449. of the join point, the modifiers pattern does not match the modifiers of
  450. the method m in S which is the static target of the call.
  451. </para>
  452. <para>The pointcut <literal>call(R' m(String))</literal> matches the
  453. calls <literal>t.m("hello")</literal> and <literal>s.m("hello")</literal>.
  454. It does not match the call <literal>p.m("hello")</literal> since the
  455. signature pattern does not match any signature for the call join point
  456. of m in P.</para>
  457. </sect1>
  458. </chapter>