Comments
yourfanat wrote: I am using another tool for Oracle developers - dbForge Studio for Oracle. This IDE has lots of usefull features, among them: oracle designer, code competion and formatter, query builder, debugger, profiler, erxport/import, reports and many others. The latest version supports Oracle 12C. More information here.
Cloud Computing
Conference & Expo
November 2-4, 2009 NYC
Register Today and SAVE !..

2008 West
DIAMOND SPONSOR:
Data Direct
SOA, WOA and Cloud Computing: The New Frontier for Data Services
PLATINUM SPONSORS:
Red Hat
The Opening of Virtualization
GOLD SPONSORS:
Appsense
User Environment Management – The Third Layer of the Desktop
Cordys
Cloud Computing for Business Agility
EMC
CMIS: A Multi-Vendor Proposal for a Service-Based Content Management Interoperability Standard
Freedom OSS
Practical SOA” Max Yankelevich
Intel
Architecting an Enterprise Service Router (ESR) – A Cost-Effective Way to Scale SOA Across the Enterprise
Sensedia
Return on Assests: Bringing Visibility to your SOA Strategy
Symantec
Managing Hybrid Endpoint Environments
VMWare
Game-Changing Technology for Enterprise Clouds and Applications
Click For 2008 West
Event Webcasts

2008 West
PLATINUM SPONSORS:
Appcelerator
Get ‘Rich’ Quick: Rapid Prototyping for RIA with ZERO Server Code
Keynote Systems
Designing for and Managing Performance in the New Frontier of Rich Internet Applications
GOLD SPONSORS:
ICEsoft
How Can AJAX Improve Homeland Security?
Isomorphic
Beyond Widgets: What a RIA Platform Should Offer
Oracle
REAs: Rich Enterprise Applications
Click For 2008 Event Webcasts
In many cases, the end of the year gives you time to step back and take stock of the last 12 months. This is when many of us take a hard look at what worked and what did not, complete performance reviews, and formulate plans for the coming year. For me, it is all of those things plus a time when I u...
SYS-CON.TV
Web Service Versioning and Deprecation
Web Service Versioning and Deprecation

Current standards for SOAP, WSDL, and UDDI have no explicit support for the versioning and deprecation of Web services. This article introduces a means for Web service versioning and deprecation that is lightweight and flexible, and requires minimal development effort.

This approach is intended primarily for use within a corporation using one or more internal UDDI registries. It may be applied in the UDDI public registry "cloud," but only for controlling versioning and deprecation for Web services controlled by a single provider.

Requirements
The following is a preliminary set of requirements that a successful strategy for Web service versioning and deprecation should support.

1.   The ability for a consuming application to automatically determine and consume the most recent version of the Web service that supports the required functionality
2.   A standard means through which the Web service version implementation may be discovered.
3.   The ability to have multiple versions of the same Web service running simultaneously (to avoid the need for all applications to perform a hard cutover)
4. A standard means through which an application may discover that a Web service has been deprecated
5.   The ability to support an arbitrary "sunsetting" length for a given Web service
6.   The ability for an application to check, at any time, whether it should be using a more recent version of a Web service (i.e., once an hour, once a day, once a week, etc.)
7.   Integration with source code control

Versioning
One approach to these requirements is a Web service versioning and deprecation strategy centered on applications searching for and binding to Web services by searching for services that support one or more required interfaces (tModels). The following scenarios illustrate the strategy, first from the Web service developer side, and then from the application developer side.

Scenario: Web Service Developer
The scenario begins with the Web service developer developing a new Web service, or modifying an existing Web service. One message supported by the Web service is getVersion(), which returns a complex data structure of three integers (major version, minor version, and patch level); the developer codes this function to return the appropriate values for the Web service (the reference implementation code distributed with this document shows an example of the Version class, and the getVersion Web method).

As part of the Web service development or deployment, the developer creates a WSDL (Web Service Description Language) file, describing the interface of the Web service. The developer registers this WSDL file as a TModel in an appropriate UDDI registry, with the Overview URL field in the TModel data structure pointing to the URL of the WSDL file.

If the deployed service is a new version of an existing service, it is registered as a new binding on the existing service, and that binding is linked to all the tModels it supports.

Scenario: Application Developer
At application design time, the developer discovers an appropriate Web service to reuse. The developer codes his or her application to use the messages specified in the WSDL (tModel).

The developer incorporates code to find a service binding dynamically, at application startup time (in lieu of looking up the access point from a configuration file, or hard-coding the value), at predetermined intervals, and/or in exception handling (i.e., when a Web service call fails). This code, taking as its argument a tModel key corresponding to the expected interface, searches for all services supporting the specified interface.

Special Cases
The basic versioning scenario may not be applicable in all instances. However, since it is a straightforward use of the existing UDDI standards, we believe that the strategy can be easily extended to accommodate more unusual cases.

  • Application requires a Web service supporting multiple tModels: Since bindings may support any number of tModel bindings, an application may eventually require a Web service that supports multiple tModels. In this event, the code provided in this article may be used to search for bindings supporting each of the needed tModels, and then select a binding from the intersection of the individual binding lists.
  • Identical versions of a service that report different data: Multiple services, each supporting the same interface, may return different data sets. As an example, consider a sales reporting Web service, implemented to provide headquarters with a simple means of pulling sales data from a wide variety of servers around the world, in a standard format. All are registered as separate services (e.g., Western Region Sales Data, Eastern Region Sales Data, etc.), but all support the identical interface. In this event, the application developer would need to limit the search for bindings to those bindings within one specific service (identified by the service key), rather than searching for bindings across all services.

    Implementation
    All Web services implementing the strategy must support a getVersion() message. The message returns a complex data type, Version, consisting of three integer values (major, minor, and patch).

    Should an application developer require a Web service binding, he or she searches by tModel key for the service bindings supporting that tModel (while it is possible to search by name, there is nothing preventing multiple tModels from all having the same name). For each service implementing that interface, the application retrieves the version information (using getVersion()) and selects the highest (i.e., most up-to-date) version of the Web service.

    For example, take the following UDDI entry shown in Table 1.

     

    An application programmed to use the interface described in Service 1 Interface would be able to use Service 1 v1.01 initially; when Service 1 v1.5.0 was released, the application would automatically begin using it (since it is the highest version supported by the required interface). When Service 1 v2.0 is released, the application will ignore it; even though it is the same service, it does not support the required interface.

    Public Registry Applications
    As mentioned above, while this strategy works within the bounds of an internal registry, it must be applied with more caution for Web services in the public UDDI "cloud," for a number of reasons.

    One issue is that of trust. In the world of public Web services, trust should be established prior to using a service:

  • To guarantee the source and accuracy of the data: While it may be that a tModel specifies source, accuracy, and other characteristics of the data returned, it cannot be automatically assumed that the service provider has fully or correctly implemented the tModel.
  • To avoid incurring unknown service charges, or inadvertently entering into a service contract: Although UDDI business models have not yet been established, it is conceivable that one model might be that by using a particular provider's version of a service, you are automatically agreeing to be billed for that service (at a very unfavorable rate).

    Another issue that could arise when applying this strategy blindly within the public registry is that of multiple distinct services, from one or more providers, supporting the same interface. As a simple example, take an interface for retrieving stock quotations. On January 1, 2003, CompanyA releases version 1.0 of a service implementing the interface, and in April of the same year, follows up with version 1.5. In July, CompanyB releases version 1.0 of their service implementing the interface. Under the versioning strategy described, applications would continue to use CompanyA's version 1.5 service, despite the fact that CompanyB's service is actually the most recent version of the service implementing the interface. Version numbers are, and always have been, meaningless between software providers.

    Versioning Code Walkthrough
    In this section, we'll examine some aspects of the versioning code. The code examples used are Java and UDDI4J, but the concepts are easily transferred to .NET.

    First, assume the existence of a Web service supporting a getVersion message (see Listing 1). The values populated for major, minor, and patch are under the control of the Web service. Thus, the ability to allow the source code control system to supply the values returned by getVersion is totally under the control of the developer, and is dependent upon the programming language and source code control system chosen.

    The code required to locate the binding(s) corresponding to the most recent version of the service is, unfortunately, rather complex when implemented directly in UDDI API v1.0 calls. The complexity is due to the API not supporting searches for services, across all businesses that support a given tModel. As a result, the code is somewhat clunky: we must retrieve a list of all businesses, then for each business, look at each service to discover whether there is a binding supporting the given tModel (represented below by the String tModelKey, containing a valid TModel key with the prefix "uuid:"). This complexity goes away with the UDDI API v2.0 (release version, not draft).

    If the application developer is quite sure that he or she is interested only in services from a specific provider, he or she may optionally limit the search for bindings to that single provider (or to a pool of potential providers). While this would make the code considerably faster, the disadvantage is that if the service is shifted to a different provider, the service bindings would no longer be found. This particular disadvantage may be overcome by performing the wider search across all businesses only if the limited search fails (see Listing 2).

    The BindingObj class holds the UDDI BindingTemplate instance, as well as storing the results of the getVersion() call on the access point named in the BindingTemplate (by storing the BindingObj in a Java TreeSet with a custom comparator used to sort based on version numbers, we avoid the need to do an explicit sort later).

    The call to the Web service's getVersion() message is handled in the same way as a call to any other message in the service to be consumed. The developer should keep in mind that getVersion() returns a complex data structure of three integer values. As an example, when handling the response from a .NET service in Apache SOAP, it is necessary to explicitly deserialize the structure (see Listing 3).

    The reference implementation provided with this article contains the full code examples (source code for this article can be found online at www.sys-con.com/webservices/sourcec.cfm).

    Deprecation
    If service versioning is implemented using the method described above (i.e., searching by bindings based on tModel), deprecation of a Web service may be implemented by deprecating the specific tModel(s) supported by that Web service.

    When a specific tModel is to be taken out of service, its UDDI registry entry is modified to add the identifier DEPRECATED, with a value of the date (in YYYY/MM/DD format) after which the tModel is no longer supported. Optional identifiers are DEPRECATED_MSG, containing additional details on the deprecation, and DEPRECATED_ LINK, a URL to which users may refer for information that is more detailed.

    To support deprecation, the application developer inserts a check into the service binding code; prior to looking for services that support the tModel, the tModel "identifierBag" data structure is checked for the DEPRECATED flag and value. There are three possible outcomes to this check:

  • The DEPRECATED flag is not set: The code continues to try to find the most recent service version.
  • The DEPRECATED flag is set with a date greater than the current date: The result is a console message warning of the deprecation (optionally populated with information from DEPRECATED_MSG and DEPRECATED_LINK). The code continues to look for the most recent service version.
  • The DEPRECATED flag is set with a date less than or equal to the current date: The result is a fatal exception (optionally populated with information from DEPRECATED_ MSG and DEPRECATED_LINK).

    To implement this deprecation method, developers only need to insert their own code when encountering the aforementioned conditions, and direct the information appropriately within their application (e.g., to the console, to an alarming system, e-mail to the administrator, etc.).

    The Web service should be kept in service for some locally defined minimum period of time following the deprecation date of its last tModel(s), and its access logs checked on a daily basis. Continued access implies that an application has bound directly to the Web service (or that deprecation warnings have been ignored), and it will be necessary to immediately follow up with the application developers to directly notify them of the Web service's impending demise. The application architect should also be contacted, to provide remedial education on the recommended method of binding to a Web service.

    After this period, the Web service may be removed from service. The owner of the tModel should then delete the registry entry for the tModel from any UDDI registries to prevent any inadvertent future use of that TModel.

    Deprecation Code Walkthrough
    Assuming the existence of a string tModelKey, containing a valid tModel key with the prefix "uuid:", the Java code in Listing 4 may be used to retrieve a tModel object.

    Now that we have a tModel object (tm), we can examine the identifierBag in the deprecation-related tags (see Listing 5).

    If the DEPRECATED identifier is not present, the deprecation check is complete. If it is present, we must compare the deprecation date to the current date to see whether the error produced should be nonfatal (deprecation has not yet occurred) or fatal (deprecation has occurred).

    In either case, when we generate the message explaining the deprecation, we should include the content of DEPRECATED_MSG (a brief explanation of the deprecation) and DEPRECATED_LINK (a link to a more complete explanation of the deprecation; see Listing 6).

    Development Roadmap and Final Notes
    In summary, to implement versioning and deprecation, the following roadmap is recommended:

    1.   Web service developer builds support for getVersion message into his or her service.
    2.   Web service developer registers Web service in UDDI.
    3.   Web service consumer programs to interface, rather than implementation.
    4.   Web service consumer checks for deprecation of interface on a regular basis.

    The process outlined in this document is reasonably lightweight. By limiting the requirements to placing versioning and deprecation data in standard locations, the developers are free to determine the best approach for implementation within their own application context. For an application that carries out a startup procedure at regular intervals, it may mean retrieving the appropriate binding upon startup and performing a deprecation check as a maintenance process once a month. For an application intended to run continuously, it may mean checking for more recent versions and deprecations once a week.

    To be successful, Web service and application developers must follow the processes outlined here. While I believe that this strategy is logical and sound in its own right, it is further supported by the design of the UDDI businessService and bindingTemplate data structures. The absence of identifiers on these structures requires that versioning and deprecation information be stored either in the free-text description fields, or in some other data structure as dictated by some internal process.

    One very important principle that Web service developers must follow is that any time they modify the WSDL interface, they must create a new tModel. A given tModel represents a version of a specification (in this case, an interface and implementation specification). Just as you cannot go back and modify an existing specification and keep the original version number, you cannot modify a tModel (or the underlying versions of the documents it refers to) once released. Developers will code their applications to the interface described in the WSDL file attached to the tModel but if the Web service developer changes that interface without issuing a new tModel, application Web service calls will suddenly start breaking.

    This approach to versioning takes advantage of the features of UDDI, but relies upon the participation of both application and Web service developers in equal measure (sort of the Web services version of Mutual Assured Destruction). Application developers rely on Web service developers to implement the getVersion message, to maintain proper UDDI registry entries, and to continue supporting specific interfaces until they are officially deprecated. Web service developers rely on application developers to bind to a service based on the tModel required, and to use UDDI to find the binding for the latest version of a service supporting that tModel.

    Programming to interfaces, rather than to specific implementations of Web services, ensures that application developers will always use the most up-to-date Web service, and will be notified in a timely manner of all (and only) relevant interface deprecations.

  • About Jeffrey Kenyon
    Jeff Kenyon is a software development engineer and architect with Qwest
    Communications, and was a technical lead on Qwest's internal implementation
    of UDDI. He is a Sun Certified Java Programmer and Web Component Developer.

    Email address to use with article: jkenyon@indra.com

    In order to post a comment you need to be registered and logged in.

    Register | Sign-in

    Reader Feedback: Page 1 of 1

    SOA World Latest Stories
    The dynamic nature of the cloud means that change is a constant when it comes to modern cloud-based infrastructure. Delivering modern applications to end users, therefore, is a constantly shifting challenge. Delivery automation helps IT Ops teams ensure that apps are providing an optim...
    Kubernetes is an open source system for automating deployment, scaling, and management of containerized applications. Kubernetes was originally built by Google, leveraging years of experience with managing container workloads, and is now a Cloud Native Compute Foundation (CNCF) project...
    Modern software design has fundamentally changed how we manage applications, causing many to turn to containers as the new virtual machine for resource management. As container adoption grows beyond stateless applications to stateful workloads, the need for persistent storage is founda...
    The past few years have brought a sea change in the way applications are architected, developed, and consumed—increasing both the complexity of testing and the business impact of software failures. How can software testing professionals keep pace with modern application delivery, given...
    SYS-CON Events announced today that Synametrics Technologies will exhibit at SYS-CON's 22nd International Cloud Expo®, which will take place on June 5-7, 2018, at the Javits Center in New York, NY. Synametrics Technologies is a privately held company based in Plainsboro, New Jersey th...
    You know you need the cloud, but you’re hesitant to simply dump everything at Amazon since you know that not all workloads are suitable for cloud. You know that you want the kind of ease of use and scalability that you get with public cloud, but your applications are architected in a w...
    Subscribe to the World's Most Powerful Newsletters
    Subscribe to Our Rss Feeds & Get Your SYS-CON News Live!
    Click to Add our RSS Feeds to the Service of Your Choice:
    Google Reader or Homepage Add to My Yahoo! Subscribe with Bloglines Subscribe in NewsGator Online
    myFeedster Add to My AOL Subscribe in Rojo Add 'Hugg' to Newsburst from CNET News.com Kinja Digest View Additional SYS-CON Feeds
    Publish Your Article! Please send it to editorial(at)sys-con.com!

    Advertise on this site! Contact advertising(at)sys-con.com! 201 802-3021


    SYS-CON Featured Whitepapers
    ADS BY GOOGLE