Author: alessio.soldano(a)jboss.com Date: 2008-11-18 03:43:48 -0500 (Tue, 18 Nov 2008) New Revision: 8749 Added: stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/AbstractSOAPMessage.java Modified: stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/SOAPMessageImpl.java Log: Externalize basic SOAPMessage impl to core Added: stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/AbstractSOAPMessage.java =================================================================== --- stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/AbstractSOAPMessage.java (rev 0) +++ stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/AbstractSOAPMessage.java 2008-11-18 08:43:48 UTC (rev 8749) @@ -0,0 +1,323 @@ +/* + * JBoss, Home of Professional Open Source. + * Copyright 2006, Red Hat Middleware LLC, and individual contributors + * as indicated by the @author tags. See the copyright.txt file in the + * distribution for a full listing of individual contributors. + * + * This is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ +package org.jboss.ws.core.soap; + +import java.io.IOException; +import java.io.OutputStream; +import java.util.HashMap; +import java.util.Iterator; + +import javax.activation.DataHandler; +import javax.xml.soap.AttachmentPart; +import javax.xml.soap.MimeHeaders; +import javax.xml.soap.SOAPBody; +import javax.xml.soap.SOAPElement; +import javax.xml.soap.SOAPEnvelope; +import javax.xml.soap.SOAPException; +import javax.xml.soap.SOAPHeader; +import javax.xml.soap.SOAPMessage; +import javax.xml.soap.SOAPPart; + +/** The root class for all SOAP messages. As transmitted on the "wire", a SOAP message is an XML document or a + * MIME message whose first body part is an XML/SOAP document. + * + * A SOAPMessage object consists of a SOAP part and optionally one or more attachment parts. + * The SOAP part for a SOAPMessage object is a SOAPPart object, which contains information used for message routing and + * identification, and which can contain application-specific content. All data in the SOAP Part of a message must be in XML format. + * + * A new SOAPMessage object contains the following by default: + * + * A SOAPPart object + * A SOAPEnvelope object + * A SOAPBody object + * A SOAPHeader object + * + * The SOAP part of a message can be retrieved by calling the method SOAPMessage.getSOAPPart(). + * The SOAPEnvelope object is retrieved from the SOAPPart object, and the SOAPEnvelope object is used to retrieve the + * SOAPBody and SOAPHeader objects. + * + * SOAPPart sp = message.getSOAPPart(); + * SOAPEnvelope se = sp.getEnvelope(); + * SOAPBody sb = se.getBody(); + * SOAPHeader sh = se.getHeader(); + * + * In addition to the mandatory SOAPPart object, a SOAPMessage object may contain zero or more AttachmentPart objects, + * each of which contains application-specific data. The SOAPMessage interface provides methods for creating AttachmentPart + * objects and also for adding them to a SOAPMessage object. A party that has received a SOAPMessage object can examine + * its contents by retrieving individual attachment parts. + * + * Unlike the rest of a SOAP message, an attachment is not required to be in XML format and can therefore be anything from + * simple text to an image file. Consequently, any message content that is not in XML format must be in an AttachmentPart object. + * + * A MessageFactory object may create SOAPMessage objects with behavior that is specialized to a particular + * implementation or application of SAAJ. For instance, a MessageFactory object may produce SOAPMessage objects that + * conform to a particular Profile such as ebXML. In this case a MessageFactory object might produce SOAPMessage + * objects that are initialized with ebXML headers. + * + * In order to ensure backward source compatibility, methods that are added to this class after version 1.1 of the SAAJ + * specification are all concrete instead of abstract and they all have default implementations. + * Unless otherwise noted in the JavaDocs for those methods the default implementations simply throw an + * UnsupportedOperationException and the SAAJ implementation code must override them with methods that provide + * the specified behavior. Legacy client code does not have this restriction, however, so long as there is no claim + * made that it conforms to some later version of the specification than it was originally written for. + * A legacy class that extends the SOAPMessage class can be compiled and/or run against succeeding versions of + * the SAAJ API without modification. If such a class was correctly implemented then it will continue to behave + * correctly relative the the version of the specification against which it was written. + * + * @author Scott.Stark(a)jboss.org + */ +public abstract class AbstractSOAPMessage extends SOAPMessage +{ + private HashMap properties = new HashMap(); + + /** Specifies the character type encoding for the SOAP Message. Valid values include "utf-8" and "utf-16". The default is "utf-8". */ + public static final String CHARACTER_SET_ENCODING = "javax.xml.soap.character-set-encoding"; + /** Specifies whether the SOAP Message will contain an XML declaration when it is sent. The default is "false". */ + public static final String WRITE_XML_DECLARATION = "javax.xml.soap.write-xml-declaration"; + + /** + * Adds the given AttachmentPart object to this SOAPMessage object. + * An AttachmentPart object must be created before it can be added to a message. + * @param attachmentpart an AttachmentPart object that is to become part of this SOAPMessage object + */ + public abstract void addAttachmentPart(AttachmentPart attachmentpart); + + /** + * Creates a new empty AttachmentPart object. Note that the method addAttachmentPart must be called with this new + * AttachmentPart object as the parameter in order for it to become an attachment to this SOAPMessage object. + * @return a new AttachmentPart object that can be populated and added to this SOAPMessage object + */ + public abstract AttachmentPart createAttachmentPart(); + + /** + * Creates an AttachmentPart object and populates it using the given DataHandler object. + * @param datahandler the javax.activation.DataHandler object that will generate the content for this SOAPMessage object + * @return a new AttachmentPart object that contains data generated by the given DataHandler object + */ + public AttachmentPart createAttachmentPart(DataHandler datahandler) + { + AttachmentPart part = createAttachmentPart(); + part.setDataHandler(datahandler); + return part; + } + + /** + * Creates an AttachmentPart object and populates it with the specified data of the specified content type. + * @param content an Object containing the content for this SOAPMessage object + * @param contentType a String object giving the type of content; examples are "text/xml", "text/plain", and "image/jpeg" + * @return a new AttachmentPart object that contains the given data + */ + public AttachmentPart createAttachmentPart(Object content, String contentType) + { + AttachmentPart part = createAttachmentPart(); + part.setContent(content, contentType); + return part; + } + + /** + * Retrieves value of the specified property. + * @param property the name of the property to retrieve + * @return the value associated with the named property or null if no such property exists. + * @throws SOAPException if the property name is not recognized. + */ + public Object getProperty(String property) throws SOAPException + { + return properties.get(property); + } + + /** + * Associates the specified value with the specified property. If there was already a value associated with this + * property, the old value is replaced. + * + * The valid property names include WRITE_XML_DECLARATION and CHARACTER_SET_ENCODING. + * All of these standard SAAJ properties are prefixed by "javax.xml.soap". + * Vendors may also add implementation specific properties. + * These properties must be prefixed with package names that are unique to the vendor. + * + * Setting the property WRITE_XML_DECLARATION to "true" will cause an XML Declaration to be written out at the start + * of the SOAP message. The default value of "false" suppresses this declaration. + * + * The property CHARACTER_SET_ENCODING defaults to the value "utf-8" which causes the SOAP message to be + * encoded using UTF-8. Setting CHARACTER_SET_ENCODING to "utf-16" causes the SOAP message to be encoded using UTF-16. + * + * Some implementations may allow encodings in addition to UTF-8 and UTF-16. Refer to your vendor's documentation for details. + * + * @param property the property with which the specified value is to be associated. + * @param value the value to be associated with the specified property + * @throws SOAPException if the property name is not recognized + */ + public void setProperty(String property, Object value) throws SOAPException + { + properties.put(property, value); + } + + /** + * Gets the SOAP Body contained in this SOAPMessage object. + * @return the SOAPBody object contained by this SOAPMessage object + * @throws SOAPException if the SOAP Body does not exist or cannot be retrieved + */ + public SOAPBody getSOAPBody() throws SOAPException + { + SOAPPart soapPart = getSOAPPart(); + if (soapPart != null) + { + SOAPEnvelope soapEnvelope = soapPart.getEnvelope(); + if (soapEnvelope != null) + { + SOAPBody soapBody = soapEnvelope.getBody(); + return soapBody; + } + } + throw new SOAPException("Cannot obtain SOAPBody from SOAPMessage"); + } + + /** + * Gets the SOAP Header contained in this SOAPMessage object. + * @return the SOAPHeader object contained by this SOAPMessage object + * @throws SOAPException if the SOAP Header does not exist or cannot be retrieved + */ + public SOAPHeader getSOAPHeader() throws SOAPException + { + SOAPPart soapPart = getSOAPPart(); + if (soapPart != null) + { + SOAPEnvelope soapEnvelope = soapPart.getEnvelope(); + if (soapEnvelope != null) + { + SOAPHeader soapHeader = soapEnvelope.getHeader(); + return soapHeader; + } + } + throw new SOAPException("Cannot obtain SOAPHeader from SOAPMessage"); + } + + /** + * Retrieves a description of this SOAPMessage object's content. + * @return a String describing the content of this message or null if no description has been set + */ + public abstract String getContentDescription(); + + /** + * Sets the description of this SOAPMessage object's content with the given description. + * @param description a String describing the content of this message + */ + public abstract void setContentDescription(String description); + + /** + * Returns all the transport-specific MIME headers for this SOAPMessage object in a transport-independent fashion. + * @return a MimeHeaders object containing the MimeHeader objects + */ + public abstract MimeHeaders getMimeHeaders(); + + /** + * Gets the SOAP part of this SOAPMessage object. + * + * SOAPMessage object contains one or more attachments, the SOAP Part must be the first MIME body part in the message. + * + * @return the SOAPPart object for this SOAPMessage object + */ + public abstract SOAPPart getSOAPPart(); + + /** + * Removes all AttachmentPart objects that have been added to this SOAPMessage object. + * + * This method does not touch the SOAP part. + */ + public abstract void removeAllAttachments(); + + /** + * Removes all the AttachmentPart objects that have header entries that match the specified headers. + * Note that the removed attachment could have headers in addition to those specified. + * @param headers a MimeHeaders object containing the MIME headers for which to search + * @since SAAJ 1.3 + */ + public abstract void removeAttachments(MimeHeaders headers); + + /** + * Gets a count of the number of attachments in this message. This count does not include the SOAP part. + * @return the number of AttachmentPart objects that are part of this SOAPMessage object + */ + public abstract int countAttachments(); + + /** + * Retrieves all the AttachmentPart objects that are part of this SOAPMessage object. + * @return an iterator over all the attachments in this message + */ + public abstract Iterator getAttachments(); + + /** + * Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null + * if no such attachment exists. References can be made via an href attribute as described in SOAP Messages with Attachments, + * or via a single Text child node containing a URI as described in the WS-I Attachments Profile 1.0 for elements of + * schema type ref:swaRef(ref:swaRef). These two mechanisms must be supported. + * The support for references via href attribute also implies that this method should also be supported on an element that + * is an xop:Include element ( XOP). other reference mechanisms may be supported by individual implementations of this standard. + * Contact your vendor for details. + * @param element The SOAPElement containing the reference to an Attachment + * @return the referenced AttachmentPart or null if no such AttachmentPart exists or no reference can be found in this SOAPElement. + * @throws SOAPException if there is an error in the attempt to access the attachment + * @since SAAJ 1.3 + */ + public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException; + + /** + * Retrieves all the AttachmentPart objects that have header entries that match the specified headers. + * Note that a returned attachment could have headers in addition to those specified. + * @param mimeheaders a MimeHeaders object containing the MIME headers for which to search + * @return an iterator over all attachments that have a header that matches one of the given headers + */ + public abstract Iterator getAttachments(MimeHeaders mimeheaders); + + /** + * Updates this SOAPMessage object with all the changes that have been made to it. + * This method is called automatically when writeTo(OutputStream) is called. + * However, if changes are made to a message that was received or to one that has already been sent, the method + * saveChanges needs to be called explicitly in order to save the changes. + * The method saveChanges also generates any changes that can be read back (for example, + * a MessageId in profiles that support a message id). All MIME headers in a message that is created for sending + * purposes are guaranteed to have valid values only after saveChanges has been called. + * + * In addition, this method marks the point at which the data from all constituent AttachmentPart objects are pulled into the message. + * + * @throws SOAPException if there was a problem saving changes to this message. + */ + public abstract void saveChanges() throws SOAPException; + + /** + * Indicates whether this SOAPMessage object needs to have the method saveChanges called on it. + * @return true if saveChanges needs to be called; false otherwise. + */ + public abstract boolean saveRequired(); + + /** + * Writes this SOAPMessage object to the given output stream. The externalization format is as defined by the + * SOAP 1.1 with Attachments specification. + * + * If there are no attachments, just an XML stream is written out. For those messages that have attachments, + * writeTo writes a MIME-encoded byte stream. + * + * @param outputstream the OutputStream object to which this SOAPMessage object will be written + * @throws SOAPException if there was a problem in externalizing this SOAP message + * @throws IOException if an I/O error occurs + */ + public abstract void writeTo(OutputStream outputstream) throws SOAPException, IOException; +} Property changes on: stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/AbstractSOAPMessage.java ___________________________________________________________________ Name: svn:executable + * Name: svn:keywords + Id Revision Name: svn:eol-style + LF Modified: stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/SOAPMessageImpl.java =================================================================== --- stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/SOAPMessageImpl.java 2008-11-18 08:42:58 UTC (rev 8748) +++ stack/native/branches/asoldano/modules/core/src/main/java/org/jboss/ws/core/soap/SOAPMessageImpl.java 2008-11-18 08:43:48 UTC (rev 8749) @@ -61,7 +61,7 @@ * @author Thomas.Diesler(a)jboss.org * @author <a href="mailto:jason@stacksmash.com">Jason T. Greene</a> */ -public class SOAPMessageImpl extends SOAPMessage implements SOAPMessageAbstraction +public class SOAPMessageImpl extends AbstractSOAPMessage implements SOAPMessageAbstraction { private boolean saveRequired = true; private MimeHeaders mimeHeaders = new MimeHeaders();