Menu: Integrated flyoutmenu into menu, and moved flyoutmenu.html - jquery-ui.git - The official jQuery user interface library: https://github.com/jquery/jquery-ui

index : jquery-ui.git

The official jQuery user interface library: https://github.com/jquery/jquery-ui

www-data

about summary refs log tree commit diff stats

path: root/ui/jquery.ui.mouse.js

diff options

author	jzaefferer <joern.zaefferer@gmail.com>	2011-02-24 15:51:51 +0100
committer	jzaefferer <joern.zaefferer@gmail.com>	2011-02-24 15:51:51 +0100
commit	0ddf677e40a7feaaeefcc44f2a4910923f1bc258 (patch)
tree	385812d1fbb9f0e0bafc40457330ec5b6d1d98e7 /ui/jquery.ui.mouse.js
parent	38cfcfffe92f2ac2572ab7ebc51e860de9312baf (diff)
download	jquery-ui-0ddf677e40a7feaaeefcc44f2a4910923f1bc258.tar.gz jquery-ui-0ddf677e40a7feaaeefcc44f2a4910923f1bc258.zip

Menu: Integrated flyoutmenu into menu, and moved flyoutmenu.html

testmenu into contextmenu.html

Diffstat (limited to 'ui/jquery.ui.mouse.js')

0 files changed, 0 insertions, 0 deletions

href='#n110'>110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270

<!--<!DOCTYPE chapter SYSTEM "file:/C:/Documents%20and%20Settings/colyer/My%20Documents/projects/aspectjdev/lib/docbook/docbook-dtd/docbookx.dtd">
-->
<chapter id="generics" xreflabel="Generics">

  <title>Generics</title>

  <sect1 id="generics-inJava5">
    <title>Generics in Java 5</title>

	<para>
		This section provides the essential information about generics in
		Java 5 needed to understand how generics are treated in AspectJ 5.
		For a full introduction to generics in Java, please see the
		documentation for the Java 5 SDK.
	</para>

	<sect2 id="declaring-generic-types" xreflabel="declaring-generic-types">
		<title>Declaring Generic Types</title>

        <para>
            A generic type is declared with one or more type parameters following the type name.
            By convention formal type parameters are named using a single letter, though this is not required.
            A simple generic list type
            (that can contain elements of any type <literal>E</literal>) could be declared:
        </para>

        <programlisting><![CDATA[
interface List<E> {
   Iterator<E> iterator();
   void add(E anItem);
   E remove(E anItem);
}
]]></programlisting>


        <para>
            It is important to understand that unlike template mechanisms there will only be one type, and one class file, corresponding to
            the <literal>List</literal> interface, regardless of how many different instantiations of the <literal>List</literal> interface a program
            has (each potentially providing a different value for the type parameter <literal>E</literal>). A consequence of this
            is that you cannot refer to the type parameters of a type declaration in a static method or initializer, or in the declaration or
            initializer of a static variable.
        </para>
         <para>
             A <emphasis>parameterized type</emphasis>
            is an invocation of a generic type with concrete values supplied for
            all of its type parameters (for example, <literal>List&lt;String></literal> or <literal>List&lt;Food></literal>).
        </para>

        <para>A generic type may be declared with multiple type parameters. In addition to simple type parameter names, type
        parameter declarations can also constrain the set of types allowed by using the <literal>extends</literal>
        keyword. Some examples follow:</para>

        <variablelist>

        <varlistentry>
          <term>class Foo&lt;T> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with one type parameter, <literal>T</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Foo&lt;T,S> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with two type parameters, <literal>T</literal> and <literal>S</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Foo&lt;T extends Number> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with one type parameter <literal>T</literal>, where <literal>T</literal> must be
            instantiated as the type <literal>Number</literal> or a subtype of <literal>Number</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Foo&lt;T, S extends T> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with two type parameters, <literal>T</literal> and <literal>S</literal>. <literal>Foo</literal>
            must be instantiated with a type <literal>S</literal> that is a subtype of the type specified for parameter <literal>T</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Foo&lt;T extends Number &amp; Comparable> {...}</term>
          <listitem>
            <para>A class <literal>Foo</literal> with one type parameter, <literal>T</literal>. <literal>Foo</literal>
            must be instantiated with a type that is a subtype of <literal>Number</literal> and that implements <literal>Comparable</literal>.
            </para>
          </listitem>
        </varlistentry>

       </variablelist>

	</sect2>

	<sect2 id="using-generic-and-parameterized-types" xreflabel="using-generic-and-parameterized-types">
	    <title>Using Generic and Parameterized Types</title>

	    <para>You declare a variable (or a method/constructor argument) of a parameterized type  by specifying a concrete type specfication for each type parameter in
	        the generic type. The following example declares a list of strings and a list of numbers:</para>

        <programlisting><![CDATA[
List<String> strings;
List<Number> numbers;
]]></programlisting>

	    <para>It is also possible to declare a variable of a generic type without specifying any values for the type
	        parameters (a <emphasis>raw</emphasis> type). For example, <literal>List strings</literal>.
	        In this case, unchecked warnings may be issued by the compiler
	        when the referenced object is passed as a parameter to a method expecting a parameterized type such as a
	        <literal>List&lt;String></literal>. New code written in the Java 5 language would not be expected to use
	        raw types.</para>

	    <para>Parameterized types are instantiated by specifying type parameter values in the constructor call expression as in
	    the following examples:</para>

        <programlisting><![CDATA[
List<String> strings = new MyListImpl<String>();
List<Number> numbers = new MyListImpl<Number>();
]]></programlisting>

	    <para>
	     When declaring parameterized types, the <literal>?</literal> wildcard may be used, which stands for "some type".
	     The <literal>extends</literal> and <literal>super</literal> keywords may be used in conjunction with the wildcard
	     to provide upper and lower bounds on the types that may satisfy the type constraints. For example:
	    </para>

        <variablelist>

        <varlistentry>
          <term>List&lt;?&gt;</term>
          <listitem>
            <para>A list containing elements of some type, the type of the elements in the list is unknown.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;? extends Number&gt;</term>
          <listitem>
            <para>A list containing elements of some type that extends Number, the exact type of the elements in the list is unknown.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>List&lt;? super Double&gt;</term>
          <listitem>
            <para>A list containing elements of some type that is a super-type of Double, the exact type of the elements in the list is unknown.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      	<para>
      	  A generic type may be extended as any other type. Given a generic type <literal>Foo&lt;T&gt;</literal> then
      	  a subtype <literal>Goo</literal> may be declared in one of the following ways:
      	</para>

        <variablelist>

        <varlistentry>
          <term>class Goo extends Foo</term>
          <listitem>
            <para>Here <literal>Foo</literal> is used as a raw type, and the appropriate warning messages will be
            issued by the compiler on attempting to invoke methods in <literal>Foo</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo&lt;E&gt; extends Foo</term>
          <listitem>
            <para><literal>Goo</literal> is a generic type, but the super-type <literal>Foo</literal> is used as a raw
            type and the appropriate warning messages will be
            issued by the compiler on attempting to invoke methods defined by <literal>Foo</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo&lt;E&gt; extends Foo&lt;E&gt;</term>
          <listitem>
            <para>This is the most usual form. <literal>Goo</literal> is a generic type with one parameter that extends
            the generic type <literal>Foo</literal> with that same parameter. So <literal>Goo&lt;String&lt;</literal> is
            a subclass of <literal>Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo&lt;E,F&gt; extends Foo&lt;E&gt;</term>
          <listitem>
            <para><literal>Goo</literal> is a generic type with two parameters that extends
            the generic type <literal>Foo</literal> with the first type parameter of <literal>Goo</literal> being used
            to parameterize <literal>Foo</literal>. So <literal>Goo&lt;String,Integer&lt;</literal> is
            a subclass of <literal>Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>class Goo extends Foo&lt;String&gt;</term>
          <listitem>
            <para><literal>Goo</literal> is a type that extends
            the parameterized type <literal>Foo&lt;String&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

	    <para>A generic type may implement one or more generic interfaces, following the type binding
	    rules given above. A type may also implement one or more parameterized interfaces (for example,
	    <literal>class X implements List&lt;String&gt;</literal>, however a type may not at the same time
	    be a subtype of two interface types which are different parameterizations of the same interface.</para>
	</sect2>

	<sect2 id="subtypes-supertypes-and-assignability" xreflabel="subtypes-supertypes-and-assignability">
	    <title>Subtypes, Supertypes, and Assignability</title>

	    <para>
	      The supertype of a generic type <literal>C</literal> is the type given in the extends clause of
	      <literal>C</literal>, or <literal>Object</literal> if no extends clause is present. Given the type declaration
	    </para>

        <programlisting><![CDATA[
public interface List<E> extends Collection<E> {... }
]]></programlisting>

	    <para>
	      then the supertype of <literal>List&lt;E&gt;</literal> is <literal>Collection&lt;E&gt;</literal>.
	    </para>

	    <para>
	      The supertype of a parameterized type <literal>P</literal> is the type given in the extends clause of
	      <literal>P</literal>, or <literal>Object</literal> if no extends clause is present. Any type parameters in
	      the supertype are substituted in accordance with the parameterization of <literal>P</literal>. An example
	      will make this much clearer: Given the type <literal>List&lt;Double&gt;</literal> and the definition of
	      the <literal>List</literal> given above, the direct supertype is
	      <literal>Collection&lt;Double&gt;</literal>. <literal>List&lt;Double&gt;</literal> is <emphasis>not</emphasis>
	      considered to be a subtype of <literal>List&lt;Number&gt;</literal>.
	    </para>

	    <para>
	      An instance of a parameterized type <literal>P&lt;T1,T2,...Tn&gt;</literal>may be assigned to a variable of
	      the same type or a supertype
	      without casting. In addition it may be assigned to a variable <literal>R&lt;S1,S2,...Sm&gt;</literal> where
	      <literal>R</literal> is a supertype of <literal>P</literal> (the supertype relationship is reflexive),
	      <literal>m &lt;= n</literal>, and for all type parameters <literal>S1..m</literal>, <literal>Tm</literal> equals
	      <literal>Sm</literal> <emphasis>or</emphasis> <literal>Sm</literal> is a wildcard type specification and
	      <literal>Tm</literal> falls within the bounds of the wildcard. For example, <literal>List&lt;String&gt;</literal>
	      can be assigned to a variable of type <literal>Collection&lt;?&gt;</literal>, and <literal>List&lt;Double&gt;</literal>
	      can be assigned to a variable of type <literal>List&lt;? extends Number&gt;</literal>.
	    </para>

	</sect2>

	<sect2 id="generic-methods-and-constructors" xreflabel="generic-methods-and-constructors">
	    <title>Generic Methods and Constructors</title>
	    <para>
	      A static method may be declared with one or more type parameters as in the following declaration:
	    </para>

        <programlisting><![CDATA[
static <T> T first(List<T> ts) { ... }
]]></programlisting>

	    <para>
	        Such a definition can appear in any type, the type parameter <literal>T</literal> does not need to
	        be declared as a type parameter of the enclosing type.
	    </para>

	    <para>
	      Non-static methods may also be declared with one or more type parameters in a similar fashion:
	    </para>

        <programlisting><![CDATA[
<T extends Number> T max(T t1, T t2) { ... }
]]></programlisting>

	    <para>The same technique can be used to declare a generic constructor.</para>

	</sect2>

	<sect2 id="erasure" xreflabel="erasure">
	  <title>Erasure</title>
	  <para>Generics in Java are implemented using a technique called <emphasis>erasure</emphasis>. All
	  type parameter information is erased from the run-time type system. Asking an object of a parameterized
	  type for its class will return the class object for the raw type (eg. <literal>List</literal> for an object
	  declared to be of type <literal>List&lt;String&gt;</literal>. A consequence of this is that you cannot at
	  runtime ask if an object is an <literal>instanceof</literal> a parameterized type.</para>
	</sect2>
  </sect1>

<!-- ===================================================================== -->

  <sect1 id="generics-inAspectJ5">
      <title>Generics in AspectJ 5</title>

      <para>
        AspectJ 5 provides full support for all of the Java 5 language features, including generics. Any legal Java 5 program is a
        legal AspectJ 5 progam. In addition, AspectJ 5 provides support for generic and parameterized types in pointcuts, inter-type
        declarations, and declare statements.  Parameterized types may freely be used within aspect members, and support is
        also provided for generic <emphasis>abstract</emphasis> aspects.
      </para>

      <sect2 id="matching-generic-and-parameterized-types-in-pointcut-expressions" xreflabel="matching-generic-and-parameterized-types-in-pointcut-expressions">
          <title>Matching generic and parameterized types in pointcut expressions</title>

          <para>
            The simplest way to work with generic and parameterized types in pointcut expressions and type patterns
            is simply to use the raw type name. For example, the type pattern <literal>List</literal> will match
            the generic type <literal>List&lt;E&gt;</literal> and any parameterization of that type
            (<literal>List&lt;String&gt;, List&lt;?&gt;, List&lt;? extends Number&gt;</literal> and so on. This
            ensures that pointcuts written in existing code that is not generics-aware will continue to work as
            expected in AspectJ 5. It is also the recommended way to match against generic and parameterized types
            in AspectJ 5 unless you explicitly wish to narrow matches to certain parameterizations of a generic type.
          </para>

          <para>Generic methods and constructors, and members defined in generic types, may use type variables
          as part of their signature. For example:</para>

        <programlisting><![CDATA[
public class Utils {

  /** static generic method */
  static <T> T first(List<T> ts) { ... }

  /** instance generic method */
  <T extends Number> T max(T t1, T t2) { ... }

}

public class G<T> {

   // field with parameterized type
   T myData;

   // method with parameterized return type
   public List<T> getAllDataItems() {...}

}
]]></programlisting>

          <para>
            AspectJ 5 does not allow the use of type variables in pointcut expressions and type patterns. Instead, members that
            use type parameters as part of their signature are matched by their <emphasis>erasure</emphasis>. Java 5 defines the
            rules for determing the erasure of a type as follows.
          </para>

          <para>Let <literal>|T|</literal> represent the erasure of some type <literal>T</literal>. Then:</para>

          <simplelist>
            <member>The erasure of a parameterized type <literal>T&lt;T1,...,Tn&gt;</literal> is <literal>|T|</literal>.
            For example, the erasure of <literal>List&lt;String&gt;</literal> is <literal>List</literal>.</member>

            <member>The erasure of a nested type <literal>T.C</literal> is <literal>|T|.C</literal>. For example,
            the erasure of the nested type <literal>Foo&lt;T&gt;.Bar</literal> is <literal>Foo.Bar</literal>.</member>

            <member>The erasure of an array type <literal>T[]</literal> is <literal>|T|[]</literal>. For example,
            the erasure of <literal>List&lt;String&gt;[]</literal> is <literal>List[]</literal>.</member>

            <member>The erasure of a type variable is its leftmost bound. For example, the erasure of a
            type variable <literal>P</literal> is <literal>Object</literal>, and the erasure of a type
            variable <literal>N extends Number</literal> is <literal>Number</literal>.</member>

            <member>The erasure of every other type is the type itself</member>
          </simplelist>

          <!-- see tests/java5/generics/ajdk/ErasureMatching.aj -->
          <para>Applying these rules to the earlier examples, we find that the methods defined in <literal>Utils</literal>
          can be matched by a signature pattern matching <literal>static Object Utils.first(List)</literal> and
          <literal>Number Utils.max(Number, Number)</literal> respectively. The members of the generic type
          <literal>G</literal> can be matched by a signature pattern matching <literal>Object G.myData</literal> and
          <literal>public List G.getAllDataItems()</literal> respectively.</para>

          <sect3>
            <title>Restricting matching using parameterized types</title>

          <para>Pointcut matching can be further restricted to match only given parameterizations of parameter types (methods and constructors), return
          types (methods) and field types (fields). This is achieved by specifying a parameterized type pattern at the appropriate point
          in the signature pattern. For example, given the class <literal>Foo</literal>:</para>

        <programlisting><![CDATA[
public class Foo {

  List<String> myStrings;
  List<Float>  myFloats;

  public List<String> getStrings() { return myStrings; }
  public List<Float> getFloats() { return myFloats; }

  public void addStrings(List<String> evenMoreStrings) {
     myStrings.addAll(evenMoreStrings);
  }

}
]]></programlisting>

        <!-- see tests/java5/generics/ajdk/SimpleParameterizedTypeExamples.aj -->

        <para>Then a <literal>get</literal> join point for the field <literal>myStrings</literal> can be matched by the
        pointcut <literal>get(List Foo.myStrings)</literal> and by the pointcut <literal>get(List&lt;String&gt; Foo.myStrings)</literal>,
        but <emphasis>not</emphasis> by the pointcut <literal>get(List&lt;Number&gt; *)</literal>.</para>

        <para>A <literal>get</literal> join point for the field <literal>myFloats</literal> can be matched by the
        pointcut <literal>get(List Foo.myFloats)</literal>, the pointcut <literal>get(List&lt;Float&gt; *)</literal>,
        and the pointcut <literal>get(List&lt;Number+&gt; *)</literal>. This last example shows how AspectJ type
        patterns can be used to match type parameters types just like any other type. The pointcut
        <literal>get(List&lt;Double&gt; *)</literal> does <emphasis>not</emphasis> match.</para>

        <para>The execution of the methods <literal>getStrings</literal> and <literal>getFloats</literal> can be
        matched by the pointcut expression <literal>execution(List get*(..))</literal>, and the pointcut
        expression <literal>execution(List&lt;*&gt; get*(..))</literal>, but only <literal>getStrings</literal>
        is matched by <literal>execution(List&lt;String&gt; get*(..))</literal> and only <literal>getFloats</literal>
        is matched by <literal>execution(List&lt;Number+&gt; get*(..))</literal></para>

        <para>A call to the method <literal>addStrings</literal> can be matched by the pointcut expression
        <literal>call(* addStrings(List))</literal> and by the expression <literal>call(* addStrings(List&lt;String&gt;))</literal>,
        but <emphasis>not</emphasis> by the expression <literal>call(* addStrings(List&lt;Number&gt;))</literal>.
        </para>

        <para>Remember that any type variable reference in a generic member is
        <emphasis>always</emphasis> matched by its erasure. Thus given the following
        example:</para>

        <programlisting><![CDATA[
class G<T> {
    List<T> foo(List<String> ls) { return null; }
}
]]></programlisting>

        <!-- see tests/java5/generics/ajdk/MixedParameterizedAndTypeVariables.aj -->
        <para>The execution of <literal>foo</literal> can be matched by
        <literal>execution(List foo(List))</literal>,
        <literal>execution(List foo(List&lt;String&gt;>))</literal>, and
        <literal>execution(* foo(List&lt;String&lt;))</literal>but
        <emphasis>not</emphasis> by <literal>execution(List&lt;Object&gt; foo(List&lt;String&gt;>)</literal>
        since the erasure of <literal>List&lt;T&gt;</literal> is <literal>List</literal>
        and not <literal>List&lt;Object&gt;</literal>.
        </para>

        </sect3>

        <sect3>
          <title>Generic wildcards and signature matching</title>

          <para>
            When it comes to signature matching, a type parameterized using a generic wildcard is a distinct type.
            For example, <literal>List&lt;?&gt;</literal> is a very different type to <literal>List&lt;String&gt;</literal>,
            even though a variable of type <literal>List&lt;String&gt;</literal> can be assigned to a variable of
            type <literal>List&lt;?&gt;</literal>. Given the methods:
          </para>

        <programlisting><![CDATA[
class C {
  public void foo(List<? extends Number> listOfSomeNumberType) {}

  public void bar(List<?> listOfSomeType) {}

  public void goo(List<Double> listOfDoubles) {}
}
]]></programlisting>

          <!-- see java5/generics/ajdk/SignatureWildcards.aj -->

        <variablelist>

        <varlistentry>
          <term>execution(* C.*(List))</term>
          <listitem>
            <para>Matches an execution join point for any of the three methods.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution(* C.*(List&lt;? extends Number&gt;))</term>
          <listitem>
            <para>matches only the
          execution of <literal>foo</literal>, and <emphasis>not</emphasis> the execution
          of <literal>goo</literal> since <literal>List&lt;? extends Number&gt;</literal> and
          <literal>List&lt;Double&gt;</literal> are distinct types.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution(* C.*(List&lt;?&gt;))</term>
          <listitem>
            <para>matches only the execution of <literal>bar</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>execution(* C.*(List&lt;? extends Object+&gt;))</term>
          <listitem>
            <para>matches both the execution of <literal>foo</literal> and the execution of <literal>bar</literal>
          since the upper bound of <literal>List&lt;?&gt;</literal> is implicitly <literal>Object</literal>.
            </para>
          </listitem>
        </varlistentry>

        </variablelist>

        </sect3>

        <sect3>
          <title>Treatment of bridge methods</title>

          <para>Under certain circumstances a Java 5 compiler is required to create <emphasis>bridge
          methods</emphasis> that support the compilation of programs using raw types. Consider the types</para>

       <programlisting><![CDATA[
class Generic<T> {
  public T foo(T someObject) {
    return someObject;
  }
}

class SubGeneric<N extends Number> extends Generic<N> {
  public N foo(N someNumber) {
    return someNumber;
  }
}
]]></programlisting>

		 <para>The class <literal>SubGeneric</literal> extends <literal>Generic</literal>
		 and overrides the method <literal>foo</literal>. Since the upper bound of the type variable
		 <literal>N</literal> in <literal>SubGeneric</literal> is different to the upper bound of
		 the type variable <literal>T</literal> in <literal>Generic</literal>, the method <literal>foo</literal>
		 in <literal>SubGeneric</literal> has a different erasure to the method <literal>foo</literal>
		 in <literal>Generic</literal>. This is an example of a case where a Java 5 compiler will create
		 a <emphasis>bridge method</emphasis> in <literal>SubGeneric</literal>. Although you never see it,
		 the bridge method will look something like this:</para>

       <programlisting><![CDATA[
public Object foo(Object arg) {
  Number n = (Number) arg; // "bridge" to the signature defined in this type
return foo(n);
}
]]></programlisting>

		 <!-- see java5/generics/ajdk/BridgeMethodExamples.aj -->
		 <para>Bridge methods are synthetic artefacts generated as a result of a particular compilation strategy and
		 have no execution join points in AspectJ 5. So the pointcut <literal>execution(Object SubGeneric.foo(Object))</literal>
		 does not match anything. (The pointcut <literal>execution(Object Generic.foo(Object))</literal> matches the
		 execution of <literal>foo</literal> in both <literal>Generic</literal> and <literal>SubGeneric</literal> since
		 both are implementations of <literal>Generic.foo</literal>).
		 </para>

		 <para>It <emphasis>is</emphasis> possible to <emphasis>call</emphasis> a bridge method as the following short
		 code snippet demonstrates. Such a call <emphasis>does</emphasis> result in a call join point for the call to
		 the method.
		 </para>

       <programlisting><![CDATA[
SubGeneric rawType = new SubGeneric();
rawType.foo("hi");  // call to bridge method (will result in a runtime failure in this case)
Object n = new Integer(5);
rawType.foo(n);     // call to bridge method that would succeed at runtime
]]></programlisting>

        </sect3>

        <sect3>
          <title>Runtime type matching with this(), target() and args()</title>

          <para>The <literal>this()</literal>, <literal>target()</literal>, and
          <literal>args()</literal> pointcut expressions all match based on the runtime
          type of their arguments. Because Java 5 implements generics using erasure, it is not
          possible to ask at runtime whether an object is an instance of a given parameterization of a type
          (only whether or not it is an instance of the erasure of that parameterized type). Therefore
          AspectJ 5 does not support the use of parameterized types with the <literal>this()</literal> and
          <literal>target()</literal> pointcuts. Parameterized types may however be used in conjunction with
          <literal>args()</literal>. Consider the following class
          </para>

       <programlisting><![CDATA[
public class C {
  public void foo(List<String> listOfStrings) {}

  public void bar(List<Double> listOfDoubles) {}

  public void goo(List<? extends Number> listOfSomeNumberType) {}
}
]]></programlisting>

            <!-- see java5/generics/ajdk/ArgsExamples.aj -->

        <variablelist>

          <varlistentry>
            <term>args(List)</term>
            <listitem>
              <para>will match an execution or call join point for any of
              these methods
              </para>
            </listitem>
          </varlistentry>

        <varlistentry>
            <term>args(List&lt;String&gt;)</term>
            <listitem>
              <para>will match an execution
              or call join point for <literal>foo</literal>.
              </para>
            </listitem>
          </varlistentry>

       <varlistentry>
            <term>args(List&lt;Double&gt;)</term>
            <listitem>
              <para>matches an execution or call join point for <literal>bar</literal>, and <emphasis>may</emphasis> match
              at an execution or call join point for <literal>goo</literal> since it is legitimate to pass an
              object of type <literal>List&lt;Double&gt;</literal> to a method expecting a <literal>List&lt;? extends Number&gt;</literal>.
              </para>
              <para>
                  In this situation a runtime test would normally be applied to ascertain whether or not the argument
              was indeed an instance of the required type. However, in the case of parameterized types such a test is not
              possible and therefore AspectJ 5 considers this a match, but issues an <emphasis>unchecked</emphasis> warning.
              For example, compiling the aspect <literal>A</literal> below with the class <literal>C</literal> produces the
              compilation warning: "unchecked match of List&lt;Double&gt; with List&lt;? extends Number&gt; when argument is
              an instance of List at join point method-execution(void C.goo(List&lt;? extends Number&gt;)) [Xlint:uncheckedArgument]";
              </para>
            </listitem>
          </varlistentry>

        </variablelist>

       <programlisting><![CDATA[
public aspect A {
   before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
      for (Double d : listOfDoubles) {
         // do something
      }
   }
}
]]></programlisting>

            <para>Like all Lint messages, the <literal>uncheckedArgument</literal> warning can be
            configured in severity from the default warning level to error or even ignore if preferred.
            In addition, AspectJ 5 offers the annotation <literal>@SuppressAjWarnings</literal> which is
            the AspectJ equivalent of Java's <literal>@SuppressWarnings</literal> annotation. If the
            advice is annotated with <literal>@SuppressWarnings</literal> then <emphasis>all</emphasis>
            lint warnings issued during matching of pointcut associated with the advice will be
            suppressed. To suppress just an <literal>uncheckedArgument</literal> warning, use the
            annotation <literal>@SuppressWarnings("uncheckedArgument")</literal> as in the following
            examples:
            </para>

       <programlisting><![CDATA[
import org.aspectj.lang.annotation.SuppressAjWarnings
public aspect A {
   @SuppressAjWarnings   // will not see *any* lint warnings for this advice
   before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
      for (Double d : listOfDoubles) {
         // do something
      }
   }

   @SuppressAjWarnings("uncheckedArgument")   // will not see *any* lint warnings for this advice
   before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
      for (Double d : listOfDoubles) {
         // do something
      }
   }
}
]]></programlisting>

            <para>
              The safest way to deal with <literal>uncheckedArgument</literal> warnings however is to restrict the pointcut
              to match only at those join points where the argument is guaranteed to match. This is achieved by combining
              <literal>args</literal> with a <literal>call</literal> or <literal>execution</literal> signature matching
              pointcut. In the following example the advice will match the execution of <literal>bar</literal> but not
              of <literal>goo</literal> since the signature of <literal>goo</literal> is not matched by the execution pointcut
              expression.
            </para>

       <programlisting><![CDATA[
public aspect A {
   before(List<Double> listOfDoubles) : execution(* C.*(List<Double>)) && args(listOfDoubles) {
      for (Double d : listOfDoubles) {
         // do something
      }
   }
}
]]></programlisting>

            <para>Generic wildcards can be used in args type patterns, and matching follows regular Java 5 assignability rules. For
            example, <literal>args(List&lt;?&gt;)</literal> will match a list argument of any type, and
            <literal>args(List&lt;? extends Number&gt;)</literal> will match an argument of type
            <literal>List&lt;Number&gt;, List&lt;Double&gt;, List&lt;Float&gt;</literal> and so on. Where a match cannot be
            fully statically determined, the compiler will once more issue an <literal>uncheckedArgument</literal> warning.
            </para>

            <para>Consider the following program:</para>

         <programlisting><![CDATA[
public class C {
   public static void main(String[] args) {
      C c = new C();
      List<String> ls = new ArrayList<String>();
      List<Double> ld = new ArrayList<Double>();
      c.foo("hi");
      c.foo(ls);
      c.foo(ld);
   }

   public void foo(Object anObject) {}
}

aspect A {
    before(List<? extends Number> aListOfSomeNumberType)
      : call(* foo(..)) && args(aListOfSomeNumberType) {
       // process list...
    }
}
]]></programlisting>

            <!-- see java5/generics/ajdk/WildcardArgsExamples.aj -->

            <para>From the signature of <literal>foo</literal> all we know is that the runtime argument will be an instance of
            <literal>Object</literal>.Compiling this program gives the unchecked argument warning:
            "unchecked match of List&lt;? extends Number&gt; with List when argument is
              an instance of List at join point method-execution(void C.foo(Object)) [Xlint:uncheckedArgument]".
              The advice will not execute at the call join point for <literal>c.foo("hi")</literal> since <literal>String</literal>
              is not an instance of <literal>List</literal>. The advice <emphasis>will</emphasis> execute at the call join points
              for <literal>c.foo(ls)</literal> and <literal>c.foo(ld)</literal> since in both cases the argument is an instance of
              <literal>List</literal>.
            </para>

            <para>Combine a wildcard argument type with a signature pattern to avoid unchecked argument matches. In the example
            below we use the signature pattern <literal>List&lt;Number+&gt;</literal> to match a call to any method taking
            a <literal>List&lt;Number&gt;, List&lt;Double&gt;, List&lt;Float&gt;</literal> and so on. In addition the
            signature pattern <literal>List&lt;? extends Number+&gt;</literal> can be used to match a call to a method
            declared to take a <literal>List&lt;? extends Number&gt;</literal>, <literal>List&lt;? extends Double&gt;</literal>
            and so on. Taken together, these restrict matching to only
            those join points at which the argument is guaranteed to be an instance of <literal>List&lt;? extends Number&gt;</literal>.</para>


         <programlisting><![CDATA[
aspect A {
    before(List<? extends Number> aListOfSomeNumberType)
      : (call(* foo(List<Number+>)) || call(* foo(List<? extends Number+>)))
        && args(aListOfSomeNumberType) {
        // process list...
    }
}
]]></programlisting>

        </sect3>

        <sect3>
          <title>Binding return values in after returning advice</title>

          <para>
            After returning advice can be used to bind the return value from a matched join point. AspectJ 5 supports the use of
            a parameterized type in the returning clause, with matching following the same rules as described for args. For
            example, the following aspect matches the execution of any method returning a <literal>List</literal>, and makes
            the returned list available to the body of the advice.
          </para>

       <programlisting><![CDATA[
public aspect A {
  pointcut executionOfAnyMethodReturningAList() : execution(List *(..));

  after() returning(List<?> listOfSomeType) : executionOfAnyMethodReturningAList() {
    for (Object element : listOfSomeType) {
       // process element...
    }
  }
}
]]></programlisting>

          <!-- see java5/generics/ajdk/AfterReturningExamples.aj -->
          <para>The pointcut uses the raw type pattern <literal>List</literal>, and hence it
          matches methods returning any kind of list (<literal>List&lt;String&gt;, List&lt;Double&gt;</literal>,
          and so on). We've chosen to bind the returned list as the parameterized type
          <literal>List&lt;?&gt;</literal> in the advice since Java's type checking will now ensure
          that we only perform safe operations on the list.</para>

          <para>Given the class</para>

       <programlisting><![CDATA[
public class C {
  public List<String> foo(List<String> listOfStrings) {...}

  public List<Double> bar(List<Double> listOfDoubles) {...}

  public List<? extends Number> goo(List<? extends Number> listOfSomeNumberType) {...}
}
]]></programlisting>

          <para>The advice in the aspect below will run after the execution of <literal>bar</literal>
          and bind the return value. It will also run after the execution of <literal>goo</literal> and
          bind the return value, but gives an <literal>uncheckedArgument</literal> warning during
          compilation. It does <emphasis>not</emphasis> run after the execution of <literal>foo</literal>.
          </para>

      <programlisting><![CDATA[
public aspect Returning {
  after() returning(List<Double> listOfDoubles) : execution(* C.*(..)) {
     for(Double d : listOfDoubles) {
        // process double...
     }
  }
}
]]></programlisting>

		<para>As with <literal>args</literal> you can guarantee that after returning advice only
		executes on lists <emphasis>statically determinable</emphasis> to be of the right
		type by specifying a return type pattern in the associated pointcut. The
		<literal>@SuppressAjWarnings</literal> annotation can also be used if desired.</para>

        </sect3>

        <sect3>
            <title>Declaring pointcuts inside generic types</title>

            <para>Pointcuts can be declared in both classes and aspects. A pointcut declared in a generic
            type may use the type variables of the type in which it is declared. All references to
            a pointcut declared in a generic type from outside of that type must be via a parameterized type reference,
            and not a raw type reference.</para>

            <para>Consider the generic type <literal>Generic</literal> with a pointcut <literal>foo</literal>:
            </para>

        <programlisting><![CDATA[
public class Generic<T> {
   /**
    * matches the execution of any implementation of a method defined for T
    */
   public pointcut foo() : execution(* T.*(..));
}
]]></programlisting>

		<!-- see java5/generics/ajdk/PointcutInGenericClassExample.aj -->

		<para>Such a pointcut must be refered to using a parameterized reference as shown
		below.</para>

		<programlisting><![CDATA[
public aspect A {
  // runs before the execution of any implementation of a method defined for MyClass
  before() : Generic<MyClass>.foo() {
     // ...
  }

  // runs before the execution of any implementation of a method defined for YourClass
  before() : Generic<YourClass>.foo() {
      // ...
  }

  // results in a compilation error - raw type reference
  before() : Generic.foo() { }
}
]]></programlisting>

        </sect3>

      </sect2>

      <sect2 id="inter-type-declarations" xreflabel="inter-type-declarations">
          <title>Inter-type Declarations</title>

          <para>
            AspectJ 5 supports the inter-type declaration of generic methods, and of members on
            generic types. For generic methods, the syntax is exactly as for a regular method
            declaration, with the addition of the target type specification:
          </para>

        <variablelist>

        <varlistentry>
          <term>&lt;T extends Number&gt; T Utils.max(T first, T second) {...}</term>
          <listitem>
            <para>Declares a generic instance method <literal>max</literal> on the class <literal>Util</literal>.
            The <literal>max</literal> method takes two arguments, <literal>first</literal> and <literal>second</literal> which must
            both be of the same type (and that type must be Number or a subtype of Number) and returns an instance
            of that type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>static &lt;E&gt; E Utils.first(List&lt;E&gt; elements) {...}</term>
          <listitem>
            <para>Declares a static generic method <literal>first</literal> on the class <literal>Util</literal>.
            The <literal>first</literal> method takes a list of elements of some type, and returns an instance
            of that type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>&lt;T&gt; Sorter.new(List&lt;T&gt; elements,Comparator&lt;? super T&gt; comparator) {...}</term>
          <listitem>
            <para>Declares a constructor on the class <literal>Sorter</literal>.
            The constructor takes a list of elements of some type, and a comparator that can compare instances
            of the element type.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
         A generic type may be the target of an inter-type declaration, used either in its raw form or with
         type parameters specified. If type parameters are specified, then the number of type parameters given
          must match the number of type parameters in
         the generic type declaration. Type parameter <emphasis>names</emphasis> do not have to match.
         For example, given the generic type <literal>Foo&lt;T,S extends Number&gt;</literal> then:
      </para>

        <variablelist>

        <varlistentry>
          <term>String Foo.getName() {...}</term>
          <listitem>
            <para>Declares a <literal>getName</literal> method on behalf of the type <literal>Foo</literal>. It is
            not possible to refer to the type parameters of Foo in such a declaration.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public R Foo&lt;Q, R&gt;.getMagnitude() {...}</term>
          <listitem>
            <para>Declares a method <literal>getMagnitude</literal> on the generic class <literal>Foo</literal>.
            The method returns an instance of the type substituted for the second type parameter in an invocation
            of <literal>Foo</literal> If <literal>Foo</literal> is declared as
            <literal>Foo&lt;T,N extends Number&gt; {...}</literal> then this inter-type declaration is
            equivalent to the declaration of a method <literal>public N getMagnitude()</literal>
            within the body of <literal>Foo</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>R Foo&lt;Q, R extends Number&gt;.getMagnitude() {...}</term>
          <listitem>
            <para>Results in a compilation error since a bounds specification is not allowed in this
                form of an inter-type declaration (the bounds are determined from the declaration of the
                target type).
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>A parameterized type may not be the target of an inter-type declaration. This is because
      there is only one type (the generic type) regardless of how many different invocations (parameterizations) of
      that generic type are made in a program. Therefore it does not make sense to try and declare a member
      on behalf of (say) <literal>Bar&lt;String&gt;</literal>, you can only declare members on the generic
      type <literal>Bar&lt;T&gt;</literal>.
      </para>

      </sect2>

      <sect2 id="declare-parents-java5" xreflabel="declare-parents-java5">
          <title>Declare Parents</title>

          <para>Both generic and parameterized types can be used as the parent type in a <literal>declare parents</literal>
          statement (as long as the resulting type hierarchy would be well-formed in accordance with Java's sub-typing
          rules). Generic types may also be used as the target type of a <literal>declare parents</literal> statement.</para>

        <variablelist>

        <varlistentry>
          <term>declare parents: Foo implements List&lt;String&gt;</term>
          <listitem>
            <para>The <literal>Foo</literal> type implements the <literal>List&lt;String&gt;</literal> interface. If
            <literal>Foo</literal> already implements some other parameterization of the <literal>List</literal>
            interface (for example, <literal>List&lt;Integer&gt;</literal> then a compilation error will result since a
            type cannot implement multiple parameterizations of the same generic interface type.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      </sect2>

      <sect2 id="declare-soft" xreflabel="declare-soft">
          <title>Declare Soft</title>
          <para>It is an error to use a generic or parameterized type as the softened exception type in a declare soft statement. Java 5 does
          not permit a generic class to be a direct or indirect subtype of <literal>Throwable</literal> (JLS 8.1.2).</para>
      </sect2>

      <sect2 id="generic-aspects" xreflabel="generic-aspects">
          <title>Generic Aspects</title>

          <para>
            AspectJ 5 allows an <emphasis>abstract</emphasis> aspect to be declared as a generic type. Any concrete
            aspect extending a generic abstract aspect must extend a parameterized version of the abstract aspect.
            Wildcards are not permitted in this parameterization.
          </para>

          <para>Given the aspect declaration:</para>

        <programlisting><![CDATA[
public abstract aspect ParentChildRelationship<P,C> {
    ...
}
]]></programlisting>

           <para>then</para>

       <variablelist>

        <varlistentry>
          <term>public aspect FilesInFolders extends ParentChildRelationship&lt;Folder,File&gt; {...</term>
          <listitem>
            <para>declares a concrete sub-aspect, <literal>FilesInFolders</literal> which extends the
            parameterized abstract aspect <literal>ParentChildRelationship&lt;Folder,File&gt;</literal>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public aspect FilesInFolders extends ParentChildRelationship {...</term>
          <listitem>
            <para>results in a compilation error since the <literal>ParentChildRelationship</literal> aspect must
            be fully parameterized.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public aspect ThingsInFolders&lt;T&gt; extends ParentChildRelationship&lt;Folder,T&gt;</term>
          <listitem>
            <para>results in a compilation error since concrete aspects may not have type parameters.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>public abstract aspect ThingsInFolders&lt;T&gt; extends ParentChildRelationship&lt;Folder,T&gt;</term>
          <listitem>
            <para>declares a sub-aspect of <literal>ParentChildRelationship</literal> in which <literal>Folder</literal>
            plays the role of parent (is bound to the type variable <literal>P</literal>).
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

        <para>The type parameter variables from a generic aspect declaration may be used in place of a type within any
        member of the aspect, <emphasis>except for within inter-type declarations</emphasis>.
        For example, we can declare a <literal>ParentChildRelationship</literal> aspect to
        manage the bi-directional relationship between parent and child nodes as follows:
        </para>

        <programlisting><![CDATA[
/**
 * a generic aspect, we've used descriptive role names for the type variables
 * (Parent and Child) but you could use anything of course
 */
public abstract aspect ParentChildRelationship<Parent,Child> {

  /** generic interface implemented by parents */
  interface ParentHasChildren<C extends ChildHasParent>{
    List<C> getChildren();
    void addChild(C child);
    void removeChild(C child);
  }

  /** generic interface implemented by children */
  interface ChildHasParent<P extends ParentHasChildren>{
    P getParent();
    void setParent(P parent);
  }

  /** ensure the parent type implements ParentHasChildren<child type> */
  declare parents: Parent implements ParentHasChildren<Child>;

  /** ensure the child type implements ChildHasParent<parent type> */
  declare parents: Child implements ChildHasParent<Parent>;

  // Inter-type declarations made on the *generic* interface types to provide
  // default implementations.

  /** list of children maintained by parent */
  private List<C> ParentHasChildren<C>.children = new ArrayList<C>();

  /** reference to parent maintained by child */
  private P ChildHasParent<P>.parent;

  /** Default implementation of getChildren for the generic type ParentHasChildren */
  public List<C> ParentHasChildren<C>.getChildren() {
        return Collections.unmodifiableList(children);
  }

  /** Default implementation of getParent for the generic type ChildHasParent */
  public P ChildHasParent<P>.getParent() {
       return parent;
  }

  /**
    * Default implementation of addChild, ensures that parent of child is
    * also updated.
    */
  public void ParentHasChildren<C>.addChild(C child) {
       if (child.parent != null) {
         child.parent.removeChild(child);
       }
       children.add(child);
       child.parent = this;
    }

   /**
     * Default implementation of removeChild, ensures that parent of
     * child is also updated.
     */
   public void ParentHasChildren<C>.removeChild(C child) {
       if (children.remove(child)) {
         child.parent = null;
       }
    }

    /**
      * Default implementation of setParent for the generic type ChildHasParent.
      * Ensures that this child is added to the children of the parent too.
      */
    public void ChildHasParent<P>.setParent(P parent) {
       parent.addChild(this);
    }

    /**
      * Matches at an addChild join point for the parent type P and child type C
      */
    public pointcut addingChild(Parent p, Child c) :
      execution(* ParentHasChildren.addChild(ChildHasParent)) && this(p) && args(c);

    /**
      * Matches at a removeChild join point for the parent type P and child type C
      */
    public pointcut removingChild(Parent p, Child c) :
      execution(* ParentHasChildren.removeChild(ChildHasParent)) && this(p) && args(c);

}
]]></programlisting>


        <para>
          The example aspect captures the protocol for managing a bi-directional parent-child relationship between
          any two types playing the role of parent and child. In a compiler implementation managing an abstract syntax
          tree (AST) in which AST nodes may contain other AST nodes we could declare the concrete aspect:
        </para>

        <programlisting><![CDATA[
public aspect ASTNodeContainment extends ParentChildRelationship<ASTNode,ASTNode> {
    before(ASTNode parent, ASTNode child) : addingChild(parent, child) {
      ...
    }
}
]]></programlisting>

         <para>
           As a result of this declaration, <literal>ASTNode</literal> gains members:
         </para>

        <simplelist>
            <member><literal>List&lt;ASTNode&gt; children</literal></member>
            <member><literal>ASTNode parent</literal></member>
            <member><literal>List&lt;ASTNode&gt;getChildren()</literal></member>
            <member><literal>ASTNode getParent()</literal></member>
            <member><literal>void addChild(ASTNode child)</literal></member>
            <member><literal>void removeChild(ASTNode child)</literal></member>
            <member><literal>void setParent(ASTNode parent)</literal></member>
        </simplelist>

         <para>
           In a system managing orders, we could declare the concrete aspect:
         </para>

        <programlisting><![CDATA[
public aspect OrderItemsInOrders extends ParentChildRelationship<Order, OrderItem> {
}
]]></programlisting>

         <para>
           As a result of this declaration, <literal>Order</literal> gains members:
         </para>

        <simplelist>
            <member><literal>List&lt;OrderItem&gt; children</literal></member>
            <member><literal>List&lt;OrderItem&gt; getChildren()</literal></member>
            <member><literal>void addChild(OrderItem child)</literal></member>
            <member><literal>void removeChild(OrderItem child)</literal></member>
        </simplelist>

        <para>and <literal>OrderItem</literal> gains members:</para>

        <simplelist>
            <member><literal>Order parent</literal></member>
            <member><literal>Order getParent()</literal></member>
            <member><literal>void setParent(Order parent)</literal></member>
        </simplelist>


         <para>A second example of an abstract aspect, this time for handling exceptions in a uniform
         manner, is shown below:</para>

       <programlisting><![CDATA[
abstract aspect ExceptionHandling<T extends Throwable> {

  /**
   * method to be implemented by sub-aspects to handle thrown exceptions
   */
  protected abstract void onException(T anException);

  /**
   * to be defined by sub-aspects to specify the scope of exception handling
   */
  protected abstract pointcut inExceptionHandlingScope();

  /**
   * soften T within the scope of the aspect
   */
  declare soft: T : inExceptionHandlingScope();

  /**
   * bind an exception thrown in scope and pass it to the handler
   */
  after() throwing (T anException) : inExceptionHandlingScope() {
    onException(anException);
  }

}
]]></programlisting>

      <para>Notice how the type variable <literal>T extends Throwable</literal> allows the
      components of the aspect to be designed to work together in a type-safe manner. The
      following concrete sub-aspect shows how the abstract aspect might be extended to
      handle <literal>IOExceptions</literal>.</para>

      <programlisting><![CDATA[
public aspect IOExceptionHandling extends ExceptionHandling<IOException>{

  protected pointcut inExceptionHandlingScope() :
    call(* doIO*(..)) && within(org.xyz..*);

  /**
   * called whenever an IOException is thrown in scope.
   */
  protected void onException(IOException ex) {
    System.err.println("handled exception: " + ex.getMessage());
    throw new MyDomainException(ex);
  }
}
]]></programlisting>

      </sect2>

  </sect1>

</chapter>