JBoss.orgCommunity Documentation
This pages is meant to be something like a bridge from the very high level web service concepts highlighted here and the most important specifications the web service technology platform is based on.
Contracts carry technical constraints and requirements of the exposed service as well as information about data to be exchange to interact with the service. They comprise technical descriptions and optional non-technical documents. The latter might include human readable description of the service and the business process it is part of as well as service level agreement / quality of provided service information.
Service description is mainly provided using the standard Web Service Description Language (WSDL). Practically speaking this means one or more XML files containing information including the service location (endpoint address), the service functionalities (operations), the input/output messages involved in the communication and the business data structure. The latter is basically one or more XML Schema definition. Moreover recent specifications (like WS-Policy) allow for more advanced service capabilities to be stated in the contract through WSDL extensions.
Web service stacks like JBossWS usually have tools to both generate and consume technical contracts. This helps ensuring also from a practical point of view that owners of service producer (server) and consumer (client) only need contracts to establish the communication.
One of the main concerns about service contracts is the way they're obtained.
As previously said, tools allow developers to automatically generate WSDL contract files given their service implementation. Advantages and disadvantage of this delivery process include:
Developers do not have to deal with contracts by hand thus deep knowledge of WSDL and XML is not required.
Less effort and time required for services to be developed and go live to production environment.
Contracts usually need frequent maintenance, refactoring and versioning.
Developers may write contracts first instead. This usually implies an initial collaboration of architects and business analysts to define a conceptual service design together.
Services with contracts obtained this way may easily cooperate in a service oriented architecture
More effort and time required for web service project start-up
Deep knowledge of WSDL and related technology required
Contracts tend to have longer lifespans and usually require less maintenance.
As stated by the W3C definition, the communication between web services is standardized by the SOAP specification. This means XML messages flow from the provider and consumer endpoints.
Messages' content is described in the wsdl contract. The WSDL file also states the transport protocol to be used for the transmission; the most common one is of course HTTP, however JMS, SMTP and other ones are allowed.
The above mentioned specifications are quite common nowadays in the IT industry and many enterprise have been using them since years.
However a real added value to the web service platform is coming from a lot of recent additional specifications. These cover features that are really relevant to deliver mission critical enterprise services. For example some of the most important agreements major vendors came to are those on security (WS-Security) and reliable messaging (WS-Reliable Messaging).
Unfortunately the web service platform is still being defined and many other specifications have not been implemented by all vendors yet. It is nevertheless important to know from a web service beginner point of view that many advanced features are actually supported and thus make possible to cope with many real world enterprise level issues. Moreover the platform is being continuously enriched and standardized.
Further knowledge is of course required to better understand the web service technology platform. This however goes beyond the aim of this web service introduction. The highlighted concepts and references above should nevertheless allow developers with no previous exposure to web service technology to go through the core of JBossWS documentation.
A rich list of specifications and articles can be found here and should be used to acquire deeper knowledge. Moreover the whole documentation refers to authoritative third-party documentation and official specifications whenever required.