discontinued / server · Files

index.html 203 KB
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 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 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>SOAP Version 1.2 Part 0: Primer (Second Edition)</title><style type="text/css">
code           { font-family: monospace; }

div.constraint,
div.issue,
div.note,
div.notice     { margin-left: 2em; }



.diff-chg	{ background-color:  #E47833;; }
.diff-del	{ background-color: red; text-decoration: line-through;}
.diff-add	{ background-color: lime; }

table          { empty-cells: show; }


div.exampleInner pre { margin-left: 1em;
                       margin-top: 0em; margin-bottom: 0em}
div.exampleOuter {border: 4px double gray;
                  margin: 0em; padding: 0em}
div.exampleInner { background-color: #d5dee3;
                   border-top-width: 4px;
                   border-top-style: double;
                   border-top-color: #d3d3d3;
                   border-bottom-width: 4px;
                   border-bottom-style: double;
                   border-bottom-color: #d3d3d3;
                   padding: 4px; margin: 0em }
div.exampleWrapper { margin: 4px }
div.exampleHeader { font-weight: bold;
                    margin: 4px}
</style><link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-REC.css"></head><body>
  <div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a></p>
<h1>SOAP Version 1.2 Part 0: Primer (Second Edition)</h1>
<h2>W3C Recommendation 27 April 2007</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2007/REC-soap12-part0-20070427/">http://www.w3.org/TR/2007/REC-soap12-part0-20070427/</a></dd><dt>Latest version:</dt><dd><a href="http://www.w3.org/TR/soap12-part0/">http://www.w3.org/TR/soap12-part0/</a></dd><dt>Previous versions:</dt><dd><a href="http://www.w3.org/TR/2006/PER-soap12-part0-20061219/">http://www.w3.org/TR/2006/PER-soap12-part0-20061219/</a></dd><dt>Editors:</dt>
      <dd>Nilo Mitra, Ericsson</dd>
      <dd>Yves Lafon, W3C</dd>
    </dl><p>Please refer to the <a href="http://www.w3.org/2007/04/REC-soap12-part0-20070427-errata.html"><strong>errata</strong></a> for this document, which may
      include normative corrections.</p>
<p>See also <a href="http://www.w3.org/2003/03/Translations/byTechnology?technology=soap12-part0">  translations</a>.</p>
<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2007 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr><div>
<h2><a name="abstract">Abstract</a></h2>



<p>SOAP Version 1.2 Part 0: Primer (Second Edition) is a non-normative document intended to
provide an easily understandable tutorial on the features of SOAP Version
1.2. In particular, it describes the features through various usage
scenarios, and is intended to complement the normative text contained in <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427">Part 1</a> and <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427">Part 2</a> of the
SOAP 1.2 specifications. This second edition includes additional material on
the SOAP Message Transmission Optimization Mechanism (MTOM), the XML-binary
Optimized Packaging (XOP) and the Resource Representation SOAP Header Block
(RRSHB) specifications.</p>
</div><div>
<h2><a name="status">Status of this Document</a></h2>

<p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p>

<p>This document is a <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#RecsW3C">W3C Recommendation</a>. It has been produced by the <a href="http://www.w3.org/2000/xp/Group/">XML Protocol Working Group</a>, which
is part of the <a href="http://www.w3.org/2002/ws/Activity">Web Services
Activity</a>.
This second edition is not a new version of the SOAP1.2 Primer. Rather, as a convenience to readers, it incorporates the changes reflected in the accumulated <a href="http://www.w3.org/2003/06/REC-soap12-20030624-errata.html#Errata0">errata</a> to the <a href="http://www.w3.org/TR/2003/REC-soap12-part0-20030624/">original Recommendation</a>. Additionally, it incorporates changes to incorporate an overview of the <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/">XML-binary Optimized Packaging</a>, <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">SOAP Message Transmission Optimization Mechanism</a> and <a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/">Resource Representation SOAP Header Block</a> specifications and their usage. Changes between these two versions are described in a
<a href="diff-part0.html">diff document</a>.</p>

<p>This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.</p>

<p>Please report errors in this document to the public mailing list <a href="mailto:xmlp-comments@w3.org">xmlp-comments@w3.org</a>
(<a href="http://lists.w3.org/Archives/Public/xmlp-comments/">archive</a>).
It is inappropriate to send discussion email to this address.</p>

<p>Since the primary purpose of this specification is to present a set of
SOAP Version 1.2 specifications and fonctionalities, no implementation report is provided. However, the SOAP 1.2 Implementation Report can be found at <a href="http://www.w3.org/2000/xp/Group/2/03/soap1.2implementation.html">
http://www.w3.org/2000/xp/Group/2/03/soap1.2implementation.html</a> and the
SOAP MTOM/XOP/RRSHB Implementation/Interop Summary can be found at <a href="http://www.w3.org/2000/xp/Group/4/08/implementation.html">http://www.w3.org/2000/xp/Group/4/08/implementation.html</a>.</p>

<p> This document is governed by the <a href="http://www.w3.org/TR/2002/NOTE-patent-practice-20020124">24 January 2002 CPP</a> as amended by the <a href="http://www.w3.org/2004/02/05-pp-transition">W3C Patent Policy Transition Procedure</a>. This document is informative only. W3C maintains a <a rel="disclosure" href="http://www.w3.org/2000/xp/Group/2/10/16-IPR-statements.html">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>. </p>

<p>A list of current <a href="http://www.w3.org/TR/">W3C Recommendations and
other technical reports</a> can be found at <a href="http://www.w3.org/TR">http://www.w3.org/TR</a>.</p>

</div>



<hr><div class="toc">
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#intro">Introduction</a><br>2. <a href="#L1161">Basic Usage Scenarios</a><br>3. <a href="#L1244">SOAP Processing Model</a><br>4. <a href="#transport">Using Various Protocol Bindings</a><br>5. <a href="#L579">Advanced Usage Scenarios</a><br>6. <a href="#L4697">Changes Between SOAP 1.1 and SOAP 1.2</a><br>7. <a href="#L810">References</a><br>A. <a href="#L10313">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="toc">
<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#intro">Introduction</a><br>    1.1 <a href="#L1153">Overview</a><br>    1.2 <a href="#L1157">Notational Conventions</a><br>2. <a href="#L1161">Basic Usage Scenarios</a><br>    2.1 <a href="#L1165">SOAP Messages</a><br>    2.2 <a href="#L1177">SOAP Message Exchange</a><br>        2.2.1 <a href="#L977">Conversational Message Exchanges</a><br>        2.2.2 <a href="#L1185">Remote Procedure Calls</a><br>    2.3 <a href="#L11549">Fault Scenarios</a><br>3. <a href="#L1244">SOAP Processing Model</a><br>    3.1 <a href="#L1271">The "role" Attribute</a><br>    3.2 <a href="#L1474">The "mustUnderstand" Attribute</a><br>    3.3 <a href="#LL10047">The "relay" Attribute</a><br>4. <a href="#transport">Using Various Protocol Bindings</a><br>    4.1 <a href="#L10309">The SOAP HTTP Binding</a><br>        4.1.1 <a href="#L26854">SOAP HTTP GET Usage</a><br>        4.1.2 <a href="#L26866">SOAP HTTP POST Usage</a><br>        4.1.3 <a href="#L3677">Web Architecture Compatible SOAP Usage</a><br>    4.2 <a href="#SMTP">SOAP Over Email</a><br>5. <a href="#L579">Advanced Usage Scenarios</a><br>    5.1 <a href="#L635">Using SOAP Intermediaries</a><br>    5.2 <a href="#L3374">Using Other Encoding Schemes</a><br>    5.3 <a href="#L3360">Optimized serialization of SOAP messages</a><br>        5.3.1 <a href="#L3785">The Abstract SOAP Transmission Optimization Feature</a><br>        5.3.2 <a href="#L3787">The Optimized Transmission Serialization Format</a><br>        5.3.3 <a href="#L3791">Using the Resource Representation SOAP Header Block</a><br>6. <a href="#L4697">Changes Between SOAP 1.1 and SOAP 1.2</a><br>7. <a href="#L810">References</a><br></p>
<h3><a name="appendix" id="appendix">Appendix</a></h3><p class="toc">A. <a href="#L10313">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="body">
    <div class="div1">
      
<h2><a name="intro"></a>1. Introduction</h2>

<p>SOAP Version 1.2 Part 0: Primer (Second Edition) is a non-normative document intended to
provide an easily understandable tutorial on the features of the SOAP Version
1.2 specifications. Its purpose is to help a technically competent person
understand how SOAP may be used, by describing representative SOAP message
structures and message exchange patterns.</p>

<p>In particular, this primer describes the features of SOAP through various
usage scenarios, and is intended to complement the normative text contained
in <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/">SOAP
Version 1.2 Part 1: Messaging Framework</a> (hereafter <a href="#L1092">[SOAP
Part1]</a>), <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/">SOAP Version 1.2
Part 2: Adjuncts</a> (hereafter <a href="#L1098">[SOAP Part2]</a>), the <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">SOAP Message
Transmission Optimization Mechanism</a> (MTOM) (hereafter <a href="#L9527">[MTOM]</a>), XML-binary Optimized Packaging <a href="#L3777">[XOP]</a> and the Resource Representation SOAP Header Block <a href="#L4299">[ResRep]</a> specifications.</p>

<p>It is expected that the reader has some familiarity with the basic syntax
of XML, including the use of XML namespaces and infosets, and Web concepts
such as URIs and HTTP. It is intended primarily for users of SOAP, such as
application designers, rather than implementors of the SOAP specifications,
although the latter may derive some benefit. This primer aims at highlighting
the essential features of SOAP Version 1.2, not at completeness in describing
every nuance or edge case. Therefore, there is no substitute for the main
specifications to obtain a fuller understanding of SOAP. To that end, this
primer provides extensive links to the main specifications wherever new
concepts are introduced or used.</p>

<p><a href="#L1092">[SOAP Part1]</a> defines the SOAP envelope, which is a
construct that defines an overall framework for representing the contents of
a SOAP message, identifying who should deal with all or part of it, and
whether handling such parts are optional or mandatory. It also defines a
protocol binding framework, which describes how the specification for a
binding of SOAP onto another underlying protocol may be written.</p>

<p><a href="#L1098">[SOAP Part2]</a> defines a data model for SOAP, a
particular encoding scheme for data types which may be used for conveying
remote procedure calls (RPC), as well as one concrete realization of the
underlying protocol binding framework defined in <a href="#L1092">[SOAP
Part1]</a>. This binding allows the exchange of SOAP messages either as
payload of a HTTP POST request and response, or as a SOAP message in the
response to a HTTP GET.</p>

<p><a href="#L9527">[MTOM] </a>describes an abstract feature for optimizing
the wire format of a SOAP message for certain type of content, as well as a
concrete implementation of it realized in an HTTP binding, while still
maintaining the modeling of a SOAP message as a single XML Infoset.</p>

<p><a href="#L3777">[XOP]</a>defines a convention for serializing more
efficiently an XML Infoset that has binary content. 
<a href="#L9527">[MTOM]</a> makes use of the
[<a href="#L3777">XOP</a>] format for optimizing the transmission of SOAP
messages.</p>

<p><a href="#L4299">[ResRep]</a> specifies a SOAP header block which carries a
representation of a Web resource, which is needed for processing a SOAP
message but which a receiver would prefer not to or cannot obtain by
dereferencing the URI for the resource carried within the message.</p>

<p>This document (the primer) is not normative, which means that it does not
provide the definitive specification of SOAP Version 1.2 or the other
specifications cited above. The examples provided here are intended to
complement the formal specifications, and in any question of interpretation
the formal specifications naturally take precedence. The examples shown here
provide a subset of the uses expected for SOAP. In actual usage scenarios,
SOAP will most likely be a part of an overall solution, and there will no
doubt be other application-specific requirements which are not captured in
these examples.</p>

<div class="div2">
  
<h3><a name="L1153"></a>1.1 Overview</h3>

<p>SOAP Version 1.2 provides the definition of the XML-based information
which can be used for exchanging structured and typed information between
peers in a decentralized, distributed environment. <a href="#L1092">[SOAP
Part1]</a> explains that a SOAP message is formally specified as an XML
Information Set [<a href="#R12">XML Infoset</a>] (henceforth often simply
infoset), which provides an abstract description of its contents. Infosets
can have different on-the-wire representations (aka serializations), one
common example of which is as an XML 1.0 [<a href="#L3532">XML 1.0</a>]
document. However, other serializations are also possible, and <a href="#L9527">[MTOM]</a> using the [<a href="#L3777">XOP</a>] format offers
one mechanism for doing so for the cases where there is a need to optimize
the processing and size of the transmitted message.</p>

<p>SOAP is fundamentally a stateless, one-way message exchange paradigm, but
applications can create more complex interaction patterns (e.g.,
request/response, request/multiple responses, etc.) by combining such one-way
exchanges with features provided by an underlying protocol and/or
application-specific information. SOAP is silent on the semantics of any
application-specific data it conveys, as it is on issues such as the routing
of SOAP messages, reliable data transfer, firewall traversal, etc. However,
SOAP provides the framework by which application-specific information may be
conveyed in an extensible manner. Also, SOAP provides a full description of
the required actions taken by a SOAP node on receiving a SOAP message.</p>

<p><a href="#L1161">Section 2</a> of this document provides an introduction
to the basic features of SOAP starting with the simplest usage scenarios,
namely a one-way SOAP message, followed by various request-response type
exchanges, including RPCs. Fault situations are also described.</p>

<p><a href="#L3631">Section 3</a> provides an overview of the SOAP processing
model, which describes the rules for initial construction of a message, rules
by which messages are processed when received at an intermediary or ultimate
destination, and rules by which portions of the message can be inserted,
deleted or modified by the actions of an intermediary.</p>

<p><a href="#transport">Section 4</a> of this document describes the ways in
which SOAP messages may be transported to realize various usage scenarios. It
describes the SOAP HTTP binding specified in <a href="#L1098">[SOAP
Part2]</a>, as well as an example of how SOAP messages may be conveyed in
email messages. As a part of the HTTP binding, it introduces two message
exchange patterns which are available to an application, one of which uses
the HTTP POST method, while the other uses HTTP GET. Examples are also
provided on how RPCs, in particular those that represent "safe" information
retrieval, may be represented in SOAP message exchanges in a manner that is
compatible with the architectural principles of the World Wide Web .</p>

<p><a href="#L579">Section 5</a> of this document provides a treatment of
various aspects of SOAP that can be used in more complex usage scenarios.
These include the extensibility mechanism offered through the use of header
elements, which may be targeted at specific intermediate SOAP nodes to
provide value-added services to communicating applications, using various
encoding schemes to serialize application-specific data in SOAP messages, and
the means to provide a more optimized serialization of a SOAP message under
certain circumstances.</p>

<p><a id="Section" href="#L4697" name="Section">Section 6</a> of this
document describes the changes from <a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">SOAP Version 1.1</a> [<a href="#R11">SOAP 1.1</a>].</p>

<p><a href="#L810">Section 7</a> of this document provides references.</p>

<p>For ease of reference, terms and concepts used in this primer are
hyper-linked to their definition in the main specifications.</p>

</div>

<div class="div2">
  
<h3><a name="L1157"></a>1.2 Notational Conventions</h3>

<p>Throughout this primer, sample SOAP envelopes and messages are shown as
[<a href="#L3532">XML 1.0</a>] documents. <a href="#L1092">[SOAP Part1]</a>
explains that a SOAP message is formally specified as an [<a href="#R12">XML
InfoSet</a>], which is an abstract description of its contents. The
distinction between the SOAP message infosets and their representation as XML
documents is unlikely to be of interest to those using this primer as an
introduction to SOAP; those who do care (typically those who port SOAP to new
protocol bindings where the messages may have alternative representations)
should understand these examples as referring to the corresponding XML
infosets. Further elaboration of this point is provided in <a href="#transport">Section 4</a> of this document.</p>

<p>The namespace prefixes "env", "enc",  "rpc", "rep", "xop" and "xmime"
used in the prose sections of this document are associated with the namespace
names "<a href="http://www.w3.org/2003/05/soap-envelope">http://www.w3.org/2003/05/soap-envelope</a>"
, "<a href="http://www.w3.org/2003/05/soap-encoding">http://www.w3.org/2003/05/soap-encoding</a>",
"<a href="http://www.w3.org/2003/05/soap-rpc">http://www.w3.org/2003/05/soap-rpc</a>",
<a href="http://www.w3.org/2004/08/representation">"http://www.w3.org/2004/08/representation",
"</a><a href="http://www.w3.org/2004/08/xop/include">http://www.w3.org/2004/08/xop/include</a>"
and "<a href="http://www.w3.org/2004/11/xmlmime">http://www.w3.org/2004/11/xmlmime</a>"
respectively.</p>

<p>The namespace prefixes "xs" and "xsi" used in the prose sections of this
document are associated with the namespace names
"http://www.w3.org/2001/XMLSchema" and
"http://www.w3.org/2001/XMLSchema-instance" respectively, both of which are
defined in the XML Schema specifications <a href="#R7">[XML Schema
Part1]</a>, <a href="#R8">[XML Schema Part2]</a>.</p>

<p>Note that the choice of any other namespace prefix is arbitrary and not
semantically significant.</p>

<p>Namespace URIs of the general form "http://example.org/..." and
"http://example.com/..." represent an application-dependent or
context-dependent URI <a href="#RFC3986">[RFC 3986]</a>.</p>
</div>
</div>

<div class="div1">
  
<h2><a name="L1161"></a>2. Basic Usage Scenarios</h2>

<p>A <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
SOAP message</a> is fundamentally a one-way transmission between<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts"> SOAP
nodes</a>, from a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
SOAP sender</a> to a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
SOAP receiver</a>, but SOAP messages are expected to be combined by
applications to implement more complex interaction patterns ranging from
request/response to multiple, back-and-forth "conversational" exchanges.</p>

<p>The primer starts by exposing the structure of a SOAP message and its
exchange in some simple usage scenarios based on a travel reservation
application. Various aspects of this application scenario will be used
throughout the primer. In this scenario, the travel reservation application
for an employee of a company negotiates a travel reservation with a travel
booking service for a planned trip. The information exchanged between the
travel reservation application and the travel service application is in the
form of SOAP messages.</p>

<p>The ultimate recipient of a SOAP message sent from the travel reservation
application is the travel service application, but it is possible that the
SOAP message may be "routed" through one or more <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
SOAP intermediaries</a> which act in some way on the message. Some simple
examples of such SOAP intermediaries might be ones that log, audit or,
possibly, amend each travel request. Examples, and a more detailed discussion
of the behavior and role of SOAP intermediaries, is postponed to <a href="#L635">section 5.1</a>.</p>

<p><a href="#L1165">Section 2.1</a> describes a travel reservation request
expressed as a SOAP message, which offers the opportunity to describe the
various "parts" of a SOAP message.</p>

<p><a href="#L977">Section 2.2.1</a> continues the same scenario to show a
response from the travel service in the form of another SOAP message, which
forms a part of a conversational message exchange as the various choices
meeting the constraints of the travel request are negotiated.</p>

<p><a href="#L1185">Section 2.2.2</a> assumes that the various parameters of
the travel reservation have been accepted by the traveller, and an exchange -
modelled as a remote procedure call (RPC) - between the travel reservation
and the travel service applications confirms the payment for the
reservation.</p>

<p><a href="#L11549">Section 2.3</a> shows examples of fault handling.</p>

<div class="div2">
    
<h3><a name="L1165"></a>2.1 SOAP Messages</h3>

<p><a href="#Example">Example 1</a> shows data for a travel reservation
expressed in a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
SOAP message</a>.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example" name="Example">Example 1</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
   &lt;m:dateAndTime&gt;2001-11-29T13:20:00.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   &lt;n:name&gt;Åke Jógvan Øyvind&lt;/n:name&gt;
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     &lt;p:departing&gt;New York&lt;/p:departing&gt;
     &lt;p:arriving&gt;Los Angeles&lt;/p:arriving&gt;
     &lt;p:departureDate&gt;2001-12-14&lt;/p:departureDate&gt;
     &lt;p:departureTime&gt;late afternoon&lt;/p:departureTime&gt;
     &lt;p:seatPreference&gt;aisle&lt;/p:seatPreference&gt;
   &lt;/p:departure&gt;
   &lt;p:return&gt;
     &lt;p:departing&gt;Los Angeles&lt;/p:departing&gt;
     &lt;p:arriving&gt;New York&lt;/p:arriving&gt;
     &lt;p:departureDate&gt;2001-12-20&lt;/p:departureDate&gt;
     &lt;p:departureTime&gt;mid-morning&lt;/p:departureTime&gt;
     &lt;p:seatPreference/&gt;
   &lt;/p:return&gt;
  &lt;/p:itinerary&gt;
  &lt;q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels"&gt;
   &lt;q:preference&gt;none&lt;/q:preference&gt;
  &lt;/q:lodging&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message for a travel reservation containing header blocks and a
body</div>
</div>

<p>The SOAP message in <a href="#Example">Example 1</a> contains two
SOAP-specific sub-elements within the overall <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenvelope">env:Envelope</a></code>,
namely an <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaphead">env:Header</a></code>
and an <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapbody">env:Body</a></code>.
The contents of these elements are application defined and not a part of the
SOAP specifications, although the latter do have something to say about how
such elements must be handled.</p>

<p>A <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
SOAP header</a> element is optional, but it has been included in the example
to explain certain features of SOAP. A SOAP header is an extension mechanism
that provides a way to pass information in SOAP messages that is not
application payload. Such "control" information includes, for example,
passing directives or contextual information related to the processing of the
message. This allows a SOAP message to be extended in an application-specific
manner. The immediate child elements of the <code>env:Header</code> element
are called<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
header blocks</a>, and represent a logical grouping of data which, as shown
later, can individually be targeted at SOAP nodes that might be encountered
in the path of a message from a sender to an ultimate receiver.</p>

<p>SOAP headers have been designed in anticipation of various uses for SOAP,
many of which will involve the participation of other SOAP processing nodes -
called <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
SOAP intermediaries</a> - along a message's path from an <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">initial
SOAP sender</a> to an <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">ultimate
SOAP receiver</a>. This allows SOAP intermediaries to provide value-added
services. Headers, as shown later, may be inspected, inserted, deleted or
forwarded by SOAP nodes encountered along a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">SOAP
message path</a>. (It should be kept in mind, though, that the SOAP
specifications do not deal with what the contents of header elements are, or
how SOAP messages are routed between nodes, or the manner by which the route
is determined and so forth. These are a part of the overall application, and
could be the subject of other specifications.)</p>

<p>The<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#encapsulation">
SOAP body</a> is the mandatory element within the SOAP <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenvelope">env:Envelope</a></code>,
which implies that this is where the main end-to-end information conveyed in
a SOAP message must be carried.</p>

<p>A pictorial representation of the SOAP message in <a href="#Example">Example 1</a> is as follows.</p>

<img src="primer-figure-1.png" alt="SOAP message structure">
<p align="center">Figure 1: SOAP message structure</p>


<p>In <a href="#Example">Example 1</a>, the header contains two header
blocks, each of which is defined in its own XML namespace and which represent
some aspect pertaining to the overall processing of the body of the SOAP
message. For this travel reservation application, such "meta" information
pertaining to the overall request is a <code>reservation</code> header block
which provides a reference and time stamp for this instance of a reservation,
and the traveller's identity in the <code>passenger</code> block.</p>

<p>The header blocks <code>reservation</code> and <code>passenger</code> must
be processed by the next SOAP intermediary encountered in the message path
or, if there is no intermediary, by the ultimate recipient of the message.
The fact that it is targeted at the next SOAP node encountered <em>en
route</em> is indicated by the presence of the attribute <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaprole">env:role</a></code>
with the value "http://www.w3.org/2003/05/soap-envelope/role/next" (hereafter
simply "next"), which is a<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">
role</a> that all SOAP nodes must be willing to play. The presence of an
<code>env:mustUnderstand</code> attribute with value "true" indicates that
the node(s) processing the header must absolutely process these header blocks
in a manner consistent with their specifications, or else not process the
message at all and throw a fault. Note that whenever a header block is
processed, either because it is marked <code>env:mustUnderstand="true"</code>
or for another reason, the block must be processed in accordance with the
specifications for that block. Such header block specifications are
application defined and not a part of SOAP. <a href="#L1244">Section 3</a>
will elaborate further on SOAP message processing based on the values of
these attributes.</p>

<p>The choices of what data is placed in a header block and what goes in the
SOAP body are decisions made at the time of application design. The main
point to keep in mind is that header blocks may be targeted at various nodes
that might be encountered along a message's path from a sender to the
ultimate recipient. Such intermediate SOAP nodes may provide value-added
services based on data in such headers. In <a href="#Example">Example 1</a>,
the passenger data is placed in a header block to illustrate the use of this
data at a SOAP intermediary to do some additional processing. For example, as
shown later in <a href="#L635">section 5.1,</a> the outbound message is
altered by the SOAP intermediary by having the travel policies pertaining to
this passenger appended to the message as another header block.</p>

<p>The <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapbody">env:Body</a></code>
element and its associated child elements, <code>itinerary</code> and
<code>lodging</code>, are intended for exchange of information between the<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
initial SOAP sender</a> and the SOAP node which assumes the role of the<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
ultimate SOAP receiver</a> in the message path, which is the travel service
application. Therefore, the <code>env:Body</code> and its contents are
implicitly targeted and are expected to be understood by the ultimate
receiver. The means by which a SOAP node assumes such a role is not defined
by the SOAP specification, and is determined as a part of the overall
application semantics and associated message flow.</p>

<p>Note that a SOAP intermediary may decide to play the role of the ultimate
SOAP receiver for a given message transfer, and thus process the
<code>env:Body</code>. However, even though this sort of a behavior cannot be
prevented, it is not something that should be done lightly as it may pervert
the intentions of the message's sender, and have undesirable side effects
(such as not processing header blocks that might be targeted at
intermediaries further along the message path).</p>

<p>A SOAP message such as that in <a href="#Example">Example 1</a> may be
transferred by different underlying protocols and used in a variety of<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts"> message
exchange patterns</a>. For example, for a Web-based access to a travel
service application, it could be placed in the body of a HTTP POST request.
In another protocol binding, it might be sent in an email message (see <a href="#SMTP">section 4.2</a>). <a href="#transport"> Section 4</a> will
describe how SOAP messages may be conveyed by a variety of underlying
protocols. For the time being, it is assumed that a mechanism exists for
message transfer and the remainder of this section concentrates on the
details of the SOAP messages and their processing.</p>

</div>
<div class="div2">
  
<h3><a name="L1177"></a>2.2 SOAP Message Exchange</h3>

<p>SOAP Version 1.2 is a simple messaging framework for transferring
information specified in the form of an XML infoset between an initial SOAP
sender and an ultimate SOAP receiver. The more interesting scenarios
typically involve multiple message exchanges between these two nodes. The
simplest such exchange is a request-response pattern. Some early uses of [<a href="#R11">SOAP 1.1</a>] emphasized the use of this pattern as means for
conveying remote procedure calls (RPC), but it is important to note that not
all SOAP request-response exchanges can or need to be modelled as RPCs. The
latter is used when there is a need to model a certain programmatic behavior,
with the exchanged messages conforming to a pre-defined description of the
remote call and its return.</p>

<p>A much larger set of usage scenarios than that covered by the
request-response pattern can be modeled simply as XML-based content exchanged
in SOAP messages to form a back-and-forth "conversation", where the semantics
are at the level of the sending and receiving applications. <a href="#L977">Section 2.2.1</a> covers the case of XML-based content exchanged
in SOAP messages between the travel reservation application and the travel
service application in a conversational pattern, while <a href="#L1185">section 2.2.2</a> provides an example of an exchange modeled as
an RPC.</p>

<div class="div3">
   
<h4><a name="L977"></a>2.2.1 Conversational Message Exchanges</h4>

<p>Continuing with the travel request scenario, <a href="#Example3">Example
2</a> shows a SOAP message returned from the travel service in response to
the reservation request message in <a href="#Example">Example 1</a>. This
response seeks to refine some information in the request, namely the choice
of airports in the departing city.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example3" name="Example3">Example 2</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
   &lt;m:dateAndTime&gt;2001-11-29T13:35:00.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   &lt;n:name&gt;Åke Jógvan Øyvind&lt;/n:name&gt;
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;p:itineraryClarification 
    xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     &lt;p:departing&gt;
       &lt;p:airportChoices&gt;
          JFK LGA EWR 
       &lt;/p:airportChoices&gt;
     &lt;/p:departing&gt;
   &lt;/p:departure&gt;
   &lt;p:return&gt;
     &lt;p:arriving&gt;
       &lt;p:airportChoices&gt;
         JFK LGA EWR 
       &lt;/p:airportChoices&gt;
     &lt;/p:arriving&gt;
   &lt;/p:return&gt;  
  &lt;/p:itineraryClarification&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message sent in response to the message in <a href="#Example">Example
1</a></div>
</div>

<p>As described earlier, the <code>env:Body</code> contains the primary
content of the message, which in this example includes a list of the various
alternatives for the airport, conforming to a schema definition in the XML
namespace http://travelcompany.example.org/reservation/travel. In this
example, the header blocks from <a href="#Example">Example 1</a> are returned
(with some sub-element values altered) in the response. This could allow
message correlation at the SOAP level, but such headers are very likely to
also have other application-specific uses.</p>

<p>The message exchange<span class="insert">s</span> in Examples 1 and 2 are
cases where XML-based contents conforming to some application-defined schema
are exchanged via SOAP messages. Once again, a discussion of the means by
which such messages are transferred is deferred to <a href="#transport">section 4</a>.</p>

<p>It is easy enough to see how such exchanges can build up to a multiple
back-and-forth "conversational" message exchange pattern. <a href="#Example4">Example 3</a> shows a SOAP message sent by the travel
reservation application in response to that in <a href="#Example3">Example
2</a> choosing one from the list of available airports. The header block
<code>reservation</code> with the same value of the <code>reference</code>
sub-element accompanies each message in this conversation, thereby offering a
way, should it be needed, to correlate the messages exchanged between them at
the application level.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example4" name="Example4">Example 3</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation 
     xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
    &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
    &lt;m:dateAndTime&gt;2001-11-29T13:36:50.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   &lt;n:name&gt;Åke Jógvan Øyvind&lt;/n:name&gt;
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;p:itinerary 
   xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     &lt;p:departing&gt;LGA&lt;/p:departing&gt;
   &lt;/p:departure&gt;
   &lt;p:return&gt;
     &lt;p:arriving&gt;EWR&lt;/p:arriving&gt;
   &lt;/p:return&gt;
  &lt;/p:itinerary&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Response to the message in <a href="#Example3">Example 2</a> continuing a
conversational message exchange</div>
</div>
</div>
<div class="div3">
  
<h4><a name="L1185"></a>2.2.2 Remote Procedure Calls</h4>

<p>One of the design goals of SOAP Version 1.2 is to encapsulate remote
procedure call functionality using the extensibility and flexibility of XML.
<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapforrpc">
SOAP Part 2 section 4</a> has defined a uniform representation for RPC
invocations and responses carried in SOAP messages. This section continues
with the travel reservation scenario to illustrate the use of SOAP messages
to convey remote procedure calls and their return.</p>

<p>To that end, the next example shows the payment for the trip using a
credit card. (It is assumed that the conversational exchanges described in <a href="#L977">section 2.2.1</a> have resulted in a confirmed itinerary.) Here,
it is further assumed that the payment happens in the context of an overall
transaction where the credit card is charged only when the travel and the
lodging (not shown in any example, but presumably reserved in a similar
manner) are both confirmed. The travel reservation application provides
credit card information and the successful completion of the different
activities results in the card being charged and a reservation code returned.
This reserve-and-charge interaction between the travel reservation
application and the travel service application is modeled as a SOAP RPC.</p>

<p>To invoke a SOAP RPC, the following information is needed:</p>
<ol>
  <li id="underlying">The address of the target SOAP node.</li>
  <li>The procedure or method name.</li>
  <li>The identities and values of any arguments to be passed to the
    procedure or method together with any output parameters and return
  value.</li>
  <li id="clear">A clear separation of the arguments
    used to identify the Web resource which is the actual target for the RPC,
    as contrasted with those that convey data or control information used for
    processing the call by the target resource.</li>
  <li id="message">The
    message exchange pattern which will be employed to convey the RPC,
    together with an identification of the so-called "Web Method" (on which
    more later) to be used.</li>
  <li id="Optionally">Optionally, data which may be carried as a part of
    SOAP header blocks.</li>
</ol>

<p>Such information may be expressed by a variety of means, including formal
Interface Definition Languages (IDL). Note that SOAP does not provide any
IDL, formal or informal. Note also that the above information differs in
subtle ways from information generally needed to invoke other, non-SOAP
RPCs.</p>

<p>Regarding <a href="#underlying">Item 1</a> above, there is, from a SOAP
perspective, a SOAP node which "contains" or "supports" the target of the
RPC. It is the SOAP node which (appropriately) adopts the role of the <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#senderreceiverconcepts">
ultimate SOAP receiver</a>. As required by <a href="#underlying">Item 1</a>,
the ultimate recipient can identify the target of the named procedure or
method by looking for its URI. The manner in which the target URI is made
available depends on the underlying protocol binding. One possibility is that
the URI identifying the target is carried in a SOAP header block. Some
protocol bindings, such as the SOAP HTTP binding defined in [<a href="#L1098">SOAP Part2</a>], offer a mechanism for carrying the URI outside
the SOAP message. In general, one of the properties of a protocol binding
specification must be a description of how the target URI is carried as a
part of the binding. <a href="#L10309">Section 4.1</a> provides some concrete
examples of how the URI is carried in the case of the standardized SOAP
protocol binding to HTTP.</p>

<p><a href="#clear">Item 4</a> and <a>Item 5</a> above are required to ensure
that RPC applications that employ SOAP can do so in a manner which is
compatible with the architectural principles of the World Wide Web. <a href="#L3677">Section 4.1.3</a> discusses how the information provided by
items 4 and 5 are utilized.</p>

<p>For the remainder of this section, it is assumed that the RPC conveyed in
a SOAP message as shown in <a href="#Example2">Example 4</a> is appropriately
targeted and dispatched. The purpose of this section is to highlight the
syntactical aspects of RPC requests and returns carried  within a SOAP
message.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example2" name="Example2">Example 4</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" &gt;
 &lt;env:Header&gt;
   &lt;t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" &gt;5&lt;/t:transaction&gt;
 &lt;/env:Header&gt;  
 &lt;env:Body&gt;
  &lt;m:chargeReservation
      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
         xmlns:m="http://travelcompany.example.org/"&gt;
   &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation"&gt;
    &lt;m:code&gt;FT35ZBQ&lt;/m:code&gt;
   &lt;/m:reservation&gt;
   &lt;o:creditCard xmlns:o="http://mycompany.example.com/financial"&gt;
    &lt;n:name xmlns:n="http://mycompany.example.com/employees"&gt;
           Åke Jógvan Øyvind
    &lt;/n:name&gt;
    &lt;o:number&gt;123456789099999&lt;/o:number&gt;
    &lt;o:expiration&gt;2005-02&lt;/o:expiration&gt;
   &lt;/o:creditCard&gt;
  &lt;/m:chargeReservation&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP RPC request with a mandatory header and two input (or "in")
parameters</div>
</div>

<p>The RPC itself is carried as a child of the <code>env:Body</code> element,
and is modelled as a <code>struct</code> which takes the name of the
procedure or method, in this case <code>chargeReservation</code>. (A
<code>struct</code> is <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#values">a concept
from the SOAP Data Model</a> defined in [<a href="#L1098">SOAP Part2</a>]
that models a structure or record type that occurs in some common programming
languages.) The design of the RPC in the example (whose formal description
has not been explicitly provided) takes two input (or "in") parameters, the
<code>reservation</code> corresponding to the planned trip identified by the
reservation <code>code</code>, and the <code>creditCard</code> information.
The latter is also a <code>struct</code>, which takes three elements, the
card holder's <code>name</code>, the card <code>number</code> and an
<code>expiration</code> date.</p>

<p>In this example, the <code>env:encodingStyle</code> attribute with the
value <a href="http://www.w3.org/2003/05/soap-encoding">http://www.w3.org/2003/05/soap-encoding</a>
shows that the contents of the <code>chargeReservation</code> structure have
been serialized according to the SOAP encoding rules, i.e., the particular
rules defined in<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapenc"> SOAP
Part 2 section 3</a>. Even though SOAP specifies this particular encoding
scheme, its use is optional and the specification makes clear that other
encoding schemes may be used for application-specific data within a SOAP
message. It is for this purpose that it provides the
<code>env:encodingStyle</code> attribute to qualify header blocks and body
sub-elements. The choice of the value for this attribute is an
application-specific decision and the ability of a caller and callee to
interoperate is assumed to have been settled "out-of-band". <a href="#L3374">Section 5.2</a> shows an example of using another encoding
scheme.</p>

<p>As noted in <a href="#Optionally">Item 6</a> above, RPCs may also require
additional information to be carried, which can be important for the
processing of the call in a distributed environment, but which are not a part
of the formal procedure or method description. (Note, however, that providing
such additional contextual information is not specific to RPCs, but may be
required in general for the processing of any distributed application.) In
the example, the RPC is carried out in the context of an overall transaction
which involves several activities which must all complete successfully before
the RPC returns successfully. <a href="#Example2">Example 4</a> shows how a
header block <code>transaction</code> directed at the ultimate recipient
(implied by the absence of the <code>env:role</code> attribute) is used to
carry such information. (The value "5" is some transaction identifier set by
and meaningful to the application. No further elaboration of the
application-specific semantics of this header are provided here, as it is not
germane to the discussion of the syntactical aspects of SOAP RPC
messages.)</p>

<p>Let us assume that the RPC in the charging example has been designed to
have the procedure description which indicates that there are two output (or
"out") parameters, one providing the reference code for the reservation and
the other a URL where the details of the reservation may be viewed. The RPC
response is returned in the <code>env:Body</code> element of a SOAP message,
which is modeled as a <code>struct</code> taking the procedure name
<code>chargeReservation</code> and, as a convention, the word "Response"
appended. The two output (or "out") parameters accompanying the response are
the alphanumeric <code>code</code> identifying the reservation in question,
and a URI for the location, <code>viewAt</code>, from where the reservation
may be retrieved.</p>

<p>This is shown in <a href="#Example5">Example 5a</a>, where the header
again identifies the transaction within which this RPC is performed.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example5" name="Example5">Example 5a</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" &gt;
 &lt;env:Header&gt;
     &lt;t:transaction
        xmlns:t="http://thirdparty.example.org/transaction"
          env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true"&gt;5&lt;/t:transaction&gt;
 &lt;/env:Header&gt;  
 &lt;env:Body&gt;
     &lt;m:chargeReservationResponse 
         env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
             xmlns:m="http://travelcompany.example.org/"&gt;
       &lt;m:code&gt;FT35ZBQ&lt;/m:code&gt;
       &lt;m:viewAt&gt;
         http://travelcompany.example.org/reservations?code=FT35ZBQ
       &lt;/m:viewAt&gt;
     &lt;/m:chargeReservationResponse&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
RPC response with two output (or "out") parameters for the call shown in <a href="#Example2">Example 4</a></div>
</div>

<p>RPCs often have descriptions where a particular output parameter is
distinguished, the so-called "return" value. The<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#rpcresponse"> SOAP
RPC convention</a> offers a way to distinguish this "return" value from the
other output parameters in the procedure description. To show this, the
charging example is modified to have an RPC description that is almost the
same as that for <a href="#Example5">Example 5a</a>, i.e, with the same two
"out" parameters, but in addition it also has a "return" value, which is an
enumeration with potential values of "confirmed" and "pending". The RPC
response conforming to this description is shown in <a href="#Example51">Example 5b</a>, where the SOAP header, as before,
identifies the transaction within which this RPC is performed.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example51" name="Example51">Example 5b</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" &gt;
 &lt;env:Header&gt;
    &lt;t:transaction
       xmlns:t="http://thirdparty.example.org/transaction"
         env:encodingStyle="http://example.com/encoding"
          env:mustUnderstand="true"&gt;5&lt;/t:transaction&gt;
 &lt;/env:Header&gt;  
 &lt;env:Body&gt;
    &lt;m:chargeReservationResponse 
       env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
           xmlns:rpc="http://www.w3.org/2003/05/soap-rpc"
             xmlns:m="http://travelcompany.example.org/"&gt;
       &lt;rpc:result&gt;m:status&lt;/rpc:result&gt;
       &lt;m:status&gt;confirmed&lt;/m:status&gt;
       &lt;m:code&gt;FT35ZBQ&lt;/m:code&gt;
       &lt;m:viewAt&gt;
        http://travelcompany.example.org/reservations?code=FT35ZBQ
       &lt;/m:viewAt&gt;
    &lt;/m:chargeReservationResponse&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
RPC response with a "return" value and two "out" parameters for the call
shown in <a href="#Example2">Example 4</a></div>
</div>

<p>In <a href="#Example51">Example 5b</a>, the return value is identified by
the element <code>rpc:result</code>, and contains the XML Qualified Name (of
type <code>xs:QName</code>) of another element within the <code>struct</code>
which is <code>m:status</code>. This, in turn, contains the actual return
value, "confirmed". This technique allows the actual return value to be
strongly typed according to some schema. If the <code>rpc:result</code>
element is absent, as is the case in <a href="#Example5">Example 5a</a>, the
return value is not present or is of the type <code>void</code>.</p>

<p>While, in principle, using SOAP for RPC is independent of the decision to
use a particular means for transferring the RPC call and its return, certain
protocol bindings that support the SOAP<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">
Request-Response message exchange pattern</a> may be more naturally suited
for such purposes. A protocol binding supporting this message exchange
pattern can provide the correlation between a request and a response. Of
course, the designer of an RPC-based application could choose to put a
correlation ID relating a call and its return in a SOAP header, thereby
making the RPC independent of any underlying transfer mechanism. In any case,
application designers have to be aware of all the characteristics of the
particular protocols chosen for transferring SOAP RPCs, such as latency,
synchrony, etc.</p>

<p>In the commonly used case, standardized in<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapinhttp"> SOAP
Part 2 section 7</a>, of using HTTP as the underlying transfer protocol, an
RPC invocation maps naturally to the HTTP request and an RPC response maps to
the HTTP response. <a href="#L10309">Section 4.1</a> provides examples of
carrying RPCs using the HTTP binding.</p>

<p>However, it is worth keeping in mind that even though most examples of
SOAP for RPC use the HTTP protocol binding, it is not limited to that means
alone.</p>

 </div>
</div>

<div class="div2">
  
<h3><a name="L11549"></a>2.3 Fault Scenarios</h3>

<p>SOAP provides a model for handling situations when faults arise in the
processing of a message. SOAP distinguishes between the conditions that
result in a fault, and the ability to signal that fault to the originator of
the faulty message or another node. The ability to signal the fault depends
on the message transfer mechanism used, and one aspect of the binding
specification of SOAP onto an underlying protocol is to specify how faults
are signalled, if at all. The remainder of this section assumes that a
transfer mechanism is available for signalling faults generated while
processing received messages, and concentrates on the structure of the SOAP
fault message.</p>

<p>The SOAP <code>env:Body</code> element has another distinguished role in
that it is the place where such fault information is placed. The SOAP fault
model (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#procsoapmsgs">
SOAP Part 1, section 2.6</a>) requires that all SOAP-specific and
application-specific faults be reported using a <em>single</em> distinguished
element, <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapfault">
env:Fault</a></code>, carried within the <code>env:Body</code> element. The
<code>env:Fault</code> element contains two mandatory sub-elements, <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodeelement">env:Code</a></code>
and <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultstringelement">env:Reason</a></code>,
and (optionally) application-specific information in the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultdetailelement">env:Detail</a></code>
sub-element. Another optional sub-element,<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultactorelement">
env:Node</a></code>, identifies via a URI the SOAP node which generated the
fault, its absence implying that it was the ultimate recipient of the message
which did so. There is yet another optional sub-element, <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultroleelement">env:Role</a></code>,
which identifies the role being played by the node which generated the
fault.</p>

<p>The <code>env:Code</code> sub-element of <code>env:Fault</code> is itself
made up of a mandatory <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultvalueelement">env:Value</a></code>
sub-element, whose content is specified in the SOAP specification (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodes"> SOAP
Part 1 section 5.4.6</a>) as well as an optional <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultsubcodeelement">env:Subcode</a></code>
sub-element.</p>

<p><a href="#Example7">Example 6a</a> shows a SOAP message returned in
response to the RPC request in <a href="#Example2">Example 4</a>, and
indicating a failure to process the RPC.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example7" name="Example7">Example 6a</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
            xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'&gt;
  &lt;env:Body&gt;
   &lt;env:Fault&gt;
     &lt;env:Code&gt;
       &lt;env:Value&gt;env:Sender&lt;/env:Value&gt;
       &lt;env:Subcode&gt;
        &lt;env:Value&gt;rpc:BadArguments&lt;/env:Value&gt;
       &lt;/env:Subcode&gt;
     &lt;/env:Code&gt;
     &lt;env:Reason&gt;
      &lt;env:Text xml:lang="en-US"&gt;Processing error&lt;/env:Text&gt;
      &lt;env:Text xml:lang="cs"&gt;Chyba zpracování&lt;/env:Text&gt;
     &lt;/env:Reason&gt;
     &lt;env:Detail&gt;
      &lt;e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults"&gt;
        &lt;e:message&gt;Name does not match card number&lt;/e:message&gt;
        &lt;e:errorcode&gt;999&lt;/e:errorcode&gt;
      &lt;/e:myFaultDetails&gt;
     &lt;/env:Detail&gt;
   &lt;/env:Fault&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message indicating failure <span class="exampleWrapper">to
process the RPC in <a href="#Example2">Example 4</a></span></div>
</div>

<p>In <a href="#Example7">Example 6a</a>, the top-level
<code>env:Value</code> uses a standardized XML Qualified Name (of type
<code>xs:QName</code>) to identify that it is an <code>env:Sender</code>
fault, which indicates that it is related to some syntactical error or
inappropriate information in the message. (When a <code>env:Sender</code>
fault is received by the sender, it is expected that some corrective action
is taken before a similar message is sent again.) The
<code>env:Subcode</code> element is optional, and, if present, as it is in
this example, qualifies the parent value further. In <a href="#Example7">Example 6a</a>, the <code>env:Subcode</code> denotes that an
RPC specific fault, <code>rpc:BadArguments</code>, defined in <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#rpcfaults">SOAP
Part 2 section 4.4</a>, is the cause of the failure to process the
request.</p>

<p>The structure of the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultsubcodeelement">env:Subcode</a></code>
element has been chosen to be hierarchical - each child
<code>env:Subcode</code> element has a mandatory <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultsubvalueelem">env:Value</a></code>
and an optional <code>env:Subcode</code> sub-element - to allow
application-specific codes to be carried. This hierarchical structure of the
<code>env:Code</code> element allows for an uniform mechanism for conveying
multiple level of fault codes. The top-level <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultvalueelement">env:Value</a></code>
is a base fault that is specified in the SOAP Version 1.2 specifications (see
<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodes">SOAP
Part 1 section 5.4.6</a>) and must be understood by all SOAP nodes. Nested
<code>env:Value</code>s are application-specific, and represent further
elaboration or refinement of the base fault from an application perspective.
Some of these values may well be standardized, such as the RPC codes
standardized in SOAP 1.2 (see<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#rpcfaults"> SOAP
Part 2 section 4.4</a>), or in some other standards that use SOAP as an
encapsulation protocol. The only requirement for defining such
application-specific subcode values is that they be namespace qualified using
any namespace other than the SOAP <code><a href="http://www.w3.org/2003/05/soap-envelope">env</a></code> namespace which
defines the main classifications for SOAP faults. There is no requirement
from a SOAP perspective that applications need to understand, or even look at
all levels of the subcode values.</p>

<p>The <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultstringelement">env:Reason</a></code>
sub-element is not meant for algorithmic processing, but rather for human
understanding; so, even though this is a mandatory item, the chosen value
need not be standardized. Therefore all that is required is that it
reasonably accurately describe the fault situation. It must have one or more
<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#reasontextelement">env:Text</a></code>
sub-elements, each with a unique <code>xml:lang</code> attribute, which
allows applications to make the fault reason available in multiple languages.
(Applications could negotiate the language of the fault text using a
mechanism built using SOAP headers; however this is outside the scope of the
SOAP specifications.)</p>

<p>The absence of a  <code>env:Node</code> sub-element within
<code>env:Fault</code> in <a href="#Example7">Example 6a</a> implies that it
is generated by the ultimate receiver of the call. The contents of
<code>env:Detail</code>, as shown in the example, are
application-specific.</p>

<p>During the processing of a SOAP message, a fault may also be generated if
a mandatory header element is not understood or the information contained in
it cannot be processed. Errors in processing a header block are also
signalled using a <code>env:Fault</code> element within the
<code>env:Body</code>, but with a particular distinguished header block,
<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapnotunderstood">env:NotUnderstood</a></code>,
that identifies the offending header block.</p>

<p><a href="#Example12">Example 6b</a> shows an example of a response to the
RPC in <a href="#Example2">Example 4</a> indicating a failure to process the
<code>t:transaction</code> header block. Note the presence of the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#faultcodes">env:MustUnderstand</a></code>
fault code in the <code>env:Body</code>, and the identification of the header
not understood using an (unqualified) attribute, <code>qname</code>, in the
special (empty) header block <code>env:NotUnderstood</code>.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example12" id="Example12">Example 6b</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt;
 &lt;env:Header&gt;
    &lt;<span class="highlight">env:NotUnderstood</span> qname="t:transaction"
               xmlns:t="http://thirdparty.example.org/transaction"/&gt;
 &lt;/env:Header&gt;  
 &lt;env:Body&gt;
  &lt;env:Fault&gt;
   &lt;env:Code&gt;
    &lt;env:Value&gt;<span class="highlight">env:MustUnderstand</span>&lt;/env:Value&gt;
   &lt;/env:Code&gt;
   &lt;env:Reason&gt;
      &lt;env:Text xml:lang="en-US"&gt;Header not understood&lt;/env:Text&gt;
      &lt;env:Text xml:lang="fr"&gt;En-tête non compris&lt;/env:Text&gt;
   &lt;/env:Reason&gt;    
  &lt;/env:Fault&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message indicating failure <span class="exampleWrapper">to
process the header block in <a href="#Example2">Example 4</a></span></div>
</div>

<p>If there were several mandatory header blocks that were not understood,
then each could be identified by its <code>qname</code> attribute in a series
of such <code>env:NotUnderstood</code> header blocks.</p>

 </div>
</div>

<div class="div1">
  
<h2><a name="L1244"></a>3. <span id="L3631">SOAP Processing Model</span></h2>

<p>Having established the various syntactical aspects of a SOAP message as
well as some basic message exchange patterns, this section provides a general
overview of the SOAP processing model (specified in<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#msgexchngmdl">
SOAP Part 1, section 2</a>). The SOAP processing model describes the actions
taken by a SOAP node on receiving a SOAP message.</p>

<p><a href="#Example1">Example 7a</a> shows a SOAP message with several
header blocks (with their contents omitted for brevity). Variations of this
will be used in the remainder of this section to illustrate various aspects
of the processing model.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example1" name="Example1">Example 7a</a></div>

<div class="exampleInner">
<pre>&lt;?xml version="1.0" ?&gt;
 &lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt;
   &lt;env:Header&gt;
     &lt;p:oneBlock xmlns:p="http://example.com" 
            env:role="http://example.com/Log"&gt;
     ...
     ...
     &lt;/p:oneBlock&gt;
     &lt;q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"&gt;
     ...
     ...
     &lt;/q:anotherBlock&gt;
     &lt;r:aThirdBlock xmlns:r="http://example.com"&gt;
     ...
     ...
     &lt;/r:aThirdBlock&gt;
   &lt;/env:Header&gt;
   &lt;env:Body &gt;
     ...
     ...
   &lt;/env:Body&gt;
 &lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message showing a variety of header blocks</div>
</div>

<p>The SOAP processing model describes the (logical) actions taken by a SOAP
node on receiving a SOAP message. There is a requirement for the node to
analyze those parts of a message that are SOAP-specific, namely those
elements in the SOAP "<a href="http://www.w3.org/2003/05/soap-envelope">env</a>" namespace. Such
elements are the envelope itself, the header element and the body element. A
first step is, of course, the overall check that the SOAP message is
syntactically correct. That is, it conforms to the SOAP XML infoset subject
to the restrictions on the use of certain XML constructs - Processing
Instructions and Document Type Definitions - as defined in <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenv"> SOAP
Part 1, section 5.</a></p>

<div class="div2">
   
<h3><a name="L1271"></a>3.1 <span id="L6293">The "role" Attribute</span></h3>

<p>Further processing of header blocks and the body depend on the<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">
role</a>(s) assumed by the SOAP node for the processing of a given message.
SOAP defines the (optional) <code>env:role</code> attribute - syntactically,
<code>xs:anyURI</code> - that may be present in a header block, which
identifies the role played by the intended target of that header block. A
SOAP node is required to process a header block if it assumes the role
identified by the value of the URI. How a SOAP node assumes a particular role
is not a part of the SOAP specifications.</p>

<p>Three standardized roles have been defined (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaproles"> SOAP
Part 1, section 2.2</a>), which are</p>
<ul>
  <li>"http://www.w3.org/2003/05/soap-envelope/role/none" (hereafter simply
    "none")</li>
  <li>"http://www.w3.org/2003/05/soap-envelope/role/next" (hereafter simply
    "next"), and</li>
  <li>"http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver"
    (hereafter simply "ultimateReceiver").</li>
</ul>

<p>In <a href="#Example1">Example 7a</a>, the header block
<code>oneBlock</code> is targeted at any SOAP node that plays the
application-defined role defined by the URI http://example.com/Log. For
purposes of illustration, it is assumed that the specification for such a
header block requires that any SOAP node adopting this role log the entire
message.</p>

<p>Every SOAP node receiving a message with a header block that has a
<code>env:role</code> attribute of "next" must be capable of processing the
contents of the element, as this is a standardized role that every SOAP node
must be willing to assume. A header block thus attributed is one which is
expected to be examined and (possibly) processed by the next SOAP node along
the path of a message, assuming that such a header has not been removed as a
result of processing at some node earlier in the message path.</p>

<p>In <a href="#Example1">Example 7a</a>, the header block
<code>anotherBlock</code> is targeted at the next node in the message path.
In <a href="#Example1"></a>this case, the SOAP message received by the node
playing the application-defined role of "http://example.com/Log", must also
be willing to play the SOAP-defined role of "next". This is also true for the
node which is the ultimate recipient of the message, as it obviously (and
implicitly) also plays the "next" role by virtue of being next in the message
path.</p>

<p>The third header block, <code>aThirdBlock</code>, in <a href="#Example1">Example 7a</a> does not have the <code>env:role</code>
attribute. It is targeted at a SOAP node which assumes the "ultimateReceiver"
role. The "ultimateReceiver" role (which can be explicitly declared or is
implicit if the <code>env:role</code> attribute is absent in a header block)
is played by a SOAP node that assumes the role of the ultimate recipient of a
particular SOAP message. The absence of a <code>env:role</code> attribute in
the <code>aThirdBlock</code> header block means that this header element is
targeted at the SOAP node that assumes the "ultimateReceiver" role.</p>

<p>Note that the <code>env:Body</code> element does not have a
<code>env:role</code> attribute. The body element is <em>always</em> targeted
at the SOAP node that assumes the "ultimateReceiver" role. In that sense, the
body element is just like a header block targeted at the ultimate receiver,
but it has been distinguished to allow for SOAP nodes (typically SOAP
intermediaries) to skip over it if they assume roles other than that of the
ultimate receiver. SOAP does not prescribe any structure for the
<code>env:Body</code> element, except that it recommends that any
sub-elements be XML namespace qualified. Some applications, such as that in
<a href="#Example">Example 1</a>, may choose to organize the sub-elements of
<code>env:Body</code> in blocks, but this is not of concern to the SOAP
processing model.</p>

<p>The other distinguished role for the <code>env:Body</code> element, as the
container where information on SOAP-specific faults, i.e., failure to process
elements of a SOAP message, is placed has been described previously in <a href="#L11549">section 2.3</a>.</p>

<p>If a header element has the standardized <code>env:role</code> attribute
with value "none", it means that no SOAP node should process the contents,
although a node may need to examine it if the content are data referenced by
another header element that is targeted at the particular SOAP node.</p>

<p>If the <code>env:role</code> attribute has an empty value, i.e.,
<code>env:role=""</code>, it means  that the relative URI identifying the
role is resolved to the base URI for the SOAP  message in question. SOAP
Version 1.2 does not define a base URI for a SOAP message, but defers  to the
mechanisms defined in [<a href="#L2778">XMLBase</a>] for deriving the base
URI, which can be used to make  any relative URIs absolute. One such
mechanism is for the protocol binding to establish a base URI,  possibly by
reference to the encapsulating protocol in which the SOAP  message is
embedded for transport. (In fact, when SOAP messages are transported  using
HTTP, <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#httpuse">SOAP Part
2 section 7.1.2</a> defines the base URI as the  Request-URI of the HTTP
request,  or the value of the HTTP Content-Location header.)</p>

<p>The following table summarizes the applicable standardized roles that may
be assumed at various SOAP nodes. ("Yes" and "No" means that the
corresponding node does or does not, respectively, play the named role.)</p>

<a name="tabrolesnodes"></a><table border="1" summary="Table summarizing the applicable standardized roles that may be assumed at various SOAP nodes">
  <tbody>
    <tr>
      <td align="right" rowspan="1" colspan="1"><em>Role</em></td>
      <td align="center" rowspan="1" colspan="1">absent</td>
      <td align="center" rowspan="1" colspan="1">"none"</td>
      <td align="center" rowspan="1" colspan="1">"next"</td>
      <td align="center" rowspan="1" colspan="1">"ultimateReceiver"</td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1"><em>Node</em></td>
      <td align="center" rowspan="1" colspan="1"> </td>
      <td align="center" rowspan="1" colspan="1"> </td>
      <td align="center" rowspan="1" colspan="1"> </td>
      <td align="center" rowspan="1" colspan="1"> </td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">initial sender</td>
      <td align="center" rowspan="1" colspan="1">not applicable</td>
      <td align="center" rowspan="1" colspan="1">not applicable</td>
      <td align="center" rowspan="1" colspan="1">not applicable</td>
      <td align="center" rowspan="1" colspan="1">not applicable</td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">intermediary</td>
      <td align="center" rowspan="1" colspan="1">no</td>
      <td align="center" rowspan="1" colspan="1">no</td>
      <td align="center" rowspan="1" colspan="1">yes</td>
      <td align="center" rowspan="1" colspan="1">no</td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">ultimate receiver</td>
      <td align="center" rowspan="1" colspan="1">yes</td>
      <td align="center" rowspan="1" colspan="1">no</td>
      <td align="center" rowspan="1" colspan="1">yes</td>
      <td align="center" rowspan="1" colspan="1">yes</td>
    </tr>
  </tbody>
</table>

</div>

<div class="div2">
  
<h3><a name="L1474"></a>3.2 <span id="L3031">The "mustUnderstand" Attribute</span></h3>

<p><a href="#Example8">Example 7b</a> augments the previous example by
introducing another (optional) attribute for header blocks, the <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapmu">env:mustUnderstand</a></code>
attribute.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example8" name="Example8">Example 7b</a></div>

<div class="exampleInner">
<pre>&lt;?xml version="1.0" ?&gt;
 &lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt;
   &lt;env:Header&gt;
     &lt;p:oneBlock xmlns:p="http://example.com" 
           env:role="http://example.com/Log" 
               <span class="highlight">env:mustUnderstand="true"</span>&gt;
     ...
     ...
     &lt;/p:oneBlock&gt;
     &lt;q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"&gt;
     ...
     ...
     &lt;/q:anotherBlock&gt;
     &lt;r:aThirdBlock xmlns:r="http://example.com"&gt;
     ...
     ...
     &lt;/r:aThirdBlock&gt;
   &lt;/env:Header&gt;
   &lt;env:Body &gt;
     ...
     ...
   &lt;/env:Body&gt;
 &lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message showing a variety of header blocks, one of which is mandatory
for processing</div>
</div>

<p>After a SOAP node has correctly identified the header blocks (and possibly
the body) targeted at itself using the <code>env:role</code> attribute, the
additional attribute, <code>env:mustUnderstand</code>, in the header elements
determines further processing actions that have to be taken. In order to
ensure that SOAP nodes do not ignore header blocks which are important to the
overall purpose of the application, SOAP header blocks also provide for the
additional optional attribute, <code>env:mustUnderstand</code>, which, if
"true", means that the targeted SOAP node <em>must</em> process the
block according to the specification of that block. Such a block is
colloquially referred to as a mandatory header block. In fact, processing of
the SOAP message must not even start until the node has identified all the
mandatory header blocks targeted at itself, and "understood" them.
Understanding a header means that the node must be prepared to do whatever is
described in the specification of that block. (Keep in mind that the
specifications of header blocks are not a part of the SOAP
specifications.)</p>

<p>In <a href="#Example8">Example 7b</a>, the header block
<code>oneBlock</code> is marked with a <code>env:mustUnderstand</code> value
set to "true", which means that it is mandatory to process this block if the
SOAP node plays the role identified by "http://example.com/Log". The other
two header blocks are not so marked, which means that SOAP node at which
these blocks are targeted need not process them. (Presumably the
specifications for these blocks allow for this.)</p>

<p>A <code>env:mustUnderstand</code> value of "true" means that the SOAP node
must process the header with the semantics described in that header's
specification, or else generate a SOAP fault. Processing the header
appropriately may include removing the header from any generated SOAP
message, reinserting the header with the same or altered value, or inserting
a new header. The inability to process a mandatory header requires that all
further processing of the SOAP message cease, and a SOAP fault be generated.
The message is not forwarded any further.</p>

<p>The <code>env:Body</code> element has no <code>env:mustUnderstand</code>
attribute but it <em>must</em> be processed by the ultimate recipient. In <a href="#Example8">Example 7b</a>, the ultimate recipient of the message - the
SOAP node which plays the "ultimateReceiver" role - must process the
<code>env:Body</code> and may process the header block
<code>aThirdBlock</code>. It may also process the header block
<code>anotherBlock</code>, as it is targeted at it (in the role of "next")
but it is not mandatory to do so if the specifications for processing the
blocks do not demand it. (If the specification for <code>anotherBlock</code>
demanded that it must be processed at the next recipient, it would have
required that it be marked with a <code>env:mustUnderstand=</code>"true".)</p>

<p>The role(s) a SOAP node plays when processing a SOAP message can be
determined by many factors. The role could be known<em> a priori</em>, or set
by some out-of-band means, or a node can inspect all parts of a received
message to determine which roles it will assume before processing the
message. An interesting case arises when a SOAP node, during the course of
processing a message, decides that there are additional roles that it needs
to adopt. No matter when this determination is made, externally it must
appear as though the processing model has been adhered to. That is, it must
appear as though the role had been known from the start of the processing of
the message. In particular, the external appearance must be that the
<code>env:mustUnderstand</code> checking of any headers with those additional
roles assumed was performed before any processing began. Also, if a SOAP node
assumes such additional roles, it must ensure that it is prepared to do
everything that the specifications for those roles require.</p>

<p>The following table summarizes how the processing actions for a header
block are qualified by the <code>env:mustUnderstand</code> attribute with
respect to a node that has been appropriately targeted (via the
<code>env:role</code> attribute).</p>

<a name="tabmustunderstand"></a><table border="1" summary="Table summarizing the use of the mustUnderstand attribute">
  <tbody>
    <tr>
      <td align="right" rowspan="1" colspan="1"><em>Node</em></td>
      <td align="center" rowspan="1" colspan="1">intermediary</td>
      <td align="center" rowspan="1" colspan="1">ultimate receiver</td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1"><em>mustUnderstand</em></td>
      <td align="center" rowspan="1" colspan="1"> </td>
      <td align="center" rowspan="1" colspan="1"> </td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">"true"</td>
      <td align="center" rowspan="1" colspan="1">must process</td>
      <td align="center" rowspan="1" colspan="1">must process</td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">"false"</td>
      <td align="center" rowspan="1" colspan="1">may process</td>
      <td align="center" rowspan="1" colspan="1">may process</td>
    </tr>
    <tr>
      <td rowspan="1" colspan="1">absent</td>
      <td align="center" rowspan="1" colspan="1">may process</td>
      <td align="center" rowspan="1" colspan="1">may process</td>
    </tr>
  </tbody>
</table>

<p>As a result of processing a SOAP message, a SOAP node may generate a
single SOAP fault if it fails to process a message, or, depending on the
application, generate additional SOAP messages for consumption at other SOAP
nodes. <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapfault">SOAP
Part 1 section 5.4</a> describes the structure of the fault message while the
<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#msgexchngmdl">SOAP
processing model</a> defines the conditions under which it is generated. As
illustrated previously in <a href="#L11549">section 2.3</a>, a SOAP fault is
a SOAP message with a standardized <code>env:Body</code> sub-element named
<code>env:Fault</code>.</p>

<p>SOAP makes a distinction between generating a fault and ensuring that the
fault is returned to the originator of the message or to another appropriate
node which can benefit from this information. However, whether a generated
fault can be propagated appropriately depends on the underlying protocol
binding chosen for the SOAP message message exchange. The specification does
not define what happens if faults are generated during the propagation of
one-way messages. The only normative underlying protocol binding, which is
the SOAP HTTP binding, offers the HTTP response as a means for reporting a
fault in the incoming SOAP message. (See <a href="#transport">Section 4</a>
for more details on SOAP protocol bindings.)</p>

</div>
<div class="div2">
  
<h3><a name="LL10047"></a>3.3 The "relay" Attribute</h3>

<p>SOAP Version 1.2 defines another optional attribute for header blocks,
<code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soaprelay">env:relay</a></code>
of type <code>xs:boolean</code>, which indicates if a header block targeted
at a SOAP intermediary must be relayed if it is <em>not</em> processed.</p>

<p>Note that if a header block <em>is</em> processed, the SOAP processing
rules (see <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#forwardinter">SOAP
Part 1 section 2.7.2</a>) requires that it be removed from the outbound
message. (It may, however, be reinserted, either unchanged or with its
contents altered, if the processing of other header blocks determines that
the header block be retained in the forwarded message.) The default behavior
for <em>an un</em>processed header block targeted at a role played by a SOAP
intermediary is that it must be removed before the message is relayed.</p>

<p>The reason for this choice of default is to lean on the side of safety by
ensuring that a SOAP intermediary make no assumptions about the survivability
past itself of a header block targeted at a role it assumes, and representing
some value-added feature, particularly if it chooses not to process the
header block, very likely because it does not "understand" it. That is
because certain header blocks represent hop-by-hop features, and it may not
make sense to unknowingly propagate it end-to-end. As an intermediary may not
be in a position to make this determination, it was thought that it would be
safer if unprocessed header blocks were removed before the message was
relayed.</p>

<p>However, there are instances when an application designer would like to
introduce a new feature, manifested through a SOAP header block, targeted at
<em>any</em> capable intermediary which might be encountered in the SOAP
message path. Such a header block would be available to those intermediaries
that "understood" it, but ignored and relayed onwards by those that did not.
Being a new feature, the processing software for this header block may be
implemented, at least initially, in some but not all SOAP nodes. Marking such
a header block with <code>env:mustUnderstand</code> = "false" is obviously
needed, so that intermediaries that have not implemented the feature do not
generate a fault. To circumvent the default rule of the processing model,
marking a header block with the additional attribute <code>env:relay</code>
with the value "true" allows the intermediary to forward the header block
targeted at itself in the event that it chooses not to process it.</p>

<p>Targeting the header block at the role "next" together with the
<code>env:relay</code> attribute set to "true" can always serve to ensure
that each intermediary has a chance to examine the header, because one of the
anticipated uses of the "next" role is with header blocks that carry
information that are expected to persist along a SOAP message path. Of
course, the application designer can always define a custom role that allows
targetting at specific intermediaries that assume this role. Therefore, there
is no restriction on the use of the <code>env:relay</code> attribute with any
role except of course the roles of "none" and "ultimateReceiver", for which
it is meaningless.</p>

<p><a href="#Example11">Example 7c</a> shows the use of the
<code>env:relay</code> attribute.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example11" id="Example11">Example 7c</a></div>

<div class="exampleInner">
<pre>&lt;?xml version="1.0" ?&gt;
 &lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt;
   &lt;env:Header&gt;
     &lt;p:oneBlock xmlns:p="http://example.com" 
           env:role="http://example.com/Log" 
               env:mustUnderstand="true"&gt;
     ...
     ...
     &lt;/p:oneBlock&gt;
     &lt;q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
       <span class="highlight">env:relay="true"</span>&gt;
     ...
     ...
     &lt;/q:anotherBlock&gt;
     &lt;r:aThirdBlock xmlns:r="http://example.com"&gt;
     ...
     ...
     &lt;/r:aThirdBlock&gt;
   &lt;/env:Header&gt;
   &lt;env:Body &gt;
     ...
     ...
   &lt;/env:Body&gt;
 &lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message showing a variety of header blocks, one of which must be relayed
if unprocessed.</div>
</div>

<p>The header block <code>q:anotherBlock</code>, targeted at the "next" node
in the message path, has the additional attribute
<code>env:relay</code>="true". A SOAP node receiving this message may process
this header block if it "understands" it, but if it does so the processing
rules require that this header block be removed before forwarding. However,
if the SOAP node chooses to ignore this header block, which it can because it
is not mandatory to process it, as indicated by the absence of the
<code>env:mustUnderstand</code> attribute, then it must forward it.</p>

<p>Processing the header block <code>p:oneBlock</code> is mandatory and the
SOAP processing rules require that it not be relayed, unless the processing
of some other header block requires that it be present in the outbound
message. The header block <code>r:aThirdBlock</code> does not have an
<code>env:relay</code> attribute, which is equivalent to having it with the
value of <code>env:relay </code>= "false". Hence, this header is not
forwarded if it is not processed.</p>

<p><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#tabforwarding">SOAP
1.2 Part 1 Table 3</a> summarizes the conditions which determine when a SOAP
intermediary assuming a given role is allowed to forward unprocessed header
blocks.</p>
</div>
</div>

<div class="div1">
  
<h2><a name="transport"></a>4. Using Various Protocol Bindings</h2>

<p>SOAP messages may be exchanged using a variety of "underlying" protocols,
including other application layer protocols. The specification of how SOAP
messages may be passed from one SOAP node to another using an underlying
protocol is called a <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">SOAP
binding</a>. <a href="#L1092">[SOAP Part1]</a> defines a SOAP message in the
form of an [<a href="#R12">XML Infoset</a>], i.e., in terms of element and
attribute information items of an abstract "document" called the
<code>env:Envelope</code> (see<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapenv"> SOAP
Part 1, section 5</a>). Any SOAP <code>env:Envelope</code> infoset
representation will be made concrete through a protocol binding, whose task,
among other things, it is to provide a serialized representation of the
infoset that can be conveyed to the next SOAP node in the message path in a
manner such that the original infoset can be reconstructed without loss of
information.</p>

<p>In typical examples of SOAP messages, and certainly in all the examples in
this primer, the serialization shown is that of a well-formed [<a href="#L3532">XML 1.0</a>] document. However, there may be
other protocol bindings - for example a protocol binding between two SOAP
nodes over a limited bandwidth interface - where an alternative, compressed
serialization of the same infoset may be chosen. Another binding, chosen for
a different purpose, may provide a serialization which is an encrypted
structure representing the same infoset. The <a href="#L9527">[MTOM]</a>
specification provides a SOAP binding to HTTP that allows for an optimized
serialization of the SOAP message infoset under certain circumstances. A more
detailed discussion of this binding is deferred to <a href="#L3360">Section
5.3</a>.</p>

<p>In addition to providing a concrete realization of a SOAP infoset between
adjacent SOAP nodes along a SOAP message path, a protocol binding provides
the mechanisms to support <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#concepts">features</a>
that are needed by a SOAP application. A feature is a specification of a
certain functionality required in the interactions between two SOAP nodes,
which may be provided by a binding. A feature description is identified by a
URI, so that all applications referencing it are assured of the same
semantics. Features are qualified by <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#bindprops">properties</a>,
which provide additional information that help in the implementation of the
feature. For example, a typical usage scenario might require many concurrent
request-response exchanges between adjacent SOAP nodes, in which case the
feature that is required is the ability to correlate a request with a
response. The abstract property associated with this feature is a
"correlation ID". Other examples includes "an encrypted channel" feature, or
a "reliable delivery channel" feature, or a particular <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapmep">SOAP
message exchange pattern feature</a>. In particular, the <a href="#L9527">[MTOM]</a> specification defines an <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
SOAP Transmission Optimization feature</a> which may be used by SOAP bindings
to optimize the serialization of selected element information items of a SOAP
message infoset. (See <a href="#L3785">section 5.3.1</a> for details).</p>

<p>A SOAP binding specification (see <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#transpbindframew">SOAP
Part 1 section 4</a>) describes, among other things, which (if any) features
it provides. Some features may be provided natively by the underlying
protocol. If the feature is not available through the binding, it may be
implemented within the SOAP envelope, using SOAP header blocks. The
specification of a feature implemented using SOAP header blocks is called a
<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapmodules">SOAP
module</a>.</p>

<p>For example, if SOAP message exchanges were being transported directly
over a datagram protocol like UDP, obviously the message correlation feature
mentioned earlier would have to be provided by other means, either directly
by the application or more likely as a part of the SOAP infosets being
exchanged. In the latter case, the message correlation feature has a
binding-specific expression within the SOAP envelope, i.e., as a SOAP header
block, defined in a "Request-Response Correlation" module identified by a
URI. However, if the SOAP infosets were being exchanged using an underlying
protocol that was itself request/response, the application could implicitly
"inherit" this feature provided by the binding, and no further support need
be provided at the application or the SOAP level. (In fact, the HTTP binding
for SOAP takes advantage of just this feature of HTTP.) The Abstract SOAP
Transmission Optimization feature defined in <a href="#L9527" class="insert">[MTOM]</a> is similarly implemented as a part of an augmented
SOAP HTTP binding, by serializing particular nodes of a SOAP message infoset
in binary format together with a modified SOAP Envelope, which are then
carried in separate parts of a MIME Multipart/Related <a href="#L3362">[RFC
2387]</a> package (see <a href="#L3787">section 5.3.2</a> for details).</p>

<p>However, a SOAP message may travel over several hops between a sender and
the ultimate receiver, where each hop may be a different protocol binding. In
other words, a feature (e.g., message correlation, reliability etc.) that is
supported by the protocol binding in one hop may not be supported by another
along the message path. SOAP itself does not provide any mechanism for hiding
the differences in features provided by different underlying protocols.
However, any end-to-end or multi-hop feature that is required by a particular
application, but which may not be available in the underlying infrastructure
along the <em>anticipated</em> message path, can be compensated for by being
carried as a part of the SOAP message infoset, i.e., as a SOAP header block
specified in some module.</p>

<p>Thus it is apparent that there are a number of issues that have to be
tackled by an application designer to accomplish particular application
semantics, including how to take advantage of the native features of
underlying protocols that are available for use in the chosen environment. <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#bindfw">SOAP Part
1 section 4.2</a> provides a general framework for describing how SOAP-based
applications may choose to use the features provided by an underlying
protocol binding to accomplish particular application semantics. It is
intended to provide guidelines for writing interoperable protocol binding
specifications for exchanging SOAP messages.</p>

<p>Among other things, a binding specification must define one particular
feature, namely the message exchange pattern(s) that it supports. <a href="#L1098">[SOAP Part2]</a> defines two such message exchange patterns,
namely a <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">
SOAP Request-Response message exchange pattern</a> where one SOAP message is
exchanged in each direction between two adjacent SOAP nodes, and a <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep"> SOAP
Response message exchange pattern</a> which consists of a non-SOAP message
acting as a request followed by a SOAP message included as a part of the
response.</p>

<p><a href="#L1098">[SOAP Part2]</a> also offers the application designer a
general feature called the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#WebMethodFeature">
SOAP Web Method feature</a> that allows applications full control over the
choice of the so-called "Web method" - one of GET, POST, PUT, DELETE whose
semantics are as defined in the [<a href="#L3133">HTTP 1.1</a>]
specifications - that may be used over the binding. This feature is defined
to ensure that applications using SOAP can do so in a manner which is
compatible with the architectural principles of the World Wide Web. (Very
briefly, the simplicity and scalability of the Web is largely due to the fact
that there are a few "generic" methods (GET, POST, PUT, DELETE) which can be
used to interact with any resource made available on the Web via a URI.) The
<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#WebMethodFeature">SOAP
Web Method feature</a> is supported by the SOAP HTTP binding, although, in
principle, it is available to all SOAP underlying protocol bindings. <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapinhttp"></a></p>

<p><a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapinhttp">SOAP
Part 2 section 7</a> specifies one standardized
protocol binding using the binding framework of <a href="#L1092">[SOAP
Part1]</a>, namely how SOAP is used in conjunction with HTTP as the
underlying protocol. SOAP Version 1.2 restricts itself to the definition of a
HTTP binding allowing only the use of the POST method in conjunction with the
Request-Response message exchange pattern and the GET method with the SOAP
Response message exchange pattern. Other specifications in future could
define SOAP bindings to HTTP or other transports that make use of the other
Web methods (i.e., PUT, DELETE).</p>

<p>The next sections show examples of two underlying protocol bindings for
SOAP, namely those to [<a href="#L3133">HTTP 1.1</a>] and email. It should be
emphasized again that the only normative binding for SOAP 1.2 messages is to
[<a href="#L3133">HTTP 1.1</a>]. The examples in <a href="#SMTP">section
4.2</a> showing email as a transport mechanism for SOAP is simply meant to
suggest that other choices for the transfer of SOAP messages are possible,
although not standardized at this time. A W3C Note [<a href="#L3215">SOAP
Email Binding</a>] offers an application of the SOAP protocol binding
framework of <a href="#L1092">[SOAP Part1]</a> by describing an experimental
binding of SOAP to email transport, specifically [<a href="#R9">RFC
2822</a>]-based message transport. The discussion of <a href="#L9527">[MTOM]</a> and its concrete realization in an HTTP binding is
provided in <a href="#L3360">section 5.3</a>.</p>

<div class="div2">

<h3><a name="L10309"></a>4.1 The SOAP HTTP Binding</h3>

<p>HTTP has a well-known connection model and a message exchange pattern. The
client identifies the server via a URI, connects to it using the underlying
TCP/IP network, issues a HTTP request message and receives a HTTP response
message over the same TCP connection. HTTP implicitly correlates its request
message with its response message; therefore, an application using this
binding can chose to infer a correlation between a SOAP message sent in the
body of a HTTP request message and a SOAP message returned in the HTTP
response. Similarly, HTTP identifies the server endpoint via a URI, the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2">Request-URI</a>,
which can also serve as the identification of a SOAP node at the server.</p>

<p>HTTP allows for multiple intermediaries between the initial client and the
<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html#sec1.3">origin
server</a> identified by the Request-URI, in which case the request/response
model is a series of such pairs. Note, however, that HTTP intermediaries are
distinct from SOAP intermediaries.</p>

<p>The HTTP binding in <a href="#L1098">[SOAP
Part2]</a> makes use of the<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#WebMethodFeature">SOAP
Web Method feature</a> to allow applications to choose the so-called Web
method - restricting it to one of GET or POST - to use over the HTTP message
exchange. In addition, it makes use of two message exchange patterns that
offer applications two ways of exchanging SOAP messages via HTTP: 1) the use of the
HTTP POST method for conveying SOAP messages in the bodies of HTTP request 
and response messages, and 2) the use of the HTTP GET
method in a HTTP request to return a SOAP message in the body of a HTTP
response. The first usage pattern is the HTTP-specific instantiation of a
binding feature called the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">SOAP request-response message exchange pattern</a>, while the second uses a feature
called the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep">SOAP response message exchange pattern</a>.</p>

<p>The purpose of providing these two types of usages is
to accommodate the two interaction paradigms which are well established on
the World Wide Web. The first type of interaction allows for the use of data
within the body of a HTTP POST to create or modify the state of a resource
identified by the URI to which the HTTP request is destined. The second type
of interaction pattern offers the ability to use a HTTP GET request to obtain
a representation of a resource without altering its state in any way. In the
first case, the SOAP-specific aspect of concern is that the body of the HTTP
POST request is a SOAP message which has to be processed (per the SOAP
processing model) as a part of the application-specific processing required
to conform to the POST semantics. In the second case, the typical usage that
is forseen is the case where the representation of the resource that is being
requested is returned not as a HTML, or indeed a generic XML document, but as
a SOAP message. That is, the HTTP content type header of the response message
identifies it as being of media type "application/soap+xml" 
[<a href="#r13">RFC 3902</a>]. Presumably,
there will be publishers of resources on the Web who determine that such
resources are best retrieved and made available in the form of SOAP messages.
Note, however, that resources can, in general, be made available in multiple
representations, and the desired or preferred representation is indicated by
the requesting application using the HTTP <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">Accept</a>
header.</p>

<p>One further aspect of
the SOAP HTTP binding is the question of how an application determines which
of these two types of message exchange patterns to use.
<a href="#L1098">[SOAP Part2]</a> offers guidance on
circumstances when applications may use one of the two specified message
exchange patterns. (It is guidance - albeit a strong one - as it is phrased
in the form of a "<a href="http://www.ietf.org/rfc/rfc2119.txt">SHOULD</a>" in the
specifications rather than an absolute requirement identified by the word
"<a href="http://www.ietf.org/rfc/rfc2119.txt">MUST</a>", where these
words are interpreted as defined in the IETF [<a href="#L15789">RFC
2119</a>].) The SOAP response message exchange pattern with the HTTP GET
method is used when an application is assured that the message exchange is
for the purposes of information retrieval, where the information resource is
"untouched" as a result of the interaction. Such interactions are referred to
as <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1">safe and
idempotent</a> in the HTTP specification. As the
HTTP SOAP GET usage does not allow for a SOAP message in the request,
applications that need features in the outbound interaction that can only be
supported by a binding-specific expression within the SOAP infoset (i.e., as
SOAP header blocks) obviously cannot make use of this message exchange
pattern. Note that the HTTP POST binding is available for use in all
cases.</p>

<p>The following
subsections provide examples of the use of these two message exchange
patterns defined for the HTTP binding.</p>

<div class="div3">
 
<h4><a name="L26854"></a>4.1.1 SOAP HTTP GET Usage</h4>

<p>Using the HTTP binding with the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep">SOAP Response message exchange pattern</a> is restricted to the HTTP GET method. This means that
the response to a HTTP GET request from a requesting SOAP node is a SOAP
message in the HTTP response.</p>

<p><a href="#Ref4774883961121">Example 8a</a> shows a HTTP GET directed by the
traveller's application (in the continuing travel reservation scenario) at
the URI<code>
http://travelcompany.example.org/reservations?code=FT35ZBQ</code> &gt;where the traveler's itinerary may be viewed. (How
this URL was made available can be seen in
<a href="#Example5">Example 5a</a>.)</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Ref4774883961121" name="Ref4774883961121">Example 8a</a></div>

<div class="exampleInner">
<pre>GET /travelcompany.example.org/reservations?code=FT35ZBQ  HTTP/1.1
Host: travelcompany.example.org
Accept: text/html;q=0.5, application/soap+xml</pre>
</div>

<div class="exampleWrapper">
HTTP GET Request</div>
</div>

<p>The HTTP <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">Accept</a>
header is used to indicate the preferred representation of the resource being
requested, which in this example is an "application/soap+xml" media type for
consumption by a machine client, rather than the "text/html" media type for
rendition by a browser client for consumption by a human.</p>

<p><a href="#Example13">Example 8b</a> shows the HTTP
response to the GET in <a href="#Ref4774883961121">Example 8a</a>. The body
of the HTTP response contains a SOAP message showing the travel details. A
discussion of the contents of the SOAP message is postponed until <a href="#L3374">section 5.2</a> , as it is not relevant, at this point, to
understanding the HTTP GET binding usage.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example13" id="Example13">Example 8b</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
   &lt;m:dateAndTime&gt;2001-11-30T16:25:00.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
            xmlns:x="http://travelcompany.example.org/vocab#"
     env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#"&gt;
   &lt;x:ReservationRequest 
 rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ"&gt;
      &lt;x:passenger&gt;Åke Jógvan Øyvind&lt;/x:passenger&gt;
      &lt;x:outbound&gt;
       &lt;x:TravelRequest&gt;
        &lt;x:to&gt;LAX&lt;/x:to&gt;
        &lt;x:from&gt;LGA&lt;/x:from&gt;
        &lt;x:date&gt;2001-12-14&lt;/x:date&gt;
       &lt;/x:TravelRequest&gt;
      &lt;/x:outbound&gt;
      &lt;x:return&gt;
       &lt;x:TravelRequest&gt;
        &lt;x:to&gt;JFK&lt;/x:to&gt;
        &lt;x:from&gt;LAX&lt;/x:from&gt;
        &lt;x:date&gt;2001-12-20&lt;/x:date&gt;
       &lt;/x:TravelRequest&gt;
      &lt;/x:return&gt;
    &lt;/x:ReservationRequest&gt;
  &lt;/rdf:RDF&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message returned as a response to the HTTP GET in <a href="#Ref4774883961121">Example 8a</a></div>
</div>

<p>Note that the
reservation details could well have been returned as an (X)HTML document, but
this example wanted to show a case where the reservation application is
returning the state of the resource (the reservation) in a data-centric media
form (a SOAP message) which can be machine processed, instead of (X)HTML
which would be processed by a browser. Indeed, in the most likely anticipated
uses of SOAP, the consuming application will not be a browser.</p>

<p>Also, as shown in the example, the use of
SOAP in the HTTP response body offers the possibility of expressing some
application-specific feature through the use of SOAP headers. By using SOAP,
the application is provided with a useful and consistent framework and
processing model for expressing such features.</p>

</div>
<div class="div3">

<h4><a name="L26866"></a>4.1.2 SOAP HTTP POST Usage</h4>

<p>Using the HTTP binding with the<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">
SOAP Request-Response message exchange pattern</a> is restricted to the HTTP
POST method. Note that the use of this message exchange pattern in the SOAP
HTTP binding is available to all applications, whether they involve the
exchange of general XML data or RPCs (as in the following examples)
encapsulated in SOAP messages.</p>

<p>Examples <a href="#Ref47748839611">9</a> and
<a href="#Ref47748860211">10</a> show an example of a HTTP binding
using the SOAP Request-Response message exchange
pattern, using the same scenario as that
for <a href="#Example2">Example 4</a> and <a href="#Example5">Example 5a</a>, respectively, namely conveying an RPC and its return
in the body of a SOAP message. The examples and discussion in this section
only concentrate on the HTTP headers and their role.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Ref47748839611" name="Ref47748839611">Example 9</a></div>

<div class="exampleInner">
<pre>POST /Reservations HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" &gt;
 &lt;env:Header&gt;
   &lt;t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" &gt;5&lt;/t:transaction&gt;
 &lt;/env:Header&gt;  
 &lt;env:Body&gt;
  &lt;m:chargeReservation
     env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
          xmlns:m="http://travelcompany.example.org/"&gt;
   &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation"&gt;
    &lt;m:code&gt;FT35ZBQ&lt;/m:code&gt;
   &lt;/m:reservation&gt;
    &lt;o:creditCard xmlns:o="http://mycompany.example.com/financial"&gt;
     &lt;n:name xmlns:n="http://mycompany.example.com/employees"&gt;
           Åke Jógvan Øyvind
     &lt;/n:name&gt;
     &lt;o:number&gt;123456789099999&lt;/o:number&gt;
     &lt;o:expiration&gt;2005-02&lt;/o:expiration&gt;
    &lt;/o:creditCard&gt;
   &lt;/m:chargeReservation
  &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
RPC in <a href="#Example2">Example 4</a> carried in an HTTP POST Request</div>
</div>

<p><a href="#Ref47748839611">Example 9</a> shows an RPC request directed at
the travel service application. The SOAP message is sent in the body of a
HTTP POST method directed at the URI identifying the "Reservations" resource
on the server travelcompany.example.org. When using HTTP, the Request-URI
indicates the resource to which the invocation is "posted". Other than
requiring that it be a valid URI, SOAP places no <em>formal</em> restriction
on the form of the request URI (see <a href="#RFC3986">[RFC 3986]</a> for more
information on URIs). However, one of the principles of the Web architecture
is that all important resources be identified by URIs. This implies that most
well-architected SOAP services will be embodied as a large number of
resources, each with its own URI. Indeed, many such resources are likely to
be created dynamically during the operation of a service, such as, for
instance, the specific travel reservation shown in the example. So, a
well-architected travel service application should have different URIs for
each reservation, and SOAP requests to retrieve or manipulate those
reservations will be directed at their URIs, and not at a single monolithic
"Reservations" URI, as shown in <a href="#Ref47748839611">Example 9</a>. <a href="#Ref477488396111"> Example 13</a> in <a href="#L3677">section 4.1.3</a>
shows the preferred way to address resources such as a particular travel
reservation. Therefore, we defer until <a href="#L3677">section 4.1.3</a>
further discussion of Web architecture compatible SOAP/HTTP usage.</p>

<p>When placing SOAP messages in HTTP bodies, the HTTP Content-type header
must be chosen as "application/soap+xml" [<a href="#r13">RFC 3902</a>]. (The
optional charset parameter, which can take the value of "<a href="http://www.ietf.org/rfc/rfc2279.txt">utf-8</a>" or "<a href="http://www.ietf.org/rfc/rfc2781.txt">utf-16</a>", is shown in this
example, but if it is absent the character set rules for freestanding [<a href="#L3532">XML 1.0</a>] apply to the body of the HTTP request.)</p>

<p><a href="#Ref47748860211">Example 10</a> shows the RPC return (with
details omitted) sent by the travel service application in the corresponding
HTTP response to the request from <a href="#Example5">Example 5a</a>. SOAP,
using HTTP transport, follows the semantics of the HTTP status codes for
communicating status information in HTTP. For example, the 2xx series of HTTP
status codes indicate that the client's request (including the SOAP
component) was successfully received, understood, and accepted etc.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Ref47748860211" name="Ref47748860211">Example 10</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" &gt;
 &lt;env:Header&gt;
       ...
       ...
 &lt;/env:Header&gt;  
 &lt;env:Body&gt;
       ...
       ...
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
RPC return in <a href="#Example5">Example 5a</a> embedded in an HTTP Response
indicating a successful completion</div>
</div>

<p>If an error occurs  processing the request, the HTTP binding specification
requires that a HTTP 500 "Internal Server Error" be used with an embedded
SOAP message containing a SOAP fault indicating the server-side processing
error.</p>

<p><a href="#Example10">Example 11</a> is the same SOAP fault message as <a href="#Example7">Example 6a</a>, but this time with the HTTP headers
added.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example10" id="Example10">Example 11</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 500 Internal Server Error
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt;
  &lt;env:Body&gt;
    &lt;env:Fault&gt;
     &lt;env:Code&gt;
       &lt;env:Value&gt;env:Sender&lt;/env:Value&gt;
       &lt;env:Subcode&gt;
        &lt;env:Value&gt;rpc:BadArguments&lt;/env:Value&gt;
       &lt;/env:Subcode&gt;
     &lt;/env:Code&gt;
     &lt;env:Reason&gt;
      &lt;env:Text xml:lang="en-US"&gt;Processing error&lt;/env:Text&gt;
      &lt;env:Text xml:lang="cs"&gt;Chyba zpracování&lt;/env:Text&gt;
     &lt;/env:Reason&gt;
     &lt;env:Detail&gt;
      &lt;e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults" &gt;
        &lt;e:message&gt;Name does not match card number&lt;/e:message&gt;
        &lt;e:errorcode&gt;999&lt;/e:errorcode&gt;
      &lt;/e:myFaultDetails&gt;
     &lt;/env:Detail&gt;
   &lt;/env:Fault&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message in a HTTP Response indicating failure <span class="exampleWrapper">to handle the SOAP Body in <a href="#Example2">Example
4</a></span></div>
</div>

<p><a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#http-reqbindwaitstate">SOAP
Part 2 Table 16</a> provides detailed behavior for handling the various
possible HTTP response codes, i.e., the 2xx (successful), 3xx (redirection),
4xx (client error) and 5xx (server error).</p>

</div>
<div class="div3">

<h4><a name="L3677"></a>4.1.3 Web Architecture Compatible SOAP Usage</h4>

<p>One of the most central concepts of the World Wide Web is that of a URI as
a resource identifier. SOAP services that use the HTTP binding and wish to
interoperate with other Web software should use URIs to address all important
resources in their service. For example, a very important - indeed
predominant - use of the World Wide Web is pure information retrieval, where
the representation of an available resource, identified by a URI, is fetched
using a HTTP GET request without affecting the resource in any way. (This is
called a <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1">safe and
idempotent method</a> in HTTP terminology.) The
key point is that the publisher of a resource makes available its URI, which
consumers may "GET".</p>

<p>There are many
instances when SOAP messages are designed for uses which are purely for
information retrieval, such as when the state of some resource (or object, in
programming terms) is requested, as opposed to uses that perform resource
manipulation. In such instances, the use of a SOAP body to carry the request
for the state, with an element of the body representing the object in
question, is seen as counter to the spirit of the Web because the resource is
not identified by the Request-URI of the HTTP GET. (In some SOAP/RPC
implementations, the HTTP Request-URI is often not the identifier of the
resource itself but some intermediate entity which has to evaluate the SOAP
message to identify the resource.)</p>

<p>To highlight the changes needed, <a href="#Example211">Example 12a</a> shows the way that is <em>not</em>
recommended for doing safe information retrieval on the Web. This is an
example of an RPC carried in a SOAP message, again using the travel
reservation theme, where the request is to retrieve the itinerary for a
particular reservation identified by one of the parameters,
<code>reservationCode</code>, of the RPC. (For purposes of this discussion,
it is assumed that the application using this RPC request does not need
features which require the use of SOAP headers.)</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example211" name="Example211">Example 12a</a></div>

<div class="exampleInner">
<pre>POST /Reservations HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" &gt;
  &lt;env:Body&gt;
    &lt;m:retrieveItinerary 
        env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
             xmlns:m="http://travelcompany.example.org/"&gt;
      &lt;m:reservationCode&gt;FT35ZBQ&lt;/m:reservationCode&gt;
    &lt;/m:retrieveItinerary&gt;
  &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
This representation is discouraged in cases where the operation is a "safe"
retrieval (i.e., it has no side effects)</div>
</div>

<p>Note that the resource to be retrieved is not
identified by the target URI in the HTTP request but has to be obtained by
looking within the SOAP envelope. Thus, it is not possible, as would be the
case with other "gettable" URIs on the Web, to make this available via HTTP
alone to consumers on the World Wide Web.</p>

<p><a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#RPConWeb">SOAP
Part 2 section 4.1</a> offers recommendations on how RPCs that constitute
safe and idempotent information retrievals may be defined in a Web-friendly
manner. It does so by distinguishing aspects of the method and specific
parameters in an RPC definition that serve to identify resources from those
that serve other purposes. In <a href="#Example211">Example 12a</a>, the
resource to be retrieved is identified by two things: the first is that it is
an itinerary (part of the method name), and the second is the reference to a
specific instance (a parameter to the method). In such a case, the
recommendation is that these resource-identifying parts be made available in
the HTTP Request-URI identifying the resource, as for example, as follows:
<code>http://travelcompany.example.org/reservations/itinerary?reservationCode=FT35ZBQ</code>.</p>

<p>Furthermore, when an RPC definition is such that
all parts of its method description can be described as resource-identifying,
the entire target of the RPC may be identified by a URI. In this case, if the
supplier of the resource can also assure that a retrieval request is safe,
then SOAP Version 1.2 recommends that the choice of the Web method property
of GET and the use of the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapresmep"> SOAP
Response message exchange pattern</a> be used as described in <a href="#L26854">section 4.1.1</a>. This will ensure that the SOAP RPC is
performed in a Web architecture compatible manner.  <a href="#Ref4774883961111">Example 12b </a>shows the preferred way for a SOAP
node to request the safe retrieval of a resource.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Ref4774883961111" name="Ref4774883961111">Example 12b</a></div>

<div class="exampleInner">
<pre>GET /Reservations/itinerary?reservationCode=FT35ZBQ  HTTP/1.1
Host: travelcompany.example.org
Accept: application/soap+xml</pre>
</div>

<div class="exampleWrapper">
The Web architecture compatible alternative to representing the RPC in <a href="#Example211">Example 12a</a></div>
</div>

<p>It should be noted that SOAP Version 1.2 does not
specify any algorithm on how to compute a URI from the definition of an RPC
which has been determined to represent pure information retrieval.</p>

<p>Note, however, that if
the application requires the use of features that can only have a
binding-specific expression within the SOAP infoset, i.e., using SOAP header
blocks, then the application must choose HTTP POST method with a SOAP message
in the request body.</p>

<p>It also requires the use of the <a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#singlereqrespmep">SOAP Request-Response message exchange pattern</a> implemented via a HTTP POST if the RPC description
includes data (parameters) which are not resource-identifying. Even in this
case, the HTTP POST with a SOAP message can be represented in a Web-friendly
manner. As with the use of the GET, <a href="#L1098">[SOAP Part2]</a>
recommends for the general case that any part of the SOAP message that serves
to identify the resource to which the request is POSTed be identified in the
HTTP Request-URI. The same parameters may, of course, be retained in the
SOAP <code>env:Body</code> element. (The parameters must be retained in the Body
in the case of a SOAP-based RPC as these are related to the procedure/method
description expected by the receiving application.)</p>

<p><a href="#Ref477488396111">Example 13</a> is the same as that in <a href="#Ref47748839611">Example 9</a>, except that the HTTP Request-URI has
been modified to include the reservation <code>code</code>, which serves to identify the
resource (the reservation in question, which is being confirmed and paid
for).</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Ref477488396111" name="Ref477488396111">Example 13</a></div>

<div class="exampleInner">
<pre>POST /Reservations?code=FT35ZBQ HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0'?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" &gt;
 &lt;env:Header&gt;
   &lt;t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" &gt;5&lt;/t:transaction&gt;
 &lt;/env:Header&gt;  
 &lt;env:Body&gt;
  &lt;m:chargeReservation
      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
         xmlns:m="http://travelcompany.example.org/"&gt;
   &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation"&gt;
    &lt;m:code&gt;FT35ZBQ&lt;/m:code&gt;
   &lt;/m:reservation&gt;
   &lt;o:creditCard xmlns:o="http://mycompany.example.com/financial"&gt;
    &lt;n:name xmlns:n="http://mycompany.example.com/employees"&gt;
           Åke Jógvan Øyvind
    &lt;/n:name&gt;
    &lt;o:number&gt;123456789099999&lt;/o:number&gt;
    &lt;o:expiration&gt;2005-02&lt;/o:expiration&gt;
   &lt;/o:creditCard&gt;
  &lt;/m:chargeReservation&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
RPC from <a href="#Example2">Example 4</a> carried in an HTTP POST Request in
a Web-friendly manner</div>
</div>

<p>In <a href="#Ref477488396111">Example 13</a>, the resource to be
manipulated is identified by two things: the first is that it  is a
reservation (part of the method name), and the second is the specific
instance of a reservation (which is the value of the parameter
<code>code</code> to the method). The remainder of the parameters in the RPC
such as the <code>creditCard</code> number are not resource-identifying, but
are ancillary data to be processed by the resource. It is the recommendation
of [<a href="#L1098">SOAP Part2</a>] that resources that may be accessed by
SOAP-based RPCs should, where practical, place any such resource-identifying
information as a part  of the URI identifying the target of the RPC. It
should be noted, however, that [<a href="#L1098">SOAP Part2</a>] does not
offer any algorithm to do so. Such algorithms may be developed in future.
Note, however, that  all the resource-identifying elements have been retained
as in <a href="#Ref47748839611">Example 9</a> in their encoded form in  the
SOAP <code>env:Body</code> element.</p>

<p>In other words, as seen from the above
examples, the recommendation in the SOAP specifications is to use URIs in a
Web-architecture compatible way - that is, as resource identifiers - whether
or not it is GET or POST that is used.</p>

</div>
</div>

<div class="div2">

<h3><a name="SMTP"></a>4.2 SOAP Over Email</h3>

<p>Application developers can use the Internet email infrastructure to move
SOAP messages as either email text or attachments. The examples shown below
offer one way to carry SOAP messages, and should not be construed as being
the standard way of doing so. The SOAP Version 1.2 specifications do not
specify such a binding. However, there is a <em>non-normative</em> W3C Note
[<a href="#L3215">SOAP Email Binding</a>] describing an email binding for
SOAP, its main purpose being to demonstrate the application of the general
SOAP Protocol Binding Framework described in [<a href="#L1092">SOAP Part
1</a>].</p>

<p><a href="#Example14">Example 14</a> shows the travel reservation request
message from <a href="#Example">Example 1</a> carried as an email message
between a sending and receiving mail user agent. It is implied that the
receiver node  has SOAP capabilities, to which the body of the email is
delivered for processing. (It is assumed that the sending node also has SOAP
capabilities so as to be able to process any SOAP faults received in
response, or to correlate any SOAP messages received in response to this
one.)</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example14" name="Example14">Example 14</a></div>

<div class="exampleInner">
<pre>From: a.oyvind@mycompany.example.com
To: reservations@travelcompany.example.org
Subject: Travel to LA
Date: Thu, 29 Nov 2001 13:20:00 EST
Message-Id: &lt;EE492E16A090090276D208424960C0C@mycompany.example.com&gt;
Content-Type: application/soap+xml 

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
         env:mustUnderstand="true"&gt;
   &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
   &lt;m:dateAndTime&gt;2001-11-29T13:20:00.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
         env:mustUnderstand="true"&gt;
   &lt;n:name&gt;Åke Jógvan Øyvind&lt;/n:name&gt;
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;p:itinerary 
     xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     &lt;p:departing&gt;New York&lt;/p:departing&gt;
     &lt;p:arriving&gt;Los Angeles&lt;/p:arriving&gt;
     &lt;p:departureDate&gt;2001-12-14&lt;/p:departureDate&gt;
     &lt;p:departureTime&gt;late afternoon&lt;/p:departureTime&gt;
     &lt;p:seatPreference&gt;aisle&lt;/p:seatPreference&gt;
   &lt;/p:departure&gt;
   &lt;p:return&gt;
     &lt;p:departing&gt;Los Angeles&lt;/p:departing&gt;
     &lt;p:arriving&gt;New York&lt;/p:arriving&gt;
     &lt;p:departureDate&gt;2001-12-20&lt;/p:departureDate&gt;
     &lt;p:departureTime&gt;mid morning&lt;/p:departureTime&gt;
     &lt;p:seatPreference/&gt;
   &lt;/p:return&gt;
  &lt;/p:itinerary&gt;
  &lt;q:lodging 
     xmlns:q="http://travelcompany.example.org/reservation/hotels"&gt;
   &lt;q:preference&gt;none&lt;/q:preference&gt;
  &lt;/q:lodging&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message from <a href="#Example">Example 1</a> carried in a SMTP
message</div>
</div>

<p>The header in <a href="#Example14">Example 14</a> is in the standard form
[<a href="#R9">RFC 2822</a>] for email messages.</p>

<p>Although an email is a one-way message exchange, and no guarantee of
delivery is provided, email infrastructures like the Simple Mail Transport
Protocol (SMTP) specification [<a href="#R9">SMTP</a>] offer a delivery
notification mechanism which, in the case of SMTP, are called Delivery Status
Notification (DSN) and Message Disposition Notification (MDN). These
notifications take the form of email messages sent to the email address
specified in the mail header. Applications, as well as email end users, can
use these mechanisms to provide the status of an email transmission, but
these, if delivered, are notifications at the SMTP level. The application
developer must fully understand the capabilities and limitations of these
delivery notifications or risk assuming a successful data delivery when none
occurred.</p>

<p>SMTP delivery status messages are separate from message processing at the
SOAP layer. Resulting SOAP responses to the contained SOAP data will be
returned through a new email message which may or may not have a link to the
original requesting email at the SMTP level. The use of the [<a href="#R9">RFC 2822</a>] <code>In-reply-to:</code> header can achieve a
correlation at the SMTP level, but does not necessarily offer a correlation
at the SOAP level.</p>

<p><a href="#Example31">Example 15</a> is exactly the same scenario as
described for <a href="#Example3">Example 2</a>, which shows the SOAP message
(body details omitted for brevity) sent from the travel service application
to the travel reservation application seeking clarification on some
reservation details, except that it is carried as an email message. In this
example, the original email's<code> Message-Id</code> is carried in the
additional email header <code>In-reply-to:</code>, which correlates email
messages at the SMTP level, but cannot provide a SOAP-specific correlation.
In this example, the application relies on the <code>reservation</code>
header block to correlate SOAP messages. Again, how such correlation is
achieved is application-specific, and is not within the scope of SOAP.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example31" name="Example31">Example 15</a></div>

<div class="exampleInner">
<pre>From: reservations@travelcompany.example.org
To: a.oyvind@mycompany.example.com
Subject: Which NY airport?
Date: Thu, 29 Nov 2001 13:35:11 EST
Message-Id: &lt;200109251753.NAA10655@travelcompany.example.org&gt;
In-reply-to:&lt;EE492E16A090090276D208424960C0C@mycompany.example.com&gt;
Content-Type: application/soap+xml

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
       env:mustUnderstand="true"&gt;
   &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
   &lt;m:dateAndTime&gt;2001-11-29T13:35:00.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
        env:mustUnderstand="true"&gt;
   &lt;n:name&gt;Åke Jógvan Øyvind&lt;/n:name&gt;
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;p:itinerary
     xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:itineraryClarifications&gt;
      ...
      ...
   &lt;/p:itineraryClarifications&gt;
  &lt;/p:itinerary&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message from <a href="#Example3">Example 2</a> carried in an email
message with a header correlating it to a previous message.</div>
</div>

</div>
</div>
<div class="div1">

<h2><a name="L579"></a>5. Advanced Usage Scenarios</h2>

<div class="div2">

<h3><a name="L635"></a>5.1 Using SOAP Intermediaries</h3>

<p>The travel reservation scenario used throughout the primer offers an
opportunity to expose some uses of SOAP intermediaries. Recall that the basic
exchange was the exchange of a travel reservation request between a travel
reservation application and a travel service application. SOAP does not
specify how such a message path is determined and followed. That is outside
the scope of the SOAP specification. It does describe, though, how a SOAP
node should behave if it receives a SOAP message for which it is not the
ultimate receiver. SOAP Version 1.2 describes two types of intermediaries: <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#forwardinter">forwarding
intermediaries</a> and <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#activeinter">active
intermediaries</a>.</p>

<p>A <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#forwardinter">forwarding
intermediary</a> is a SOAP node which, based on the semantics of a header
block in a received SOAP message or based on the message exchange pattern in
use, forwards the SOAP message to another SOAP node. For example, processing
a "routing" header block describing a message path feature in an incoming
SOAP message may dictate that the SOAP message be forwarded to another SOAP
node identified by data in that header block. The format of the SOAP header
of the outbound SOAP message, i.e., the placement of inserted or reinserted
header blocks, is determined by the overall processing at this
<em>forwarding</em> intermediary based on the semantics of the processed
header blocks.</p>

<p>An <a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#activeinter">active
intermediary</a> is one that does additional processing on an incoming SOAP
message before forwarding the message using criteria that are not described
by incoming SOAP header blocks, or by the message exchange pattern in use.
Some examples of such active intervention at a SOAP node could be, for
instance, encrypting some parts of a SOAP message and providing the
information on the cipher key in a header block, or including some additional
information in a new header block in the outbound message providing a
timestamp or an annotation, for example, for interpretation by appropriately
targeted nodes downstream.</p>

<p>One mechanism by which an active intermediary can describe the
modifications performed on a message is by inserting header blocks into the
outbound SOAP message. These header blocks can inform  downstream SOAP nodes
acting in roles whose correct operation depends on receiving such
notification. In this case, the semantics of such inserted header blocks
should also call for either the same or other header blocks to be
(re)inserted at subsequent intermediaries as necessary to ensure that the
message can be safely processed by nodes yet further downstream. For example,
if a message with header blocks removed for encryption passes through a
second intermediary (without the original header blocks being decrypted and
reconstructed), then indication that the encryption has occurred must be
retained in the second relayed message.</p>

<p>In the following example, a SOAP node is introduced in the message path
between the travel reservation and travel service applications, which
intercepts the message shown in <a href="#Example">Example 1</a>. An example
of such a SOAP node is one which logs all travel requests for off-line review
by a corporate travel office. Note that the header blocks
<code>reservation</code> and <code>passenger</code> in that example are
intended for the node(s) that assume the role "next", which means that it is
targeted at the next SOAP node in the message path that receives the message.
The header blocks are mandatory (the <code>mustUnderstand</code> attribute is
set to "true"), which means that the node must have knowledge (through an
external specification of the header blocks' semantics) of what to do. A
logging specification for such header blocks might simply require that
various details of the message be recorded at every node that receives such a
message, and that the message be relayed along the message path unchanged.
(Note that the specifications of the header blocks must require that the same
header blocks be reinserted in the outbound message, because otherwise, the
SOAP processing model would require that they be removed.) In this case, the
SOAP node acts as a forwarding intermediary.</p>

<p>A more complex scenario is one where the received SOAP message is amended
in some way not anticipated by the initial sender. In the following example,
it is assumed that a corporate travel application at the SOAP intermediary
attaches a header block to the SOAP message from <a href="#Example">Example
1</a> before relaying it along its message path towards the travel service
application - the ultimate recipient. The header block contains the
constraints imposed by a travel policy for this requested trip. The
specification of such a header block might require that the ultimate
recipient (and only the ultimate recipient, as implied by the absence of the
<code>role</code> attribute) make use of the information conveyed by it when
processing the body of the message.</p>

<p><a href="#Example6">Example 16</a> shows an active intermediary inserting
an additional header block, <code>travelPolicy</code>, intended for the
ultimate recipient which includes information that qualifies the
application-level processing of this travel request.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example6" name="Example6">Example 16</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
        env:mustUnderstand="true"&gt;
   &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
   &lt;m:dateAndTime&gt;2001-11-29T13:20:00.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
       env:mustUnderstand="true"&gt;
   &lt;n:name&gt;Åke Jógvan Øyvind&lt;/n:name&gt;
  &lt;/n:passenger&gt;
  <span class="highlight">&lt;z:travelPolicy 
    xmlns:z="http://mycompany.example.com/policies" 
      env:mustUnderstand="true"&gt;</span>
   &lt;z:class&gt;economy&lt;/z:class&gt;
   &lt;z:fareBasis&gt;non-refundable&lt;z:fareBasis&gt;
   &lt;z:exceptions&gt;none&lt;/z:exceptions&gt;
  <span class="highlight">&lt;/z:travelPolicy&gt;</span>
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;p:itinerary 
    xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     &lt;p:departing&gt;New York&lt;/p:departing&gt;
     &lt;p:arriving&gt;Los Angeles&lt;/p:arriving&gt;
     &lt;p:departureDate&gt;2001-12-14&lt;/p:departureDate&gt;
     &lt;p:departureTime&gt;late afternoon&lt;/p:departureTime&gt;
     &lt;p:seatPreference&gt;aisle&lt;/p:seatPreference&gt;
   &lt;/p:departure&gt;
   &lt;p:return&gt;
     &lt;p:departing&gt;Los Angeles&lt;/p:departing&gt;
     &lt;p:arriving&gt;New York&lt;/p:arriving&gt;
     &lt;p:departureDate&gt;2001-12-20&lt;/p:departureDate&gt;
     &lt;p:departureTime&gt;mid morning&lt;/p:departureTime&gt;
     &lt;p:seatPreference/&gt;
   &lt;/p:return&gt;
  &lt;/p:itinerary&gt;
  &lt;q:lodging 
    xmlns:q="http://travelcompany.example.org/reservation/hotels"&gt;
   &lt;q:preference&gt;none&lt;/q:preference&gt;
  &lt;/q:lodging&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message from <a href="#Example">Example 1</a> for a travel reservation
after an active intermediary has inserted a mandatory header intended for the
ultimate recipient of the message</div>
</div>
</div>
<div class="div2">

<h3><a name="L3374"></a>5.2 Using Other Encoding Schemes</h3>

<p>Even though SOAP Version 1.2 defines a particular encoding scheme (see<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#soapenc"> SOAP
Part 2 section 3</a>), its use is optional and the specification makes clear
that other encoding schemes may be used for application-specific data within
a SOAP message. For this purpose it provides the attribute<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#soapencattr">
<code>env:encodingStyle</code></a>, of type <code>xs:anyURI</code>, to
qualify header blocks, any child elements of the SOAP <code>env:Body,</code>
and any child elements of the <code>env:Detail</code> element and their
descendants. It signals a serialization scheme for the nested contents, or at
least the one in place until another element is encountered which indicates
another encoding style for its nested contents. The choice of the value for
the <code>env:encodingStyle</code> attribute is an application-specific
decision and the ability to interoperate is assumed to have been settled
"out-of-band". If this attribute is not present, then no claims are being
made about the encoding being used.</p>

<p>The use of an alternative encoding scheme is illustrated in <a href="#Example9">Example 17</a>. Continuing with the travel reservation
theme, this example shows a SOAP message which is sent to the passenger from
the travel service after the reservation is confirmed, showing the travel
details. (The same message was used in <a href="#Example13">Example 8b</a> in another context.)</p>

<div class="exampleOuter">

<div class="exampleHead">
<a id="Example9" name="Example9">Example 17</a></div>

<div class="exampleInner">
<pre>&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
        env:mustUnderstand="true"&gt;
   &lt;m:reference&gt;uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d&lt;/m:reference&gt;
   &lt;m:dateAndTime&gt;2001-11-30T16:25:00.000-05:00&lt;/m:dateAndTime&gt;
  &lt;/m:reservation&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
            xmlns:x="http://travelcompany.example.org/vocab#"
    <span class="highlight">env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#"</span>&gt;
   &lt;x:ReservationRequest 
 rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ"&gt;
      &lt;x:passenger&gt;Åke Jógvan Øyvind&lt;/x:passenger&gt;
      &lt;x:outbound&gt;
       &lt;x:TravelRequest&gt;
        &lt;x:to&gt;LAX&lt;/x:to&gt;
        &lt;x:from&gt;LGA&lt;/x:from&gt;
        &lt;x:date&gt;2001-12-14&lt;/x:date&gt;
       &lt;/x:TravelRequest&gt;
      &lt;/x:outbound&gt;
      &lt;x:return&gt;
       &lt;x:TravelRequest&gt;
        &lt;x:to&gt;JFK&lt;/x:to&gt;
        &lt;x:from&gt;LAX&lt;/x:from&gt;
        &lt;x:date&gt;2001-12-20&lt;/x:date&gt;
       &lt;/x:TravelRequest&gt;
      &lt;/x:return&gt;
    &lt;/x:ReservationRequest&gt;
  &lt;/rdf:RDF&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
SOAP message showing the use of an alternative encoding for the
<code>Body</code> element</div>
</div>

<p>In <a href="#Example9">Example 17</a>, the body of the SOAP message
contains a description of the itinerary using the encoding of a graph of
resources and their properties using the syntax of the Resource Description
Framework (RDF) [<a href="#L4867">RDF</a>]. (Very briefly, as RDF syntax or
usage is not the subject of this primer, an RDF graph relates resources -
such as the travel reservation resource available at
<code>http://travelcompany.example.org/reservations?code=FT35ZBQ</code> - to
other resources (or values) via properties, such as the
<code>passenger</code>, the <code>outbound</code> and <code>return</code>
dates of travel. The RDF encoding for the itinerary might have been chosen,
for example, to allow the passenger's travel application to store it in an
RDF-capable calendar application, which could then be queried in complex
ways.)</p>

</div>
<div class="div2">

<h3><a name="L3360"></a>5.3 Optimized serialization of SOAP messages</h3>

There are many use cases where it is necessary for an application to send a
large amount of binary (i.e., non-textual) data (e.g., a JPEG image, binary
executable etc.) in a SOAP message. The conventional way of conveying binary
data in an XML document, such as the SOAP <code>env:Envelope</code>, is to
transform the binary data into a character representation of type <code><a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">xs:base64Binary</a></code>
using the Base64 content-transfer-encoding scheme defined in <a href="#L3410">[RFC 2045]</a>. The disadvantages of this approach are that
there is a significant increase in message size, as well as a potential
processing overhead in encoding/decoding the binary data to/from its
character representation, which may create throughput problems in case of
message transmission over low bandwidth links or SOAP nodes with low
processing power.

<p>The [<a href="#L9527">MTOM</a>] specification provides a mechanism to
support such use cases. It should be noted, though, that the specification
does not address the general problem of handling the inclusion of non-XML
content in arbitrary XML documents, but confines itself to the specific case
of SOAP message transmission optimization for certain type of content.</p>

<p>In order to allow for independence from the underlying protocol binding,
so that the optimization mechanism may be available over a variety of
transports, as well as to retain the principal SOAP binding paradigm - that
the SOAP message infoset, however serialized, be transmitted unchanged
between adjacent nodes - [<a href="#L9527">MTOM</a>] defines an <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
SOAP Transmission Optimization feature</a>, of which <em class="insert">one</em> implementation is provided for the particular case of
HTTP-based transmission of an optimized SOAP message in a MIME
Multipart/Related [<a href="#L3362">RFC 2387</a>] package. This makes use of
the <a href="#L3777">[XOP]</a> format (on which more in <a href="#L3787">Section 5.3.2</a>) which is an alternative serialization of an
XML infoset geared towards a more eficient processing and representation of
Base64-encoded content.</p>

<div class="div3">

<h4><a name="L3785"></a>5.3.1 The Abstract SOAP Transmission Optimization Feature</h4>

<p>The <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
SOAP Transmission Optimization feature</a> is defined for certain <a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204/#infoitem.element">element
information item</a> in the SOAP message infoset which are identified as
potential candidates for optimization. XML infosets identify the structure
and content of  XML documents, but not the data type of the contents of
elements and attributes. One way to identify these would require schema
validation of the infoset, something which is <em>not</em> a
requirement for SOAP. A more likely possibility is that the sending
application already "knows" the type of data - a binary stream, and perhaps
also the nature of the media type that it represents - that it wishes to
transmit because that is the way in which the data is already available to
it. The <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
SOAP Transmission Optimization feature</a> assumes that the type information
for those <a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204/#infoitem.element" class="insert">element information items</a> which are potential candidates
for optimization are somehow available to the sender of a SOAP message. This
feature is restricted to the optimization of character information items of
any element information item in the SOAP message infoset which is known to be
of type <a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">xs:base64Binary</a>
in its canonical lexical form (see [<a href="#R8">Schema Part2</a>] <a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#base64Binary">Section
3.2.16 base64Binary</a>). (The rationale for the restriction to the canonical
form of <code>xs:base64Binary</code> is provided at <a href="#important">the
end</a> of this section.)</p>

<p>To motivate the need for [<a href="#L9527">MTOM</a>], consider the example
of a SOAP message sent in response to the request for the travel itinerary in
<a href="#Ref4774883961111">Example 12b</a>. The travel reservation
application may wish to send, in addition to the information which can
readily be represented in XML, a corporate logo, a map of the destination and
other such information which is available in binary format (e.g., image
files). If there were only a small amount of non-XML data, it may be possible
to convert such data to its base64 encoding and convey the result in a SOAP
message sent in the HTTP response as shown in <a href="#Example15">Example
18</a> (with irrelevant content indicated by ellipses for brevity, and line
breaks added for clarity).</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example15">Example 18</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   :::
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   :::
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  <span class="highlight">&lt;o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"&gt;</span>HlkR4cT
YvAQLAcOAAAAAAQCAAgEAA0GAAEJAAYLAAoNAA8PAAAAJAQCJAgEJA0GJAEJJAYLJAoNJ
A8PJAAASAQCSAgESA0GSAEJSAYLSAoNSA8PSAAQbAQSbAgUbA0WbAEZbAYbbAodbA8fbAAQkAQSk
AgUkA0WkAEZkAYbkAodkA8fkAAgtAQitAgktA0mtAEptAYrtAottA8vtAAg2AQi2Agk2A0m2AEp2
              :::
qG4dSiwpp2eK4LZLr6tuqTWump4H4xSz6G1dioPCqT5eWq5EtdUdJSSoYLAMjqasWYLZYmTOrz+o
7aJOt+aM9rWrxut4DAArILM9t0kShRgCFJaUk+uvAgshVRaPlXebGyv67APwKb9qw/r0di/a6Cxn
lELvZYABAsD==<span class="highlight">&lt;/o:travelAgencyLogo&gt;</span>
  &lt;p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     :::
   &lt;/p:departure&gt;
   &lt;p:return&gt;     
     :::
   &lt;/p:return&gt;
  &lt;/p:itinerary&gt;
  &lt;q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels"&gt;
   &lt;hotel&gt; 
    :::
   &lt;/hotel&gt;
   <span class="highlight">&lt;r:areaMap xmlns:r="http://travelcompany.example.org/maps"&gt;</span>HlkR4kTYMCgoAQMAAAA
AA8///ru6q/8zPzMzM/7v/CLsw6pne+4jPCIgACHcwFWYhBFUQBEQABDM
AEBAsAAAAAAjAIKAAUw/gRRCFlmnopqrFHJvvNyyLw2Ji56789+/ADKcHia3OiMpSEoEobgKHDnS
             :::
w83hCNkr0gECT1bgEaJigpDmwFEvYOkDCgYQLMus1QDgFUYOoGGN+gtPdYYgOMDZLhwyA+BHyDMR
qweAJoAgAcYHvzTQktoAsODhl4LYBIDMevgtHPUDiAmg5gSQTUB8ETxO1HKAJRj4OI70AMeKgriF
LOECAAwO=<span class="highlight">&lt;/r:areaMap&gt;</span>
  &lt;/q:lodging&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message representing a travel itinerary showing non-XML data
carried using base64 encoding</div>
</div>

<p><a href="#Example15">Example 18</a> highlights two elements contained
within the SOAP <code>env:Body&gt;</code>, namely
<code>o:travelAgencyLogo</code> and <code>r:areaMap</code>, containing the
base64 encoding of binary data corresponding to a corporate logo and an area
map. While small amounts of binary data can be placed in a SOAP message using
the base64 encoding without incurring the performance overheads noted
earlier, binary data anticipated in typical use cases is typically quite
large, often many orders of magnitude larger than the XML content. To avoid
the performance penalty in such circumstances,  <a href="#L9527">[MTOM]</a>
offers an optimization that avoids the need to base64-encode large binary
content. (Note that SOAP nodes that do not implement [<a href="#L9527">MTOM</a>] have no choice but to carry binary data re-encoded in
its base64 character representation, as in <a href="#Example15">Example
18</a>.)</p>

<p>The <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
SOAP Transmission Optimization feature</a> provides the optimization by
conceptually describing the binary data that needs to be conveyed as the
content of an element information item in the SOAP message infoset in terms
of its base64 encoding. While this character based representation is
conceptually present at the sender and receiver, [MTOM] works on the
optimistic assumption that the sending and receiving applications will not
actually need the character-based representation of the binary value, and
therefore there will be no real processing overhead in conversion between the
binary value and its base64 encoding. Similarly, the implementation of this
feature using the [XOP] format (more details are provided in <a href="#L3787">section 5.3.2</a>) employs a MIME Multipart/Related [<a href="#L3362">RFC 2387</a>] package to convey the binary data as an
"attachment"  referenced from within a modified, serialized SOAP message;
therefore, there is also no overhead of increased message size.</p>

<p>As noted earlier, it is assumed that the sending implementation somehow
knows or determines the type information of the element information items
that are candidates for potential optimization; otherwise the optimization
feature does not work. The scope of <a href="#L9527">[MTOM]</a>  is solely to
optimize the transmission of the SOAP message infoset for those element
information items that have base64 encoded binary data in canonical form as
their content.</p>

<p>As with all features, <a href="#L9527">[MTOM]</a> needs a SOAP protocol
binding to transfer the optimized serialization. Recall from <a href="#transport">Section 4</a> that a SOAP protocol binding must transfer
the SOAP message infoset in such a way that it can be reconstructed at the
receiver unchanged. An MTOM-aware binding is one where a sender can serialize
a SOAP message infoset by transmitting the actual value - that is, the actual
bits - of certain element information items known to be in the canonical
lexical representation of type <code>xs:base64Binary</code> rather than their
lexical character representation. A receiver supporting this binding can,
from the received value, reconstruct, at least conceptually, the lexical
character representation if that is required by the application.</p>

<p>[MTOM] provides an enhancement to the existing SOAP HTTP binding to
provide an implementation of the <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
SOAP Transmission Optimization feature</a>. It uses the <a href="#L3777">[XOP]</a>-based inclusion mechanism described in section 5.3.2,
and places the resulting MIME Multipart/Related package in the body of a HTTP
message.</p>

<p>As noted earlier, applications, in many implementations, will deal
directly with the binary values and there is no implication that a base64
encoded character representation of the received value needs to be created,
if there is no need to do so. However, there are instances when there may be
a need to obtain the character representation, for example at a SOAP
intermediary which has to forward the message on a non-MTOM-aware binding.</p>

<p><a name="important" id="important">One important subtlety</a> in ensuring
that the original message infoset can be reconstructed faithfully is to
mandate, as does <a href="#L9527">[MTOM]</a>, that the original base64
encoded characters be in their canonical form. <a href="#R8">[XML Schema
Part2]</a> allows for multiple lexical representations of the
<code>xs:base64Binary</code> data type, mainly in the handling of white
space, and therefore defines a canonical form which permits a 1-to-1
correspondence between a binary value and its lexical representation. By
restricting itself to optimization candidates which are in the canonical form
of <code>xs:base64Binary</code>, it can be ensured that the transferred
message infoset is reproduced unchanged.</p>

<p>Therefore, in the following sections, whenever we, for the sake of
brevity, refer to base64-encoded data, the reader should keep in mind that we
mean XML element content whose type is in the canonical lexical
representation of <code>xs:base64Binary</code><span class="insert">.</span></p>

</div>
<div class="div3">

<h4><a name="L3787"></a>5.3.2 The Optimized Transmission Serialization Format</h4>

<p>The next step in implementing the <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#feature">Abstract
SOAP Transmission Optimization feature</a> is to define the format in which
the SOAP message infoset (with potential optimization candidates identified,
as described in the previous section) is serialized in an optimal way for
transmission. The serialization technique is described in <a href="#L9527">[MTOM]</a> by making use of an "inclusion" technique specified
in the XML-binary Optimized Packaging <a href="#L3777">[XOP]</a>
specification together with a MIME Multipart/Related packaging ([RFC
2387]).</p>

<p><a href="#L3777">[XOP]</a> defines an <code><a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_include">xop:Include</a></code>
element that ties, at a SOAP binding level, the binary content for an element
to its infoset representation as base64-encoded character information items
in the [children] property of that element information item. A SOAP binding
that is capable of optimized serialization of an infoset containing such
binary data represented by their character information items uses this
<code><a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_include">xop:Include</a></code>
element in the SOAP envelope as a placeholder to link (using an
<code>href</code> attribute) to the optimized (i.e., binary) data carried
along with the SOAP envelope in an overall package.</p>

<p>The overall package chosen is the extensible MIME Multipart/Related <a href="#L3362">[RFC 2387]</a> format. The root body part of this MIME package
contains the XML 1.0 serialization of the SOAP <code>env:Envelope</code>,
modified by the presence of one (or more) <code>xop:Include</code>
element(s), while the other (related) body part(s) of the MIME package
contain the compact (i.e, binary) data referenced by the
<code>xop:Include</code> element(s).</p>

<p>The serialization of the SOAP message from <a href="#Example15">Example
18</a>, converted to this optimized format using [XOP], is shown in <a href="#Example16">Example 19a</a>.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example16">Example 19a</a></div>

<div class="exampleInner">
<pre>MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=example-boundary; 
  type=application/xop+xml; 
  start="&lt;itinerary123.xml@travelcompany.example.org&gt;";
  startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Description: This is an example of an optimized SOAP message

--example-boundary
<span class="highlight">Content-Type: application/xop+xml;</span> charset=UTF-8
<span class="highlight">type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""</span>
Content-Transfer-Encoding: 8bit
Content-ID: &lt;itinerary123.xml@travelcompany.example.org&gt;

&lt;?xml version='1.0'?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
     <span class="highlight">xmlns:xmime='http://www.w3.org/2004/06/xmlmime'</span>&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   :::
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   :::
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"
    <span class="highlight">xmime:contentType='image/jpg'&gt;&lt;xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
      href="cid:logo.gif@travelcompany.example.org"/&gt;</span>&lt;/o:travelAgencyLogo&gt;
  &lt;p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     :::
   &lt;/p:departure&gt;
   &lt;p:return&gt;     
     :::
   &lt;/p:return&gt;
  &lt;/p:itinerary&gt;
  &lt;q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels"&gt;
   &lt;hotel&gt; 
    :::
   &lt;/hotel&gt;
   &lt;r:areaMap xmlns:r="http://travelcompany.example.org/maps" 
      <span class="highlight">xmime:contentType="image/jpg"&gt;&lt;xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
         href="cid:map123.jpg@travelcompany.example.org"/&gt;</span>&lt;/r:areaMap&gt;
  &lt;/q:lodging&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: <span class="highlight">&lt;logo.gif@travelcompany.example.org&gt;</span>

::: the binary data :::

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: <span class="highlight">&lt;map123.jpg@travelcompany.example.org&gt;</span>

::: the binary data :::

--example-boundary--</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message for a travel itinerary showing non-XML (binary) data
carried using the <a href="#L3777">[XOP]</a> format</div>
</div>

<p>In <a href="#Example16">Example 19a</a>, the conventional MIME
Multipart/Related package conveys a compound "object" broken up into multiple
inter-related body parts. The "start" parameter of the overall Content-Type
conveys, via a Content-ID, the body part which contains the compound object's
"root", while the media type parameter value of "<a href="http://www.iana.org/assignments/media-types/application/xop+xml">application/xop+xml</a>"
identifies the contents as an XML document serialized using the [XOP] format.
The "startinfo" parameter of the package shows that this root part is the XML
1.0 serialization of the SOAP <code>env:Envelope</code> modified by the
inclusion of <code>xop:Include</code> elements where appropriate.</p>

<p>Compared with <a href="#Example15">Example 18</a>, note, in <a href="#Example16">Example 19a</a>, the presence of the two <code><a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_include">xop:Include</a></code>
elements which replace the character representations of the binary data
corresponding to the company logo and the lodging area map. Each of these
elements provides via the <code>href</code> attribute the link by which the
binding knows which MIME body part contains the binary data that corresponds
to the (canonical form of the) equivalent base64-encoded character
representation.</p>

<p>Note also the presence of the additional attribute <code><a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/#contentType">xmime:contentType</a></code>
(see [<a href="#L3991">MediaType</a>] <a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/#contentType">Section
2.1 contentType Attribute</a>) in the <code>xop:Include</code> elements to
indicate the media type of the contents of the
<code>o:TravelAgencyLogo</code> and <code>r:AreaMap</code> elements.</p>

<p>When such an optimized MIME Multipart/Related package based on the [XOP]
format is sent in a HTTP message, [<a name="MTOM" id="MTOM" href="#L9527">MTOM</a>] <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/#httpof-implementation">Section
4.3</a> requires that the resultant MIME headers are sent as HTTP headers,
while the remainder of the package is placed in the HTTP body. <a href="#Example161">Example 19b</a> shows the SOAP message from <a href="#Example16">Example 19a</a> returned in a HTTP response (with the
relevant HTTP headers highlighted).</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example161" id="Example161">Example 19b</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 200 OK
<span class="highlight">Content-Type: Multipart/Related; boundary=example-boundary; 
  type=application/xop+xml; 
  start="&lt;itinerary123.xml@travelcompany.example.org&gt;";
  startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Description: This is an example of an optimized SOAP message</span>
Content-Length: nnnn

--example-boundary
Content-Type: application/xop+xml; charset=UTF-8
type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Transfer-Encoding: 8bit
Content-ID: &lt;itinerary123.xml@travelcompany.example.org&gt;

&lt;?xml version='1.0'?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
     xmlns:xmime='http://www.w3.org/2004/06/xmlmime'&gt; 
 &lt;env:Header&gt;
  &lt;m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   :::
  &lt;/m:reservation&gt;
  &lt;n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true"&gt;
   :::
  &lt;/n:passenger&gt;
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"
    xmime:contentType='image/jpg'&gt;&lt;xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
      href="cid:logo.gif@travelcompany.example.org"/&gt;&lt;/o:travelAgencyLogo&gt;
  &lt;p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel"&gt;
   &lt;p:departure&gt;
     :::
   &lt;/p:departure&gt;
   &lt;p:return&gt;     
     :::
   &lt;/p:return&gt;
  &lt;/p:itinerary&gt;
  &lt;q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels"&gt;
   &lt;hotel&gt; 
    :::
   &lt;/hotel&gt;
   &lt;r:areaMap xmlns:r="http://travelcompany.example.org/maps" 
      xmime:contentType="image/jpg"&gt;&lt;xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
         href="cid:map123.jpg@travelcompany.example.org"/&gt;&lt;/r:areaMap&gt;
  &lt;/q:lodging&gt;
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: &lt;logo.gif@travelcompany.example.org&gt;

::: the binary data :::

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: &lt;map123.jpg@travelcompany.example.org&gt;

::: the binary data :::

--example-boundary--</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message for a travel itinerary carried in a HTTP response,
showing the MIME Multipart/Related headers carried as HTTP headers</div>
</div>

<p>In <a name="Example20" id="Example20" href="#Example161">Example 19b</a>,
the MIME Multipart/Related headers arising from the [XOP] format (see <a href="#Example16">Example 19a</a>) are carried as HTTP headers in the HTTP
200 OK response.</p>

</div>
<div class="div3">

<h4><a name="L3791"></a>5.3.3 Using the Resource Representation SOAP Header Block</h4>

<p>Another optimization that has been identified as useful for processing a
SOAP message which includes URI-based references to Web resources is one
where the sender includes <em>a</em> representation of each such resource in
the SOAP message to either the ultimate receiver or an intermediary. This
helps in situations where the processing of the SOAP message depends on
dereferencing the URIs, but which may not be possible because the receiver is
not able or wishes to avoid the overhead of the network traffic needed to do
so. The gain is even greater if the same resource (the image of a logo, say)
is referenced multiple times within the message.</p>

<p>The Resource Representation SOAP Header Block [<a href="#L4299">ResRep</a>] specification describes a SOAP header block,
containing a <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
element, which defines how URI-based representations of resources referenced
within a SOAP message infoset may be carried and processed by an identified
receiver. Its use is illustrated by examples that follow.</p>

<p>Recall, from <a href="#Example15">Example 18</a>, that a base64-encoded
form of the travel agency logo was sent in the SOAP message. However, this
may well have been included by providing a HTTP URL link to the location from
which the (ultimate) receiver could retrieve the image as a part of
processing the message. This is shown, with all inessentials deleted, in <a href="#Example17">Example 20</a>.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example17">Example 20</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"&gt; 
 &lt;env:Header&gt;
   :::
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  <span class="highlight">&lt;o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"&gt;</span>
   <span class="highlight">&lt;o:image o:source= "http://travelcompany.example.org/images/logo.jpg"/&gt;</span>
  <span class="highlight">&lt;/o:travelAgencyLogo&gt;</span>
  
     :::
     :::
     
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message based on <a href="#Example15">Example 18</a> showing the
travel agency logo element content as a link to a Web resource</div>
</div>

<p>In <a href="#Example17">Example 20</a>, the expectation is that the
contents of the <code>o:image</code> element would be obtained by
dereferencing the URL identified by the <code>o:source</code> attribute.
However, as identified earlier, if a situation were anticipated where the
processing overhead of dereferencing the URI were considered unacceptable, a
representation of the logo image can be sent using the <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
element, as shown in <a href="#Example18">Example 21</a> (with the header
highlighted).</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example18">Example 21</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
   <span class="highlight">xmlns:rep='http://www.w3.org/2004/02/representation'
     xmlns:xmime='http://www.w3.org/2004/06/xmlmime'</span>&gt; 
 &lt;env:Header&gt;
  <span class="highlight">&lt;rep:Representation resource='http://travelcompany.example.org/images/logo.jpg'&gt;
   &lt;rep:Data xmime:contentType='image/jpg'&gt;</span>HlkR4cTYvAQLAcOAAAAAAQCAAgEAA0GA
AEJAAYLAAoNAA8PAAAAJAQCJAgEJA0GJAEJJAYLJAoNJA8PJAAASAQCSAgESA0GSAEJSAYLSAoNSA
8PSAAQbAQSbAgUbA0WbAEZbAYbbAodbA8fbAAQkAQSkAgUkA0WkAEZkAYbkAodkA8fkAAgtAQitAgk
              :::
qG4dSiwpp2eK4LZLr6tuqTWump4H4xSz6G1dioPCqT5eWq5EtdUdJSSoYLAMjqasWYLZYmTOrz+o
7aJOt+aM9rWrxut4DAArILM9t0kShRgCFJaUk+uvAgshVRaPlXebGyv67APwKb9qw/r0di/a6Cxn
lELvZYABAsD==<span class="highlight">&lt;/rep:Data&gt;
  &lt;/rep:Representation&gt;</span>
   :::
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  <span class="highlight">&lt;o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"&gt;</span>
   <span class="highlight">&lt;o:image o:source= "http://travelcompany.example.org/images/logo.jpg"/&gt;</span>
  <span class="highlight">&lt;/o:travelAgencyLogo&gt;</span>
  
     :::
     :::
     
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message based on <a href="#Example17">Example 20</a> showing a
representation of a Web resource (an image of the travel agency logo) carried
in the Representation header.</div>
</div>

<p><a>In </a><a href="#Example18">Example 21</a>, the <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
element contains a mandatory <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-resource">resource</a></code>
attribute whose value is the URI identifying the Web resource, while the
<code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-data">rep:Data</a></code>
element is a base64-encoded representation of the resource. The optional
<code><a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/#contentType">xmime:contentType</a></code>
attribute in <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-data">rep:Data</a></code>
is used to identify the media type of the resource representation being
conveyed. The <code><a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-representation">rep:Representation</a></code>
element can make use of other attributes (see [<a href="#L4299">ResRep</a>]
<a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/#rep-construct">Section
2.2 Representation header block Constructs</a> for details) including the
SOAP-defined ones, <code>env:mustUnderstand</code> and <code>env:Role</code>,
described in section 3. The use of such additional headers allows the
targeted receiver to know that the resource representation is available to
it.</p>

<p>If the binary content representing the resource were available to the
sender, and sending the base64-encoded form of that (presumably large) binary
content was deemed inefficient, the use of the
<code>rep:Representation</code> element can be combined with [<a href="#L9527" class="insert">MTOM</a>] and the [<a href="#L3777">XOP</a>]
format to gain the efficiencies of that feature. This is shown in <a href="#Example19">Example 22</a>, with the <code>xop:Include</code> element
highlighted.</p>

<div class="exampleOuter">

<div class="exampleHead">
<a name="Example19">Example 22</a></div>

<div class="exampleInner">
<pre>HTTP/1.1 200 OK
Content-Type: mime/multipart-related; charset="utf-8"
Content-Length: nnnn

MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=example-boundary; 
  type=application/xop+xml; 
  start="&lt;itinerary123.xml@travelcompany.example.org&gt;";
  startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Description: This is an example of an optimized SOAP message

--example-boundary
Content-Type: application/xop+xml; charset=UTF-8;
type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Transfer-Encoding: 8bit
Content-ID: &lt;itinerary123.xml@travelcompany.example.org&gt;

&lt;?xml version='1.0' ?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
   xmlns:rep='http://www.w3.org/2004/02/representation'
     xmlns:xmime='http://www.w3.org/2004/06/xmlmime'&gt; 
 &lt;env:Header&gt;
  &lt;rep:Representation resource='http://travelcompany.example.org/images/logo.jpg'&gt;
   <span class="highlight">&lt;xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
      href="cid:logo.gif@travelcompany.example.org"/&gt;</span>&lt;/rep:Representation&gt;
   :::
 &lt;/env:Header&gt;
 &lt;env:Body&gt;
  &lt;o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"&gt;
   &lt;o:image o:source= "http://travelcompany.example.org/images/logo.jpg"/&gt;
  &lt;/o:travelAgencyLogo&gt;
     :::
     :::     
 &lt;/env:Body&gt;
&lt;/env:Envelope&gt;

<span class="highlight">--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: &lt;logo.gif@travelcompany.example.org&gt;

::: the binary data for the travel agency logo :::</span>

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: &lt;map123.jpg@travelcompany.example.org&gt;

::: the binary data :::

--example-boundary--</pre>
</div>

<div class="exampleWrapper">
Sample SOAP message based on <a href="#Example18">Example 21</a> showing the
representation of a Web resource (an image of the travel agency logo) carried
in the Representation header using the MTOM/XOP optimization.</div>
</div>
</div>
</div>
</div>
<div class="div1">

<h2><a name="L4697"></a>6. Changes Between SOAP 1.1 and SOAP 1.2</h2>

<p>SOAP Version 1.2 has a number of changes in syntax and provides additional
(or clarified) semantics from those described in [<a href="#R11">SOAP
1.1]</a>. The following is a list of features where the two specifications
differ. The purpose of this list is to provide the reader with a quick and
easily accessible summary of the differences between the two specifications.
The features have been put in categories purely for ease of reference, and in
some cases, an item might equally well have been placed in another
category.</p>

<p><em>Document structure</em></p>
<ul>
  <li>The SOAP 1.2 specifications have been provided in two parts. <a href="#L1092">[SOAP Part1]</a> provides an abstract Infoset-based
    definition of the SOAP message structure, a processing model and an
    underlying protocol binding framework, while <a href="#L1098">[SOAP
    Part2]</a> provides serialization rules for conveying that infoset as
    well as a particular HTTP binding.</li>
  <li>SOAP 1.2 will not spell out the acronym.</li>
  <li>SOAP 1.2 has been rewritten in terms of XML infosets, and not as
    serializations of the form &lt;?xml....?&gt; required by SOAP 1.1.</li>
</ul>

<p><em>Additional or changed syntax</em></p>
<ul>
  <li>SOAP 1.2 does not permit any element after the body. The SOAP 1.1 <a href="http://schemas.xmlsoap.org/soap/envelope/">schema definition</a>
    allowed for such a possibility, but the textual description is silent
    about it.</li>
  <li>SOAP 1.2 does not allow the <code>env:encodingStyle</code> attribute to
    appear on the SOAP <code>env:Envelope</code>, whereas SOAP 1.1 allows it
    to appear on any element. SOAP 1.2 specifies specific elements where this
    attribute may be used.</li>
  <li>SOAP 1.2 defines the new <code>env:NotUnderstood</code> header element
    for conveying information on a mandatory header block which could not be
    processed, as indicated by the presence of an
    <code>env:MustUnderstand</code> fault code. SOAP 1.1 provided the fault
    code, but no details on its use.</li>
  <li>In the SOAP 1.2 infoset-based description, the
    <code>env:mustUnderstand</code> attribute in header elements takes the
    (logical) value "true" or "false", whereas in SOAP 1.1 they are the
    literal value "1" or "0" respectively.</li>
  <li>SOAP 1.2 provides a new fault code
  <code>DataEncodingUnknown</code>.</li>
  <li>The various namespaces defined by the two protocols are of course
    different.</li>
  <li>SOAP 1.2 replaces the attribute <code>env:actor</code> with
    <code>env:role</code> but with essentially the same semantics.</li>
  <li>SOAP 1.2 defines a new attribute, <code>env:relay</code>, for header
    blocks to indicate if unprocessed header blocks should be forwarded.</li>
  <li>SOAP 1.2 defines two new roles, "none" and "ultimateReceiver", together
    with a more detailed processing model on how these behave.</li>
  <li>SOAP 1.2 has removed the "dot" notation for fault codes, which are now
    simply an XML Qualified Name, where the namespace prefix is the SOAP
    envelope namespace.</li>
  <li>SOAP 1.2 replaces "client" and "server" fault codes with "Sender" and
    "Receiver".</li>
  <li>SOAP 1.2 uses the element names <code>env:Code</code> and
    <code>env:Reason</code>, respectively, for what used to be called
    <code>faultcode</code> and <code>faultstring</code> in SOAP 1.1. SOAP 1.2
    also allows multiple <code>env:Text</code> child elements of
    <code>env:Reason</code> qualified by <code>xml:lang</code> to allow
    multiple language versions of the fault reason.</li>
  <li>SOAP 1.2 provides a hierarchical structure for the mandatory SOAP
    <code>env:Code</code> sub-element in the <code>env:Fault</code> element,
    and introduces two new optional subelements, <code>env:Node</code> and
    <code>env:Role</code>.</li>
  <li>SOAP 1.2 removes the distinction that was present in SOAP 1.1 between
    header and body faults as indicated by the presence of the
    <code>env:Details</code> element in <code>env:Fault</code>. In SOAP 1.2,
    the presence of the <code>env:Details</code> element has no significance
    as to which part of the fault SOAP message was processed.</li>
  <li>SOAP 1.2 uses XML Base <a href="#L2778">[XML Base]</a> for determining
    a base URI for relative URI references whereas SOAP 1.1 is silent about
    the matter.</li>
</ul>

<p><em>SOAP HTTP binding</em></p>
<ul>
  <li>In the SOAP 1.2 HTTP binding, the <code>SOAPAction</code> HTTP header
    defined in SOAP 1.1 has been removed, and a new HTTP status code 427 has
    been sought from IANA for indicating (at the discretion of the HTTP
    origin server) that its presence is required by the server application.
    The contents of the former <code>SOAPAction</code> HTTP header are now
    expressed as a value of an (optional) "<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427/#ietf-draft">action</a>"
    parameter of the "application/soap+xml" media type that is signaled in
    the HTTP binding.</li>
  <li>In the SOAP 1.2 HTTP binding, the Content-type header should be
    "application/soap+xml" instead of "text/xml" as in SOAP 1.1. The IETF
    registration for this new media type is [<a href="#r13">RFC 3902</a>].</li>
  <li>SOAP 1.2 provides a finer grained description of use of the various
    2xx, 3xx, 4xx HTTP status codes.</li>
  <li>Support of the HTTP extensions framework has been removed from SOAP
  1.2.</li>
  <li>SOAP 1.2 provides an additional message
    exchange pattern which may be used as a part of the HTTP binding that
    allows the use of HTTP GET for safe and idempotent information
    retrievals.</li>
</ul>

<p><em>RPC</em></p>
<ul>
  <li>SOAP 1.2 provides a <code>rpc:result</code> element accessor for
  RPCs.</li>
  <li>SOAP 1.2 provides several additional fault codes in the <a href="http://www.w3.org/2003/05/soap-rpc">RPC namespace</a>.</li>
  <li>SOAP 1.2 offers guidance on a Web-friendly
    approach to defining RPCs where the procedure's purpose is purely "safe"
    informational retrieval.</li>
</ul>

<p><em>SOAP encodings</em></p>
<ul>
  <li>An abstract data model based on a directed edge labeled graph has been
    formulated for SOAP 1.2. The SOAP 1.2 encodings are dependent on this
    data model. The SOAP RPC conventions are dependent on this data model,
    but have no dependencies on the SOAP encoding. Support of the SOAP 1.2
    encodings and SOAP 1.2 RPC conventions are optional.</li>
  <li>The syntax for the serialization of an array has been changed in SOAP
    1.2 from that in SOAP 1.1.</li>
  <li>The support provided in SOAP 1.1 for partially transmitted and sparse
    arrays is not available in SOAP 1.2.</li>
  <li>SOAP 1.2 allows the inline (embedded) serialization of multiref
  values.</li>
  <li>The <code>href</code> attribute in SOAP 1.1 (of type
    <code>xs:anyURI</code>) is called <code>enc:ref</code> in SOAP 1.2 and is
    of type <code>IDREF</code>.</li>
  <li>In SOAP 1.2, omitted accessors of compound types are made equal to
  NILs.</li>
  <li>SOAP 1.2 provides several fault sub-codes for indicating encoding
    errors.</li>
  <li>Types on nodes are made optional in SOAP 1.2.</li>
  <li>SOAP 1.2 has removed generic compound values from the SOAP Data
  Model.</li>
  <li>SOAP 1.2 has added an optional attribute <code>enc:nodeType</code> to
    elements encoded using SOAP encoding that identifies its structure (i.e.,
    a simple value, a struct or an array).</li>
</ul>

<p><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#version">SOAP Part
1 Appendix A</a> provides version management rules for a SOAP node that can
support the version transition from [<a href="#R11">SOAP 1.1</a>] to SOAP
Version 1.2. In particular, in defines an <code><a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427/#vmfault">env:Upgrade</a></code>
header block which can be used by a SOAP 1.2 node on receipt of a [<a href="#R11">SOAP 1.1</a>] message to send a SOAP fault message to the
originator to signal which version of SOAP it supports.</p>

</div>

<div class="div1">

<h2><a name="L810"></a>7. References</h2>

        <dl>
   <dt class="label"><a name="L1092"></a>[SOAP Part 1] </dt><dd>
	<a href="http://www.w3.org/TR/2007/REC-soap12-part1-20070427"><cite>SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)</cite></a>, 
	Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau,
	Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors.
	World Wide Web Consortium, 27 April 2007.
	This version is http://www.w3.org/TR/2007/REC-soap12-part1-20070427.
	The <a href="http://www.w3.org/TR/soap12-part1/">latest version</a> is
	available at http://www.w3.org/TR/soap12-part1/.</dd>

   <dt class="label"><a name="L1098"></a>[SOAP Part 2] </dt><dd>
	<a href="http://www.w3.org/TR/2007/REC-soap12-part2-20070427"><cite>SOAP Version 1.2 Part 2: Adjuncts (Second Edition)</cite></a>, 
	Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau,
        Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors. 
	World Wide Web Consortium, 27 April 2007.
	This version is http://www.w3.org/TR/2007/REC-soap12-part2-20070427.
	The <a href="http://www.w3.org/TR/soap12-part2/">latest version</a> is
	available at http://www.w3.org/TR/soap12-part2/.</dd>

   <dt class="label"><a name="L9527"></a>[MTOM] </dt><dd>
        <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/"><cite>SOAP Message 
	Transmission Optimization Mechanism</cite></a>, Hervé Ruellan,
	Noah Mendelsohn, Martin Gudgin, and Mark Nottingham, Editors. 
	World Wide Web Consortium, 
	25 January 2005. 
	This version is http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.
	The <a href="http://www.w3.org/TR/soap12-mtom/">latest version</a> is
	available at http://www.w3.org/TR/soap12-mtom/.</dd>

    <dt class="label"><a name="RFC3986"></a>[RFC 3986] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc3986.txt"><cite>Uniform Resource 
	Identifiers (URI): Generic Syntax</cite></a>, T. Berners-Lee, 
	R. Fielding and L. Masinter, Editors.
	IETF, January 2005. 
	<em>Obsoletes: <span id="L1105">RFC 2396</span>, 
	<span id="RFC2732">RFC 2732</span></em>.
	This RFC is available at http://www.ietf.org/rfc/rfc3986.txt.</dd>

    <dt class="label"><a name="RFC3987"></a>[RFC 3987] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc3987.txt"><cite>
	Internationalized Resource Identifiers (IRIs)
	</cite></a>, 
	M. Duerst, Editors.
	IETF, January 2005. 
	This RFC is available at http://www.ietf.org/rfc/rfc3987.txt.</dd>

    <dt class="label"><a name="L3133"></a>[RFC 2616] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2616.txt"><cite>Hypertext 
	Transfer Protocol -- HTTP/1.1</cite></a>, R. Fielding,
 	J. Gettys, J. C. Mogul, H. Frystyk Nielsen, P. Leach, 
	L. Masinter and T. Berners-Lee,
	Editors.
	IETF, June 1999. 
	This RFC is available at http://www.ietf.org/rfc/rfc2616.txt.</dd>

    <dt class="label"><a name="L3532"></a>[XML 1.0] </dt><dd>
	<a href="http://www.w3.org/TR/2006/REC-xml-20060816"><cite>Extensible
	Markup Language (XML) 1.0 (Fourth Edition)</cite></a>, Jean Paoli,
	Eve Maler, Tim Bray, <em>et. al.</em>, Editors. 
	World Wide Web Consortium, 16 August 2006. 
	This version is http://www.w3.org/TR/2006/REC-xml-20060816. 
	The <a href="http://www.w3.org/TR/REC-xml">latest version</a> is
	available at http://www.w3.org/TR/REC-xml.</dd>

    <dt class="label"><a name="XMLNS"></a>[Namespaces in XML] </dt><dd>
	<a href="http://www.w3.org/TR/2006/REC-xml-names-20060816"><cite>
	Namespaces in
	XML (Second Edition)</cite></a>, Tim Bray, Dave Hollander, 
        Andrew Layman, and Richard Tobin, Editors. 
	World Wide Web Consortium, 16 August 2006. 
	This version is http://www.w3.org/TR/2006/REC-xml-names-20060816.
	The <a href="http://www.w3.org/TR/REC-xml-names">latest version</a> is
	available at http://www.w3.org/TR/REC-xml-names.</dd>

    <dt class="label"><a name="R7"></a>[XML Schema Part 1] </dt><dd>
        <a href="http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/"><cite>
	XML Schema Part 1: 
	Structures Second Edition</cite></a>, David Beech, Murray Maloney, 
	Henry S. Thompson, and Noah Mendelsohn, Editors. 
	World Wide Web Consortium, 28 October 2004. 
	This version is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/
	The <a href="http://www.w3.org/TR/xmlschema-1/">latest version</a> is
	available at http://www.w3.org/TR/xmlschema-1/.</dd>

    <dt class="label"><a name="R8"></a>[XML Schema Part 2] </dt><dd>
	<a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/"><cite>
	XML Schema Part 2:
	Datatypes Second Edition</cite></a>, 
	Ashok Malhotra and Paul V. Biron, Editors. 
	World Wide Web Consortium, 28 October 2004. 
	This version is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. 
	The <a href="http://www.w3.org/TR/xmlschema-2/">latest version</a> is
	available at http://www.w3.org/TR/xmlschema-2/.</dd>

   <dt class="label"><a name="xml11"></a>[XML 1.1] </dt><dd>
      <a href="http://www.w3.org/TR/2006/REC-xml11-20060816"><cite>
	Extensible Markup Language (XML) 1.1 (Second Edition)</cite></a>, 
	Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 
        François Yergeau, John Cowan, Editors.
	World Wide Web Consortium, 16 August 2006, edited in place 29 September 2006.
	This version is http://www.w3.org/TR/2006/REC-xml11-20060816.
	The <a href="http://www.w3.org/TR/xml11/">latest version</a> is 
	available at http://www.w3.org/TR/xml11/.</dd>

    <dt class="label"><a name="R9"></a>[SMTP] </dt><dd>
	SMTP is defined in a series of RFCs:
      <dl>
	<dt class="label"><a name="RFC2822"></a>[RFC 2822] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2822.txt"><cite>
	Internet Message Format</cite></a>
	P. Resnick, Editor.
	IETF, April 2001.
	This RFC is available at http://www.ietf.org/rfc/rfc2822.txt.</dd>

        <dt class="label"><a name="L3410"></a>[RFC 2045] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2045.txt"><cite>
	Multipurpose Internet Mail Extensions (MIME) Part One:
        Format of Internet Message Bodies
	</cite></a>, N. Freed, N. Borenstein, Editors.
	IETF, November 1996. 
	This RFC is available at http://www.ietf.org/rfc/rfc2045.txt.</dd>

        <dt class="label"><a name="RFC2046"></a>[RFC 2046] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2046.txt"><cite>
	Multipurpose Internet Mail Extensions (MIME) Part Two:
        Media Types
	</cite></a>, N. Freed, N. Borenstein, Editors.
	IETF, November 1996. 
	This RFC is available at http://www.ietf.org/rfc/rfc2046.txt.</dd>

        <dt class="label"><a name="RFC1894"></a>[RFC 1894] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc1894.txt"><cite>
	An Extensible Message Format for Delivery Status Notifications
	</cite></a>, K. Moore, G. Vaudreuil, Editors.
	IETF, January 1996. 
	This RFC is available at http://www.ietf.org/rfc/rfc1894.txt.</dd>

        <dt class="label"><a name="RFC2852"></a>[RFC 2852] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2852.txt"><cite>
	Deliver By SMTP Service Extension
	</cite></a>, D. Newman, Editor.
	IETF, June 2000.
	This RFC is available at http://www.ietf.org/rfc/rfc2852.txt.</dd>

        <dt class="label"><a name="RFC2298"></a>[RFC 2298] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2298.txt"><cite>
	An Extensible Message Format for Message Disposition Notifications
	</cite></a>, R. Fajman, Editor.
	IETF, March 1998. 
	This RFC is available at http://www.ietf.org/rfc/rfc2298.txt.</dd>
      </dl>
   </dd>

   <dt class="label"><a name="L4867"></a>[RDF Primer] </dt><dd>
	<a href="http://www.w3.org/TR/2004/REC-rdf-primer-20040210/"><cite>RDF
	Primer</cite></a>, Frank Manola and Eric Miller, Editors. 
	World Wide Web Consortium, 10 February 2004.
	This version is http://www.w3.org/TR/2004/REC-rdf-primer-20040210/. 
	The <a href="http://www.w3.org/TR/rdf-primer/">latest version</a> is 
	available at http://www.w3.org/TR/rdf-primer/.</dd>

    <dt class="label"><a name="R11"></a>[SOAP 1.1] </dt><dd>
        <a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/"><cite>Simple 
	Object Access Protocol (SOAP) 1.1</cite></a>, 
	Don Box	, David Ehnebuske, Gopal Kakivaya, Andrew Layman, 
	Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer.
	DevelopMentor, Microsoft, IBM, UserLand Software, Inc., 
	Lotus Development Corp., 
	8 May 2000.
	This Note is available at 
	http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.</dd>

    <dt class="label"><a name="R12"></a>[XML InfoSet] </dt><dd>
	<a href="http://www.w3.org/TR/2004/REC-xml-infoset-20040204"><cite>XML
	Information Set (Second Edition)</cite></a>, Richard Tobin and 
	John Cowan, Editors. 
	World Wide Web Consortium, 04 February 2004. 
	This version is http://www.w3.org/TR/2004/REC-xml-infoset-20040204. 
	The <a href="http://www.w3.org/TR/xml-infoset">latest version</a> is
	available at http://www.w3.org/TR/xml-infoset.</dd>

    <dt class="label"><a name="r13"></a>[RFC 3902] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc3902.txt"><cite>
	The "application/soap+xml" media type</cite></a>, M. Baker, 
	M. Nottingham, Editors.
	IETF, September 2004.
	This RFC is available at http://www.ietf.org/rfc/rfc3902.txt.</dd>


   <dt class="label"><a name="L3215"></a>[SOAP Email Binding] </dt><dd>
      <a href="http://www.w3.org/TR/2002/NOTE-soap12-email-20020703"><cite>
	SOAP Version 1.2 Email Binding</cite></a>, 
	Highland Mary Mountain, Jacek Kopecky, Stuart Williams, 
	<em>et. al.</em>, Editors. 
	World Wide Web Consortium, 03 July 2002.
	This version is http://www.w3.org/TR/2002/NOTE-soap12-email-20020703.
	The <a href="http://www.w3.org/TR/soap12-email">latest version</a>
	is available at http://www.w3.org/TR/soap12-email.</dd>

   <dt class="label"><a name="L2778"></a>[XML Base] </dt><dd>
      <a href="http://www.w3.org/TR/2001/REC-xmlbase-20010627/"><cite>XML 
	Base</cite></a>, 
	Jonathan Marsh, Editor. 
   	World Wide Web Consortium, 27 June 2001. 
	This version is http://www.w3.org/TR/2001/REC-xmlbase-20010627/. 
	The <a href="http://www.w3.org/TR/xmlbase/">latest version</a> is 
	available at http://www.w3.org/TR/xmlbase/.</dd>

    <dt class="label"><a name="L15789"></a>[RFC 2119] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for 
	use in RFCs to Indicate Requirement Levels</cite></a>, S. Bradner, 
	Editor.
	IETF, March 1997.
	This RFC is available at http://www.ietf.org/rfc/rfc2119.txt.</dd>

    <dt class="label"><a name="L3362"></a>[RFC 2387] </dt><dd>
	<a href="http://www.ietf.org/rfc/rfc2387.txt"><cite>The MIME 
	Multipart/Related Content-type</cite></a>, E. Levinson, 
	Editor.
	IETF, August 1998. 
	This RFC is available at http://www.ietf.org/rfc/rfc2387.txt.</dd>


   <dt class="label"><a name="L3777"></a>[XOP] </dt><dd>
        <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/"><cite>XML-binary Optimized 
	Packaging</cite></a>, Mark Nottingham, Noah Mendelsohn, Martin Gudgin,
	and Hervé Ruellan, Editors. 
	World Wide Web Consortium, 
	25 January 2005. 
	This version is http://www.w3.org/TR/2005/REC-xop10-20050125/. 
	The <a href="http://www.w3.org/TR/xop10/">latest version</a> is 
	available at http://www.w3.org/TR/xop10/.</dd>

    <dt class="label"><a name="L4299"></a>[ResRep] </dt><dd>
	<a href="http://www.w3.org/TR/2005/REC-soap12-rep-20050125/"><cite>Resource 
	Representation SOAP Header Block</cite></a>, Martin Gudgin, 
	Yves Lafon, and Anish Karmarkar, Editors. 
	World Wide Web Consortium, 
	25 January 2005. 
	This version is http://www.w3.org/TR/2005/REC-soap12-rep-20050125/. 
	The <a href="http://www.w3.org/TR/soap12-rep/">latest version</a> is
	available at http://www.w3.org/TR/soap12-rep/.</dd>

    <dt class="label"><a name="L3991"></a>[MediaTypes] </dt><dd>
	<a href="http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/"><cite>Assigning Media Types to 
        Binary Data in XML</cite></a>, Anish Karmarkar, 
        Ümit Yalçinalp, Editors.
	World Wide Web Consortium, 04 May 2005.
	This version is http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/. 
	The <a href="http://www.w3.org/TR/xml-media-types">latest version</a>
	is available at http://www.w3.org/TR/xml-media-types.</dd>

</dl>

</div>
</div>

<div class="back">

<div class="div1">

<h2><a name="L10313"></a>A. Acknowledgements (Non-Normative)</h2>

<p>Highland Mary Mountain provided the initial material for the section on
the SMTP binding. Paul Denning provided material for a usage scenario, which
has since been moved to the SOAP Version 1.2 Usage Scenarios Working Draft.
Stuart Williams, Oisin Hurley, Chris Ferris, Lynne Thompson, John Ibbotson,
Marc Hadley, Yin-Leng Husband and Jean-Jacques Moreau provided detailed
comments on earlier versions of this document, as did many others during the
Last Call Working Draft review. Jacek Kopecky provided a list of RPC and SOAP
encoding changes.</p>

<p>Martin Gudgin reviewed the additional material in the second edition and
provided many helpful comments.</p>

<p>This document is the work of the W3C XML Protocol Working Group.</p>

      <p>Participants in the Working Group are (at the time of writing, and by
      alphabetical order): Glen Daniels (Sonic Software, formerly of Macromedia),
Vikas Deolaliker (Sonoa Systems, Inc.),
Chris Ferris (IBM, formerly of Sun Microsystems),
Marc Hadley (Sun Microsystems),
David Hull (TIBCO Software, Inc.),
Anish Karmarkar (Oracle),
Yves Lafon (W3C),
Jonathan Marsh (WSO2),
Jeff Mischkinsky (Oracle),
Eric Newcomer (IONA Technologies),
David Orchard (BEA Systems, formerly of Jamcracker),
Seumas Soltysik (IONA Technologies),
Davanum Srinivas (WSO2),
Pete Wenzel (Sun Microsystems, formerly of SeeBeyond).
</p>

      <p>Previous participants were: Yasser alSafadi (Philips Research),
Bill Anderson (Xerox),
Vidur Apparao (Netscape),
Camilo Arbelaez (webMethods),
Mark Baker (Idokorro Mobile, Inc., formerly of Sun Microsystems),
Philippe Bedu (EDF (Electricite De France)),
Olivier Boudeville (EDF (Electricite De France)),
Carine Bournez (W3C),
Don Box (Microsoft Corporation, formerly of DevelopMentor),
Tom Breuel (Xerox),
Dick Brooks (Group 8760),
Winston Bumpus (Novell, Inc.),
David Burdett (Commerce One),
Charles Campbell (Informix Software),
Alex Ceponkus (Bowstreet),
Michael Champion (Software AG),
David Chappell (Sonic Software),
Miles Chaston (Epicentric),
David Clay (Oracle),
David Cleary (Progress Software),
Dave Cleary (webMethods),
Ugo Corda (Xerox),
Paul Cotton (Microsoft Corporation),
Fransisco Cubera (IBM),
Jim d'Augustine (Excelon Corporation),
Ron Daniel (Interwoven),
Doug Davis (IBM),
Ray Denenberg (Library of Congress),
Paul Denning (MITRE Corporation),
Frank DeRose (TIBCO Software, Inc.),
Mike Dierken (DataChannel),
Andrew Eisenberg (Progress Software),
Brian Eisenberg (DataChannel),
Colleen Evans (Sonic Software),
John Evdemon (XMLSolutions),
David Ezell (Hewlett Packard),
James Falek (TIBCO Software, Inc.),
David Fallside (IBM),
Eric Fedok (Active Data Exchange),
Daniela Florescu (Propel),
Dan Frantz (BEA Systems),
Michael Freeman (Engenia Software),
Dietmar Gaertner (Software AG),
Scott Golubock (Epicentric),
Tony Graham (Sun Microsystems),
Mike Greenberg (IONA Technologies),
Rich Greenfield (Library of Congress),
Martin Gudgin (Microsoft Corporation, formerly of DevelopMentor),
Hugo Haas (W3C),
Mark Hale (Interwoven),
Randy Hall (Intel),
Bjoern Heckel (Epicentric),
Frederick Hirsch (Zolera Systems),
Gerd Hoelzing (SAP AG),
Erin Hoffmann (Tradia Inc.),
Steve Hole (MessagingDirect Ltd.),
Mary Holstege (Calico Commerce),
Jim Hughes (Fujitsu Limited),
Oisin Hurley (IONA Technologies),
Yin-Leng Husband (Hewlett Packard, formerly of Compaq),
John Ibbotson (IBM),
Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.),
Scott Isaacson (Novell, Inc.),
Kazunori Iwasa (Fujitsu Limited),
Murali Janakiraman (Rogue Wave),
Mario Jeckle (DaimlerChrysler Research and Technology),
Eric Jenkins (Engenia Software),
Mark Jones (AT&amp;T),
Jay Kasi (Commerce One),
Jeffrey Kay (Engenia Software),
Suresh Kodichath (IONA Technologies),
Richard Koo (Vitria Technology Inc.),
Jacek Kopecky (Systinet),
Alan Kropp (Epicentric),
Julian Kumar (Epicentric),
Peter Lecuyer (Progress Software),
Tony Lee (Vitria Technology Inc.),
Michah Lerner (AT&amp;T),
Bob Lojek (Intalio Inc.),
Henry Lowe (OMG),
Brad Lund (Intel),
Matthew MacKenzie (XMLGlobal Technologies),
Michael Mahan (Nokia),
Murray Maloney (Commerce One),
Richard Martin (Active Data Exchange),
Noah Mendelsohn (IBM, formerly of Lotus Development),
Alex Milowski (Lexica),
Kevin Mitchell (XMLSolutions),
Nilo Mitra (Ericsson),
Ed Mooney (Sun Microsystems),
Jean-Jacques Moreau (Canon),
Dean Moses (Epicentric),
Highland Mary Mountain (Intel),
Don Mullen (TIBCO Software, Inc.),
Rekha Nagarajan (Calico Commerce),
Raj Nair (Cisco Systems),
Masahiko Narita (Fujitsu Limited),
Mark Needleman (Data Research Associates),
Art Nevarez (Novell, Inc.),
Henrik Nielsen (Microsoft Corporation),
Mark Nottingham (BEA Systems, formerly of Akamai Technologies),
Conleth O'Connell (Vignette),
Kevin Perkins (Compaq),
Doug Purdy (Microsoft Corporation),
Jags Ramnaryan (BEA Systems),
Andreas Riegg (DaimlerChrysler Research and Technology),
Vilhelm Rosenqvist (NCR),
Herve Ruellan (Canon),
Marwan Sabbouh (MITRE Corporation),
Waqar Sadiq (Vitria Technology Inc.),
Rich Salz (Zolera Systems),
Krishna Sankar (Cisco Systems),
Jeff Schlimmer (Microsoft Corporation),
George Scott (Tradia Inc.),
Shane Sesta (Active Data Exchange),
Lew Shannon (NCR),
John-Paul Sicotte (MessagingDirect Ltd.),
Miroslav Simek (Systinet),
Simeon Simeonov (Macromedia),
Aaron Skonnard (DevelopMentor),
Nick Smilonich (Unisys),
Soumitro Tagore (Informix Software),
James Tauber (Bowstreet),
Anne Thomas Manes (Sun Microsystems),
Lynne Thompson (Unisys),
Patrick Thompson (Rogue Wave),
Jim Trezzo (Oracle),
Asir Vedamuthu (webMethods),
Mike Vernal (Microsoft Corporation),
Randy Waldrop (WebMethods),
Fred Waskiewicz (OMG),
David Webber (XMLGlobal Technologies),
Ray Whitmer (Netscape),
Volker Wiechers (SAP AG),
Stuart Williams (Hewlett Packard),
Yan Xu (DataChannel),
Amr Yassin (Philips Research),
Susan Yee (Active Data Exchange),
Jin Yu (MartSoft Corp.).
</p>

<p>We also wish to thank all the people who have contributed to discussions
on <a href="mailto:xml-dist-app@w3.org">xml-dist-app@w3.org</a>.</p>

</div>

</div>
</body></html>