Namespaces and stuff

, ,
1

I’m working to resolve a couple of issues with the Integration Server’s (6.5) handling of namespaces in relation to Doc/Literal Web Services and the Integration Server’s use of the Doc/Literal Wrapped convention.

As we know there are several variations of how an xml schema can be represented within the Integration Server. There are three scenarios in particular I want to address. A fully qualified namespace, a default namespace, and a partially qualified namespace for elements. I’m going to give examples of each from an instance document point of view instead of the xml schema. I’ll then give examples of how they look in Integration Server form.

Scenario 1
Elements are fully qualified with a namespace. In this example there is no default namespace. Here is some ref. material on namespace qualification if your are curious or having trouble sleeping - [URL=“http://www.xfront.com/DefaultNamespace.pdf”]http://www.xfront.com/DefaultNamespace.pdf[/URL] and [URL=“XML Schemas: Best Practices”]http://www.xfront.com/BestPracticesHomepage.html[/URL] .

<?xml version="1.0"?>
  <ser:ServiceResponse
        xmlns:ser="urn:www.pgn.wbmethod.service.request">
    <ser:ticketnumber>han</ser:ticketnumber>
  </ser:ServiceResponse>

Scenario 2
Elements belong to an established default namespace. The lack of a prefix designates a default namespace in xml.

<?xml version="1.0"?>
  <ServiceResponse
        xmlns="urn:www.pgn.wbmethod.service.request">
    <ticketnumber>han</ticketnumber>
  </ser:ServiceResponse>

Scenario 3
The element ticketnumber is not namespace qualified and is not in the scope of “urn:www.pgn.wbmethod.service.request”. In this scenario namespace qualification applies to the element it is declared on and all children of that element unless a fully qualified namespace has been given. In that case the ticketnumber element would have to have the prefix “ser” to become namespace qualified.

<?xml version="1.0"?>
  <ser:ServiceResponse
        xmlns:ser="urn:www.pgn.wbmethod.service.request">
    <ticketnumber>han</ticketnumber>
  </ser:ServiceResponse>

In the Integration Server, the documents that correspond to the above scenarios are given below.

Scenario 1 – In addition to the prefix, the namespace properties for each element are set.

Scenario 2 – This is what it would look like, but you can’t use it in Integration Server without the prefix on the root node. The xml conversion services will bomb out when trying to get it into valid soap message format. It is a valid representation and it does work in other soap processors (it actually works for inbound soap messages to Integration Server) found in .Net and others just not in the Integration Server. Anybody got a default namespace working? (That means no prefixes on this root node). The namespaces are set on the element properties but it doesn’t matter, it does not work without the prefixes.

Scenario 3 –In this scenario the ServiceResponse element is fully qualified but the ticketnumber element does not belong to any namespace. It is local in scope which is valid. However other soap processors (works fine within Integration Server), namely .Net, seem to have problems with this. .Net seems to expect the response to be either fully qualified or have a default namespace. Namespace properties for each element are set in the elements below. I used VS2003 and VS2005 to test this, using their default web services client stub generation program.

I’m curious about scenario 2 and 3. Has anyone been able to get a document in SOAP format using a default namespace? Has anyone tested interoperability with Scenario 3 with .Net using the default .Net web services client stub generator, the add web reference thingy? I know you could handle it by hand.

My thinking here is that you should probably always fully qualify your elements to maximize reuse and avoid potential namespace collisions. What do you think about that? I’m curious as to how others are doing it.

Okay on to Doc/Literal Wrapped style.

The Integration Server has this thing where the input message element name has to match the local name of the service that is being called within the Integration Server. It does this so it can associate an inbound message with the service that is supposed to receive it.

This is all well and good but unfortunately it also corresponds to another spec. which is already out there. [URL=“https://jax-rpc.dev.java.net/docs/wsdl-bindings.html#doc/litWSDL”]https://jax-rpc.dev.java.net/docs/wsdl-bindings.html#doc/litWSDL[/URL] It is the doc/literal wrapped style.

The unfortunate side affect of this is the way other client stub generators will interpret the WSDL. Instead of generating beans for the input and output messages, the signature of the messages become parameters, similar to a RPC style of message ie createPO(String 1 , String 2, String 3, String 4, etc) . This can get to be very cumbersome to work with especially when there are a lot of elements. The client stub generators are actually working correctly according to the spec but I don’t think that was the effect webMethods was going for when they chose this format. It is possible to turn off wrapped support in some of the client stub generators such as Axis, and even .Net. There is no switch in Eclipse to turn this off.

Anyone else running into this? Sorry for the long post but I had a lot of questions.

2

Mark,

Great questions deserving more time than I have today. I do have inbound soap requests working in my custom soap processor with no prefix and a default namespace. However, my soap processor uses external meta-data to lookup the name of the service to invoke and does not rely on the universal name settings.

Mark

3

Hi Mark,
The default namespace scenario does seem to work for inbound messages from .Net. .Net seems to only use default namespaces, at least using their default tools. They have facilities to set fully qualified namespaces on elements but I haven’t tried them yet.

The outbound messages from the Integration Server back to .Net seem to be a bit more of a problem if not fully qualified.

The meta-data layer is interesting. I was wondering if someone was doing something like that. When (if) you have time, I would love to hear more about it.

4

I have some more follow up to this discussion. I love XML by the way. :eek:
Given the following XML Schema:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:ser="urn:www.pgn.wbmethod.service.request" 
targetNamespace="urn:www.pgn.wbmethod.service.request" elementFormDefault="qualified" 
attributeFormDefault="unqualified">
    <xs:simpleType name="customerid">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:simpleType name="address1">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:simpleType name="address2">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:simpleType name="problemdescription">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:simpleType name="contact">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:simpleType name="ticketnumber">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:complexType name="ServiceRequest">
        <xs:sequence>
            <xs:element name="customerid" type="ser:customerid"/>
            <xs:element name="address1" type="ser:address1"/>
            <xs:element name="address2" type="ser:address2"/>
            <xs:element name="problemdescription" type="ser:problemdescription"/>
            <xs:element name="contact" type="ser:contact"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="ServiceResponse">
        <xs:sequence>
            <xs:element name="ticketnumber" type="ser:ticketnumber"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="ServiceRequest" type="ser:ServiceRequest"/>
    <xs:element name="ServiceResponse" type="ser:ServiceResponse"/>
</xs:schema>

There are several things to notice.
1- This is based on a Venetian Blind (Not the kind you hang) style of schema design.
It attempts to maximize reuse. It also gives you the ability to hide the namespaces or expose
the namespaces of the locally declared elements. In this example the elements
(not the types which can have the same name) customerid, address1, address2, problemdescription,
contact and ticketnumber are all local. Exposing or hiding the namespaces of these elements are
controlled by the elementFormDefault=“qualified” setting within the namespace declarations.

If set to “qualified” then an instance document would like either of the following:

Implicit namespace qualification (default namespace set)-

<?xml version="1.0" encoding="UTF-8"?>
<ServiceRequest xmlns="urn:www.pgn.wbmethod.service.request" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="urn:www.pgn.wbmethod.service.request
C:\Data\documents\webservices\serviceresponseschver1.xsd">
    <customerid/>
    <address1/>
    <address2/>
    <problemdescription/>
    <contact/>
</ServiceRequest>

or explicit namespace qualification (no default namespace, explicitly set) –

<?xml version="1.0" encoding="UTF-8"?>
<ser:ServiceRequest xmlns:ser="urn:www.pgn.wbmethod.service.request" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="urn:www.pgn.wbmethod.service.request
C:\Data\documents\webservices\serviceresponseschver1.xsd">
    <ser:customerid/>
    <ser:address1/>
    <ser:address2/>
    <ser:problemdescription/>
    <ser:contact/>
</ser:ServiceRequest>

If the elementFormDefault attribute is set to unqualified or left out
then the instance document would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<ser:ServiceRequest xmlns:ser="urn:www.pgn.wbmethod.service.request" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="urn:www.pgn.wbmethod.service.request
C:\Data\documents\webservices\serviceresponseschver1.xsd">
    <customerid/>
    <address1/>
    <address2/>
    <problemdescription/>
    <contact/>
</ser:ServiceRequest>

Notice that the customerid, address1, address2, problemdescription,
contact are not in the scope of any namespace declaration.
They therefore have no namespace.

All three of these are valid from an XML standpoint however:

-Implicit namespace qualification (default namespace) doesn’t work within
webMethods Integration Server when working with SOAP messages. It requires
that the root level node be namespace qualified with a prefix which means
its not default, it’s explicit.

From WebServicesDevGuide

-No namespace qualification for local elements does work within the webMethods
Integration Server as well as other parsers. I originally didn’t think it would
work with .Net but I have that working as well now.

The key here I believe is your schema design. If you choose to use the Venetian Blind
type design you have the option of whether you hide or expose you local elements using
the elementFormDefault=”” switch. (Note, global elements are always qualified either
implicit or explicit).

What this essentially means (my understanding) is if you choose to validate against
the schema then you must follow the elementFormDefault=”” switch. In other words if
you attempt to validate and you do not have you elements qualified according to the
switch then it will fail.

5

Excellent summary. Thanks for taking the time to write this up and share it with the community.

IMHO, one of the essential requirements for success in web services and SOA is a thorough understanding of XML schema. Stumbling around through web services efforts without this is a huge mistake that will wreak havoc as long as the so-called “services” are in use.

Mark

6

Griffima,
Your explanation about this xml schema is very helpful.
Also the links you have provided in the post are very useful.
Once again thanks for sharing this with the community.
Mallik

7

Always glad to share, this forum has helped me more than I have helped it.

Mark, you bring up some very good points on schema design and it’s importance. The idea of schema first and WSDL first approaches to design are a very important point.

One of the big issues facing EAI and Web Services is choosing the right level of granularity for shared interfaces/resources. A big part of that is affected by the schema designs and the level of effort put into understanding the data. Reuse has very different meaning in the world of EAI and Web Services than it did in the OOP world. We are talking about reusing live instances of interfaces/code as opposed to checking out a component that gets incorporated into another piece of code as a version.

Changes to these live interfaces have a potentially large impact on the downstream/upstream applications. Part of what this person is going through - [URL=“wmusers.com”]wmusers.com

I think if you find yourself changing these public interfaces frequently then you have to step back and look at what you are doing and where you are spending your time.

8

Thomas Erl’s book on SOA Concepts outlines a service-oriented analysis and design approach that helps design teams focus on course-grained “business services” and the XML data design that models the underlying business entities. We attempted to follow his approach on my current project and have been pleased, so far, with the results.

We identified service candidates, operations for each service, xml schemas to describe the business entities and xml schemas to describe messages for operations dealing with those business entities.

The schemas were used both in the integration layer to validate incoming soap messages and to build generic handling services and in the application layer which was enhanced to invoke existing EJB methods based on receipt of incoming JMS messages.

I’m sure there are many other approaches, but Erl’s has seemed to be the right balance between reuse and pragmatism skipping most of the hype.

9

I wrote the following in an earlier post:

I left out the part where the operation name has to be the same as the input message in order to be a doc/literal wrapped. So to further clarify or confuse you, the input message must map to the service name on the webMethods IS side but the operation name can be different. This will give you plain old Doc/literal and not Doc/literal wrapped. It will prevent the problem with the parameters versus beans.

To recap if you want parameter based but need to use Doc/literal then use Doc/literal wrapped. If you want a more message based approach then use just plain old Doc/literal. A side note, .Net requires the part name of the input message to be named “parameters” in order to get the parameters. Otherwise .Net will generate a class for your input message even though you are using the Doc/literal wrapped convention.

Confused? :confused: Welcome to the world of Web Services.:smiley:

10

I guess my preferred style id plain ole document/literal. I like to name my messages Req and Resp, define them in a schema that imports a “common types” schema and then import the “messages” schema into my hand-crafted WSDL.

The external web service meta-data allows me to name the messages anything I want, validate them against any doc type I want and invoke any service I want. The built-in UniversalName functionality is just a bit too basic for my tastes. Not enough meta-data options.

Mark

11

Mark,
I like your approach especially given the limitations of the IS server when it comes to web services. I’m curious about your external meta-data approach.

I’m guessing you are using a database backend as the directory and repository for your meta-data. Do you store you schemas and WSDL there as well? How about runtime performance? Do you cache anything local to IS server?

12

I have written the meta-data access services to use either a database backend or an XML file. The services that retrieve or update meta-data don’t care what the physical storage mechanism is. Either way, the meta-data is cached for runtime performance.

I have not expanded the metadata to contain schema or WSDL files, but that could be done.

From my initial review of the Infravio X-Registry, I think it would do that kind of thing out of the box and provide the “multi-tenancy” to restrict access to service metadata and documentation to only those with permission to read/update/delete it.

Mark

13

Mark and Mark,
You guys have hit upon the most important aspects of integration pain. Thanks for the great info.
I would like to know more about the 2 pieces of discussion topics.
First, from Mark G s post on 9/26
-No namespace qualification for local elements does work within the webMethods
Integration Server as well as other parsers. I originally didn’t think it would
work with .Net but I have that working as well now.
Is there setting/property that you had to set to get that to work ?

And
Mark Cs comment about working with external web service meta-data . Like Mark G , I would like to hear some more details on that.
Thanks
Joy

14

Nothing special to get it to work. Mark C. posted a very good example in this forum. If you follow that it should work okay with .Net.

No namespace qualification may not be a best practice however for insuring that your schemas are interoperable (Think of multiple schemas and using imports to extend and reuse). And only local elements can go unqualified, global elements must be qualified. I talked briefly about this with one of the product managers of XML technologies at Microsoft. His recommendation was to always use qualification unless there was a really good reason not to. Still there may be some times when you want to be able to do either.

If you want to go that route, take a look at the Venetian blind example at the start of this thread. Using that style allows you to use the elementFormDefault switch on your local elements. That way you can turn qualification on or off as needed. The elementFormDefault switch has no affect on global elements.

15

Miko Matsumura from Infravio quoted Burton Group’s Anne Thomas Manes a few times in the SOA Master Class this week. Today I ran across this post from her blog discussing the document/literal wrapped style.

16

I’m curious as to what the use case would be to drive one to using a doc/literal wrapped style. I haven’t found one yet. It seems to take away the advantage of having your XML deserialized into Beans (in java terms). For a method with only a few parameters, this would be okay. But for something larger like a PO or workorder, it would be very cumbersome to work with. Although most of the client tools have switches to turn this support off so you still get the XML deserialized into beans.

On a side note, Anne came and spoke to our company this year. We are a Burton Group client. She was very pro XML Appliance and also XML intermediaries/mediators. I wonder what she thinks of webMethods now that they have acquired Infravio.

17

This Oct 2006 article titled XML Schema considerations for WSDL design in conformation with WS-I Basic Profile addresses the three major XML schema design patterns (Russian Doll, Salami Slice, Venetian Blind) and how they impact WSDL design.

18

The article does a good job explaining the differences and the pros/cons.

I’ve been using the Venetian Blind style for most of the work we have been doing (which isn’t huge yet). I’m trying to get some level of common vocabulary and reuse out of common types. I’ve basically been creating schemas that have the common types defined within certain domains then using another schema that is more specific to the actual service but uses the common types.

It makes the scheme creation a little more complex with imports/namespaces etc. But it does seem to establish a common vocabulary and common type definitions.

I’m curious to what others are doing. This area is still fairly new with best practices still being flushed out. What styles are you using? What issues have you run into?

19

Our XML schema design pattern is Venetian blind with an element defined for each request and reply message. Each Web Service (caps intended) uses a single schema to define the message structures that will be referenced in the WSDL. Each of those schemas import one or more XML schemas containing common types. Because the WSDL is modular and imports all of its types, it rarely needs to be changed once the operations have been defined even when the message structures themselves change. The common types schemas change very frequently and the schemas for each operation change as the message structures change during development or when defects detected during testing necessitate changes.

I think what we’re doing is pretty close to the document/literal wrapped style of soap messaging, with the exception that our request messages follow the naming convention Req instead of simply . This would be easy enough to change since my custom soap processor uses meta-data to determine which processing service to call based on the content of the soap body, but at this point downstream apps are expecting this Req message name in the JMS payload they receive from the ESB we implemented in IS.

All of the XML schema design was performed using XML Spy 2006 - Professional Edition. WSDL design was done using XML Spy 2006 - Enterprise.

We published schemas and WSDL’s to a project FTP site for our partners. In the future I would see using Infravio’s X-Registry for this purpose due to the ability to restrict access by user, environment, Service and operation and to enforce our (limited) governance standards auto-magically.

Mark C