Anne Thomas Manes wrote:
I'm thinking about reusability.
Picture yourself a couple of years from now when your company has a few
thousand services deployed. Like most companies you have about half dozen or
so data structures that represent customer information. And now you want to
find services that use a particular "customer" format.
If you have defined each of your various customer formats as separate
schemas, then each customer element has a unique Qname, at which point you
can search for services that use the abc:Customer as opposed to the
xyz:Customer.
If you have defined the customer element repeatedly in every web service,
you have no way to search for services that use one format versus another
without doing a detailed analysis of each WSDL file.
Anne
-----Original Message-----
From: Anand Natrajan [mailto:[EMAIL PROTECTED] Sent: Tuesday, November 16, 2004 1:19 PM
To: [EMAIL PROTECTED]
Subject: RE: Best Practice
While I understand the attraction to factor out common definitions into a separate schema file, I am a bit conflicted about the use of schema files within a WSDL for describing a service.
If your WSDL imports a schema, you can no longer hand out a single file to your customers and ask them to generate clients for your service; you must hand out the schema files as well. Giving out multiple files seems clunky.
Some of you may counter that I shouldn't be pamphleteering my WSDLs directly anyway; customers should use the service URL followed by "?wsdl" or some such device to get at the WSDL. While such devices may resolve imports (if they do), that doesn't solve the problem entirely. What if my service is published redundantly, i.e., what if multiple servers can serve a client?
In such cases, the customer could copy over the WSDL, change the service URL to reflect another server and access the service. Ah, but now, the customer has a version of the WSDL that is different from what I have on the server side, which could lead to interoperability problems later.
So what's my approach? Much as there is talk about writing WSDLs first, I prefer generating them automatically. I can do all the refactoring I want in my Java code and trust the java2wsdl generator to generate non-import WSDLs. Except for cosmetic changes (copyrights, formatting, etc.) I don't touch the WSDLs after that. This way I can control what WSDL the server and clients use.
Perhaps my approach is heresy. If it is, I'd like to know how my concerns can be countered. Thanks!
Anand
On Tue, 16 Nov 2004, Anne Thomas Manes wrote:
: Technically, an "import" is importing a namespace, not the schema or WSDL : file that creates the namespace. : The WS-I Basic Profile says that you must not coerce (i.e., change) the : namespace name during import: : 5.1.9 Namespace Coercion : Namespace coercion on wsdl:import is disallowed by the Profile. : R2005 The targetNamespace attribute on the wsdl:definitions element of a : description that is being imported MUST have same the value as the namespace : attribute on the wsdl:import element in the importing DESCRIPTION. : : In other words, if the imported WSDL file has a target namespace of : "urn:foo", when you import it, you must do so by saying: : <wsdl:import namespace="urn:foo" location="http://foo-url"; /> : and you can't change the namespace to : <wsdl:import namespace="urn:foobar" location="http://foo-url"; /> : : In addition, you must declare the namespace to reference any elements within : the namespace: : xmlns:foo="urn:foo" : : The same goes for schema imports. : : Anne : : _____ : : From: HG [mailto:[EMAIL PROTECTED] : Sent: Tuesday, November 16, 2004 8:57 AM : To: [EMAIL PROTECTED] : Subject: Re: Best Practice : : Hi Anne : : Thanx for your fantastic reply/comments on this post. They really makes : sence. : : Actually I used your suggestions already (maybe without knowing it ??!) on a : small-sized project where I only had one xsd file for all types. The whole : "domain model" in one file. : : BTW, do you know that WS-I Basic Profile suggests according to schema : imports and wsdl imports in respect to namespaces.? : : /Henrik : : ----- Original Message ----- : From: Anne Thomas Manes <mailto:[EMAIL PROTECTED]> : To: [EMAIL PROTECTED] : Sent: Tuesday, November 16, 2004 2:45 PM : Subject: RE: Best Practice : : Typically I prefer not to use a bunch of different schemas with a service : (e.g., one schema for each element and type). In order to reference an : element (or type) from one schema (a) in another schema (b), you must : explicitly import the (a) schema (and define a namespace declaration) into : the (b) schema using <xsd:import>. Likewise, if the (b) schema needs to : reference an element or type from the (a) schema, you must also explicitly : import the (a) schema in the (b) schema. So using lots of separate schemas : requires lots of schema imports. : : I suggest you factor schemas into the appropriate sizes to support your : requirements for reusability. In other words, if you plan to use a : particular element (or type) in a number of different applications, : combining the element with a different set of elements in each application, : then it makes sense to define it in a separate schema. But if you typically : use that element with the same group of elements in most of your : applications, then you probably want to define them in the same schema. : : My recommendation, therefore, is to define your service's data elements : (customer, purchase order, etc) and their types in a single schema unless : you have a compelling reason to factor them into separate schemas. : : I also recommend that you follow Henrik's advice to define your service's : input and output message elements in a separate schema from your data : element schema. (You will need to <xsd:import> your data element schema into : the message element schema.) If the particular set of message elements will : be used only by your service, then you can define them within the <types> : section of your WSDL. (This situation is reasonably typical because the : input message element usually has the same name as the operation so tends to : be pretty unique to the particular service). But if you anticipate that you : may have multiple services that wish to exchange the same messages, then you : probably want to factor the message elements into a standalone schema. I : suspect you're more likely to reuse fault messages than input and output : messages, so it makes sense to factor fault messages into a separate schema. : : : Note that a WSDL document may have at most only one <types> section, so you : can't <wsdl:import> multiple types sections into a WSDL document. If you : want to import multiple schemas, you must import them from within your : <types> section, and you must use <xsd:import> to do so. : : Regards, : Anne : : : _____ : : From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] : Sent: Tuesday, November 16, 2004 7:46 AM : To: [EMAIL PROTECTED] : Subject: Re: Best Practice : : Thanks, Henrik. : That's the sort of thing I'm after. : I couldn't quite work out the difference between 1 and 2, though. In 1, you : are defining the messages for the service methods and this naturally : includes the parameters of the methods. In 2, it seems you're doing the same : thing again (except for the message elements themselves). : When importing, are you referring to WSDL imports or XML schema imports? We : have some services that define a schema in the <types> element and import : another schema, in the <types> element also. The latest SOAPscope doesn't : like this, unless the imported schema is imported within the schema which : references its types. Just thought I'd mention it (XMLSpy, doesn't mind). : Keep it coming! : Tony : : : Hi Tony : : I have a few...Some on this list might disagree, but it is always nice with : a discussion. : : I have done this, on several projects, and it works very well, especially : for interop. : The main point is: Use Schemas : : 1. : Define a schema for each message you want your webservice to process. : Lets call these schemas for message-schemas. : : 1 a) : Typically a "call" to a webservice consists of some input message and maybe : some output message. Define a schema for both. : 1 b) : When you define the schema for the messages, the "value objects" will : logically appear to you. Value objects in this context is types (defined in : schemas) for parameters you pass in the message and return values of the : message. : : Outcome of 1: : You have a schema for each webservice that exactly defines request/response : messages for each web service method. : : 2. : As pointed out in 1 b) schemas for the parameter/return types can/must also : be defined. This might be an Order type, Customer type, etc. : Lets call these schemas for type-schemas. : 2 a) : Define these parameter/return types in a schema, too. : : Outcome of 2: : You have a schema (or all in one schema) for each parameter/return type that : each webservice method must be able to process. : Over time you'll have a "domain model" of types/classes described in : schemas. : : 3. : Use imports between schemas (both type-schemas and message-schemas) to : construct your WSDL document. : a) Import type-schemas in your message-schemas as needed by parameter/return : types. : b) Import message-schemas in your WSDL document as needed. : : Outcome of all three: : - You have a clean separation and description (in terms of schemas) of the : services a webservice provides and the "types of data" these service : operates on. : - Your WSDL doesn't get cluttered with types : : Anyone... comments on these steps are welcome... : : Regards : : Henrik :
.
