/docs/MyDocs

To get this branch, use:
bzr branch http://darksoft.org/webbzr/docs/MyDocs

« back to all changes in this revision

Viewing changes to xml/info/soap.txt

  • Committer: Suren A. Chilingaryan
  • Date: 2009-04-09 03:21:08 UTC
  • Revision ID: csa@dside.dyndns.org-20090409032108-w4edamdh4adrgdu3
import

Show diffs side-by-side

added added

removed removed

Lines of Context:
xml/info/soap.txt
 
1
************************************************************
 
2
*********** SOAP (Simple Object Access Protocol) ***********
 
3
************************************************************
 
4
 SOAP is a minimal protocol for invoking methods on 
 
5
 servers/services/components/objects.
 
6
 �����筮 ��� �ᯮ������ � �離� � WSDL, ����� 
 
7
 ����뢠�� ����㯭� �ࢨ��
 
8
 
 
9
**********************
 
10
******** Soap Messages
 
11
**********************
 
12
 
 
13
���������
 
14
---------
 
15
<SOAP:Envelope                                          
 
16
        xmlns:soap='http://www.w3.org/2001/12/soap-envelope'
 
17
        xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 
18
        xmlns:enc='http://www.w3.org/2001/12/soap-encoding'
 
19
        SOAP:encodingStyle='http://www.w3.org/2001/12/soap-encoding'>
 
20
        ... Other code ...
 
21
</SOAP:Envelope>
 
22
 
 
23
        encodingStyle   - XSD Schema (����뢠��� �⠭����� �ணࠬ��⪨� 
 
24
                        ⨯� ⠪��, ��� array, class � �� ⠪��)
 
25
                        �. Encoding
 
26
 
 
27
Headers
 
28
-------
 
29
<SOAP:Header>
 
30
  ... Some XML code here ... 
 
31
</SOAP:Header>  
 
32
 
 
33
 The header section is used to encapsulate data that is not tied to a specific 
 
34
 method itself, but instead provides context knowledge, such as a transaction 
 
35
 ID and security information. For example:
 
36
 
 
37
        <From>           
 
38
                cdix@soapworkshop.com
 
39
        </From>
 
40
 
 
41
 
 
42
        soap:mustUnderstand
 
43
        --------------------
 
44
        <SOAP:Header mustUnerstand="1">
 
45
        ...
 
46
        </SOAP:Header>
 
47
 
 
48
         If a SOAP server receives a message that includes a header element 
 
49
         with a mustUnderstand value of "1", and it is not expecting it, then 
 
50
         in order to comply with the SOAP protocol it should return a SOAP 
 
51
         Fault with a SOAP faultcode of "MustUnderstand".
 
52
        
 
53
        soap:actor
 
54
        ----------
 
55
        <SOAP:Header actor="URI">
 
56
 
 
57
         Defines the URI for which the header elements are intended
 
58
 
 
59
Body
 
60
----
 
61
<SOAP:Body>
 
62
  ... Some XML code here ....
 
63
</SOAP:Body>
 
64
 
 
65
 ��易⥫쭮 ������ ������⢮���� � SOAP ᮮ�饭��, ���筮 ᮤ�ন� �������
 
66
 �ࢥ�� � ��ࠬ����, ���ਬ��:
 
67
        <DoCreditCheck>
 
68
                <ssn>123-456-7890</ssn>
 
69
        </DoCreditCheck>
 
70
 
 
71
Error Response
 
72
--------------
 
73
 <SOAP:Fault>
 
74
        <SOAP:Fault>
 
75
        <faultcode>...</faultcode>
 
76
        <faultstring>...</faultstring>
 
77
        <faultactor>...</faultactor>
 
78
        <detail>...</detail>
 
79
        </SOAP:Fault>
 
80
 </SOAP:Fault>
 
81
 
 
82
 The SOAP protocol includes a way for the invoked method to return an error
 
83
 message to the requestor. 
 
84
 faultcode:     generic.refiner 
 
85
                        generic - is a generic fault message
 
86
                                VersionMistmatch
 
87
                                MustUnderstand
 
88
                                Client
 
89
                                Server
 
90
                        refiner - more details
 
91
                ���ਬ��: Client.authentication
 
92
 faultstring:   Human readable indication of error cause
 
93
 faultactor:    Indicates who, or what process, was attempting to run when
 
94
                the fault occured
 
95
 detail:        If present, contains application-specific error information
 
96
 
 
97
 ����� ���� � ��㣨� ⠣�, �� �।����⥫쭮 ��� �������⥫��� ���ଠ��
 
98
 ������� � ⥣ <detail>.
 
99
 
 
100
 
 
101
soap:href, soap:id
 
102
------------------
 
103
<SomeElement soap:href='#id1'/>
 
104
....
 
105
<OtherElement soap:id='#id1'> ... some content ... </OtherElement>
 
106
 
 
107
 
 
108
SOAP over HTTP
 
109
--------------
 
110
 SOAP is RPC over HTTP protocol
 
111
 
 
112
 Sample request:
 
113
        POST <server page> HTTP /1.1
 
114
        Content-Type: text/xml
 
115
        SOAPAction: "my-name-space#my-method-name"
 
116
        SOAP Message
 
117
 Sample response:
 
118
        MessageType: CallResponse
 
119
        Content-Type: text/xml
 
120
        SOAP Message
 
121
 
 
122
 There will need to be some form of SOAP server that either acts upon, or acts
 
123
 as routing agent for the SOAP messages. The is the URI end point of the POSTED
 
124
 HTTP request.
 
125
 
 
126
*************
 
127
**** Encoding
 
128
*************
 
129
 The aspects of SOAP described so far are sufficient to build very
 
130
 sophisticated message based systems. A server specifies the XML it expects
 
131
 in the body and/or header of a request message and the XML it will return in
 
132
 the body and/or header of the response message. Clients are coded to provide
 
133
 and consume the XML as specified by the server. Nothing more is needed.
 
134
 
 
135
 However, one of the stated goals of SOAP is to act as an RPC transport
 
136
 mechanism. In general, RPC requires that the input parameters to a method
 
137
 called on the client be encoded, passed across the network, decoded, and the
 
138
 method invoked on the server. Output parameters and the return value are
 
139
 then encoded, passed across the network, decoded and returned to the client
 
140
 application. When SOAP is used as the transport, both the client and server
 
141
 must agree on how a parameter of a given type will be encoded in the
 
142
 SOAP:Body element.
 
143
 
 
144
 SOAP allows a client to indicate the encoding style used for a message using
 
145
 the SOAP:encodingStyle attribute. The value of this attribute is an URI
 
146
 which acts as the unique name of an encoding style. The server must
 
147
 recognize URI and act to decode the data in accordance to that style. SOAP
 
148
 defines a standard encoding style. Other styles can be defined and agreed
 
149
 upon by client and server implementers, but the standard encoding style is
 
150
 sufficient for most applications.
 
151
 
 
152
 Note that using the SOAP encoding style does not require that the client or
 
153
 server side actually be implemented using RPC. A client application could
 
154
 directly generate messages that conform to the encoding style expected by
 
155
 the server and/or the server can be coded to process the messages directly.
 
156
 
 
157
 The standard SOAP encoding style defines how simple data types such as
 
158
 strings, integers, dates, etc., and complex data types such as arrays and
 
159
 structures, should be encoded. The basic rules are fairly simple: values are
 
160
 encoded as the content of elements (as opposed to attributes) and the data
 
161
 type of a given value must be specified either in the message itself or in a
 
162
 schema associated with the message. In either case, data types are described
 
163
 as specified in the XML Schema standard.
 
164
 
 
165
 For example a request with all type information contained in the message
 
166
 could be:
 
167
 
 
168
        POST /ItemService HTTP/1.1
 
169
        Host: hhhh
 
170
        Content-Type: text/xml; charset="utf-8"
 
171
        Content-Length: nnnn
 
172
        SOAPAction:
 
173
 
 
174
        <SOAP-ENV:Envelope
 
175
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 
176
          xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 
177
          xmlns:xsd="http://www.w3.org/1999/XMLSchema/"
 
178
          xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance/"
 
179
          SOAP-ENV:EncodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 
180
          <SOAP-ENV:Body>
 
181
            <is:getChildren xmlns:is="http://schemas.pge.com/ItemService">
 
182
              <path xsi:type="xsd:string">a</path>
 
183
            </is:getChildren>
 
184
          </SOAP-ENV:Body>
 
185
        </SOAP-ENV:Envelope>
 
186
 
 
187
 And the response which returns an array (the Items element) of structures
 
188
 (the Item elements) could be:
 
189
 
 
190
        HTTP/1.1 200 OK
 
191
        Content-Type: text/xml; charset="uft-8"
 
192
        Content-Length: nnnn
 
193
 
 
194
        <SOAP-ENV:Envelope
 
195
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 
196
          xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 
197
          xmlns:xsd="http://www.w3.org/1999/XMLSchema"
 
198
          xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance"
 
199
          SOAP-ENV:EncodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 
200
          <SOAP-ENV:Body>
 
201
            <is:getChildrenResponse xmlns:is="http://schemas.pge.com/ItemService">
 
202
              <items xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="is:Item[]">
 
203
                <item>
 
204
                 <name xsi:type="xsd:string">e</name>
 
205
                 <value xsi:type="xsd:integer">1</value>
 
206
                </item>
 
207
                <item>
 
208
                 <name xsi:type="xsd:string">f</name>
 
209
                 <value xsi:type="xsd:integer">2</value>
 
210
                </item>
 
211
                <item>
 
212
                 <name xsi:type="xsd:string">g</name>
 
213
                 <value xsi:type="xsd:integer">3</value>
 
214
                </item>
 
215
              </items>
 
216
            </is:getChildrenResponse>
 
217
          </SOAP-ENV:Body>
 
218
        </SOAP-ENV:Envelope>
 
219
 
 
220
 Another examples:
 
221
        <Element xsi:type="enc:base64"> base64 encoded string </Element>
 
222
 
 
223
        <Element enc:arrayType="xs:int[2]">
 
224
                <number>3</number>
 
225
                <number>4</number>
 
226
        </Element>
 
227
 
 
228
        <Element xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
 
229
                        enc:arrayType="xs:string[6]"
 
230
                        enc:offset="[3]" >
 
231
                <item>The fourth element</item>
 
232
                <item>The fifth element</item>
 
233
        </Element>
 
234
 
 
235
*****************
 
236
***** C Interface
 
237
*****************