Java, Flex 3 webservice project setup step by step.

Editted by Lim Siong Boon, last dated 16-Sep-2012 .

email:    contact->email_siongboon  



Step by Step Explaination



Steps to do
Developing Java & Flex 3 webservice application

What you need?
     - Eclipse
     - JDK (Java development kit required by Tomcat)
     - Apache Tomcat (free open source server)
     - Axis (protocol engine for tomcat server)
     - Flex builder 3

     - Apache Tomcat plugin for Eclipse IDE
     - Flex builder 3 plugin for Eclipse IDE

Software download link (you should install them in sequence)

     1) Eclipse,
     - Eclipse IDE for Java EE Developers
     - Eclipse IDE for Java Developers

     2) JDK (Java development kit required by Tomcat),

     3) Apache Tomcat 7 ,
      Download the Tomcat executable, install it to your local drive.

      (Note: Remember to set a password for your Tomcat installation, else you will have a problem access the "Tomcat Web Application Manager".
      Click the Window's start menu, and key in the search programs and files "Notepad". A notepad icon will appear. Right click the notepad and click
      "Run as administrator" to open the notepad. If the notepad is not run as administrator, the following edited file will not be able to be saved.
      Insert the following to "\Apache Software Foundation\Tomcat 7.0\conf\tomcat-users.xml" and save the file to set the admin user name and password.
      <role rolename="manager-gui"/>
      <user username="tomcat" password="s3cret" roles="manager-gui"/>
      To restart the Tomcat server, right click the Tomcat server on the taskbar and Stop the server, and then click Start.)

      (Note: To run the Tomcat with its icon on the taskbar, run Tomcat in monitoring mode "\Apache Software Foundation\Tomcat 7.0\bin\Tomcat7w.exe"
      You may encounter "Application System Error" Access is denied. Unable to open the service 'Tomcat7'. That is because it is not run as administrator in
      Win7. Right click the file "Tomcat7w.exe", select Properties, go to Compatibility, under the section Privilege Level check the box "Run this program as
      an administrator")

      Test if the Tomcat is install properly by running the program Tomcat Monitor.
      A Tomcat notification icon will appears in the taskbar (bottom right corner of the screen).
      Right click the icon, and select "Start Service" to run the Tomcat.
      Open a web-browser and go to the following URL "http://localhost:8080/"
      Localhost is the same as the ip address of your local machine. Port: 8080 is the default port serve by the Tomcat.
      You should see the following Tomcat start up webpage if the tomcat is installed correctly.

          tomcat home page     tomcat web app mgr

     Reference guide to install Tomcat.

     4) Apache Axis2, (Download: axis2.war)
      Download the & copy the axis2.war file to C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\
      The \webapps\axis2 folder will be generated if Tomcat is running. This means that the axis2 servlet is installed to tomcat.
      Do not delete the axis2.war file
      Test the axis2 servlet using the browser with the following URL "http://localhost:8080/axis2/"
, you should see the following screen

          axis2 homepage

     Reference guide to install Axis2 to Tomcat.

     Here is a link to a SmsService.aar file (a working archive of a sms webservice to help you test your axis environment)
     Copy the SmsService.aar file to "C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\axis2\WEB-INF\services\"
     Alternative, you can unzip the and copy the folder to the same directory; this is another method to deploy your webservice.
     Go to URL "http://localhost:8080/axis2/services/listServices", you should be able to see the following screen without restarting the server.

     The following service can be seen on the browser indicating that the environment is properly setup to host the webservice.


     Service EPR : http://localhost:8080/axis2/services/SmsService

     Service Description : Please Type your service description here

     Service Status : Active
     Available Operations

          - sendSms
          - sendSmsNonQueueTimeout
          - testDelay60sec
          - etc... .


     5) Adobe Flex 3 builder,

Other Reference

Reading Reference

     Flex Builder 3
     - Adobe Flex 3.0 for Dummies (recommended as your first book for learning flex)
     - Flex 3 : a beginner's guide (good reference)
     - Flex 3 Bible (more detail information inside)
     - Java and Flex Integration Bible (more detail information inside)

Webservice programming with Apache Axis2 & Eclipse IDE

A webservice is similar to a function/method call. If you are familiar with programming, function/method should be a very familiar term to you. A function is like a black box where we call it to execute some process. Sometimes we may need to pass some information to this black box. At the end of the process, we expect some return result or a process to be executed.

Functions helps to organise or consolidate our codes. Design functions so that they can reuse in future. As a programmer, we should have a lazy mindset. Lazy not for now nor the past. You want a lazy life for the future. Design and artitacte your codes in a way, such that your programming effort become lesser and lesser as you progress. Programming should be getting easier & easier to write as your codes gets larger. If you are not experiencing that, it just means that there is more that needs to be understood about the concept of programming.

Nowadays the codes seems so easy to write. For a line of codes, you can get a pop up window to do all the work for you. In fact, all the hardwork is already done for us, through the years of collective experience & software evolution. They have written libraries of functions that are so easy to use by many programmer. The progress is good because programming is getting less and less effort. Let us go back to webservice again.

What is the difference between Webservice and function/method call? Webservice is located at a remote server. Meaning, it is a function call to a remote server. The remote server provide functions for other devices on the network. We call them services.

There are many protocol standards that are design to provide such remote services (function call) across the network. One of them is call CORBA which I am aware of. There are many many more... which I do not know.

The most important benefit of using webservice technology as compare to other protocols is that it is in a readable form. The protocol is formated using ascii coded XML tags. The XML format allows developers from various operating system platform or programming languages to be able to connect the shared services, quick and easy. The protocol itself is self documentated, meaning that any developer can easily read and use the webservice for their own implementation. This is similar to the HTML tags that we have for accessing and displaying our web content. Evolving and becoming popular worldwide in such a short period of time.

In a summary, webservice is a function call from remote server using ascii texts in the format of XML tag. Apache Axis2 provides the open source library/method that implement the standard webservice. It is a ready written engine, a servlet application running under Tomcat server. Webservices written in module by module will be hosted under Axis 2 servlet.

The following sections will demonstrate a short example to illustrate the process of building a webservice.

1) Setup Axis in Eclipse. Axis plugin is already built into Eclipse by default, but a bit of configuration is still required. The axis2 module will helps to automate files generation that are required by the apache axis2 to run webservice.

Apache Axis2 (webservice)

1) Go to Apache website & download the apache axis2 Standard Binary Distribution and unzip this axis2 package. .
Copy the axis2 directory to "c:\program files\". (you can copy to anywhere if you want)
There is no need to do any installation; copy will do.

2) Next, you got to tell eclipse where is this axis2 installed. This will tell eclipse where your axis2 is located.
In eclipse, go to the menu Window>Preferences>Web Services>Axis2 Preferences>Axis2 Runtime>Axis2 runtime location: "C:\Program Files\axis2-1.5.3"

2) Open a new webservice project. Eclipse is a wonderful IDE (integrated development environment) and is built in with features that support webservice development work. In order for eclipse to help us automate some of the webservice setup files, we will have to open a project type "Dynamic Web Project".

1) Go to menu File>>New>>Others...>>Web>>Dynamic Web Project
       Project Name: DoesMagic
       Target runtime: Apache Tomcat v7.0
       Dynamic web module version: 2.5 (do not select 3.0 for this tutorial, it will not work, error message "IWAB0014E Unexpected exception occurred." may occurred during the webservice generating process)
       Click finish to create the new webservice project

2) Please ensure the following configuration. Go to the menu Window>Preferences>Web Services>Server and Runtime "
       Server: Tomcat v7.0 Server at localhost (Eclipse supports servers as well but I didn't setup my tomcat in Eclipse, so this leaving this option out is ok)
       Web service runtime: Apache Axis2          (Note: default is pointed to Apache Axis which is not correct in this example. We are using axis2)

       You may also like to set the default server run for your project.
       Right click on your project>Properties>Server> Select "Tomcat v7.0"

3) Write a new java class using the Eclipse IDE. This will be the class providing the webservice methods to be invoked over the internet. doBasicStuff will be the webservice method. 1) To create the interface class for our weservice, right click on the project>>New>>Class

public class DoesMagic
    public String doBasicStuff(String message)
        return "This is your message: " + message;
4) Generate the folder/files for implementing the axis2 webservice. Eclipse will help us generate the files structure to deploy a webservice running on Axis2. Axis2 is a opensource java servlet program that process webservice protocol. Axis2 is run under Tomcat server.

1) Right click the new java class file>Webservices>Create Webservice
Web service type: Bottom up Java bean Web Service
Service implementation: Assemble service
Configuration: Tomcat v7.0 Server, Web service runtime: Apache Axis2

The following folder/directory will be generated for the webservice deployment in axis2.
What the eclipse has done is that it copies all the axis2 library from the axis program into your project.
Without these import, objects/classes that depends on org.apache.axis2 library will have error.
This includes classes like ServiceLifeCycle and Lifecycle which maybe used in your webservice class.

Please take note that generated webservice directory may not have overwritten the previous/old webservice content.
To ensure that the webservice is the latest version, delete the whole "WebContent" folder before generating the updated webservices.

Another important file is also generated "services.xml" by the eclipse in the process. It is located in "projectNameXXX\WebContent\WEB-INF\services\serviceNameXXX\META-INF\services.xml". This file describe about the webservice interface and is important. Axis2 need this file in order to generate its *.wsdl file. *.wsdl file provides the details (xml format) for developer to interface to this webservice. Developer from various development platform can use this *.wsdl file to automatically generate function/method calls to invoke to this webservice easily. If you are building the webservice project from Ant build, remember to backup this services.xml file and include it in your *.aar package before you deploy as a service in axis2. If you are not using Ant, then you do not need to worry too much.

2) Now that the webservice structure is generated,
we copy the java webservice folder to the Tomcat\axis2.
"C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\axis2\WEB-INF\services\DoesMagic"

Take Note!!! For all resource files (example *.properties, *.log) used in a typical Java project (files loaded through the classloader()).
The files are usually store under \project\resource folder to store config, log, or properties.
They should be copied to the service/project root directory as follows,
C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\axis2\WEB-INF\services\DoesMagic
Common resource file to be accessed by all the services under axis2 (for example,
should be copy to the following axis2 directory,
C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\axis2\WEB-INF\classes\
This is the directory for axis program. The files has to be store under axis for the file retrieval.

- Alternative, you can archive the webservice project into a *.aar archive file for deployment to Tomcat Axis2 webservice's service directory. The file is like a jar file with a different *.aar extension for axis2 use. Deploymenting project in a single file unit is neater than deploying a project directory.
- Use the build program "Ant" to archive the webservice folder into a *.aar file and copy it to
C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\axis2\WEB-INF\services\. (refer to website for Ant implementation)

5) Run the Tomcat server. This will start up all servlets install in the Tomcat server. Axis2 will run, waiting for incoming webservice request. For this project example, our service name is "DoesMagic", method to invoke will be "doBasicStuff". The keyword for the data parameter/input of this webservice method will be "message".

6) The advantage of working with webservices is that the methods are self documented. The methods and the type of parameters required for any webservice will be provided. This information or documentation is found in the *.wsdl file.

The *.wsdl file contains all the methods (doBasicStuff) available on this webservice (DoesMagic). It even provides detail on the parameters (message) required by the method (doBasicStuff). The wsdl file though provides the webservice details but the real context of any complex input parameters will not be available. It will not tell you what the webservice is going to do when you call the method with its parameters. Therefore when we provide our webservice, it is necessary to design simple methods with meaningful names. This is the art of doing programming, and it can be abstract. I always have problem with this, and is still learning the art.

This *.wsdl file is important. With this file, your IDE is about to help you generate the methods/functions call available for your use in your client program. You might be using other programming language (for example C#, Visual C++), your own IDE should be able to help you generate the codes for used when coding your client program. This is possible because the *.wsdl contains all the information on how to invoke the webservice.

For example, I wrote the DoesMagic webservice using Java. You may be writing in C# wanting to invoke my webservice. In order for you to start using my webservice, I will need to give you my webservice address. From the address, you can querry the webservice *.wsdl file to learn about what the webservice offers.

The services offered by the webservice is now known. You can invoke directly by typing directly through the browser. Or you can ask your C# IDE to help you auto-generate the method interfaces; given the *.wsdl file. With this interface, your C# program will be able to invoke the webservice as if you are invoking any function call within the C#. In your programming codes, it may seems like calling a typical function, but it is calling a webservice.


1) To see the wsdl info:

From your web browser (Key in the following web address),

A short explaination,

"http://localhost:8080/", is the place where your tomcat server is located.

"axis2/", is the axis2 servlet running on the tomcat.

"services/", services directory will contain all the webservices currently running under your axis2.

"DoesMagic", is the webservice in this example.

"DoesMagic?wsdl", is the instruction given to the DoesMagic webservice, to querry about the webservice's methods and other details. The querry will respond back with the details in xml format to tell us more about this webservice (DoesMagic) interface.


2) After the DoesMagic?wsdl querry, you should be able to see the following response. These are the information regarding DoesMagic webservice.


wsdl example

Tips: Read the WSDL file from bottom to top.

In order of importance.

  1. service = "DoesMagicService" (webservice's name)
  2. service->port = "DoesMagic" (webservice access end point)
  3. service->port->location = "http://..../DoesMagic/services/DoesMagic"
  4. binding (overview)
  5. portType = "DoesMagic" (more details into the port)
  6. portType->operation = "doBasicStuff" (list of operation/function/methods available)
  7. portType->operation->input = "doBasicStuffRequest" ("section name" for the data to be send to the webservice, see the next section)
  8. portType->operation->output = "doBasicStuffResponse" ("section name" for the data to be reply from the webservice, see the next section)
  9. message (input parameters)

Go to the next few section below to read how to generate java client and run to call the webservce for this wsdl example.
7) Axis2 has a service running to help us to manage all its webservices. The services are listed, and you can also start & stop individual services, just like servlets running under Tomcat. You may need to manage the services running using axis2 with some of the classes like ServiceLifeCycle and Lifecycle, which are not covered here.

1) To see the services running in the Axis2 servlet:

From web browser (Key in the following web address),


8) Now we will test if our webservice DoesMagic works in our Tomcat server.

1) To test the webservice DoesMagic created

From web browser (Key in the following for the webservice through http request),

A short explaination,

"http://localhost:8080/", is the place where your tomcat server is located.

"axis2/", is the axis2 servlet running on the tomcat.

"services/", services directory will contain all the webservices currently running under your axis2.

"DoesMagic", is the webservice name.

"doBasicStuff", is a method from the webservice DoesMagic.

"?message=123", is the input parameter required by the doBasicStuff method. The keyword "message" must be the same as what is defined in the webservice.

Note 1:
If the webservice cannot have access to your java project's configuration/resource files, the following message may be return as the webservice result.

This XML file does not appear to have any style information associated with it. The document tree is shown below.
     <soapenv:Text xml:lang="en-US">unknown</soapenv:Text>

Note 2:
You might find that the following cannot work
For some reason, the input parameters as indicated on the *.wsdl files using "args0" instead of the name "message" when generating the wsdl file.
To ensure that the parameter is named as in what was written in the method, write the method in the following format using the @WebParm
public String doBasicStuff(@WebParam(name = "message")String message)
The following library is required "javax.jws.WebParam"


Another example of webservice with multiple parameters:

public class DoesMagic
    public String doBasicStuff2(String message, String name)
        return "This is your message: " + message;

From web browser (Key in the following for the webservice through http request),
&name=Siong Boon"

The parameters pass to the webservice are seperated by the '&' delimiter.

  I have this idea to write a standard function call like "help" for each and every webservice. It will be used to help user to learn using the webservice, and it can also have simple example to help test/troubleshoot the service. I think this additional service is will be helpful although the wsdl file is already available. The wsdl file is technically still quite difficult to completely understand the context of the webservice in used; additional help information can be very helpful.

Flex 3 client access to webservice

Now that the webservice is properly setup, I am going to create a flex project to allow the client to access the webservice that we have created.

1) Install Flex builder 3 development software.

2) Create a new flex project. Under the menu File>New>Flex project.

3) Get the flex builder to generate the functions for the access to our DoesMagic webservice.

Under the menu, select Data>Import Webservice (WSDL)...>
and select the flex project src folder, click next.
WSDL URI: "http://localhost:8080/axis2/services/DoesMagic?wsdl"
-The URI is the webservice that we have created earlier, running on tomcat server.
-Choose the service
    Service: "DoesMagic"
    Port: "DoesMagicHttpSoap11Endpoint"
    Operation: tick what ever method to be used by the flex mxml file
    Package: "generated.webservices" (default: where are the *.as files will be generated)
    Main class: "DoesMagic" (default: class name)
-a new folder generated.webservices will be generated with *.as actionscript files. These actionscript object & mthods are generated to allow access to the webservice. The access to these webservice will be as simple as a function call from our flex/actionscript. To the programmer it appear as the function call is executed locally but in fact is accessing the webservice.

Alternative method to invoke the webservice will be to use the dynamic webservice call approach. Methods are manually defined instead of auto generated through *.wsdl file. Here is the example ""

4) The example on the right demonstrate how the actionscript in a flex project access the webservice after the webservice actionscript has been auto generated programmer use. The actionscript is accessing the class's method DoesMagic.doBasicStuff, which is the webservice that we have created earlier. Example of how actionscript access the webservice:
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="" layout="absolute"
            import mx.controls.Alert;
            import generated.webservices.*;
            public function funcxyz():void
                var myService:DoesMagic=new DoesMagic();
                myService.doBasicStuff("123");               myService.adddoBasicStuffEventListener(myResultHandlingFunction);
            public function myResultHandlingFunction(data:DoBasicStuffResultEvent):void
5) Although the flex project is able to run properly in the flex builder IDE, it does mean it can be deploy properly. There will be still many things to troubleshoot. Next we will generate the html & flex necessary for our web deployment.

6) Deploy the flex project to the webserver
choose File>Export>Release Build...
Project: "your flex project name"
Application: "your main *.mxml file"
Export to folder: "bin-release"
A new bin-release will be generated.
Copy the files in the folder into the server's html hosting directory.
You can test if the build is working by clicking on it's html file. If you receive an error message stating that there is a security setting
violation or that the application can’t access a resource or asset, then you will need
to add a compiler setting that will allow you to access resources from the local file
system. Use the following steps to add the compiler setting.
In Flex Builder, right click on the flex project and select Properties from the menu.
• Select the Flex Compiler menu.
• Add a space and then -use-network=false to the complier arguments.
Redo the build process and test again.

7) Copying the web files to the following Tomcat web hosting directory.
C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\StarhomeWidget\pcadmin\Main.html


Access webservice using Java though RPC call method

There are many ways to access webservice. RPC is one of the methods. A Java example of RPC call is on the right.

Java client access to webservice


The instruction to build a client for webservice connection is all coded in the *.wsdl file. This makes client development simple.

There are 4 methods of creating webservice client.
- Static Stub (easy to implement)
- Dynamic Proxy (for portable, vendor-independent code)
- Dynamic Invocation Interfare (DII) (for use when *.wsdl file location is available only during runtime)
- Dynamic Discovery and Invocation (DDI) (self discovery)

The following section demonstrate how to setup a Java client for connection to a webservice through static stub method. Eclipse will be use to generate the stub (bare skeleton method). We will be able to use the stub as a method for access to the webservice.


2012-09-19 Using Eclipse to generate the client object for webservice access. I have tried the common Eclipse method for generating the client's code but fail. This is done through Eclipse>New>Web Services>Web Service Client. Basically you only need to supply the wizard with your *.wsdl file or URL, and it will generate the codes for you.

Instruction: 2012-09-19 Create a Web Service client using Eclipse.pdf

I have no sucessfully got this method to work. An error message dialog pops up whenever I try to run it. Error message "Exception occurred during code generation for WSDL : null". Happen to learn that there is another method to generate the stubs. The stubs is generated actually from the program "wsimport.exe" which can be found under the bin folder in your installed Java directory.

This method very direct and is easier, and I have got it done on my first trial.

Command example of generating the stubs from *.wsdl file/url
wsimport -keep -s ./src -p com.myfirst.wsClient -d ./build http://localhost:8080/axis2/services/PooWebservice?wsdl

You can run the wsimport with any parameter for help and explaination of the parameters.
-s specify the java source code folder (package/folder name of where the generated stubs will be located. Each webservice method will generate a class object)
-d specify the *.class folder
The last parameter is the path/url where your *.wsdl file is located. After running this program, the codes will be generated and they will be located under the project folder /src/com/myfirst/wsClient/

You can also use Ant script to run this wsimport, to generate your stubs.

How to generate Java code (client) from a WSDL file.

2016-05-19 Successfully generated Java client codes from wsdl file, and run.
  1. open the command prompt "cmd", go to the project directory "myProject/src"
  2. execute "wsimport -keep -p com.picControl.webservice.clientGeneratedCodes -verbose"
  3. A list of Java client codes will be generated in the project src folder. Each operation/method will generate 2 *.java file. Reference to the DoesMagic WSDL file, we have
    • doBasicStuff
    • doBasicStuffResponse
  4. Two addition file (most important) will be generated. This will be what the Java program call to have access to the generated doBasicStuff. Please refer to the DoesMagic WSDL file above to better relate to the following code. They are the ,
    •, (service = "DoesMagicService" (webservice's name))
    •, (service->port = "DoesMagic" (webservice access end point))
  5. Check the two generated files, if the service name, namespace and wsdl location are correct.
  6. The following code provide the reference to assess to the operation/method,

    DoesMagicService service = new DoesMagicService();"Retrieving the port from the following service: " + service);
    DoesMagic port = service.getDoesMagic();

Deploy the html files to the WAMPSERVER.
WAMPSERVER is typically used for hosting static HTML pages for port80. It also has a php (script) engine running. This is unlike a Tomcat server where it is used for hosting static webpage & servlet. WAMPSERVER can be deployed as the front end server, and be used to conceal link/mapped to other server service accessible from other communication port.

The root directory for the web hosting
is located at D:\wamp\www\index.html
When we access a web domain for example,
the index.html file will be loaded.

The default file to load can be configured
in the following file,

<Directory "D:/wamp/www/">
<IfModule dir_module>
    DirectoryIndex index.html index.htm index.php index.php3

These define the root directory and also the default file
to load if it is not specified.
For website, the default file is usually index.html

Setting up LCDS (LiveCycle Data Services) for Flex project
1) copy "ds-console.war" & "lcds.war"
to C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\
2) Execute C:\Program Files\Apache Software Foundation\Tomcat 7.0\bin\tomcat7.exe
Project folders will be setup under C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\
- ds-console.war
- lcds.war

Other references on webservice:

- (NTU website on webservice), Java Web Services (by Chua Hock Chuan).pdf