WsdlCustomizer - NetBeans Wiki

WsdlCustomizer

WSDL Customization in Netbeans

Contents


   The JAX-WS specification defines standard XML-based customization for WSDL to Java mapping and to control certain
   features. These customizations, or binding declarations, can customize almost all WSDL components that can be mapped to
   Java, such as the service endpoint interface class, method name, parameter name, exception class, etc. The other important
   thing you can do with these binding declarations is control certain features,such as asynchrony, provider, wrapper style,
   and additional headers. For example, a client application can enable asynchrony for a particular operation in a portType
   or all operations in a portType or all portType operations defined in the WSDL file. 
   You can find another information here



   In Netbeans the WSDL customization is enabled for two different cases - Web Service clients and Web services from WSDL
   file. It could be done by three different means - embedded in WSDL file, in external file binded to client/service or in
   WSDL customizer provided by NetBeans. We will concentrate here on WSDL customizer, which is simplest of ways, how to 
   do customization.We will describe all customization scenarios,although customizer doesn't support them all. WSDL
   Customizer is identical for both use cases, so we will describe here only one - Web service client case. Prerequisites are
   that you have created Web service client on web service. Go to Projects tab and right click on web service node under Web
   Service references. Select Edit Web Service Attributes and click mouse button. WSDL Customizer dialog window will appear.


  • WSDL customizer: 
   Image:dialog_WsdlCustomizer.png



WSDL customizer features


  • Declaring customizations
  • External Binding Declaration
  • Embedded Binding Declarations


  • Standard customizations supported by Customizer
  • Global bindings
  • Package Customization
  • Wrapper Style
  • Asynchrony
  • Class Customization
  • Java Method Customization


  • Standard customizations not supported by Customizer
  • The Provider Interface
  • Java Parameter Customization
  • Javadoc customization
  • XML Schema Customization
  • Handler Chain Customization



Declaring customizations


   All the binding declaration elements live in http://java.sun.com/xml/ns/jaxws namespace. There are two ways to specify
   binding declarations. In the first approach, all binding declarations pertaining to a given WSDL document are grouped
   together in a standalone document, called an external binding file. The second approach consists of embedding binding 
   declarations directly inside a WSDL document. In either case, the jaxws:bindings element is used as a container for JAX-WS
   binding declarations. 
   The jaxws prefix maps to the http://java.sun.com/xml/ns/jaxws namespace.


External Binding Declaration 


   External binding files are semantically equivalent to embedded binding declarations. When wsimport processes the WSDL 
   document for which there is an external binding file, it internalizes the binding declarations defined in the external
   binding file on the nodes in the WSDL document they target using the wsdlLocation attribute. The embedded binding 
   declarations can exist in a WSDL file and an external binding file targeting that WSDL, but wsimport may give an error if,
   upon embedding the binding declarations defined in the external binding files, the resulting WSDL document contains
   conflicting binding declarations.
   In Netbeans you can specify external binding file in property External Binding Files of customization dialog .



   * External Binding Files:


Image:extbind_WsdlCustomizer.png

Embedded Binding Declarations


   Embedded binding declarations follow different rules compared to the binding declarations declared in the external binding
   file. Here are some important facts and rules as defined in the JAX-WS specification:


  • An embedded binding declaration is specified by using the jaxws:bindings element as a WSDL extension.
  • When a jaxws:bindings element is used as a WSDL extension, it must not have a node attribute.
  • The binding declaration must not have a child element whose qualified name is jaxws:bindings.
  • A binding declaration embedded in a WSDL can only affect the WSDL element it extends. 


   Here's an example of embedded binding declarations in the WSDL AddNumbers.wsdl from the inline-customize sample:



 <tt><wsdl:portType name="AddNumbersImpl">
    <!-- wsdl:portType customizations -->
    <jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
        <!-- rename the generated SEI from AddNumbersImpl to MathUtil -->
        <jaxws:class name="MathUtil"/>
        ...
    </jaxws:bindings>
    <wsdl:operation name="addNumber">
    ...
</wsdl:portType></tt>


The above WSDL file excerpt shows the wsdl:portType customization. jaxws:bindings appears as extension element of portType. It customizes the class name of the generated service endpoint interface. Without this customization, or by default, the service endpoint interface class is named after the wsdl:portType name. The binding declaration jaxws:class customizes the generated class to be named MathUtil instead of AddNumberImpl.

  • Embedded binding in NB since 5.5:


Image:embbind_WsdlCustomizer.png 

  The so-called "mime content" is an attachment mechanism that provides additional metadata as to how the wsdl type is bound to Java. In the
  binding section of the wsdl, if the mime part is qualified with mime:content information, the user has the option of using this information to
  tell wsimport what types to generate. Let us take an example of an operation that sends binary data (e.g., xsd:base64Binary). Further, in the 
  binding section, it is qualified as a mime multipart-related with mime-content information that says that the type can be a GIF file. If Enable
  MIME Content is set to false, the data will be bound to a byte array. If Enable MIME Content is set to true, wsimport will use the information 
  in the mime:content portion of the binding section and bind it to java.awt.Image.
  As with wrapper style, if Enable MIME Content is set at the Global level, it is in effect at all binding operations of the wsdl. Similarly, it 
  can be overridden at the Binding level, and at a finer granularity at the binding operation level.




Standard customizations supported by Customizer


Global bindings


   The global customizations are the customizations that applies to the entire scope of wsdl:definition in the wsdl
   referenced by the roo jaxws:bindings@wsdlLocation.Following customizations have the global scopes:


  • Package name
  • Wrapper style
  • Asynchronous mapping 


* You can find them in customization dialog here::


Image:global_WsdlCustomizer.png

Package Customization


  By default wsimport generates WSDL artifacts in a package computed from the WSDL targetNamespace. For example, a WSDL file
  with the targetNamespace  http://duke.example.org without any package customization will be mapped to the org.example.duke
  package. To customize the default package mapping you would use a jaxws:package customization on the wsdl:definitions node
  or it can directly appear inside the top level bindings element. In Netbeans customizer you can customize package only in 
  Global settings parameter decribed in previous case.



Wrapper Style


  This controls the way the parameter types and return types of a wsdl  operation are generated. If there is no customization, wsimport
  generates using the wrapper style (hence this is on by default). Getting an example from the spec, let's say an operation has one input message
  named setLastTradePrice and output message named setLastTradePriceResponse. Furthermore, say, the part in the setLastTradePrice is really made
  up of two primitive types: a string and a float.
  With non-wrapper style, wsimport will generate the following Java code:


        SetLastTradePriceResponse setLastTradePrice( SetLastTradePrice setLastTradePrice);



  With wrapper style, wsimport will generate the following Java code: 


        void setLastTradePrice(String tickerSymbol, float lastTradePrice);


  As you can see, with the wrapper style, the method parameters were broken down to its components.
  Thus, specifying wrapper or non-wrapper style is dependent on the coding style of the developer.



  In NB5.5 customizer are available these three cases of wrapper style settings :


  • Global scope - in Global bindings
  • Port type - in Port Type
  • Operation - in Port Type Operations



Asynchrony


   A client application can use the jaxws:enableAsyncMappingbinding declaration so that wsimport will generate async polling
   and callback operations along with the normal synchronous method when it compiles a WSDL file. This is how the generated
   signatures look (annotations are removed from synchronous method for reading simplicity):



//synchronous method
    public int addNumbers(int number1, int number2) throws
        org.duke.AddNumbersFault_Exception,  java.rmi.RemoteException;
    //async polling Method
    public Response<AddNumbersResponse> addNumbers(int number1, int number2);
    //async callback Method
    public Future<?> addNumbers(int number1, int number2, AsyncHandler<AddNumbersResponse>);
...

   It has the same cases of settings as the wrapper style binding declaration described above :


  • Global scope - in Global bindings
  • Port type - in Port Type
  • Operation - in Port Type Operations


Class Customization


   The generated class for wsdl:portType, wsdl:fault, soap:headerfault, and wsdl:server can be customized using the
   jaxws:class binding declaration.



  • The Service Endpoint Interface Class:


Image:porttype_WsdlCustomizer.png

  • The Service Class:


Image:services_WsdlCustomizer.png

  • The Exception Class - this customization is available only when there's a service in WSDL file, which could throw 
                          exception.png ]



Java Method Customization


   The jaxws:method binding declaration is used to customize the generated Java method name of a service endpoint interface
   and to customize the port accessor method in the generated Service class.


  • Service Endpoint Interface Methods


Image:porttypeops_WsdlCustomizer.png

  • Port Accessor Methods in the Service Class


Image:portaccmethods_WsdlCustomizer.png



The Provider Interface


   By default the value of jaxws:provider binding is false. That is, provider interface generation is disabled.
   In order to mark a port as provider interface this binding declaration should refer to the wsdl:port node using 
   an XPath expression. Please note that provider binding declaration applies only when developing a server starting from a 
   WSDL file.

   Provider interface option is accessible in WSDL Customizer only for web services from WSDL, not WS clients.




   Image:provider_WsdlCustomizer.png




Standard customizations not supported by Customizer


   These customizations aren't accessible by WSDL customizer and could be used only in WSDL document or in external file.



Java Parameter Customization


   The jaxws:parameter binding declaration is used to change the parameter name of generated Java methods. It can be used to 
   change the method parameter of a wsdl:operation in a wsdl:portType    



<bindings node="wsdl:definitions/wsdl:portType[[@name=AddNumbersImpl | @name='AddNumbersImpl']]/wsdl:operation[@name=addNumbers]">
       <!-- rename method parameters-->
        <parameter part="definitions/message[[@name=addNumbers | @name='addNumbers']]/part[@name=parameters]" element="tns:number1" name="num1"/>
...


Javadoc customization


   Jaxws:javadoc customization can be used to specify javadoc text for java package, class(SEI, Service or Exception class) 
   and on the methods in SEI and service class. Inorder to do it,it should appear on the corresponding wsdl nodes. 



For package level javadoc:

<jaxws:package name="xs:string">?
<jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:package>

For class level javadoc:

<jaxws:class name="xs:string">?
<jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:class>

For method level javadoc:

<jaxws:method name="xs:string">?
<jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:method>

XML Schema Customization


   An XML schema inlined inside a compiled WSDL file can be customized by using standard JAXB bindings. These JAXB bindings 
   can live inside the schema or as the child of a jaxws:bindings element in an external binding declaration file. 




<jaxws:bindings node="wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace=http://duke.example.org]">
        <jaxb:schemaBindings>
            <jaxb:package name="fromwsdl.server"/>
       </jaxb:schemaBindings>
   </jaxws:bindings>

   External XML schema files imported by the WSDL file can be customized using a JAXB external binding declaration file:

<jxb:bindings
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
    version="1.0">
    <jxb:bindings schemaLocation="http://localhost:8080/jaxws-external-customize/schema1.xsd" node="/xsd:schema">
        <jxb:schemaBindings>
            <jxb:package name="fromjava.client"/>
        </jxb:schemaBindings>
    </jxb:bindings>
...


Handler Chain Customization


   jaxws:bindings customization can be used to customize or add handlers. All that is needed is to inline a handler chain 
   configuration conforming to JSR 181 Handler Chain configuration schema inside jaxws:bindings element. 
   Below is a sample JAX-WS binding declaration file with JSR 181 handler chain configuration: 

<jaxws:bindings
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="http://localhost:8080/jaxws-fromwsdlhandler/addnumbers?WSDL"
    xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
   xmlns:javaee="http://java.sun.com/xml/ns/javaee">
    <jaxws:bindings node="wsdl:definitions">
        <javaee:handler-chain>
            <javaee:handler-chain-name>LoggingHandlers</javaee:handler-chain-name>                    
            <javaee:handler>
                <javaee:handler-name>Logger</javaee:handler-name>
                <javaee:handler-class>fromwsdlhandler.common.LoggingHandler</javaee:handler-class>          
            </javaee:handler>                        
        </javaee:handler-chain>
    </jaxws:bindings>
</jaxws:bindings>



   Although Handler Chain Customization is not one of the sections in the WSDL Customization editor, in NetBeans it's actually used
   internally when we configure handlers for clients. You can customize handlers 
   in dialog opened after clicking on Configure Handlers in context menu from the web service / client node, and in the case of the client,
   handler chain customization is happening under the covers.









Retrieved from "http://wiki.netbeans.org/WsdlCustomizer"
Not logged in. Log in, Register

NetBeans Wiki
By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo