[CONF] Apache CXF 2.0 Documentation: Provider Services (page edited)

Wed, 12 Sep 2007 15:24:29 -0700

Page Edited : CXF20DOC : Provider Services

Provider Services has been edited by Eric Johnson (Sep 12, 2007).

(View changes)

Content:

Messaging Modes

Overview

Objects that implement the Provider interface have two messaging modes:

  • Message mode
  • Payload mode

The messaging mode you specify determines the level of messaging detail that is passed to your implementation.

Message mode

When using message mode, a Provider implementation works with complete messages. A complete message includes any binding specific headers and wrappers. For example, a Provider implementation that uses a SOAP binding would receive requests as fully specified SOAP message. Any response returned from the implementation would also need to be a fully specified SOAP message.

You specify that a Provider implementation uses message mode by providing the value java.xml.ws.Service.Mode.MESSAGE as the value to the javax.xml.ws.ServiceMode annotation.

@WebServiceProvider
@ServiceMode(value=Service.Mode.MESSAGE)
public class stockQuoteProvider implements Provider<SOAPMessage>
{
  ...
}


Payload mode



In payload mode a Provider implementation works with only the payload of a message. For example, a Provider implementation working in payload mode works only with the body of a SOAP message. The binding layer processes any binding level wrappers and headers.




When working with a binding that does not use special wrappers, such as the Artix ESB XML binding, payload mode and message mode provide the same results.


You specify that a Provider implementation uses payload mode by providing the value java.xml.ws.Service.Mode.PAYLOAD as the value to the javax.xml.ws.ServiceMode annotation.




@WebServiceProvider
@ServiceMode(value=Service.Mode.PAYLOAD)
public class stockQuoteProvider implements Provider<DOMSource>
{
  ...
}






If you do not provide the @ServiceMode annotation, the Provider implementation will default to using payload mode.



Data Types




Overview



Provider implementations, because they are low-level objects, cannot use the same JAXB generated types as the higher level consumer APIs. Provider implementations work with the following types of objects:


    
	
  • javax.xml.transform.Source
    • 
	
  • javax.xml.soap.SOAPMessage
    • 
	
  • javax.activation.DataSource
    • 





Using Source objects



A Provider implementation can accept and return objects that are derived from the javax.xml.transform.Source interface. Source objects are low level objects that hold XML documents. Each Source implementation provides methods that access the stored XML documents and manipulate its contents. The following objects implement the Source interface:


    
	
  • DOMSource holds XML messages as a Document Object Model(DOM) tree. The XML message is stored as a set of Node objects that can be accessed using the getNode() method. Nodes can be updated or added to the DOM tree using the setNode() method.
    • 
	
  • SAXSource holds XML messages as a Simple API for XML (SAX) object. SAX objects contain an InputSource object that contains the raw data and an XMLReader object that parses the raw data.
    • 
	
  • StreamSource holds XML messages as a data stream. The data stream can be manipulated as would any other data stream.

    

    When using Source objects the developer is responsible for ensuring that all required binding specific wrappers are added to the message. For example, when interacting with a service expecting SOAP messages, the developer must ensure that the required SOAP envelope is added to the outgoing request and that the SOAP envelope's contents are correct.
    • 





Using SOAPMessage objects



Provider implementations can use javax.xml.soap.SOAPMessage objects when the following conditions are true:


    
	
  • the Provider implementation is using the SOAP binding.
    • 
	
  • the Provider implementation is using message mode.
    • 





A SOAPMessage object, as the name implies, holds a SOAP message. They contain one SOAPPart object and zero or more AttachmentPart objects. The SOAPPart object contains the SOAP specific portions of the SOAP message including the SOAP envelope, any SOAP headers, and the SOAP message body. The AttachmentPart objects contain binary data that was passed as an attachment.



Using DataSource objects



Provider implementations can use objects that implement the javax.activation.DataSource interface when the following conditions are true:


    
	
  • the implementation is using the HTTP binding.
    • 
	
  • the implementation is using message mode.
    • 





DataSource objects provide a mechanism for working with MIME typed data from a variety of sources including URLs, files, and byte arrays.

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences

Reply via email to