-----------------------
WS-I Testing Tools V1.1
-----------------------

This package contains the final release of the Java implementation of the WS-I testing tools for the Basic Profile V1.0., Basic Profile V1.1 and Simple Soap Binding Profile v1.0.  

NOTE: This release can be used to make statements about WS-I conformance.

Copyright (c) 2002-2004 by The Web Services-Interoperability Organization (WS-I) and 
Certain of its Members. All Rights Reserved.

--------
Contents
--------

  1. Notice
  2. WS-I License Information
  3. Acknowledgements and Other Copyrights
  4. Information to Include When Reporting a Problem
  5. Known Problems
  6. How To Provide Feedback
  7. Using the Java Tools
     6.1 Sample Files
     6.2 Monitor
     6.3 Analyzer 
     6.4 Proxies

---------
1. Notice
---------

The material contained herein is not a license, either expressly or impliedly, to any 
intellectual property owned or controlled by any of the authors or developers of this 
material or WS-I. The material contained herein is provided on an "AS IS" basis and to 
the maximum extent permitted by applicable law, this material is provided AS IS AND WITH 
ALL FAULTS, and the authors and developers of this material and WS-I hereby disclaim all 
other warranties and conditions, either express, implied or statutory, including, but not 
limited to, any (if any) implied warranties, duties or conditions of  merchantability, 
of fitness for a particular purpose, of accuracy or completeness of responses, of results, 
of workmanlike effort, of lack of viruses, and of lack of negligence. ALSO, THERE IS NO 
WARRANTY OR CONDITION OF TITLE, QUIET ENJOYMENT, QUIET POSSESSION, CORRESPONDENCE TO 
DESCRIPTION OR NON-INFRINGEMENT WITH REGARD TO THIS MATERIAL.

IN NO EVENT WILL ANY AUTHOR OR DEVELOPER OF THIS MATERIAL OR WS-I BE LIABLE TO ANY OTHER 
PARTY FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, 
LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT, INDIRECT, OR SPECIAL DAMAGES 
WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF THIS OR 
ANY OTHER AGREEMENT RELATING TO THIS MATERIAL, WHETHER OR NOT SUCH PARTY HAD ADVANCE 
NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.


---------------------------
2. WS-I License Information
---------------------------

Use of this WS-I Material is governed by the WS-I Test License at 
http://ws-i.org/docs/license/test_license.htm. By downloading these files, 
you agree to the terms of this license.
 

----------------------------------------
3. Acknowledgements and Other Copyrights
----------------------------------------

1. This product includes software developed by the Eclipse Foundation 
   (http://www.eclipse.org/).

2. This product also includes software developed by the Apache Software Foundation 
   (http://www.apache.org/).

3. Copyright (c) 2003-2004, International Business Machines Corporation and others. All Rights Reserved.

4. Licenses for software included in this package is located in the java/licenses
   directory.


-------------------------------------------------
4 Information to Include When Reporting a Problem
-------------------------------------------------

Refer to the "How To Provide Feedback" section of the README.txt file in the base 
directory when reporting a problem with either the monitor or analyzer.  Also, please 
include a complete description of the problem as well as the following information.

Monitor:
1. Monitor version and release date (this information is displayed on the console
   when the monitor is executed)
2. Monitor config file.
3. Run the monitor using the -verbose option, and then include a copy of the console 
   messages.
4. Message log file created by the monitor.

Analyzer:
1. Analyzer version and release date (this information is displayed on the console
   when the analyzer is executed)
2. Analyzer config file.
3. Run the analyzer using the -verbose option, and then include a copy of the console 
   messages.
4. Message log file (if it was specified in the analyzer config file).
5. WSDL document (if it was specified in the analyzer config file).
6. Conformance report created by the analyzer.


---------------------------------
5. Known Problems and Limitations
---------------------------------

1. When analyzing a message without a corresponding wsdl description, the Java analyzer will always 
   return a notApplicable result for BP1204. The reason being is that it uses the description to 
   implement the assertion.

2. There are certain situations when the analyzer will display a message that starts with "[Fatal Error]".
   This message is displayed by the XML parser and is not an indication that there is a problem with 
   the analyzer.

3. The Java implementation of Assertion BP1600 does not check for  multiple Body elements within a SOAP 
   message. However the existence of multiple Body elements is caught by Assertion BP1701.

4. The Java implementation of Assertion BP1212 only checks that the envelope contains a  part accessor 
   element for each of the wsdl:part elements bound to the envelope's corresponding soapbind:body element. 
   It does not check the inverse. As such the Java test tools will return a passed result if there are
   extra part accessor elements that do not correspond to any wsdl:part elements. However extra part 
   accessor elements do cause Assertion BP1755 to fail.

5. The Java test tools return a failed result for SSBP1003 if there is a message that does not have a 
   corresponding HTTP Content-Type header. The C# tools return a notApplicable result.

6. For Assertion BP1701, the Java tool validates the message content against soapEnvelope.xsd. The C# tool
   does full validation.  If the SOAP-ENV:encodingStyle attribute is set to an invalid value, say "foo",
   the Java tool returns a passed result while the C# tool returns a failed result. Note however that an
   invalid value is caught by Assertion BP1701.

7. For Assertion BP5100, the Java tool checks that the content message is a valid xml fragment with the 
   Envelope element as the root element. The C# tool does full validation. If the SOAP-ENV namespace is 
   not the standard namespace,  the Java tool returns a passed result while the C# tool returns a failed 
   result. Note however that an non-standard namespace is caught by Assertion BP1201. 

8. For Assertion BP1013, the Java tool checks that the body contains a wrapper element matches the 
   operation name in the case of a rpc-lit binding. In case of a doc-lit binding, it checks that the child
   element of soap:body is an instance of the global element declaration referenced by the corresponding 
   wsdl:part. Finally if the message has "parts", it checks that the  order of the part elements in the 
   soap:body of the envelope, is the same as that of the wsdl:partS, in the corresponding wsdl:message. 
   Besides the above checks, the C# tool does full validation.   If the child elements are not qualified 
   with the correct namespace,  the Java tool returns a passed result while the C# tool returns a failed 
   result. Note however that an incorrect namespace is caught by Assertion BP1008. 

9. For Assertion BP1011, the C# tool does full validation. If the child elements are not qualified with 
   the correct namespace,  the Java tool returns a passed result while the C# tool returns a failed result.
   Note however that an incorrect namespace is caught by Assertion BP1008. 

10. The C# tool always uses the request message to match the WSDL binding/operation. The Java tool uses the
    message in hand to match the WSDL binding/operation. As a result, the C# and Java tools may return 
    different  results for Assertions BP1212, BP1755 and BP1214. For example, for an invalid response 
    message, the Java tool may return a notApplicable result because it could not match the response 
    message, while the C# tool returns a failed result because it was able to match the corresponding 
    request message.

11. Currently BP2724 is catagorized as "notTestable". In fact it can be tested. If a request is inconsistent
    with the description of that request in the WSDL, we could flag returning a non-error response. We 
    currently do not check the status of a request when we are processing the response.

12. The Xerces parser in the Java tool throws an exception if it encounters an empty schema element in a WSDL
    declared as <schema/>. This results in a failed BP2122 assertion. The parser does accept the alternative, 
    <schema></schema>.

13. The Xerces parser in the Java tool throws an exception if it encounters multiple inline schemas with the
    same namespace. The workaround is not to validate a document-literal message against the inline schemas 
    when the tools detect such a situation. As such the Java test tools will return a passed result for
    BP1011 whithout schema validating if there are multiple inline schemas with the same namespace and the 
    message format is document literal.
   
--------------------------
6. How To Provide Feedback
--------------------------

The Web Services-Interoperability Organization (WS-I) would like to receive input, 
suggestions and other feedback ("Feedback") on this work from a wide variety of 
industry participants to improve its quality over time. 

By sending email, or otherwise communicating with WS-I, you (on behalf of yourself if 
you are an individual, and your company if you are providing Feedback on behalf of the 
company) will be deemed to have granted to WS-I, the members of WS-I, and other parties 
that have access to your Feedback, a non-exclusive, non-transferable, worldwide, perpetual, 
irrevocable, royalty-free license to use, disclose, copy, license, modify, sublicense or 
otherwise distribute and exploit in any manner whatsoever the Feedback you provide regarding 
the work. You acknowledge that you have no expectation of confidentiality with respect to 
any Feedback you provide. You represent and warrant that you have rights to provide this 
Feedback, and if you are providing Feedback on behalf of a company, you represent and warrant 
that you have the rights to provide Feedback on behalf of your company. You also acknowledge 
that WS-I is not required to review, discuss, use, consider or in any way incorporate your 
Feedback into future versions of its work. If WS-I does incorporate some or all of your 
Feedback in a future version of the work, it may, but is not obligated to include your name 
(or, if you are identified as acting on behalf of your company, the name of your company) on 
a list of contributors to the work. If the foregoing is not acceptable to you and any company 
on whose behalf you are acting, please do not provide any Feedback.

WS-I members should direct feedback on this document to wsi_testing@lists.ws-i.org; non-members 
should direct feedback to wsi-tools@ws-i.org.

-----------------------
7. Using the Java Tools
-----------------------

Before running any of the tools, you must set the WSI_HOME environment variable to the 
location of the installed files.

  Examples:

    Windows: set WSI_HOME=c:\wsi-test-tools

    Unix: export WSI_HOME=/home/user1/wsi-test-tools

NOTE: Detailed information on how to run the WS-I testing tools can be found in the 
User's Guide which is located in the WSI_HOME\docs directory.


----------------
7.1 Sample Files
----------------

The following files are in the WSI_HOME\java\samples directory.

Filename                            Description
------------------                  ----------------------------------------------------------------
monitorConfig.xml                   Example of a configuration file used by the monitor tool.
analyzerConfig.xml                  Example of a configuration file used by the analyzer tool.  
analyzerConfigUDDI.xml              Analyzer configuration file with UDDI reference.
analyzerConfigServiceLocation.xml   Analyzer configuration file with service location specified.
RetailerService.wsdl                Sample WSDL file for instance of Retailer sample application.
log.xml                             Sample output from the monitor.
report.xml                          Sample output report generated by the analyzer.


-----------
7.2 Monitor
-----------

1. Set the configuration options in the monitor configuration file.  (Refer to the 
   User's Guide for a description of the entries in this file.)

2. To run the message monitor from the WSI_HOME java directory:

   Windows:
    cd %WSI_HOME%\java
	bin\Monitor -config <configFilename>

	Example: bin\Monitor -config samples\monitorConfig.xml

    Unix:
    cd ${WSI_HOME}/java
	bin/Monitor.sh -config <configFilename>

	Example: bin/Monitor.sh -config samples/monitorConfig.xml

      NOTE: The execute permissions may have to be set using the chmod command.


------------
7.3 Analyzer
------------

1. Set the configuration options in the analyzer configuration file. (Refer to the 
   User's Guide for a description of the entries in this file.)


2. To run the analyzer tool from the WSI_HOME java directory:

   Windows:
    cd %WSI_HOME%\java
	bin\Analyzer -config <configFilename>

	Example: bin\Analyzer -config samples\analyzerConfig.xml 

   Unix:
    cd ${WSI_HOME}/java
	bin/Analyzer.sh -config <configFilename>

	Example: bin/Analyzer.sh -config samples/analyzerConfig.xml 

      NOTE: The execute permissions may have to be set using the chmod command.

------------
7.4 Proxies
------------

If an Internet proxy server is required to access external sites over a firewall, 
then configure the appropriate system properties prior to running 
the Java testing tools, as follows:

	Windows:   
	  set WSI_JAVA_OPTS=%WSI_JAVA_OPTS% -Dhttp.proxyHost=<my proxy name> 
	  -Dhttp.proxyPort=<my proxy port> -Dhttp.nonProxyHosts="<local address list>"
	  
	Unix:
	  export WSI_JAVA_OPTS= "${WSI_JAVA_OPTS} -Dhttp.proxyHost=<my proxy name> 
	  -Dhttp.proxyPort=<my proxy port> -Dhttp.nonProxyHosts=\"<local address list>"\"
	
	  
Where:

	<my proxy name> 		is the ip address or domain name of the proxy server;
	<my proxy port> 		is the ip port of the proxy server;
	<local address list> 	is a list of ip addresses or domain names of any 
							local machines requiring proxy server bypass

Example:

		http.proxyHost=proxy.wibble.com
		http.proxyPort=8080
		http.nonProxyHosts="localhost anotherlocal.wibble.com 192.168.0.1"
	
	
