Consuming Web Services

Initial Setup

First, download Sun's Webservices and install. Go into Enterprise Manager and add all the jars in these directories to your class path.

{jwsdp_home}/jaxrpc/lib/
{jwsdp_home}/jwsdp-shared/lib/
{jwsdp_home}/saaj/lib/
{jwsdp_home}/jaxp/lib/endorsed/

In javrpc/bin make a directory called wsdl.

Setting up a webservice to consume

In jaxrpc/bin set up an xml file that looks like this.

<?xml version="1.0" encoding="UTF-8"?>
<configuration 
 xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> 
<wsdl name="babelfish" 
 location="http://www.xmethods.net/sd/2001/BabelFishService.wsdl" 
 packageName="wsdl.babelfish"> 
<typeMappingRegistry> 
</typeMappingRegistry> 
</wsdl>
</configuration>

Change the wsdl name and packageName above to whatever you want to call it. The location is the URL to the webservice definition, which the webservice provider will give you.

Then run this command to set up the java classes.

wscompile -gen {xml filename }

Then, jar it up!.

{java path}jar -cv wsdl.jar wsdl

There will now be a wsdl.jar file in that directory, make sure it's also in your class path in Enterprise Manager.

Providing Web Services

To provide webservices you first have to have a web server that can run java stuff. As far as I can tell, tomcat is the only one doing that. Tomcat is a regular web server, just like Apache or IIS, but because of questions of speed and cgi extensions it's usually run in conjunction with Apache or IIS. Instead of listening to port 80, like a regular web server does, tomcat listens to port 8080. You can either configure the main web server to pass certain requests along to port 8080, or you can tell people requesting webservices to specify the port in their URL.

Install Java SDK

First, you have to install the SDK version of java. You can tell if java is working by trying the java -version command and javac.

Install Tomcat

Then you need to download tomcat50-jwsdp from www.java.com. Just do umask 0 and use the Linux unzip command to install it. In conf is tomcat-users.xml, you need to change it to something like this.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
 <role rolename="tomcat"/>
 <role rolename="role1"/>
 <role rolename="manager"/>
 <role rolename="admin"/>
 <user username="tomcat" password="tomcat" roles="tomcat"/>
 <user username="doug" password="pass" roles="manager,admin"/>
 <user username="role1" password="tomcat" roles="role1"/>
 <user username="both" password="tomcat" roles="tomcat,role1"/>
</tomcat-users>

Next download apache-ant. Unzip it into the tomcat directory. Then Copy {tomcat}/server/lib/catalina-ant.jar to {tomcat}/apache-ant/lib directory, where {tomcat} is "home" directory for Tomcat server. Add {tomcat}/ tomcat-apache-ant/bin to PATH environment variable. In Linux this would be "$ PATH=$PATH:/ {tomcat}/tomcat-apache-ant/bin; export PATH" You have to run ant from a directory where there's a build.xml and a build.properties.

Start tomcat by going into the tomcat/bin directory and typing "./startup.sh". You can shut down tomcat with a ./shutdown.sh. You can check to see if tomcat is running with "ps -ef | grep java".

Go into a browser and go to:

http://servername:8080/index.jsp

The next step is to get someone to send you BBjAuction and QAMemos from John F. Schroeder's Advanced BBj Class. Put them in some directory. These are the special files needed.

Build.properties


Ant script that defines environment, i.e., directories, key words etc. You will have to 
modify this for your directory structure. 

Build.xml


Ant script that defines various steps in a process with dependencies, etc. The comments
at the top may not be correct. 

config.xml


XML Configuration file for client stubs

jaxrpc-ri.xml


Web Service definition. You'll have to modify this for your webservice. I modified it by 
comparing different jaxrpc-ri files. But the best description seems to be under "Creating a
Web Service with JAX-RPC from http://java.sun.com/webservices/docs/1.3/tutorial/doc/.

This was tricky at first. BuyerInfo is the name of the service as you deploy it in tomcat.
<?xml version="1.0" encoding="UTF-8"?>
<webServices xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/dd" 
 version="1.0" targetNamespaceBase="http://servername:8080/BuyerInfo"
 typeNamespaceBase="http://servername:8080/types">
 <endpoint name="BuyerInfo" 
 displayName="Buyer Info" 
 interface="ctaa.BuyerInfo" 
 implementation="ctaa.BuyerInfoImpl"/>
 
 <endpointMapping endpointName="BuyerInfo" urlPattern="/BuyerInfo" />
</webServices>

web.xml


Web title and timeout specifications

Here's the ant steps you have to run. I'm skipping the client side, since that's usually 
done at the other end, by whoever is consuming the service. All of these steps must run
without error, except the deploy. 

If you get an error saying it can't find "org.apache.catalina.ant.DeployTask", then you
 need to copy catalina-ant.jar from tomcat/server/lib to apache-ant/lib. If that doesn't
 fix it check the tomcat\jwsdp-shared\bin\setenv.bat file. This error means tha ANT-HOME is
 being set to somewhere that doesn't have the catalina-ant.jar. 
 


 ant compile-server 


Compiles server java classes and builds server jar file

 ant run-server 


Compiles server and then runs main. You probably don't need to compile-server if you
do the run-server.

 ant package-war 


Creates a temporary war file, packaging the java classes

 ant process-war 


Creates ties, Java classes, and WSDL file for the service

 ant deploy 


Deploys service by adding war to Web Server's table of web applications available for users. 
This one step can be done by going into the tomcat management page and using that deploy.

I haven't got ant-deploy to work, so I deploy either directly from tomcat, or just do a
jar xvf.
Deploying from Tomcat.

Go into the Admin page and set the deploy options to unpack war files. Go into the Tomcat 
manager page and at the bottom are the deploy options. Use the browse one to grab the war 
file from {tomcat}/apache-ant/builds/{servicename}/dist/{servicename}.war.

Make sure the jars listed at the end of build.properties got moved to WEB-INF/lib. If not, 
move them there manually. Also, once you've done this if you need to modify your classes
or xml files and recompile the war, you can just unpack it into the webapps/name
 with a jar xf filename.war command.

To see the wsdl page:
http://localhost:8080/helloworld/helloWorld?WSDL

How it works

Tomcat is designed to launch java classes thru http requests. When you write your java
classes to launch a web service you have to follow a certain format. Your classes are then
wrapped in jaxrpc and jwsdp classes to handle the calls from tomcat.

When you need to call a bbj program you use bbjbridge, which somehow runs bbj using the
config.bbx from basis/bbj directory. You specify the server's bbj directory in
builds.properties. To this config.bbx file you have to add:

ALIAS J0 com.basis.bbj.bridge.BBjBridgeOpenPlugin

You also have to add a PREFIX with a path to your webservices bbj programs, any other programs
you want to run from webservices, and probably your data path.

Java classes

You basically have to set up three java classes.
BuyerRow

This defines the basic class that the webservice client in going to work with. In a way, it's
like BB's templates. For example, I define a field called buyerid, and name in this class. A
.NET client then could define a class called BuyerRow, and get the id with something like
BuyerRow.buyerid.

In this class we're going to have methods called getBuyerID, and getName. Also setBuyerID,
and setName. Two more important methods are toString and fromString.

To make things work you are going to have to be able to access this class from bbj. That means
you have to put it in a jar and add it to the classpath in Enterprise Manager. However, the
ant proccess leaves a BuyerInfoServer.jar in the dist directory with all three classes in it.
I just added a copy of that to the class path.
Important Test!

Once you have this class added to bbjservices, you can run any bbj, and test the class. What
you need to do is test the toString and fromString functions. What I found was that somehow
an extra CHR(0) was being added at some point in this process. Webservices does not like
this, and kept giving me an "End Element Expected" error in the browser I was using to test
this. I used the String.trim function in java to fix this in the fromString method.
BuyerInfoImpl and BuyerInfo

The other two classes are BuyerInfoImpl, which is the service, and BuyerInfo, which has
the ports.

The Basis IDE is perfect for programming these classes. What I did was set up a project
called BuyerInfo. I mounted the directory the classes are in, bearing in mind the
relationship between directories and com.webdomain.BuyerInfo. I then mounted these jars.
BBjThinClient.jar
BBj.jar
jaxrpc-spi.jar
jaxrpc-api.jar
jaxrpc-impl.jar
jaxr-impl.jar
jaxr-api.jar
I also mounted the directory where I keep my bbj webservices program. The IDE is nice here because you can modify both the java classes and bbj programs in one place.
Bug in Java
I'm not going to spend anymore time explaining the compiling and deploying a webservice because the way I'm doing it, and the way I was taught by Basis, has a bad problem. Let's say you want to provide the following web service:
public String updateApproval(String PassCode, String GroupID, String Stockno, int ApprovalLevel, String ApprovalDate, String OriginalXML)
If you create the webservice using ant as explained above, what happens is that your webservice user sees this:
public String updateApproval(String String, String String, String String, int int, String String, String String)
Basis knows of another way of creating a webservice which starts with creating a WSDL file. If you figure it out let me know!
Using XML in a webservice
We use XML to return information in our webservices. Basically our class type is string, and the string we return is XML. XML is much more compatible with .NET than any of the SOAP datatypes, and it's much easier to transfer massive amounts of information, like reports, thru XML. There's an added benefit in that if there's any error, I just throw it into an XML object
When I make a report in the standard bbj system now, I do it in XML. You can present that as HTML, Excel compatable, or PDF format. Then if a customer could be interested in it, I throw it into a webservice.