10th October 2007

(1) Installing  WSO2 WSAS v2.2-RC1  as an embedded (standalone) server.
-----------------------------------------------------------------

WSO2 WSAS v2.2-RC1 can be run either as an embedded server or in a
servlet container. If it is running as an embedded server, use the following steps,

1. The directory containing the INSTALL file will the root and it will be treated as 
WSAS home directory and let it be WSO2HOME. 

2. All the shell scripts and .bat files are available in WSO2HOME/bin folder. 

3. To start WSAS one can use either wso2wsas.sh/startup.sh in Linux flavours 
or daemon.sh in all *nix system. 

4. If using wso2wsas.sh or startup.sh, execute them directly. ex: >./wso2wsas.sh 
   If using daemon.sh, one has to use it { console | start | stop | restart | status | dump } options.
   For more details please refer to documentation. ex: [./daemon.sh start] will 
   start WSAS as an embedded server. 

(2) Installing WSO2 WSAS on a J2EE Application Server
-----------------------------------------------------

    General Installation Steps
    --------------------------
    1. Download and unzip wso2wsas-2.2-RC1.zip
    2. Run install.sh or install.bat from WSO2WSAS_HOME/bin.
	(WSO2WSAS_HOME is the folder where you extracted
	wso2wsas-2.2-RC1.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.

(3) WSAS IDE Installation. (Eclipse IDE)
----------------------------------------
	1) Download the Eclipse WTP 2.0 verison from the Eclipse WTP Distribution site.
		(http://download.eclipse.org/webtools/downloads/)
	2) To Install WSAS IDE Integration one can use install.sh in *nix system and
	    Install.bat in windows systems.
	3) When we run this command it will ask for the mode of installation. On that
            list select the Eclipse WTP Plugin installaton mode.
        4) Then it asks for shutdown Eclipse WTP if its already running. 
        5) At the next step when the user point to the Eclipse WTP Home, the installer 
            will install the WSAS IDE Integration plugins to eclipse. Also one thing to 
	    note here is that if there is old version of Eclipse WTP Integration plugins 
            installed in the pointed Eclipse WTP, the installer will asks for the replace
            the old version or abort the installation.
      

(4) Running Samples
-------------------

All the samples are available in WSASHOME/samples directory. Please refer to the README
files in each respective folder 



(5) WSO2 WSAS v2.2-RC1 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.7 (http://maven.apache.org/)
3. Operating System
    Tested on Windows XP, Linux(Fedora core, Ubuntu and Gentoo), Mac OS X and Sun OS

Source distribution directory structure
---------------------------------------
WSO2_WSAS
	|- modules
		  |- 	    admin
		  |- 	    clustering
		  |- 	    core
          |-        documentation
		  |- 	    distribution
		  |- 	    integration
		  |- 	    samples
		  |- 	    sts
		  |- 	    www

	|- third_party_src
		  |-		axis2
		  |-		opensaml
		  |-		axiom
		  |-		woden
		  |-		XML Schema
		  |-		neethi
		  |-		rampart
		  |-		sandesha2
		  |-		wss4j
		  |-		wso2-commons


(6) Setting Up the Environment and Tools
----------------------------------------
Maven2:

The WSO2 WSAS build is based on Maven2. Hence the prerequisites to build WSO2
WSAS from source distribution is to have Maven2 & 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.7";
                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.
