sc002
Notify-Echo
2008/11/03
Published
This scenario is meant to serve several purposes:
-
As the first scenario done by the WSTF, it will test the processes
and infrastructure of the WSTF initiative
-
Test some very basic Web Service operations that can be used to
build a set of regression tests for the WSTF set of scenarios
-
Provide a baseline set of messages/operations that can then be used
in subsequent, more complex, scenarios
This scenario will make use of two operations: Notify and Echo.
Notify will be a one-way operation, while Echo will be a two-way
(request/response) operation. While only support for SOAP (v1.1 and v1.2) will be
required, implementations may also choose to expose WSDL describing their
endpoints. Sample WSDL is included below.
Other operations are defined as part of this scenario but are not necessary
for the tests themselves. They are defined within this document to provide
a full set of common operations that might be needed for future WSTF
scenarios.
The client must know the address of the service endpoint and whether it
supports SOAP 1.1 or SOAP 1.2. How it determines this is out of scope
for the scenario, but the most common mechanism will be through
examination of the list of endpoints provided with the scenario. In
subsequent, more advanced scenarios, it is expected that WSDL and
Policy will play a role in determining this type of information.
In general this scenario involves the client sending a series of
Notify
and Echo messages to the service. The number of messages and
types of messages may vary.
Both Notify and Echo include two parameters,
'ID' and 'text'. The 'ID' parameter
is a unique identifier that groups a series of messages together.
The service is expected to concatenate all of the 'text' values
received for each 'ID' - however, since Notify is a
one-way operation, only Echo will return the value of this concatenation
back to the client.
When using HTTP as the transport, each non-faulting Notify
should return an "HTTP 202 Accept" without any content. Each non-faulting
Echo should return an "HTTP 200 OK" with the
EchoResponse message as its content on the transport
back-channel. In the faulting case, for the Notify operation the client
should not expect to see any response at all - not even for SOAP processing
faults. For the Echo operation an "HTTP 500 Internal
Server Error" should be returned with the SOAP Fault in the content.
The service is expected to maintain the state of the concatenated 'text'
values for each 'ID' for a reasonable amount of time -
e.g. 10 minutes since the last message for any particular 'ID'.
After that time it is free to reclaim any resources associated with that
'ID'.
This scenario defines the following operations:
A one-way operation with the following outline:
http://www.wstf.org/docs/scenarios/sc002/Notify
<sc002:SessionData>
<sc002:ID> TestClient-1 </sc002:ID>
</sc002:SessionData>
<sc002:Notify>
<sc002:text> Hello World <sc002:text>
</sc002:Notify>
Has two pieces of data:
ID:
a string representing a unique identifier used to group
a series of Notify and Echo messages.
text:
a string of the client's choosing.
All calls to Notify and Echo will concatenate the
'text' values for matching IDs.
An empty string or "fault" for the 'text' parameter must
cause the service to generate a fault.
A two-way operation with the following outline:
http://www.wstf.org/docs/scenarios/sc002/Echo
<sc002:SessionData>
<sc002:ID> TestClient-1 </sc002:ID>
</sc002:SessionData>
<sc002:Echo>
<sc002:text> Hello World <sc002:text>
</sc002:Echo>
http://www.wstf.org/docs/scenarios/sc002/EchoResponse
<sc002:EchoResponse>
<sc002:text> Hello World <sc002:text>
</sc002:EchoResponse>
Has two pieces of data:
ID:
a string representing a unique identifier used to group
a series of Notify and Echo messages.
text:
a string of the client's choosing.
All calls to Notify and Echo will concatenate the
'text' values for matching ID's.
An empty string or "fault" for the 'text' parameter must
cause the service to generate a fault.
Note: leading and trailing spaces in the 'text' parameter will
be ignored. While this scenario does not require the use of higher-level
WS specifications (such as WS-Addressing), it is designed such that
additional scenarios can built upon this scenario to add-in, and test,
those more advanced features.
Overall success criteria will be determined as follows:
-
Upon receipt of the
Notify message, the service will
return an HTTP response code indicating the message was delivered.
Due to there being a variety of possible HTTP response codes
the exact value may vary. For example, a value of 200 or 202 is
a clear indication of success. Whether other values indicate
success or not will depend on the client implementation.
In many cases a value of 404 (Not Found) would be an error that
would be returned back to the application. However, another
implementation, that takes a much more strict view on the
fire-n-forget aspect of one-way messages, may view a 404 as
a success.
-
Upon receipt of the
Echo message, the service will
return a string whose value will be the concatenation of all
Notify and Echo
'text' values that also included the same
'ID'.
-
Upon receipt of a
Notify or Echo message
whose 'text' value is 'fault', or an
empty string, the service will generate a Fault. For
Echo requests, the service will return the SOAP Fault
message in the entity-body of the HTTP response. The details of
this fault message are defined by the wsdl:fault
element named 'InvalidInputFault' in the WSDL for this scenario. Examples of SOAP 1.1 and
SOAP 1.2 Fault responses can be found in the Sample Messages section.
-
Per Basic Profile 1.2 R1127, a service must not rely on the value of
the SOAPAction HTTP header field. So, a service must not generate a fault
due to the lack of this header on a SOAP 1.1
Notify or
Echo message.
-
Per Basic Profile 2.0 R2757, a service must not
require the presence of the 'action' parameter on the Content-Type
HTTP header field. So, a service must not generate a fault
due to the lack of an 'action' parameter on a
SOAP 1.2
Notify or Echo
message.
-
In the Notify case, MustUnderstand and VersionMismatch faults must
be generated but, due to the fire-n-forget nature of one-way messages,
the service is not required to transmit the these faults back to the
client. Therefore, simply returning an HTTP response code of 202
is all that is expected. If the service chooses to return the
MustUnderstand or VersionMismatch faults, that is acceptable as well.
The specific tests for this scenario are broken up into two.
The first set focuses on testing from an end-user's point of view - one
where all they want to do is send a Notify or Echo and are not concerned
with the SOAP aspects of the test. The second set of tests focus on
a low-level testing of SOAP itself. These tests will be more explicit
about the SOAP features being tested, and would typically not be of
concern for an end-user but would be of interest to SOAP stack implementers.
The Notify operation will have two variants in this part of the scenario.
The following table summarizes the tests and the expected results.
Client sends the Notify message
Service responds with an HTTP 202.
See 'Success Criteria' section for other possible responses.
Client sends a faulting Notify message
Service responds with an HTTP 202.
See 'Success Criteria' section for other possible responses.
The Echo operation will have several variants.
The following table summarizes the tests and the expected results.
Client sends the Echo message
Service responds with the appropriate EchoResponse on the
HTTP back-channel
Client sends a faulting Echo message
Service responds with a fault on the HTTP back-channel
The following test will focus on interoperability testing of SOAP from
a lower technical point of view.
Client sends the Notify message with an unknown SOAP Header with
the mustUnderstand flag set to 'true'.
Service responds with an HTTP 202.
See 'Success Criteria' section for other possible responses.
Client sends a faulting Notify message and an unknown SOAP Header
with the mustUnderstand flag set to 'true'
Service responds with an HTTP 202.
See 'Success Criteria' section for other possible responses.
Client sends the Echo message with an unknown SOAP Header with the
mustUnderstand flag set to 'true'
Service responds with a mustUnderstand fault on the HTTP back-channel
Client sends a faulting Echo message and an unknown SOAP Header with
the mustUnderstand flag set to 'true'
Service responds with a mustUnderstand fault on the HTTP back-channel
<soap:Envelope ...>
<soap:Header>
<sc002:SessionData>
<sc002:ID> Client-1 </sc002:ID>
</sc002:SessionData>
</soap:Header>
<soap:Body>
<sc002:Notify>
<sc002:text>Hello</sc002:text>
</sc002:Notify>
</soap:Body>
</soap:Envelope>
202 Accept
<soap:Envelope ...>
<soap:Header>
<sc002:SessionData>
<sc002:ID> Client-1 </sc002:ID>
</sc002:SessionData>
</soap:Header>
<soap:Body>
<sc002:Echo>
<sc002:text>-World</sc002:text>
</sc002:Echo>
</soap:Body>
</soap:Envelope>
200 OK
<soap:Envelope ...>
<soap:Header>
</soap:Header>
<soap:Body>
<sc002:EchoResponse>
<sc002:text>Hello-World</sc002:text>
</sc002:EchoResponse>
</soap:Body>
</soap:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sc002="http://www.wstf.org/docs/scenarios/sc002">
<soap:Header>
<sc002:SessionData>
<sc002:ID> Client-1 </sc002:ID>
</sc002:SessionData>
</soap:Header>
<soap:Body>
<sc002:Echo>
<sc002:text>fault</sc002:text>
</sc002:Echo>
</soap:Body>
</soap:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>invalid input: "fault"</faultstring>
<detail>
<sc002:InvalidInput xmlns:sc002="http://www.wstf.org/docs/scenarios/sc002"/>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:sc002="http://www.wstf.org/docs/scenarios/sc002">
<soap:Header>
<sc002:SessionData>
<sc002:ID> Client-1 </sc002:ID>
</sc002:SessionData>
</soap:Header>
<soap:Body>
<sc002:Echo>
<sc002:text>fault</sc002:text>
</sc002:Echo>
</soap:Body>
</soap:Envelope>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Body>
<soap:Fault>
<soap:Code>
<soap:Value>soap:Receiver</soap:Value>
</soap:Code>
<soap:Reason>
<soap:Text>invalid input: "fault"</soap:Text>
</soap:Reason>
<soap:Detail>
<sc002:InvalidInput xmlns:sc002="http://www.wstf.org/docs/scenarios/sc002"/>
</soap:Detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
This scenario exposed some ambiguity about what is expected when
a fault is generated for one-way operations. The consensus of the
group is that one-way messages should be treated as fire-n-forget
messages. This means that the sending application should not
expect to see any faults.
That being said, it is recommended that a SOAP processor at least
return MustUnderstand and VersionMismatch faults if possible and
regardless of the message exchange pattern being used. This allows
the sender to be aware of such critical errors. However, as stated
in the previous paragraph, the sender should not rely on other
implementations to follow this recommendation.
This scenario includes the use of both SOAP 1.1 and SOAP 1.2; the
WSDL for this scenario defines a service that includes a SOAP 1.1
port and a SOAP 1.1 port. However, it is not clear is whether or
not a service that implements two ports shares state between the
implementations of those ports. For example, if you send a Notify
message for session 'A' to the soap11port will a subsequent Echo
for session 'A', when sent to the soap12port, result in an
EchoResponse that contains the data from the first Notify? This
is considered to be important because of the following use case:
Suppose there is an organization that, for the usual reasons, has
built and deployed a number of services using SOAP 1.1. Further
suppose that this organization has made the strategic decision to
standardize on the use of SOAP 1.2. As part of the migration
strategy there will be a period of time in which all new services
will be required to support both SOAP 1.1 (to support the older
clients) and SOAP 1.2 (to support the newer clients). Clearly it
is important that any service supporting "dual-mode" ports share
any state changes resulting from the messages sent to either
port. It must be possible to implement a "single service" that
can be interacted with using either SOAP 1.1 or SOAP 1.2.
Note that there are no existing WSDL constructs or
WS-Policy-based assertions for indicating whether or not two
ports share state. Some people may feel that, because the two
ports are grouped together under a common service, that shared
state is implied. However, the WSDL 1.1 specification is not
explicit about this behavior, say merely "Each port provides
semantically equivalent behavior". Neither does the Basic Profile
provide any guidance on this subject.
For the purposes of this scenario implementers are free to share
state or not share state between their SOAP 1.1 and SOAP 1.2
ports (assuming they implement both ports). It is recommended
that any descriptions provided by implementers should note
whether or not state is shared. Further extensions of this
scenario may be devised to test the ability of implementations to
share state between two ports.
It was found that certain WSDL to Java tools generated incorrect artifacts
due to the lower case binding names. The lower case names mapped to lower case
classes in Java. Java typically uses upper case class names are standard practice.
In some cases this lower case class names did deploy correctly.
It either is possible to map the lower case binding names to upper case
class names using a custom name file before generating these artifacts, or simply
capitalize the binding names in the WSDL.
Initial Draft
Added WSDL and some additional 'scenario details'
s/groupID/appID/
Added some text about WS-Addressing
Pull out xsd from wsdl
Make sure the namespace and URLs are .../docs/scenarios/sc002...
Moved the appID to a SessionData header
Misc cleanup
Use absolute, instead of relative, path for css/js files
Be more explicit about the various tests people should run.
Add a comment about how mU faults are not required to be returned
for one-ways.
Converted to XML.
Add finding on sharing state between SOAP 1.1 and SOAP 1.2 ports.
Minor typos
Minor tweaks/edits
Minor edits to Success Criteria section.
Clarify expected behavior for application-level faults.
Remove Begin, End, and SendMessages operations as the new test infrastructure has made
them redundant.