[wsif] update for 1.2.0RC1 - making WSIF easier to use and build

[Aleksander Slominski <as...@cs.indiana.edu>]

hi,

as seen from recent emails building WSIF (and resolving all dependencies like JMS)
it is not that easy task ...

therefore i have worked on making WSIF experience for developers more pleasant.
i am still not there but i think to do this we need ot have two related matters
improved: documentation about WSIF (both building and design) 
and better support for building system (including dependencies etc).

as of documentation: i have added new directory doc to 
keep more specific documentation such as FAQ or how to write WSIF provider
(README file probably should be refactored into smaller doc files)

i have checked in jar files for known and available for distribution
libraries (including LICENSE info and how to get them) and 
for jar files that are not distributable a place holder directory
with informati on how to get required lib (for example javamail 
required to compile apache soap WSIF provider)

i have added also two sets of scripts:
classpath.* can be used to set classpath based on available jar file in lib subdirectories
build.* will call claspath.* and run ant (to simplify building)

however i have hit following problem. even with all libraries 
and using JDK 1.4 i still cannot compile WSIF

C:\Forge\xml-axis-wsif\java>java -version
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)

C:\Forge\xml-axis-wsif\java>classpath set
build\classes;build\samples;build\tests;lib\saaj\saaj_1_1.jar;lib\jaxrpc\jaxrpc_1_1.jar;lib\commons_
logging\commons-logging.jar;lib\commons_discovery\commons-discovery.jar;lib\axis\axis_1_0.jar;lib\ax
is\axis_1_0-ant.jar;lib\javamail\mail.jar;lib\apache_soap\soap.jar;lib\jms_api\jms_1_1.jar;lib\xerce
s2\xmlParserAPIs_2_2_0.jar;lib\xerces2\xercesImpl_2_2_0.jar;lib\log4j\log4j.jar-;lib\log4j\log4j-1.2
.4.jar;lib\wsdl4j\wsdl4j.jar-from-axis;lib\wsdl4j\wsdl4j.jar;

C:\Forge\xml-axis-wsif\java>ant15 all

C:\Forge\xml-axis-wsif\java>C:\OffNet\tools\jakarta-ant-1.5\bin\ant all
Buildfile: build.xml

init:

clean:
   [delete] Deleting directory C:\Forge\xml-axis-wsif\java\build

prepare:
    [mkdir] Created dir: C:\Forge\xml-axis-wsif\java\build

checkDependencies:

checkSoapRMI:
     [echo] Warning: SoapRMI dependencies were not resolved.

checkJMS:

checkEJB:
     [echo] Warning: EJB dependencies were not resolved.

checkApacheSOAP:

checkApacheAxis:

dynamic:
    [mkdir] Created dir: C:\Forge\xml-axis-wsif\java\build\classes
    [javac] Compiling 113 source files to C:\Forge\xml-axis-wsif\java\build\classes
    [javac] C:\Forge\xml-axis-wsif\java\src\org\apache\wsif\wsdl\AuthenticatingProxyWSDLLocatorImpl.
java:77: Interface javax.wsdl.xml.WSDLLocator of class org.apache.wsif.wsdl.AuthenticatingProxyWSDLL
ocatorImpl not found.
    [javac] public class AuthenticatingProxyWSDLLocatorImpl implements javax.wsdl.xml.WSDLLocator {

    [javac]                                                            ^
    [javac] C:\Forge\xml-axis-wsif\java\src\org\apache\wsif\wsdl\WSIFWSDLLocatorImpl.java:77: Interf
ace javax.wsdl.xml.WSDLLocator of class org.apache.wsif.wsdl.WSIFWSDLLocatorImpl not found.
    [javac] public class WSIFWSDLLocatorImpl implements javax.wsdl.xml.WSDLLocator {
    [javac]                                             ^
    [javac] C:\Forge\xml-axis-wsif\java\src\org\apache\wsif\util\WSIFUtils.java:498: Incompatible ty
pe for method. Can't convert org.apache.wsif.wsdl.WSIFWSDLLocatorImpl to java.lang.String.
    [javac]             Definition def = wsdlReader.readWSDL(lo);
    [javac]                                                  ^
    [javac] C:\Forge\xml-axis-wsif\java\src\org\apache\wsif\util\WSIFUtils.java:501: Exception javax
.wsdl.WSDLException is never thrown in the body of the corresponding try statement.
    [javac]         } catch (WSDLException e) {
    [javac]           ^
    [javac] C:\Forge\xml-axis-wsif\java\src\org\apache\wsif\util\WSIFUtils.java:539: Incompatible ty
pe for method. Can't convert org.apache.wsif.wsdl.WSIFWSDLLocatorImpl to java.lang.String.
    [javac]             Definition def = wsdlReader.readWSDL(lo);
    [javac]                                                  ^
    [javac] C:\Forge\xml-axis-wsif\java\src\org\apache\wsif\util\WSIFUtils.java:542: Exception javax
.wsdl.WSDLException is never thrown in the body of the corresponding try statement.
    [javac]         } catch (WSDLException e) {
    [javac]           ^
    [javac] 6 errors

BUILD FAILED
file:C:/Forge/xml-axis-wsif/java/build.xml:183: Compile failed; see the compiler error output for de
tails.

this is directly related to release plan:

----
* [Alek] all jar files that are required (not optional) for WSIF should
be checked into CVS to allow to retrieve old versions of WSIF
from CVS without need to checkout other dependent projects from past
(and try to build them and they may depend on other projects...)

* [Alek] require to keep version numbers for jar files and
README/LICENSE files (in separate directory?)
describing where jar files can be obtained and what is license.

i think that currently it is just: WSDL for Java API (WSDL4J),
and Apache Common Logging, essentially:
wsdl4j.jar, qname.jar, commons-logging.jar, more?
-----

i am now working on following items:

-----
* [Alek]  when dependant library is not available print warning
and URL to where to get stuff

* [Alek] build.xml that will work out of the box even if no libraries
for providers are available (axis, apache soap, JMS, ...)
and will print warning specifying what is needed.

* [Alek] split compilation into API (org.apache.wsif.* (no sub packages)
as should be all that is needed to use WSIF) and rest of WSIF
without providers then compile each provider separately to ensure
that there is no unnecessary dependencies:
that will require to split built process in build.xml into separate tasks
that compiles first core WSIF and than separately each provider.
to make sure that there is no dependency of WSIF core on
providers or optional libraries and between  providers

----

but it requires resoilving dependencie both for WSIF API (org.apache.wsif package only)
and for providers (like JMS dependencies)

and still left to go ...

-----
* [OPTIONAL] try to provide just JMS API (very handy)
without need to require users to  get whole J2EE
(maybe we could use some open source JMS
runtime for automatic tests such as Open3.org ...)
needs to check licensing issues ...

* [OPTIONAL] as of building: it would be very useful also to have ANT jar
and all dependent libraries needed to build WSIF checked in
- that should greatly improve user experience when working
with WSIF source code (instead of hunting for correct version of ANT etc.)

* [OPTIONAL] modify build.xml to  add checks that samples
are using only WSIF API (it may not be possible)


* add to bugzilla axis-wsif 1.2.0 to allow reporting bugs
(though i am not sure how to do it - or who can do it)

* [All Developers] test RC releases :-)

* [Alek + Nirmal] updated/tested documentation for samples and tests
that includes description of what is required to run each sample
(including dependencies)

* [Alek + Nirmal] WSIF uses non-standard WSDL bindings to support invocation of EJBs,
JMS-based services, etc. We need to document these extensions and provide
the schemas along with the release, AFAIK the only help users get re. these
bindings are the samples themselves which may not be sufficient or may not
exploit the proposed binding extensions fully.
-----

alek