HatMaker WebServices Example Description.

Directory ${metaboss_home}/examples/HatMaker/WebServices/Server contains the Ant build file used to build the HTTP Servlet Application which is the front end to HatMaker Web Services. This directory also contains a number of batch files used to invoke ant build. The end goal of this build is to produce the Web Archive file (war file) deployable into a Servlet container such as Apache Tomcat. The full build of the WebServices Server Application module is done in one step using the MetaBossBuilder task. The MetaBossBuilder is an expert Ant task which is able to build the required components from the model without lots of additional information. Unlike most of the basic Ant tasks, which are procedural in nature, the MetaBossBuilder task is declarative. One is only required to specify the source Model Elements and the type of the desired target module. We call this approach "Model Driven Buld". In the example the MetaBossBuilder is asked to build three configuration of the WebServices Server Application:

• Inprocess - this configuration executes services internally (i.e. does not delegate service execution anywhere). The MetaBossBuilder prepares the war file "with the lot". The resulting web archive file is placed in the ${metaboss_home}/examples/HatMaker/WebServices/Server/Release/Inprocess directory.
• JBossClient - this configuration delegates the service execution to an implementation running inside JBoss container. The MetaBossBuilder prepares the war file with a thin WebService-to-JBosss proxy. The resulting web archive file is placed in the ${metaboss_home}/examples/HatMaker/WebServices/Server/Release/JBossClient directory.
• Simulator - this configuration simulates service responses based on the XML data files. The MetaBossBuilder prepares the war file with a special simulator implementation (the simulator facility is a part of the MetaBoss Testing Framework). The resulting web archive file is placed in the ${metaboss_home}/examples/HatMaker/WebServices/Server/Release/Simulator directory.

Please note that in a real life project you will most probably standartise on the particular deployment strategy and will only be building one kind of WebServices Server Application. This means that the example build file is three times more complex and the sample build takes three times longer than it would take in real life.

• Inprocess configuration:
  • Tyrex's domainconfig.xml file with valid data sources information must reside in Tomcat's bin directory (e.g. c:/tomcat-jwsdp-1.4/bin/domainconfig.xml). This file contains actual data base connection information, so you will most definitely have to enter your own details. An example of what has to be set can be found in ${metaboss_home}/examples/HatMaker/SystemTest/domainconfig.xml file.
• JBossClient configuration:
  • jbossall-client.jar and log4j.jar from JBoss's client directory must be copied into Tomcat's common/lib directory (e.g. c:/tomcat-jwsdp-1.4/common/lib). These library files provide connectivity for the example servlet to the JBoss container.
  • Tomcat's classpath (see catalina.bat in Tomcat's bin directory) must be modified to include a jndi.properties file with JBoss's network comms settings. This file contains actual JBoss container connection information, so you will most definitely have to enter your own details. An example of what has to be set can be found in ${metaboss_home}/examples/HatMaker/WebServices/Server/config/JBossClient/jndi.properties file.
• Simulator configuration:
  • Copy the entire simulatordata directory located at ${metaboss_home}/examples/HatMaker/WebServices/Server/config/Simulator to the location under Tomcat's current working directory. The exact location of this directory depends on the way you have started Tomcat. Some examples:
    • If you are starting Tomcat from the Windows JWSDP Menu Command (Start --> Programs --> Java(TM) Web Services Developer Pack 1.4 --> Start Tomcat) created for you by the JWSDP Installation process - then the current user home directory will be the current working directory. You may also change it by altering the value of the StartIn property of the menu shortcut.
    • If you are starting Tomcat from the OS shell by changing your working directory to the JWSDP bin directory and running startup.bat or startup.sh - than the JWSDP bin directory will be your current working directory. In this case your simulatordata directory must be copied under the JWSDP bin directory (say c:/tomcat-jwsdp-1.4/bin/simulatordata).
    The simulatordata directory contains XML files with simulated responses to be returned by the simulator as an answer to appropriate requests. Supplied data files are enough to run the example WebServices client. If you wish to make an example more complex or simply modify returned data - you will have to modify data files inside this directory.

Deployment of the war files is done via Tomcat's Web Application manager. Please refer to Tomcat and JWSDP documentation for more details on how to use this feature. The actual war files to be deployed are located in the Inprocess, JBossClient or Simulator subdirectories located under the ${metaboss_home}/examples/HatMaker/WebServices/Server/Release directory.

Directory ${metaboss_home}/examples/HatMaker/WebServices/JavaClient contains the Ant build file used to build the Sample Web Service Java client - a simple command line java application calling a number of Web Services. This directory also contains a number of batch files used to invoke an ant build. The end goal of this build is to produce all classes necessary to run the client application. This build consists of the following major steps:

1. Generate Web Services code for client stubs using the wscompile tool (part of JWSDP). The wscompile tool uses the WSDL file published by the WebServices server. This step is performed in the build target section named "webservice-client-generate".
2. Compile all handcoded and generated pieces of code. The handcoded source file can be found at ${metaboss_home}/examples/HatMaker/WebServices/JavaClient/src/com/hatbuyer/services/SampleService.java. It contains a simple main() routine and example which invokes a couple of Web Services.

• This build is not MetaBoss specific and does not use any tools out of the MetaBoss suite. All it is using is the wscompile tool which is part of JWSDP.
• The Web Service Server has to be deployed and running for this build to succeed. This is because the wscompile tool uses the "live" Web Service to fetch the WSDL definition.
• You also may have to alter the URL of the Web Service (port and host parts only!!) if you have deployed your Web Service somewhere other than at localhost:8080. The URLs are stated in the files with suffix '_wscompileconfig.xml'.

Directory ${metaboss_home}/examples/HatMaker/WebServices/DotNetClient contains the Ant build file used to build the Sample Web Service .NET / C# client - a simple command line C# executable calling a number of Web Services. This directory also contains a number of batch files used to invoke an ant build. The end goal of this build is to produce a runnable Windows executable. Please note that this part of the example depends on the Microsoft .NET Framework SDK being installed (We have used version 1.1). The DOS environment variables (PATH, LIB, INCLUDE etc...) must incorporate the appropriate SDK locations at the time the Ant script is run (otherwise the build will end up with an error). Microsoft .NET Framework SDK documentation provides more details on the installation and environment setting. This build consists of the following major steps:

1. Generate Web Services code for client stubs using Wsdl tool (part of SDK). The Wsdl tool uses the WSDL file published by the WebServices server. This step is performedis in the build target section named "webservice-client-generate".
2. Compile all handcoded and generated pieces of code. The handcoded source file can be found at ${metaboss_home}/examples/HatMaker/WebServices/DotNetClient/src/HatBuyer/Tests/HatMakerTest.cs. It contains a simple Main() routine. As an example this routine invokes a couple of Web Services.

• This build is not MetaBoss specific and does not use any tools out of the MetaBoss suite. All it is using is the Wsdl tool which is part of the Microsoft .NET Framework SDK.
• The Web Service Server has to be deployed and running for this build to succeed. This is because the Wsdl tool uses the "live" Web Service to fetch the WSDL definition.
• You also may have to alter the URL of the Web Service (port and host parts only!!) if you have deployed your Web Service somewhere other than at localhost:8080. The Web server URL is set in the build.properties file and is used in the "webservice-client-generate" target of the build file.