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:
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:
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:
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::
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:
- The Service Class:
- 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
- Port Accessor Methods in the Service Class
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.
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.
Attachments
- Media:embbind_WsdlCustomizer.PNG
- Media:global_WsdlCustomizer.PNG
- Media:porttype_WsdlCustomizer.PNG
- Media:services_WsdlCustomizer.PNG
- Media:extbind_WsdlCustomizer.PNG
- Media:dialog_WsdlCustomizer.PNG
- Media:fault_WsdlCustomizer.PNG
- Media:portaccmethods_WsdlCustomizer.PNG
- Media:porttypeops_WsdlCustomizer.PNG