Simple question about Unwrapped and Wrapped SOAP messages/WSDLs

[Jason Irwin]

This is so simple I am almost embarrassed to ask.

On page 44 of "Java Web Services Up and Running" by Martin Kalin, there is an example Unwrapped document style SOAP message that looks like this

<soapenv:Envelope xmlns...>
    <soapenv:Body>
        <num1 xmlns...>27<num1>
        <num1 xmlns...>94<num1>
    </soapenv:Body>
</soapenv:Envelope>

The question I have is, how can that possible be valid? When I try to create and publish a simple method to match that message in the Unwrapped (BARE) style, I get an exception like this: "...has method increment annotated as BARE but it has more than one parameter bound to body. This is invalid. Please annotate the method with annotation..."

@SOAPBinding(style=ParamterStyle.BARE)
public int addNums(int num1, int num2)
{
  return num1+num2;
}

All the examples I have seen about the Unwrapped/BARE style use methods with one parameter, but I can find no explanation on why that is a limitation. And if it is, surely that means the example on page 44 is wrong?

Thanks.

[R Srini]

Hi. No. Please don't be embarrassed to ask. This is not a trivial question once you start going into it in detail. To quote from Martin Kalin's excellent book (italics are mine):

JWS names the attribute parameterStyle because the contrast between wrapped and unwrapped in document-style web services comes down to how parameters are represented in the SOAP body.

Also:

What may be surprising is that the structure of the underlying SOAP messages, both the request and the response, remain unchanged.

And:

The key difference is in the Java client code, of course. The simplified client, with the unwrapped parameterStyle, calls invokeSearch with one argument of type ItemSearch and expects a single response of type ItemSearchResponse. So the parameterStyle with a value of BARE eliminates the complicated call to invokeSearch with 10 arguments, 8 of which are arguments bound to the subelements in the @RequestWrapper, and 2 of which are arguments bound to subelements in the @ResponseWrapper.

Of course I am quoting from the book, but it is pretty clear to me that what changes is the programming model. Please see here for another good high-level explanation. This might help too.

And here in the Oracle javadoc for SOAPBinding, it says that parameterStyle:

Determines whether method parameters represent the entire message body, or whether the parameters are elements wrapped inside a top-level element named after the operation

This article and also this one explain the programming model in a lot of detail in case you are interested.

Hope that helps somewhat. Lots of articles. Happy reading!

[Jason Irwin]

Thanks, I have read those but I still don't understand how the exmaple Unwrapped SOAP message on page 44 can possibly be valid. It still seems to me that an Unwrapped (BARE) method can only have one parameter at most.

So either the example as shown is wrong, or I am really not getting what should be a very basic concept. I don't want to progress further through material without getting the basic theory first and this Unrwapped exmaple on page 44 has completely thrown me.

[R Srini]

Ok. Lets go slowly, one point at a time..

Bare vs wrapped:
- What is it that is wrapped? The parameters.
- Where are they wrapped? The parameters are wrapped/enclosed in the XML by the function/method/operation name in the WSDL - not in the Java code.
- Whether bare or wrapped, your method signature "public int addNums(int num1, int num2)" remains the same. You can have as many parameters as you like in the bare style.
- The bare and wrapped styles are equivalent. Some people prefer the bare style, while others prefer the wrapped style. The SOAPBinding annotation determine which style of code gets generated.
- When [Java] code is generated for the bare style, it is generated with just one parameter, and the actual multiple parameters are inside it and set using setters before invoking the web service.
- When [Java] code is generated for the wrapped style, it is generated with multiple parameters, one for each parameters. When invoking the web service, all of the parameters are passed explicitly.
- As far as I can tell, bare vs wrapped are merely conventions for different ways of calling a web service. One is not better than the other, generally speaking. It is a matter of preference, and different people will argue differently to suit their preference.
- Whether a given SOAP message is valid is determined by the WSDL that it conforms to. So, both the examples 2-8 (unwrapped) and 2-9 (wrapped) have to be viewed within the context of their respective WSDLs. Examples 2-8 and 2-9 would have different WSDLs, and I could not find the WSDLs mentioned in the book. So that may be the source of your confusion, but both of the requests are nevertheless valid in their context.

So finally, regarding your question:

All the examples I have seen about the Unwrapped/BARE style use methods with one parameter, but I can find no explanation on why that is a limitation. And if it is, surely that means the example on page 44 is wrong?

It is not a limitation. Web services using the bare style can surely have multiple parameters. Its is only the actual invocation of the web service where a single parameter is passed. Its in the programming.
LOL. Does the help clear it a bit? If not, please explain your reasoning in some more detail.

I don't want to progress further through material without getting the basic theory first and this Unrwapped example on page 44 has completely thrown me.

I think you have chosen an excellent book to get started with web services. If after reading and understanding it thoroughly, you work through the tutorials, you will breeze through them. In my view this is the best approach to learn this stuff. All the best

[Jason Irwin]

Firstly, thanks for your patience!

R Srini wrote:Bare vs wrapped:
- What is it that is wrapped? The parameters.
- Where are they wrapped? The parameters are wrapped/enclosed in the XML by the function/method/operation name in the WSDL - not in the Java code.
- The bare and wrapped styles are equivalent. Some people prefer the bare style, while others prefer the wrapped style. The SOAPBinding annotation determine which style of code gets generated.
- When [Java] code is generated for the bare style, it is generated with just one parameter, and the actual multiple parameters are inside it and set using setters before invoking the web service.
- When [Java] code is generated for the wrapped style, it is generated with multiple parameters, one for each parameters. When invoking the web service, all of the parameters are passed explicitly.
- As far as I can tell, bare vs wrapped are merely conventions for different ways of calling a web service. One is not better than the other, generally speaking. It is a matter of preference, and different people will argue differently to suit their preference.

I totally get that, or that that is how it should be. At the moment I am writing all the code (client and sever) by hand to try and understand, at a basic level, what is going on before relying on wsimport etc.

- Whether bare or wrapped, your method signature "public int addNums(int num1, int num2)" remains the same. You can have as many parameters as you like in the bare style.
- Whether a given SOAP message is valid is determined by the WSDL that it conforms to. So, both the examples 2-8 (unwrapped) and 2-9 (wrapped) have to be viewed within the context of their respective WSDLs. Examples 2-8 and 2-9 would have different WSDLs, and I could not find the WSDLs mentioned in the book. So that may be the source of your confusion, but both of the requests are nevertheless valid in their context.

I would like to agree and this is why I decided to write a simple service that would add two numbers (shown below). I wanted to be able to change the style so I could compare the WSDLs and observe the changes in SOAP messages etc. That's when I found out that a web service using the Unwrapped style cannot have more than one parameter. This got me really confused about example 2.8 as I could simply find no way of writing a service that that message could possibly be sent to.

Server

package SoapStyles;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;

import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.ParameterStyle;
import javax.xml.ws.Endpoint;

@WebService(endpointInterface = "SoapStyles.IMathServer")
public class MathServer implements IMathServer
{
	@Override
	public int addNums(int num1, int num2)
	{
		return num1+num2;
	}

	public static void main(String[ ] args)
	{
		Endpoint.publish("http://localhost:1111/MathServer", new MathServer());
	}
}

@WebService
//If the next line is uncommented, the service cannot be published
//@SOAPBinding(parameterStyle = ParameterStyle.BARE)
interface IMathServer
{
	@WebMethod
	int addNums(@WebParam(name="num1") int num1, @WebParam(name="num2") int num2);
}

Client

package SoapStyles;

import java.net.URL;

import javax.xml.namespace.QName;
import javax.xml.ws.Service;

public class MathClient
{
	public static void main(String[] args) throws Exception
	{
		URL url = new URL("http://localhost:1111/MathServer?wsdl");

		QName qname = new QName("http://SoapStyles/", "MathServerService");

		Service service = Service.create(url, qname);

		IMathServer eif = service.getPort(IMathServer.class);

		System.out.println("1+1= " + eif.addNums(1,1));
	}
}

Error if you try to use the BARE (Unwrapped) style.

Exception in thread "main" com.sun.xml.internal.ws.model.RuntimeModelerException: runtime modeler error: 
SEI SoapStyles.MathServer has method addNums annotated as BARE but it has more than one parameter bound to body. This is invalid. 
Please annotate the method with annotation: @SOAPBinding(parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

Maybe I have managed to confuse two separate (but possibly related) concepts in my head and am asking a confusing question but if what you say is true, then it should be really easy to write a server/client to get an instance of the message in example 2.8 in use.

Addendum
If I use the "header=true" value in the WebParam annotations, I can use multiple parameters as they get placed into the header. But this still doesn't show me how the example on page 44 with multiple child elements in the SOAP body can ever be used to call a web service.

[Ivan Krizsan]

Hi!
The WS-I Basic Profile limits the number of child elements to the SOAP <Body> element to zero or one.
Reference: http://www.ws-i.org/Profiles/BasicProfile-1.1.html#SOAP_Envelope_Structure
Thus bare, or non-wrapped, services may have zero or one parameter.
Best wishes!

[Jason Irwin]

Thanks Ivan, but I as I am running Java 6 thought I was using Soap 1.2 which can have multiple child elements.

Uhh...wait...the WS-I has further restrictions. So although SOAP can handle more data, the WS-I doesn't allow that (not in 1.1 at least). Would that be a fair summary?

So whilst example 2.8 (with multiple child elements in the SOAP body) is valid SOAP, it is invalid for calling a WS-I method.
So, really, it has no place in a book about Java Web Services. Would that be fair say?

I ran the server shown above and used "wsimport" to create 2 sets of stub classes. One Wrapped and one forced to be Bare via a JAXWS xml file (as shown on page 53).
I then wrote some test code against those and ran it, using Wireshark to capture the messages.
The SOAP messages sent looked identical. No difference at all. Now I am truly stumped.

To be honest if I can't bet past page 45 without being totally confused and lost, there's not much hope for me in ever understanding this!

[R Srini]

Jason. You don't give up easily, do you? Ok. Since this is not obvious stuff, lets spell this out. Here is the working code. Please check the differences, line by line, with your original code and you will see it for what it is.

// MyNumbers.java
package SoapStyles;

public class MyNumbers {
    private int num1;
    private int num2;
    public MyNumbers() {}
    public MyNumbers(int num1, int num2) { this.num1=num1; this.num2=num2;}
    public int getNum1() { return num1; }
    public void setNum1(int num1) { this.num1 = num1; }
    public int getNum2() { return num2; }
    public void setNum2(int num2) { this.num2 = num2; }
}

// IMathServer.java
package SoapStyles;

import javax.jws.WebService;
import javax.jws.WebParam;
import javax.jws.WebMethod;
import javax.jws.soap.SOAPBinding;

@WebService
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
// the following is equivalent to the above as doc/literal is the default unless we specify otherwise in the code
//@SOAPBinding(style=SOAPBinding.Style.DOCUMENT, parameterStyle = SOAPBinding.ParameterStyle.BARE, use=SOAPBinding.Use.LITERAL)
interface IMathServer
{
	@WebMethod
	int addNums(@WebParam(name="myNumbers") MyNumbers myNumbers);
}

// MathServer.java
package SoapStyles;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;

import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.ParameterStyle;
import javax.xml.ws.Endpoint;

@WebService(endpointInterface = "SoapStyles.IMathServer", targetNamespace="http://SoapStyles/")
public class MathServer implements IMathServer
{
	@Override
	public int addNums(MyNumbers myNumbers)
	{
		return myNumbers.getNum1() + myNumbers.getNum2();
	}

	public static void main(String[ ] args)
	{
		Endpoint.publish("http://localhost:1111/MathServer", new MathServer());
	}
}

// MathClient.java
package SoapStyles;

import java.net.URL;

import javax.xml.namespace.QName;
import javax.xml.ws.Service;

public class MathClient
{
	public static void main(String[] args) throws Exception
	{
		URL url = new URL("http://localhost:1111/MathServer?wsdl");

		QName qname = new QName("http://SoapStyles/", "MathServerService");

		Service service = Service.create(url, qname);

		IMathServer eif = service.getPort(IMathServer.class);

		System.out.println("1+1= " + eif.addNums(new MyNumbers(1,1)));
	}
}

To compile, run this in the SoapStyles directory: javac IMathServer.java MathServer.java MathClient.java MyNumbers.java
Run from SoapStyles' parent directory: java SoapStyles.MathServer

The addNums method has only one parameter. However, the parameter contains the other parameters inside of it. The WSDL at http://localhost:1111/MathServer?wsdl won't make much sense compared to the default wrapped WSDL, but AFAIK, this is how the bare style works. More experienced folks can correct me if I am wrong.

So, really, it has no place in a book about Java Web Services. Would that be fair say?

In my opinion, no, it is not fair to say that. In fact, one of the reasons I love Martin Kalin's book is that it starts from the simple, barebones stuff, explains it, and then builds on it. After finishing the book, you will, for the most part understand the nuts and bolts of how web services work, and the type of programming that goes on under the hood. As you can see, it took quite a bit of reading, analysis and experimenting to properly understand just this one concept of bare vs wrapped. So it is not so simple - not difficult, but not trivial either.

To be honest if I can't bet past page 45 without being totally confused and lost, there's not much hope for me in ever understanding this!

We will get you past page 45 - by hook or by crook Hang in there. Its just that a lot of this is arcane or not commonly used or simply unfamiliar, and if its not commonly used, its hard to find examples on the web. So it takes some experimenting to get some of it to work. Best of luck!

[Ivan Krizsan]

Hi again!
Good words again from Srini (sorry, I cannot write the initial letter of the first name since the forum thinks I am trying to be lazy)!
I just wanted to add a clarification regarding the WS-I Basic Profile:
First there are the XML, SOAP and WSDL standards. These standards are, like most everything else, not without flaws.
After some time of experience with the above standards, people noticed some problems that occurred more frequently and realized that the above standards were unclear, and sometimes even conflicting, in some areas. Thus the WS-I Basic Profile was born - it contains recommendations that are intended to reduce the impact of less clear areas in and conflicts between the standards.

Also, please do not hesitate to ask questions here - questions that arise out of lack of understanding are generally interesting to respond to - if you don't believe me, take a look at this thread!
Best wishes!

[Jason Irwin]

I'm more stubborn than a mule with a bad attitude.

This is pretty much what I arrived at last night using "wsimport" and fiddling about. When using the "Bare" parameterStyle, you can only have one parameter and need to contain all the relevant data in there.

@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
public interface IMathServer {
    @WebMethod
    @WebResult(name = "addNumsResponse")
    public AddNumsResponse addNums(@WebParam(name = "addNums") AddNums parameters);
}

versus

@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
public interface IMathServer {
    @WebMethod
    @WebResult(name = "addNumsResponse")
    public int addNums(@WebParam(name = "num1") int num1, @WebParam(name = "num2") int num2);
}

That to me seems a bit counter-intuitive. "Bare" means the multiple parameters need to be "wrapped" in another object?
But of course "Bare" refers to the structure of the SOAP messages that are used, not the code itself. Either parameters are contained in a "Wrapping" element within the SOAP Body, or they are "Bare" and the Body contains n "parameter" elements (as in example 2.8). Unfortunately WS-I 1.1 prohibits multiple parameters in the Body, so you are stuck with one. Leading to the confusing situation that "Bare" and "Wrapped" messages look identical (as I found out when I used Wireshark to grab the SOAP Messages sent to the servers above.
Bare

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
        <ns2:addNums xmlns:ns2="http://SoapStyles/">
            <num1>1</num1>
            <num2>2</num2>
        </ns2:addNums>
    </S:Body>
</S:Envelope>

Wrapped

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
        <ns2:addNums xmlns:ns2="http://SoapStyles/">
            <num1>3</num1>
            <num2>4</num2>
        </ns2:addNums>
    </S:Body>
</S:Envelope>

In the first the "wrapping" has been done at the code level, if you follow me. Only one parameter was passed ("addNums") and it was "Bare" in the body. In the second, the parameters were "bare" in the code, but "wrapped" at run-time by JAX-WS and what have you.

Does that seem like a reasonable summary of the situation?

So I come back to the SOAP message in example 2.8. As far as I can tell it cannot be used to call a web service. Or, if it can, I am at a total loss on how to code for it.

I can clearly see why Wrapped/Document/Literal is the default, it seems to lead to much easier coding (at least in Java and from what I have tried so far. I'll probably end up eating those words in a month! )

Thanks for all your time in this.

[R Srini]

Exactly, the SOAP request is the same, but the programming and method signatures are different. And yes, the signature does have two parameters, doesn't it? Ok. Why don't you try emailing Martin Kalin and see what he has to say about this? If you hear back, I would appreciate if you can also let me know.

[Jason Irwin]

The "signature"? Personally I'd say the Bare code has one parameter ("MyNumbers" or "AddNums") and the Wrapped two ("num1" and "num2"), .
The WSDLs are identical, which makes sense as the SOAP messages are also identical.
Interestingly, the XSDs differ. In the Bare form the "addNumsReponse" is just "int". Makes sense, this is Bare! And in the Wrapped we have an "addNumsResponse" that wraps a "return" element which is an "int". Which also makes sense (I had no annotations anywhere about the response).

I may just mail Mr. Kalin, but I rather doubt I'll get answer.

Thanks for all your help, things are a bit clearer.

[R Srini]

Oh, of course, yes, you are correct. I meant to say this earlier. My earlier statement:

Whether bare or wrapped, your method signature "public int addNums(int num1, int num2)" remains the same. You can have as many parameters as you like in the bare style.

was incorrect, and made based on the book, before I actually researched this in detail. The bare style seems to be available only with a single parameter for the addNums.

And thanks to Ivan for your earlier response - you were right on the mark regarding JAX-WS and WS-I BP 1.1 conformance being the reason for allowing a single parameter.

Take a look at this link and search for this string: "document literal (bare)" in that web page. Its very clear and verifies everything we have seen in our experiments.

And it may well be that before WS-I BP 1.1, the bare style may have allowed multiple parameters. Who knows? It does not matter now. All the best!

[Steven Jiang]

Really appreciate your detailed reply, I am looking for explanation like this as well.

Will bookmark it.

Thank you.
Steve

[Kieren Dixon]

I found myself referencing a lot of additional material while going through this book.
The following article was useful in explaining rpc vs document for me
http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/

[a sarkar]

I came across this post, just like Jason, confused about the difference among the style options, and was pleasantly surprised by the persistence and patience of the people involved in the discussion. Sadly, this kind of healthy discussion is hardly found anymore on Internet tech forums. Folks too lazy to do their homework flood the forums with questions they should never have asked and experts inundated with such 1d1otic questions quickly get disillusioned.

[Rohini Sahuji]

WOW! very old one. Still this discussion cleared so many things to me!!