WSO2 Web Services Application Server v2.1-RC6
-------------------------------------------

Welcome to the WSO2 WSAS 2.1-RC6 release
WSO2 WSAS is an integrated Web services Platform which offers a complete middleware solution.
It is a lightweight, high performing platform for Service Oriented Architectures, enabling
business logic and applications. Bringing together a number of Apache Web services projects,
WSO2 WSAS provides a secure, transactional and reliable runtime for deploying and
managing Web services.

What is new in WSAS 2.1-RC6
-----------------------

* Data services support
	Allows data in relational databases to be exposed as Web services, and to be
	included in	Web mashups with ease.	
	
* Eclipse IDE integration
	Wizard based flows to automate most steps and make easy the process of
	developing, deploying and debugging Web services.
	
* Clustering support
	Clustering support with state replication for high availability, along with
	load balancing,	failover and cluster-wide management functions. 

* Full support for WS-Security, WS-Trust, WS-Policy and WS-SecureConversation 
  and XKMS.
	Extended security with support for WS-Security, WS-Trust, WS-Policy and 
	WS-SecureConversation with additional means for secure Web-based 
	communications using public key infrastructure (PKI) with XKMS. This release
	of WSO2 WSAS also includes an inbuilt SecurityTokenService as defined in 
	WS-Trust specification.	

* EJB service provider support
	Expose EJBs deployed on a remote J2EE application server (AS) as Web 
	services. 	

* Axis1 backward compatibility 
	Easily deploy any Apache Axis1-based Web service and engage advanced WS-* 
	services, such as WS-RM and WS-Policy in front of legacy Axis1 services.

WSAS Binary Distribution Directory Structure
================================================

	WSO2WSAS_HOME
		|- bin <folder>
		|- conf <folder>
		|- database <folder>
		|- legal <folder>
		|- lib <folder>
		|- logs <folder>
		|- repository <folder>
		|- samples <folder>
		|-- LICENSE <file>
		|-- NOTICE <file>
		|-- README <file>
		|-- release-notes.html <file>
		
    -	bin
		Contains various scripts to start/stop WSAS server, change user 
		password, run tcpmon, java2wsdl, wsdl2java and admin scripts for cluster
		node management.
		
	-	conf
		Contains configuration files, properties files and keystores.
		
	-	database
		This is where the operational database for WSAS and any additional 
		modules will be created.
		
	-	legal
		Contains license documents for all third party libraries included in 
		WSO2 WSAS.
		
	-	lib
		Contains WSAS and third party libraries required for the functioning of 
		WSO2 WSAS.
		
	-	LICENSE
		Apache License 2.0 under which WSO2 WSAS is distributed.
		
	-	logs
		Execution logs will be generated here.
		
	-	NOTICE
		Notice of development.
		
	-	README
		This document.
		
	-	release-notes.html
		Release information for WSO2 WSAS 2.0.
		
	-	repository
		The repository where services and modules deployed in WSO2 WSAS are 
		stored.
		
	-	samples
		Contains some sample applications that demonstrate the functionality and
		capabilities of WSO2 WSAS 2.0.
	
For more information on WSO2 WSAS, visit the "WSO2 Oxygen Tank" at
http://wso2.org/library

Installing WSO2 WSAS on a J2EE Application Server
-------------------------------------------------

    General Installation Steps
    --------------------------

	1. Download and unzip wso2wsas-2.1-RC6.zip
    2. Run install.sh or install.bat from WSO2WSAS_HOME/bin.
	(WSO2WSAS_HOME is the folder where you extracted 
	wso2wsas-2.1-RC6.zip in step 1 above)
    You may select all the default options in the above installation or you
    could customize your installation according to following instructions.

    Advanced Configuration
    ----------------------
    1. Configure your application server as follows:
        i. Register a JNDI datasource with JNDI name jdbc/wso2wsas_db
            Use the following details to configure this datasource;
                a. Database Driver   : org.apache.derby.jdbc.EmbeddedDriver
                b. Database URL      : e.g. jdbc:derby:/home/wso2/.wsas/database/WSO2WSAS_DB
                c. Database Username : wso2wsas
                d. Database Password : wso2wsas

             NOTE: You should provide the correct path to the WSO2 WSAS Database 
             in the Database URL

    2. Copy the following jars to your app server's classpath:
        i. tools.jar from your JDK (Only if your App server does not
           add the tools.jar to its classpath by default. In the case of Mac OS
           copy classes.jar into the app server's classpath.
       ii. WSO2WSAS_HOME/lib/derby-10.1.1.0.jar
      iii. WSO2WSAS_HOME/lib/log4j-1.2.13.jar
            (Only if your App server does not contain a log4j.jar by default)

    3. Enable SSL on your application server.
          If you intend to use the Keystore file shipped with WSO2 WSAS,
       	  you should point your application server to it. The WSO2 WSAS keystore 
          file is WSO2WSAS_HOME/conf/wso2wsas.jks
          If you intend to use your own Keystore file, you need to configure the
          server.xml HTTPS KeyStore Location element.

    4. Copy the following jars to your app server's classpath:
          tools.jar from your JDK
          derby-10.1.1.0.jar
          log4j-1.2.13.jar

    5. Restart the application server.

    6. Now the Management Console should be available on
        https://127.0.0.1:<HTTPS Port>/wso2wsas

    Application Server Specific Installation Instructions
    -----------------------------------------------------
    We support the following Application Servers out of the box with our
    installer. However, if you wish to manually carry out the configuration,
    the following tips will be helpful:

    1. Apache Tomcat
       i. Supported Versions
         a) 5.5.x
            Enabling SSL on Apache Tomcat 5.5.x
            ----------------------------

            The server XML should contain the following segment

            <Connector port="9443" maxHttpHeaderSize="8192"
                       maxThreads="150" minSpareThreads="25"
                       maxSpareThreads="75"
                       enableLookups="false" disableUploadTimeout="true"
                       acceptCount="100" scheme="https" secure="true"
                       clientAuth="false" sslProtocol="TLS"
                       keystoreFile="wso2wsas/conf/wso2wsas.jks"
                       keystorePass="wso2wsas" />

            NOTE: You can use any keystoreFile of your preference instead of
            the wso2wsas.jks which ships with WSO2 WSAS.

            Registering the WSO2 WSAS Data Store
            ------------------------------------

            Include the following segment in the server.xml within the Host
            Element

            <Context path="/wso2wsas" >
                  <Resource name="jdbc/wso2wsas_db"
                            auth="Container"
                            type="javax.sql.DataSource"
                            maxActive="100"
                            maxIdle="30"
                            maxWait="10000"
                            username="wso2wsas"
                            password="wso2wsas"
                            driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
                            url="jdbc:derby:../database/WSO2WSAS_DB;create=true"/>
            </Context>

         b) 5.0.x
            Enabling SSL on Apache Tomcat 5.0.x
            ----------------------------

            The server XML should contain the following segment

            <Connector port="9443"
                   maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                   enableLookups="false" disableUploadTimeout="true"
                   acceptCount="100" debug="0" scheme="https" secure="true"
                   clientAuth="false" sslProtocol="TLS"
                   keystoreFile="wso2wsas/conf/wso2wsas.jks"
                   keystorePass="wso2wsas />

            NOTE: You can use any keystoreFile of your preference instead of
            the wso2wsas.jks which ships with WSO2 WSAS.

            Registering the WSO2 WSAS Data Store
            ------------------------------------

            Include the following segment in the server.xml within the Host
            Element

            <Context path="/wso2wsas" docBase="wso2wsas"
                     reloadable="true" crossContext="true">
              <Resource name="jdbc/wso2wsas_db" auth="Container"
                        type="javax.sql.DataSource"/>
              <ResourceParams name="jdbc/wso2wsas_db">
                <parameter><name>username</name><value>wso2wsas</value></parameter>
                <parameter><name>password</name><value>wso2wsas</value></parameter>
                <parameter><name>driverClassName</name>
                  <value>org.apache.derby.jdbc.EmbeddedDriver</value></parameter>
                <parameter><name>url</name>
                  <value>jdbc:derby:../database/WSO2WSAS_DB;create=true</value>
                  </parameter>
              </ResourceParams>
            </Context>

         c) 4.1.x
            Enabling SSL on Apache Tomcat 4.1.x
            ----------------------------

            The server.xml should contain the following segment

            <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
                       port="9443" minProcessors="5" maxProcessors="75"
                       enableLookups="true"
                       acceptCount="100" debug="0"
                       scheme="https"
                       secure="true"
                       useURIValidationHack="false"
                       disableUploadTimeout="true">

              <Factory className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
                       keystoreFile="wso2wsas/conf/wso2wsas.jks"
                       keystorePass="wso2wsas"
                       clientAuth="false" protocol="TLS" />
            </Connector>

            NOTE: You can use any keystoreFile of your preference instead of
            the wso2wsas.jks which ships with WSO2 WSAS.


            Registering the WSO2 WSAS Data Store
            ------------------------------------

            Include the following segment in the server.xml within the Host
            Element

            <Context path="/wso2wsas" docBase="wso2wsas"
                     reloadable="true" crossContext="true">
              <Resource name="jdbc/wso2wsas_db" auth="Container"
                        type="javax.sql.DataSource"/>
              <ResourceParams name="jdbc/wso2wsas_db">
                <parameter><name>username</name><value>wso2wsas</value></parameter>
                <parameter><name>password</name><value>wso2wsas</value></parameter>
                <parameter><name>driverClassName</name>
                  <value>org.apache.derby.jdbc.EmbeddedDriver</value></parameter>
                <parameter><name>url</name>
                  <value>jdbc:derby:../database/WSO2WSAS_DB;create=true</value>
                  </parameter>
              </ResourceParams>
            </Context>

    2. JBoss
           i.  Supported Versions
               3.2.x, 4.0.x

          ii.  Enabling SSL on JBoss
               Add the following segment to
               JBOSS_HOME/server/default/deploy/bossweb-tomcatxx.sar/server.xml
               as a child of the jboss.web Service element.

               <Connector port="9443" address="${jboss.bind.address}"
               maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
               emptySessionPath="true"
               scheme="https" secure="true" clientAuth="false"
               keystoreFile="${jboss.server.home.dir}/tmp/wso2wsas/conf/wso2wsas.jks"
               keystorePass="wso2wsas" sslProtocol = "TLS" />

                NOTE: You can use any keystoreFile of your preference instead of
                the wso2wsas.jks which ships with WSO2 WSAS.

         iii.  Registering the WSO2 WSAS datasource

               Create wso2wsas-derby-ds.xml file in JBOSS_HOME/server/default/deploy
               with the following text:

                <?xml version="1.0" encoding="UTF-8"?>
                <datasources>
                  <local-tx-datasource>
                    <jndi-name>jdbc/wso2wsas_db</jndi-name>
                    <connection-url>jdbc:derby:../database/WSO2WSAS_DB;create=true</connection-url>
                    <driver-class>org.apache.derby.jdbc.EmbeddedDriver</driver-class>
                    <user-name>wso2wsas</user-name>
                    <password>wso2wsas</password>
                  </local-tx-datasource>
                </datasources>

        *NOTES*:
        1. On jboss-4.0.0 and possibly some other versions, the hibernate2.jar
        and cglib-full-2.0.1.jar should be removed from the lib directories
        since WSO2 WSAS uses the latest hibernate version, which conflicts with
        the older version used by jboss.

        2. On jboss-4.0.0 and possibly some other versions if the 
        jboss-ws4ee.sar is present inside the deploy directory, the admin 
        service will not start due to a conflict in the WSDL API. In this case 
        the jboss-ws4ee.sar needs to be completely removed from the deploy 
        directory.

        3. On jboss-4.0.0 and possibly other versions the ant.jar file included
        inside the jbossweb-tomcat50.sar may cause problems with the code 
        generation. In order to ensure smooth operation replace the ant.jar with
        the ant-1.6.x.jar found in the WSO2 WSAS lib folder which is created 
        after the installation. Also the ant-nodeps-x.x.x.jar needs to be copied
        into the jbossweb-tomcat50.sar.

        4. On jboss-4.0.0 and possibly other versions, the windows installation 
        may cause problems if the WSO2 WSAS home resides in a directory path 
        which has spaces.

        5. On jboss-4.0.1, JBOSS_HOME/server/default/deploy/jboss-hibernate.deployer
        should be removed since some of its hibernate related libraries conflict
        with the latest hibernate libraries used by WSO2 WSAS.

        6. On jboss-3.2.7, JBOSS_HOME/server/default/deploy/jboss-hibernate.sar
        should be removed since some of its hibernate related libraries conflict
        with the latest hibernate libraries used by WSO2 WSAS.

        7. The output from Hibernate is extremely verbose. Add the following 
        segment to your log4j.xml to avoid this output:
           <category name="org.hibernate">
              <priority value="ERROR"/>
           </category>

        8. In MacOSX the classes.jar needs to be copied into the commons/lib dir 
        of Apache Tomcat installation in order to run the generate client and 
        'try it!' features.

    3. Apache Geronimo
        i. Supported versions
          1.1.1

        ii. Creating connectors with Apache Geronimo
          The easiest way to manage the Apache Geronimo server is using the 
          management console. The management console can be accessed from the 
          url http://localhost:8080/console. Default user name is system and 
          password is manager. Web server connectors can be managed by using the
          "Web Server" link found under the "Console Navigation".

        iii. Deploying data sources.
          Data sources can also be created easily with the management console,
          using the "Data pools" link found under the "Console Navigation".
          Deployer tool can also be used to deploy a data source if deploy plan 
          is present. In this case use the following command.
           java -jar bin/deployer.jar --user system --password manager deploy <path to deploy plan> repository/tranql/tranql-connector/1.2/tranql-connector-1.2.rar

        iv. Deploying web applications.
          Deployer tool can be used to deploy web applications. Use the 
          following command.
        	java -jar bin/deployer.jar --user system --password manager deploy <path to web application>

    Post Installation Modifications
    -------------------------------
        This section contains information about modification that can be done
        after WSO2 WSAS has been successfully installed on your App server.

        1. wso2wsas.properties file
            This file is created during installation and can be located at
            wso2wsas/WEB-INF/classes/wso2wsas.properties, in your application
            servers webapp deployment directory.
            The wso2wsas.home and other App server specific properties can be
            changed by modifying this file.
            You may have to re-archive the wso2wsas.war after modifying this file.

        2. Changing the WSO2 WSAS database configurations
            i. In your J2EE App server's configuration file, locate the section 
               where the WSO2 WSAS JDBC datasource is registered, and modify the
               relevant parameters.

           ii. Locate wso2wsas.hibernate.cfg.xml in the wso2wsas/WEB-INF/classes
               directory and change the "dialect" property, if necessary, to 
               match your RDBMS.
               e.g. for MySQL, the dialect is org.hibernate.dialect.MySQLDialect


        3. Changing HTTP/HTTPS ports
            In your App server's configuration file, locate the section where
            these ports have been registered, and changed it to the appropriate
            values.
            If you carried out a Generic installation, in addition to modifying
            your App servers configuration file, you also have to modify the
            server.xml file which can be found at WSO2WSAS_HOME/conf.
			
			
WSO2 WSAS v2.1-RC6 Java - Source Distribution
--------------------------------------------------------

This section describes how you can build WSO2 WSAS from the source distribution.			
			
System Requirements
-------------------
1. Java Runtime Environment 1.4 or 1.5
2. Maven 2.0.6 or higher (http://maven.apache.org/)
3. Operating System
    Tested on Windows XP, Linux(Fedora core, Ubuntu and Gentoo), Mac OS X

Source distribution directory structure
---------------------------------------
WSO2_WSAS
	|- modules
		  |- 	    admin
		  |- 	    clustering
		  |- 	    core
		  |- 	    distribution
		  |- 	    integration
		  |- 	    samples
		  |- 	    sts
		  |- 	    www
	
	|- third_party_src
		  |-		axis2	
		  |-		opensaml
		  |-		axiom
		  |-		woden
		  |-		XML Schema
		  |-		neethi
		  |-		rampart
		  |-		sandesha2
		  |-		wss4j
		  |-		wso2-commons 
		  
	
Setting Up the Environment and Tools
-------------------------------------
Maven:

The WSO2 WSAS build is based on Maven. Hence the prerequisites to build WSO2 
WSAS from source distribution is to have Maven & JDK installed. Extensive 
instruction guides are available at the Maven site.

This guide however contains the easiest path for quick environment setting.
Advanced users who wish to know more about Maven can visit here.

    * MS Windows
       1. Download and run the Windows installer package
       2. Set the 'Environment Variables'
            ( create system variable M2_HOME and edit path.
            eg: "C:\Program Files\Apache Software Foundation\maven-2.0.6";
                path %M2_HOME%\bin)
       3. Make sure that system variable JAVA_HOME is set to the location of 
          your JDK,
            eg. C:\Program Files\Java\jdk1.5.0_02
       4. Run mvn --version to verify that it is correctly installed.

    * Unix based OS (Linux etc)

The tar ball or the zip archive is the best option. Once the archive is 
downloaded expand it to a directory of choice and set the environment variable 
M2_HOME and add M2_HOME/bin to the path as well. More instructions for 
installing Maven in Unix based operating systems can be found here.

Once Maven is properly installed you can start building WSO2 WSAS.
Building WSO2 WSAS from the Source Distribution

The source distribution is available as a zipped archive. All the necessary 
build scripts are included with the source distribution. Expand the source 
archive to a directory of your choice. You can run the following commands inside
that directory to build WSO2 WSAS.

List of commands that can be run are as follows:

Note: The first time you run Maven it will automatically download
the dependent jars. Therefore, first run will take more time.
type 'mvn clean install' to create the complete release artifacts.


Known Issues
------------

1. POJO to Web service feature is still at an experimental stage.
One can upload jar/zip file and can create an AAR out of it. 
If you uploaded a jar/zip file which has a services.xml file in its
META-INF directory, when its transformed into AAR its services.xml
will be replaced by the generated services.xml. In addition to this,
the user cannot associate any library dependencies or web content with
the generated AAR file.

Due to limitations in Axis2, method overloading is not supported, and
hence the WSDL for services where methods are overloaded cannot be generated.
Hence all WSDL based functionality related to services will not work for 
such services.

2. WS-Policy support is still in experimental stage and limited to single
port scenarios.

3. You cannot have two different versions of the Apache Sandesha2 module
in the system.

4. A <parameter name="OmitSOAP12Action">true</parameter> entry has been
added to the HTTP & HTTPS transportSenders in order to overcome some issues
 with some browsers. In case of interoperability failures, please change
 the value of this parameter to false and retry.

 5. The 'Try It' feature does not work for MTOM enabled services.

---------------------------------------------------------------------------
 2007 WSO2 Inc.