Once the WSDL that describes your endpoint is complete, you can use the command-line wsdl2java tool to generate all of the code needed to either implement and deploy and endpoint or create a proxy to an endpoint. Below are examples for generating endpoints for OSGi and J2EE environments; each example also describes how to leverage both the Apache Axis2 and Mini SOAP engines in those environments. For more information on wsdl2java, including options on customizing the deployment descriptors and creating endpoints with multiple resource-types, see the wsdl2java reference documentation.

To generate an Axis2-based project that can be built into a deployable WAR file, run wsdl2java as follows:

wsdl2java -j2ee axis2 -wsdl pathToWSDLFile

Above, pathToWSDLFile should be replaced with the absolute or relative filesystem path to the location of the WSDL document you created. You can switch from Axis2 to the Mini SOAP Engine by replacing axis2 with mini.

After the tool has completed successfully run, the following structure will be created in the current directory (which may not be the directory where the wsdl file resides):

• /JavaSource - contains all of the generated source code. For each capability, the namespace URI of that capability will be turned into a package name (if possible) and there will be two .java files created:
  • IMyCapability.java
  • MyCapability.java
  The first file is an interface that has all of the methods of the capability. The second is a concrete implementation of the interface that has code that might need to be altered (see below).


• /WebContent - contains an expanded web archive that is ready to be deployed when the generated code is compiled and put into /WebContent/WEB-INF/lib. This compilation and packaging step is automatically handled for you by the generated Ant script (see below). This directory contains several other artifacts which are covered in the next section. Below is information about how the input to wsdl2java is carried forward into the generated structure:
  
  
  • /WEB-INF/classes - contains all of the meta information about the generated endpoint, as well as any files that you want to read from disk as part of your implementation.
    
    
    • /wsdl - the WSDL that was passed into the tool is consolidated into one file (if it was split among several files using <wsdl:import/> or <xsd:import/> and copied to this directory. See the WSDL2Java FAQ for more information about why this transformation is made.
      
    
    
    • /router-entries - by default, when the endpoint starts up, we want at least one end point to exist so that we can interact with it. The tooling will create a single endpoint persistence entry. This is not important until the resource is deployed and you are trying to connect to it. You can find further explanation here.
      
    
    
    • /muse.xml - this file is also generated based on the capabilities found in the WSDL. See the next section for more information.
      
    
    
  • /WEB-INF/services/muse/META-INF/services.xml - this file is generated based on the operations that are defined in the WSDL descriptor. The next Axis2 section will explain this in more detail.
    
  
  
• /build.xml - the ant build file script which has a default target that will compile everything in /JavaSource package it into a jar file, copy it to /WebContent/WEB-INF/lib and then package all of /WebContent into a WAR file that is ready to be deployed on a J2EE server.


• /.overwrite - a list of files generated by wsdl2java that do not contain user code. Any file named in this manifest will be overwritten by default if the wsdl2java tool is run targetting this directory and the file already exists. For more information see the reference documentation.

Before invoking Ant there might be several actions you must take:

• Fill in generated methods with business logic - The generated code in /JavaSource contains skeleton methods that have no implementation. These methods are marked with "TODO" comments and throw RuntimeException exceptions since they have no implementation. You must add implementation code for these methods.


• Provide default values for non-primitive types - if your WSDL defines properties that are non-primitive types, these properties will need to be initialized IF their minOccurs is set to at least 1. Every property is generated as a private member variable of the implementing class, hovever it leaves the property uninitialized. For primitive types (remember String is not a primitive type) Java defines a reasonable default. However, for non-primitive types this default is null. When the resource is initialized, its properties are validated against the properties document schema. If a non-primitive property must occur at least once, according to the schema, and the default value (ie. null) has not been changed, the runtime will detect 0 occurences of the property and throw a BelowMinimum runtime exception.

The actions could very well be optional if your WSDL file does not define any non-standard operations or properties. If this is the case, the Muse runtime will simply use its built-in implementation of the standard capabilities to perform the requests.

After the above steps are complete, you are ready to build the WAR file. Simply invoke:

ant

in the current directory and your WAR file will be created in the current directory.

Quite a few things can be gathered from the WSDL desriptor, but some must be guessed. The name of the jar file that is built containing all of the compiled, generated code and the name of the WAR file that is ultimately created by the build is taken from the name of the current directory. For example, if the current directory is:

c:\workspace\myMuseWork\samples\theSample

Then the corresponding jar and WAR file would be:

• theSample.jar
• theSample.war

To generate an Axis2-based project that can be built into a deployable OSGi bundle, run wsdl2java as follows:

wsdl2java -osgi axis2 -wsdl pathToWSDLFile

Above, pathToWSDLFile should be replaced with the absolute or relative filesystem path to the location of the WSDL document you created. You can switch from Axis2 to the Mini SOAP Engine by replacing axis2 with mini.

After the tool has completed successfully run, the following structure will be created in the current directory (which may not be the directory where the wsdl file resides):

• /src - contains all of the generated source code. For each capability, the namespace URI of that capability will be turned into a package name (if possible) and there will be two .java files created:
  • IMyCapability.java
  • MyCapability.java
  The first file is an interface that has all of the methods of the capability. The second is a concrete implementation of the interface that has code that might need to be altered (see below).


• /config - contains all meta information about the generated endpoint


• /muse.xml - this file is also generated based on the capabilities found in the WSDL. See the next section for more information.


• /config.ini - this is a configuration for the Eclipse-OSGi runtime, it defines which bundles should be started and sets properties for the framework. The file contains a placeholder that is filled in during the build process. This placeholder is replaced with a comma-separated list of all of the plugins that are present in the /plugins directory.


• /MANIFEST.MF - the OSGi bundle manifest. Contains information about the bundle including which bundles it depends on.


• /lib - contains jars that are necessary for compilation, these are jars from modules and common libraries in the distribution so that the project is self-contained


• /plugins - contains all of the necessary plugins needed to deploy the endpoint. In contrast to the Axis2 J2EE case, using OSGi we create a self-contained environment that has all you need to launch the endpoint.


• /router-entries - by default, when the endpoint starts up, we want at least one end point to exist so that we can interact with it. The tooling will create a single endpoint persistence entry. This is not important until the resource is deployed and you are trying to connect to it. For a further explanation see here.


• /wsdl - the WSDL that was passed into the tool is consolidated into one file (if it was split among several files using "wsdl:import" or "xsd:import") and copied to this directory. See the FAQ for more information about why this transformation is made.


• /build.xml - the ant build file script which has a default target that will compile everything in /src package it into a directory in plugins.


• /.overwrite - a list of files generated by wsdl2java that do not contain user code. Any file named in this manifest will be overwritten by default if the wsdl2java tool is run targetting this directory and the file already exists. For more information see the reference documentation.

Before invoking Ant there might be several actions you must take:

• Fill in generated methods with business logic - The generated code in /src contains skeleton methods that have no implementation. These methods are marked with "TODO" comments and throw RuntimeException exceptions since they have no implementation. You must add implementation code for these methods.


• Provide default values for non-primitive types - if your WSDL defines properties that are non-primitive types, these properties will need to be initialized IF their minOccurs is set to at least 1. Every property is generated as a private member variable of the implementing class, hovever it leaves the property uninitialized. For primitive types (remember String is not a primitive type) Java defines a reasonable default. However, for non-primitive types this default is null. When the resource is initialized, its properties are validated against the properties document schema. If a non-primitive property must occur at least once, according to the schema, and the default value (ie. null) has not been changed, the runtime will detect 0 occurences of the property and throw a BelowMinimum runtime exception.

The actions could very well be optional if your WSDL file does not define any non-standard operations or properties. If this is the case, the Muse runtime will simply use its built-in implementation of the standard capabilities to perform the requests.

After the above steps are complete, you are ready to build the WAR file. Simply invoke:

ant

in the current directory and your bundle will be created in the /plugins directory.

This option will be useful later on in the tutorial, but since it uses wsdl2java it is included here. To generate a project that can be built to create jar that is contains a Proxy that handles interaction with an endpoint described by the WSDL descriptor, run wsdl2java as follows:

wsdl2java -proxy -wsdl pathToWSDLFile

Above, pathToWSDLFile should be replaced with the absolute or relative filesystem path to the location of the WSDL document you created.

After the tool has completed successfully run, the following structure will be created in the current directory (which may not be the directory where the wsdl file resides):

• /src - contains a class and an interface that abstracts that class. The class name will end in "Proxy" and the interface will be the name without the "Proxy" suffix.


• /lib - contains jars that are necessary for compilation, these are jars from modules and common libraries in the distribution so that the project is self-contained


• /build.xml - the ant build file script which has a default target that will compile everything in /src package it into a jar that can be used in other projects to connect to the endpoint.


• /.overwrite - a list of files generated by wsdl2java that do not contain user code. Any file named in this manifest will be overwritten by default if the wsdl2java tool is run targetting this directory and the file already exists. For more information see the reference documentation.

After the above steps are complete, you are ready to build the WAR file. Simply invoke:

ant

in the current directory and your jar will be created in the current directory.