Architecture proposals for face-to-face

[Russell Butek]

Folks, here's a document that we (IBM) were planning to present at the
face-to-face next week.  Since we're not going to make it, I'll present it
here.  The intent of this thing is to get us all on the same page with
respect to how we proceed with AXIS development.  It is intended to be a
living document that everyone can add to and debate (with this in mind, I
suggest we store it in CVS).  As items on this document are resolved, we
can implement them and describe them in the architecture guide.

(See attached file: architecture-direction.html)

Russell Butek
[EMAIL PROTECTED]

Title: Axis System Integration Guide

Axis Architecture Proposals Beta 2 Version Table of Contents Introduction Proposals    Proposal 1: Change TypeMapping Framework    Proposal 2: Independent WSDL Parser    Proposal 3: Pooling of Serializers    Proposal 4: Check mustUnderstand    Proposal 5: Custom Serializers    Proposal 6: Improve writeSchema Method    Proposal 7: Providing All Meta-Data    Proposal 8: Independent Schema Model    Proposal 9: Unsupported Schema Processing    Proposal 10: Re-write Test Harness    Proposal 11: HTTP 1.1 support   Introduction The primary purpose of this guide is to present proposals for changing the axis architecture.  The goal of the document is to discuss architectural directions before committing code.  Hopefully this will allow all interested parties an opportunity to affect the future direction of Axis in a positive way. Plus a careful review of the proposals may prevent code changes which negatively impact future architecture directions. This document is also offering a system for evaluating the proposals.   The status of each proposal will be one of: Proposed, Accepted, Rejected, or Under Review. We can vote on specific proposals on the forum or chat. The reader may find useful background information in the Architecture Guide.   Proposals Proposal 1: Change TypeMapping Framework to JSR-101 Status: Proposed Proposed By: Rich Scheuerle Description There have been changes to the Axis TypeMapping framework to make it more closely match the JSR 101 specification.  The following changes are proposed: Change the Axis TypeMapping and TypeMappingRegistry code so that it contains just methods and logic identified by the JSR 101 specification.  In particular, the JSR 101 specification indicates that both the javaType and xmlType are needed as keys to obtain the serializer factory and deserializer factory.  Currently the Axis TypeMapping contains a lot of additional logic to locate information if the javaType and/or xmlType is missing. The Axis serialization framework should move to a point where the serializer and deserializer factories are always obtained by using both the javaType and xmlType.  In the mean time, the code to do 'special resolution' needs to be placed somewhere.  The proposal is to create an Axis TypeMappingQuery class which would be used to contain this special resolution code.  Here are examples of the logic that may be in the class Given a javaType with no xmlType, find the serializer factory.  (This includes code to look up through extended classes and interfaces.  Currently this code is scattered in the TypeMapping class and the SerializationContext class.) Given an xmlType with no javaType, find the deserializer factory.  (Similar to above.) Given an xmlType, return the javaType.  (i.e. what is the javaType for xsd:string) Contains the code that automatically looks in the registered TypeMapping and then looks in the DefaultTypeMapping. Deal with special types like lists and arrays. A TypeMapping can currently be registered on a service or globally.  There are several problems with this two tiered system.  Do you have to end all of the services to install a new global TypeMapping ?  If a (javaType, xmlType) is not registered in the services TM or default TM should the global TM be consulted ?  So I propose only supporting TypeMapping deployment on services. More fully support user provided TypeMappings. Since the DefaultTypeMapping registry is so closely tied to the mappings in the specifications, we should not allow them to be overridden. Justification Have a TypeMapping design that matches the JSR 101 framework.  Solidify and isolate the JSR 101 framework from the Axis extras.  Move the axis engine (and serialization framework) to a point where both the javaType and xmlType are provided for both serialization and deserialization. Proposal 2: Develop Independent WSDL Parser Status: Proposed Proposed By: Russell Butek Description Develop an  independent WSDL front end for the emitters.  The function of the front end is to: Build a symbol table that is language independent (i.e. does not contain java-isms). (still needs work) Provides an emitter factory interface which allows back end emitters to plug into the front-end. (we've got this but it still needs work) This code could/should reside in a separate jar file to isolate it from other Axis components.  It could be used outside of AXIS.  It already resides in a separate package from the WSDL2Java emitter. The models used within the implementation of the WSDL parser should not be tightly coupled to models used in the Axis runtime.  Appropriate levels of tool independence should be developed by using third party models where possible. Justification Build a more extensible tool.  Isolate the tool implementation from the runtime so this parser could be used by non-AXIS developers (possibly anticipating a separate project for the tools). Proposal 3:  Pooling of Serializers and Deserializers Status: Proposed Proposed By: Rich Scheuerle Description Serializers and Deserializers (and their corresponding Factories) are short-lived objects.  It may be appropriate to have hook points in these objects to support the pooling of them.  Changes would need to be made to the serialization framework to invoke the hook points to indicate the objects life cycle.  The default implementation in Axis would be no pooling. Justification Pooling of short-lived objects may boost performance.  There has been some disagreement on the chats about whether adding pooling hooks would complicate the architecture with little or no performance value. Proposal 4: Check mustUnderstand Status: Proposed Proposed By: Doug Davis   Description Right now I do not believe Axis follows the processing rules laid out by the SOAP 1.2 spec.  The spec states that all headers targeted for this node must be understood by the soap node before ANY processing can begin.  Right now we only do this after the handler chains have been invoked (violating the "before ANY processing can begin") - and technically we don't do the check based on QName we do it based on whether or not a handler flicked the "processed" flag - might or might not necessarily be the same thing.   Justification I know some people don't see it that way - some say its ok to process the handlers as long as we "rollback" the work when we determine a block is not understood, right now I see 2 problems with this: The "undo" method is a sore point for lots of people and quite a few people want to remove it, so if we do there is no way to "undo" what work might have started. I don't believe we can expect people to write an "undo" method that fully complies with the spec.  I like "undo" for cases where there's a fault - I believe people will know what to do and even though there might be side effects that's just a part of life.  The soap spec however doesn't want ANY side effects when there are blocks that are not understood so writing an "undo" that guarantees no side effects seems a bit too much to ask people to do.  It seems much cleaner and safer to have Axis perform a mustUnderstand check before any handlers are invoked. Proposal 5: Custom Per-Class Serializers/Deserializers Status: Proposed Proposed By: Rich Scheuerle   Description Propose changing the WSDL2Java emitter so that it can generate custom serializers/deserializers.  The existing getSerializer/getDeserializer code in the bean/helper will locate the custom serializers.  The default processing for WSDL2Java will continue to be use the Axis general purpose serializers/deserializers.   Justification I am not proposing custom per-class serializers as a replacement for meta-data and general purpose serializers.  Here are some justifications for emitting custom per-class serializers/deserializers. Users have the opportunity to provide custom serializers.  Unfortunately the only help that Axis provides is the general purpose serializers (mainly the BeanSerializer stuff).  Extending the BeanSerializer is difficult to do, and writing a general purpose serializer/deserializer is also difficult to do.  Providing a generated serializer/deserializer specific to an individual class will (IMHO) greatly help users who simply want to tweak the code.  They can isolate the changes to a particular class and feel confident that the change will work. Generating custom per-class bean Serializers is a great way to pass both the javaType and xmlType to the SerializationContext to ensure that correct xmlType is sent over the wire.  (Of course the alternative is to add this information to the meta description data and change the BeanSerializer...). Allows users (or us) to quickly provide solutions for language constructs that are presently hard to solve.  For example, a minOccurs=0 item should not be passed over the wire if it is missing (Axis passes it over the wire as xsi:nill=true).  With the custom serializer I was able to quickly generate code that simply didn't send anything over the wire in this case. Right now SimpleSerializers are constructed for each of the primitive fields that must be serialized.  The custom serializers could generate code to serialize primitives (or some subset of primitives) without constructing more Serializers.  (I have some working code that does this with Strings.) Custom serializers make it easier for customers to tweak things such as mult-ref processing.  They will now have the ability to do this on a field basis.   Proposal 6: Improve writeSchema Method Status: Proposed Proposed By: Rich Scheuerle Description: The writeSchema method in the Serializer interface should be improved to simply hand back a String containing the xml text and possibly a HashMap to map the prefixes to namespaces.  This String and HashMap will be generated directly in the meta data by the WSDL2Java emitter (which seems easy to do).  The Java2WSDL tool will simply convert the String and HashMap into the proper Node objects and shove them in the WSDL data structure. Justification There is too much  interdependence between the Java2WSDL tool and the Serializer framework.  The BeanSerializer is calling implementation methods inside Java2WSDL (which used to be private methods) is just one example.  The current approach makes it more difficult for users to extend the BeanSerializer and/or extend the processing of Java2WSDL. Providing a cleaner interface IMHO will allow both to evolve independently. Proposal 7: Providing All Meta Data Status: Proposed Proposed By: Rich Scheuerle Description Currently meta data (*Desc objects) are only generated for the cases where the "default" behavior is not correct.  This forces the general purpose Serializers to do some level of introspection even when meta data exists.  I would feel more confident if complete meta data was always generated. Justification Number of justifications: Could have a BeanMetaDataSerializer for beans with meta data and BeanSerializer for beans that don't have meta data.  The choice of which serializer should be used would be in the BeanSerializerFactory, which would simply look for meta data in the bean.  Each of these classes would be less complicated than the current BeanSerializer.  These classes would be easier to extend. Providing complete meta data would give users the opportunity to 'tweak' the meta data to solve problems. Relying on undocumented "default" behavior may be more prone to bugs. The support for xml constructs continues to grow. Proposal 8: Independent Schema Model Status: Proposed Proposed By: Glen Daniels (with comments from Russell Butek & Rich Scheuerle) Description WSDL2Java contains a lot of code to directly traverse the xml Nodes.  This approach, though it works for a good number of constructs, is ugly.  It would be nice to replace the code with a new schema model (the current code can't really be considered a 'model', it just uses the difficult-to-use XML parser model).  Two possibilities: • Find and use a non-AXIS schema model. • We haven't found one, yet. • Write one ourselves • The basic model is easy (WSDL2Java USED to look fairly clean), but it's all the complexity and corner cases in XML that made WSDL2Java ugly.  Would yet another model be any cleaner? • Growing a new model is risky.  The current implementation has had 9 months to mature.  Folks are using it.  Our tests don't adequately cover user scenarios.  If we write something in a week to replace what's been there for months, our tests may pass, but we will break users. • XML-validation would REALLY be nice to have. One possibility would be to grow a model in isolation and write reams of XML tests for it.  Once we feel comfortable that it covers at least as many cases as the current code, then we can put on our radiation-proof gloves and replace the existing code with it. Some advantages to developing it in isolation: • General purpose.   Developing it outside of the AXIS mindset will keep us from developing dependencies that make it unusable outside of AXIS. Justification See the first paragraph of the description. Proposal 9: Unsupported Schema Processing Status: Proposed Proposed By: Rich Scheuerle and Russell Butek...for John Colgrave Description The WSDL2Java emitter ignores constructs that it does not understand.  The JSR 101 specification indicates that unsupported constructs should be mapped to SOAP elements.   The emitter should be changed to recognize unsupported types and generate an UnsupportedElement and UnsupportedType symbol table elements. The recognition of unsupported schema is a difficult issue and requires some thought to do this correctly. The required attribute is currently not supported.  Should an element with a required attribute be mapped to an UnsupportedType? No, the tool should indicate that the required attribute is ignored and do the normal mapping. The union construct is not currently supported.  Should a simpleType with the union construct be mapped to an UnsupportedType ? Yes The choice construct is currently supported as if it were a sequence or all.  Should the choice construct result in a mapping to an UnsupportedType ? No, the tool should indicate that choice is not fully supported... Nested sequence and all groups are supported as if there were no nesting.  Should this kind of construct result in a mapping to an UnsupportedType ? No, need to issue a message indicating the nesting is ignored... Justification Specification compliance.  Tool evolution. Proposal 10: Re-write Test Harness Status: Proposed Proposed By: Rich Scheuerle and others Description Here are some objectives: Ability to run a single test. Ability to run a bucket of tests Ability to run all the tests Ability to run the tests that do not rely on remote resources. Ability to run tests if connection problems occur with remote resources (with warnings). Simpler installation of tests.  Best would be auto installation without changes to the build.xml files.  Give non-committers the ability to quickly give us a test that we can drop in; thus giving the group a good set of user provided tests. Fully documented process. Justification The current test harness is becoming too complicated. Proposal 11:  HTTP 1.1 support Status:  Proposed Proposed by Rick Rineholt   Description Currently, Axis only supports HTTP 1.0.   It should continue to do so, but do we want to push for support of HTTP 1.1? Justification Other SOAP engines support and primarily use HTTP 1.1 and while they should  be backward compatible my bet is that's not how they are primarily tested.  This might give the appearance of Axis being less interoperable. To some extent MIME can be more efficient when used in conjunction with HTTP chunking supported in 1.1. The SOAP envelop would not have to read in array to determine its length when used with HTTP chunking providing some performance and getting closer to a direct streaming model. More From AXIS Todo list: Management (JMX) API. Run-time (un)deployment API. EJB provider COM provider HTTPS listener and sender SMTP sender POP3 poller JMS listener and sender Transport level security SOAP level security Abstract the SD layer WSDL implementation of SD layer Literal XML encoding support C++ client Document Literal support - is it done?