Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFault.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFault.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFault.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFault.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,203 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +import java.util.Locale; + +/** + * An element in the <CODE>SOAPBody</CODE> object that contains + * error and/or status information. This information may relate to + * errors in the <CODE>SOAPMessage</CODE> object or to problems + * that are not related to the content in the message itself. + * Problems not related to the message itself are generally errors + * in processing, such as the inability to communicate with an + * upstream server. + * <P> + * The <CODE>SOAPFault</CODE> interface provides methods for + * retrieving the information contained in a <CODE> + * SOAPFault</CODE> object and for setting the fault code, the + * fault actor, and a string describing the fault. A fault code is + * one of the codes defined in the SOAP 1.1 specification that + * describe the fault. An actor is an intermediate recipient to + * whom a message was routed. The message path may include one or + * more actors, or, if no actors are specified, the message goes + * only to the default actor, which is the final intended + * recipient. + */ +public interface SOAPFault extends SOAPBodyElement { + + /** + * Sets this <CODE>SOAPFault</CODE> object with the given + * fault code. + * + * <P>Fault codes, which given information about the fault, + * are defined in the SOAP 1.1 specification.</P> + * @param faultCode a <CODE>String</CODE> giving + * the fault code to be set; must be one of the fault codes + * defined in the SOAP 1.1 specification + * @throws SOAPException if there was an error in + * adding the <CODE>faultCode</CODE> to the underlying XML + * tree. + * @see #getFaultCode() getFaultCode() + */ + public abstract void setFaultCode(String faultCode) throws SOAPException; + + /** + * Gets the fault code for this <CODE>SOAPFault</CODE> + * object. + * @return a <CODE>String</CODE> with the fault code + * @see #setFaultCode(java.lang.String) setFaultCode(java.lang.String) + */ + public abstract String getFaultCode(); + + /** + * Sets this <CODE>SOAPFault</CODE> object with the given + * fault actor. + * + * <P>The fault actor is the recipient in the message path who + * caused the fault to happen.</P> + * @param faultActor a <CODE>String</CODE> + * identifying the actor that caused this <CODE> + * SOAPFault</CODE> object + * @throws SOAPException if there was an error in + * adding the <CODE>faultActor</CODE> to the underlying XML + * tree. + * @see #getFaultActor() getFaultActor() + */ + public abstract void setFaultActor(String faultActor) throws SOAPException; + + /** + * Gets the fault actor for this <CODE>SOAPFault</CODE> + * object. + * @return a <CODE>String</CODE> giving the actor in the message + * path that caused this <CODE>SOAPFault</CODE> object + * @see #setFaultActor(java.lang.String) setFaultActor(java.lang.String) + */ + public abstract String getFaultActor(); + + /** + * Sets the fault string for this <CODE>SOAPFault</CODE> + * object to the given string. + * + * @param faultString a <CODE>String</CODE> + * giving an explanation of the fault + * @throws SOAPException if there was an error in + * adding the <CODE>faultString</CODE> to the underlying XML + * tree. + * @see #getFaultString() getFaultString() + */ + public abstract void setFaultString(String faultString) + throws SOAPException; + + /** + * Gets the fault string for this <CODE>SOAPFault</CODE> + * object. + * @return a <CODE>String</CODE> giving an explanation of the + * fault + */ + public abstract String getFaultString(); + + /** + * Returns the detail element for this <CODE>SOAPFault</CODE> + * object. + * + * <P>A <CODE>Detail</CODE> object carries + * application-specific error information related to <CODE> + * SOAPBodyElement</CODE> objects.</P> + * @return a <CODE>Detail</CODE> object with + * application-specific error information + */ + public abstract Detail getDetail(); + + /** + * Creates a <CODE>Detail</CODE> object and sets it as the + * <CODE>Detail</CODE> object for this <CODE>SOAPFault</CODE> + * object. + * + * <P>It is illegal to add a detail when the fault already + * contains a detail. Therefore, this method should be called + * only after the existing detail has been removed.</P> + * @return the new <CODE>Detail</CODE> object + * @throws SOAPException if this + * <CODE>SOAPFault</CODE> object already contains a valid + * <CODE>Detail</CODE> object + */ + public abstract Detail addDetail() throws SOAPException; + + /** + * Sets this <code>SOAPFault</code> object with the given fault code. + * + * Fault codes, which give information about the fault, are defined in the + * SOAP 1.1 specification. A fault code is mandatory and must be of type + * <code>QName</code>. This method provides a convenient way to set a fault + * code. For example, + * + * <pre> + SOAPEnvelope se = ...; + // Create a qualified name in the SOAP namespace with a localName + // of "Client". Note that prefix parameter is optional and is null + // here which causes the implementation to use an appropriate prefix. + Name qname = se.createName("Client", null, + SOAPConstants.URI_NS_SOAP_ENVELOPE); + SOAPFault fault = ...; + fault.setFaultCode(qname); + * + * It is preferable to use this method over setFaultCode(String). + * + * @param name a <code>Name</code> object giving the fault code to be set. + * It must be namespace qualified. + * @throws SOAPException if there was an error in adding the + * <code>faultcode</code> element to the underlying XML tree + */ + public abstract void setFaultCode(Name name) throws SOAPException; + + /** + * Gets the mandatory SOAP 1.1 fault code for this <code>SOAPFault</code> + * object as a SAAJ <code>Name</code> object. The SOAP 1.1 specification + * requires the value of the "faultcode" element to be of type QName. This + * method returns the content of the element as a QName in the form of a + * SAAJ <code>Name</code> object. This method should be used instead of the + * <code>getFaultCode()</code> method since it allows applications to easily + * access the namespace name without additional parsing. + * <p> + * In the future, a QName object version of this method may also be added. + * @return a <code>Name</code> representing the faultcode + */ + public abstract Name getFaultCodeAsName(); + + /** + * Sets the fault string for this <code>SOAPFault</code> object to the given + * string and localized to the given locale. + * + * @param faultString a <code>String</code> giving an explanation of + * the fault + * @param locale a <code>Locale</code> object indicating the + * native language of the <code>faultString</code> + * @throws SOAPException if there was an error in adding the + * <code>faultString</code> to the underlying XML tree + */ + public abstract void setFaultString(String faultString, Locale locale) throws SOAPException; + + /** + * Returns the optional detail element for this <code>SOAPFault</code> + * object. + * + * @return a <code>Locale</code> object indicating the native language of + * the fault string or <code>null</code> if no locale was + * specified + */ + public abstract Locale getFaultStringLocale(); +}
Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFaultElement.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFaultElement.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFaultElement.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFaultElement.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,26 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +/** + * A representation of the contents in + * a <code>SOAPFault</code> object. The <code>Detail</code> interface + * is a <code>SOAPFaultElement</code> object that has been defined. + * <p> + * Content is added to a <code>SOAPFaultElement</code> using the + * <code>SOAPElement</code> method <code>addTextNode</code>. + */ +public interface SOAPFaultElement extends SOAPElement {} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeader.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeader.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeader.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeader.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,149 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +import java.util.Iterator; + +/** + * <P>A representation of the SOAP header element. A SOAP header + * element consists of XML data that affects the way the + * application-specific content is processed by the message + * provider. For example, transaction semantics, authentication + * information, and so on, can be specified as the content of a + * <CODE>SOAPHeader</CODE> object.</P> + * + * <P>A <CODE>SOAPEnvelope</CODE> object contains an empty <CODE> + * SOAPHeader</CODE> object by default. If the <CODE> + * SOAPHeader</CODE> object, which is optional, is not needed, it + * can be retrieved and deleted with the following line of code. + * The variable <I>se</I> is a <CODE>SOAPEnvelope</CODE> + * object.</P> + * <PRE> + * se.getHeader().detachNode(); + * </PRE> + * A <CODE>SOAPHeader</CODE> object is created with the <CODE> + * SOAPEnvelope</CODE> method <CODE>addHeader</CODE>. This method, + * which creates a new header and adds it to the envelope, may be + * called only after the existing header has been removed. + * <PRE> + * se.getHeader().detachNode(); + * SOAPHeader sh = se.addHeader(); + * </PRE> + * + * <P>A <CODE>SOAPHeader</CODE> object can have only <CODE> + * SOAPHeaderElement</CODE> objects as its immediate children. The + * method <CODE>addHeaderElement</CODE> creates a new <CODE> + * HeaderElement</CODE> object and adds it to the <CODE> + * SOAPHeader</CODE> object. In the following line of code, the + * argument to the method <CODE>addHeaderElement</CODE> is a + * <CODE>Name</CODE> object that is the name for the new <CODE> + * HeaderElement</CODE> object.</P> + * <PRE> + * SOAPHeaderElement shElement = sh.addHeaderElement(name); + * </PRE> + * @see SOAPHeaderElement SOAPHeaderElement + */ +public interface SOAPHeader extends SOAPElement { + + /** + * Creates a new <CODE>SOAPHeaderElement</CODE> object + * initialized with the specified name and adds it to this + * <CODE>SOAPHeader</CODE> object. + * @param name a <CODE>Name</CODE> object with + * the name of the new <CODE>SOAPHeaderElement</CODE> + * object + * @return the new <CODE>SOAPHeaderElement</CODE> object that + * was inserted into this <CODE>SOAPHeader</CODE> + * object + * @throws SOAPException if a SOAP error occurs + */ + public abstract SOAPHeaderElement addHeaderElement(Name name) + throws SOAPException; + + /** + * Returns a list of all the <CODE>SOAPHeaderElement</CODE> + * objects in this <CODE>SOAPHeader</CODE> object that have the + * the specified actor. An actor is a global attribute that + * indicates the intermediate parties to whom the message should + * be sent. An actor receives the message and then sends it to + * the next actor. The default actor is the ultimate intended + * recipient for the message, so if no actor attribute is + * included in a <CODE>SOAPHeader</CODE> object, the message is + * sent to its ultimate destination. + * @param actor a <CODE>String</CODE> giving the + * URI of the actor for which to search + * @return an <CODE>Iterator</CODE> object over all the <CODE> + * SOAPHeaderElement</CODE> objects that contain the + * specified actor + * @see #extractHeaderElements(java.lang.String) extractHeaderElements(java.lang.String) + */ + public abstract Iterator examineHeaderElements(String actor); + + /** + * Returns a list of all the <CODE>SOAPHeaderElement</CODE> + * objects in this <CODE>SOAPHeader</CODE> object that have + * the the specified actor and detaches them from this <CODE> + * SOAPHeader</CODE> object. + * + * <P>This method allows an actor to process only the parts of + * the <CODE>SOAPHeader</CODE> object that apply to it and to + * remove them before passing the message on to the next + * actor. + * @param actor a <CODE>String</CODE> giving the + * URI of the actor for which to search + * @return an <CODE>Iterator</CODE> object over all the <CODE> + * SOAPHeaderElement</CODE> objects that contain the + * specified actor + * @see #examineHeaderElements(java.lang.String) examineHeaderElements(java.lang.String) + */ + public abstract Iterator extractHeaderElements(String actor); + + /** + * Returns an <code>Iterator</code> over all the + * <code>SOAPHeaderElement</code> objects in this <code>SOAPHeader</code> + * object that have the specified actor and that have a MustUnderstand + * attribute whose value is equivalent to <code>true</code>. + * + * @param actor a <code>String</code> giving the URI of the actor for which + * to search + * @return an <code>Iterator</code> object over all the + * <code>SOAPHeaderElement</code> objects that contain the + * specified actor and are marked as MustUnderstand + */ + public abstract Iterator examineMustUnderstandHeaderElements(String actor); + + /** + * Returns an <code>Iterator</code> over all the + * <code>SOAPHeaderElement</code> objects in this <code>SOAPHeader</code> + * object. + * + * @return an <code>Iterator</code> object over all the + * <code>SOAPHeaderElement</code> objects contained by this + * <code>SOAPHeader</code> + */ + public abstract Iterator examineAllHeaderElements(); + + /** + * Returns an <code>Iterator</code> over all the + * <code>SOAPHeaderElement</code> objects in this <code>SOAPHeader </code> + * object and detaches them from this <code>SOAPHeader</code> object. + * + * @return an <code>Iterator</code> object over all the + * <code>SOAPHeaderElement</code> objects contained by this + * <code>SOAPHeader</code> + */ + public abstract Iterator extractAllHeaderElements(); +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeaderElement.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeaderElement.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeaderElement.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPHeaderElement.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,77 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +/** + * <P>An object representing the contents in the SOAP header part + * of the SOAP envelope. The immediate children of a <CODE> + * SOAPHeader</CODE> object can be represented only as <CODE> + * SOAPHeaderElement</CODE> objects.</P> + * + * <P>A <CODE>SOAPHeaderElement</CODE> object can have other + * <CODE>SOAPElement</CODE> objects as its children.</P> + */ +public interface SOAPHeaderElement extends SOAPElement { + + /** + * Sets the actor associated with this <CODE> + * SOAPHeaderElement</CODE> object to the specified actor. The + * default value of an actor is: <CODE> + * SOAPConstants.URI_SOAP_ACTOR_NEXT</CODE> + * @param actorURI a <CODE>String</CODE> giving + * the URI of the actor to set + * @see #getActor() getActor() + * @throws java.lang.IllegalArgumentException if + * there is a problem in setting the actor. + */ + public abstract void setActor(String actorURI); + + /** + * Returns the uri of the actor associated with this <CODE> + * SOAPHeaderElement</CODE> object. + * @return a <CODE>String</CODE> giving the URI of the + * actor + * @see #setActor(java.lang.String) setActor(java.lang.String) + */ + public abstract String getActor(); + + /** + * Sets the mustUnderstand attribute for this <CODE> + * SOAPHeaderElement</CODE> object to be on or off. + * + * <P>If the mustUnderstand attribute is on, the actor who + * receives the <CODE>SOAPHeaderElement</CODE> must process it + * correctly. This ensures, for example, that if the <CODE> + * SOAPHeaderElement</CODE> object modifies the message, that + * the message is being modified correctly.</P> + * @param mustUnderstand <CODE>true</CODE> to + * set the mustUnderstand attribute on; <CODE>false</CODE> + * to turn if off + * @throws java.lang.IllegalArgumentException if + * there is a problem in setting the actor. + * @see #getMustUnderstand() getMustUnderstand() + */ + public abstract void setMustUnderstand(boolean mustUnderstand); + + /** + * Returns whether the mustUnderstand attribute for this + * <CODE>SOAPHeaderElement</CODE> object is turned on. + * @return <CODE>true</CODE> if the mustUnderstand attribute of + * this <CODE>SOAPHeaderElement</CODE> object is turned on; + * <CODE>false</CODE> otherwise + */ + public abstract boolean getMustUnderstand(); +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPMessage.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPMessage.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPMessage.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPMessage.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,378 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +import javax.activation.DataHandler; +import java.io.IOException; +import java.io.OutputStream; +import java.util.Iterator; + +/** + * <P>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.</P> + * + * <P>A <CODE>SOAPMessage</CODE> object consists of a SOAP part + * and optionally one or more attachment parts. The SOAP part for + * a <CODE>SOAPMessage</CODE> object is a <CODE>SOAPPart</CODE> + * 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.</P> + * + * <P>A new <CODE>SOAPMessage</CODE> object contains the following + * by default:</P> + * + * <UL> + * <LI>A <CODE>SOAPPart</CODE> object</LI> + * + * <LI>A <CODE>SOAPEnvelope</CODE> object</LI> + * + * <LI>A <CODE>SOAPBody</CODE> object</LI> + * + * <LI>A <CODE>SOAPHeader</CODE> object</LI> + * </UL> + * The SOAP part of a message can be retrieved by calling the + * method <CODE>SOAPMessage.getSOAPPart()</CODE>. The <CODE> + * SOAPEnvelope</CODE> object is retrieved from the <CODE> + * SOAPPart</CODE> object, and the <CODE>SOAPEnvelope</CODE> + * object is used to retrieve the <CODE>SOAPBody</CODE> and <CODE> + * SOAPHeader</CODE> objects. + * <PRE> + * SOAPPart sp = message.getSOAPPart(); + * SOAPEnvelope se = sp.getEnvelope(); + * SOAPBody sb = se.getBody(); + * SOAPHeader sh = se.getHeader(); + * </PRE> + * + * <P>In addition to the mandatory <CODE>SOAPPart</CODE> object, a + * <CODE>SOAPMessage</CODE> object may contain zero or more <CODE> + * AttachmentPart</CODE> objects, each of which contains + * application-specific data. The <CODE>SOAPMessage</CODE> + * interface provides methods for creating <CODE> + * AttachmentPart</CODE> objects and also for adding them to a + * <CODE>SOAPMessage</CODE> object. A party that has received a + * <CODE>SOAPMessage</CODE> object can examine its contents by + * retrieving individual attachment parts.</P> + * + * <P>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 <CODE> + * AttachmentPart</CODE> object.</P> + * + * <P>A <CODE>MessageFactory</CODE> object creates new <CODE> + * SOAPMessage</CODE> objects. If the <CODE>MessageFactory</CODE> + * object was initialized with a messaging Profile, it produces + * <CODE>SOAPMessage</CODE> objects that conform to that Profile. + * For example, a <CODE>SOAPMessage</CODE> object created by a + * <CODE>MessageFactory</CODE> object initialized with the ebXML + * Profile will have the appropriate ebXML headers.</P> + * @see MessageFactory MessageFactory + * @see AttachmentPart AttachmentPart + */ +public abstract class SOAPMessage { + + public SOAPMessage() {} + + /** + * Retrieves a description of this <CODE>SOAPMessage</CODE> + * object's content. + * @return a <CODE>String</CODE> describing the content of this + * message or <CODE>null</CODE> if no description has been + * set + * @see #setContentDescription(java.lang.String) setContentDescription(java.lang.String) + */ + public abstract String getContentDescription(); + + /** + * Sets the description of this <CODE>SOAPMessage</CODE> + * object's content with the given description. + * @param description a <CODE>String</CODE> + * describing the content of this message + * @see #getContentDescription() getContentDescription() + */ + public abstract void setContentDescription(String description); + + /** + * Gets the SOAP part of this <CODE>SOAPMessage</CODE> object. + * + * + * <P>If a <CODE>SOAPMessage</CODE> object contains one or + * more attachments, the SOAP Part must be the first MIME body + * part in the message.</P> + * @return the <CODE>SOAPPart</CODE> object for this <CODE> + * SOAPMessage</CODE> object + */ + public abstract SOAPPart getSOAPPart(); + + /** + * Removes all <CODE>AttachmentPart</CODE> objects that have + * been added to this <CODE>SOAPMessage</CODE> object. + * + * <P>This method does not touch the SOAP part.</P> + */ + public abstract void removeAllAttachments(); + + /** + * Gets a count of the number of attachments in this + * message. This count does not include the SOAP part. + * @return the number of <CODE>AttachmentPart</CODE> objects + * that are part of this <CODE>SOAPMessage</CODE> + * object + */ + public abstract int countAttachments(); + + /** + * Retrieves all the <CODE>AttachmentPart</CODE> objects + * that are part of this <CODE>SOAPMessage</CODE> object. + * @return an iterator over all the attachments in this + * message + */ + public abstract Iterator getAttachments(); + + /** + * Retrieves all the <CODE>AttachmentPart</CODE> objects + * that have header entries that match the specified headers. + * Note that a returned attachment could have headers in + * addition to those specified. + * @param headers a <CODE>MimeHeaders</CODE> + * 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 headers); + + /** + * Adds the given <CODE>AttachmentPart</CODE> object to this + * <CODE>SOAPMessage</CODE> object. An <CODE> + * AttachmentPart</CODE> object must be created before it can be + * added to a message. + * @param attachmentpart an <CODE> + * AttachmentPart</CODE> object that is to become part of + * this <CODE>SOAPMessage</CODE> object + * @throws java.lang.IllegalArgumentException + */ + public abstract void addAttachmentPart(AttachmentPart attachmentpart); + + /** + * Creates a new empty <CODE>AttachmentPart</CODE> object. + * Note that the method <CODE>addAttachmentPart</CODE> must be + * called with this new <CODE>AttachmentPart</CODE> object as + * the parameter in order for it to become an attachment to this + * <CODE>SOAPMessage</CODE> object. + * @return a new <CODE>AttachmentPart</CODE> object that can be + * populated and added to this <CODE>SOAPMessage</CODE> + * object + */ + public abstract AttachmentPart createAttachmentPart(); + + /** + * Creates an <CODE>AttachmentPart</CODE> object and + * populates it using the given <CODE>DataHandler</CODE> + * object. + * @param datahandler the <CODE> + * javax.activation.DataHandler</CODE> object that will + * generate the content for this <CODE>SOAPMessage</CODE> + * object + * @return a new <CODE>AttachmentPart</CODE> object that + * contains data generated by the given <CODE> + * DataHandler</CODE> object + * @throws java.lang.IllegalArgumentException if + * there was a problem with the specified <CODE> + * DataHandler</CODE> object + * @see DataHandler DataHandler + * @see javax.activation.DataContentHandler DataContentHandler + */ + public AttachmentPart createAttachmentPart(DataHandler datahandler) { + + AttachmentPart attachmentpart = createAttachmentPart(); + + attachmentpart.setDataHandler(datahandler); + + return attachmentpart; + } + + /** + * Returns all the transport-specific MIME headers for this + * <CODE>SOAPMessage</CODE> object in a transport-independent + * fashion. + * @return a <CODE>MimeHeaders</CODE> object containing the + * <CODE>MimeHeader</CODE> objects + */ + public abstract MimeHeaders getMimeHeaders(); + + /** + * Creates an <CODE>AttachmentPart</CODE> object and + * populates it with the specified data of the specified content + * type. + * @param content an <CODE>Object</CODE> + * containing the content for this <CODE>SOAPMessage</CODE> + * object + * @param contentType a <CODE>String</CODE> + * object giving the type of content; examples are + * "text/xml", "text/plain", and "image/jpeg" + * @return a new <CODE>AttachmentPart</CODE> object that + * contains the given data + * @throws java.lang.IllegalArgumentException if the contentType does not match the type of the content + * object, or if there was no <CODE> + * DataContentHandler</CODE> object for the given content + * object + * @see DataHandler DataHandler + * @see javax.activation.DataContentHandler DataContentHandler + */ + public AttachmentPart createAttachmentPart(Object content, + String contentType) { + + AttachmentPart attachmentpart = createAttachmentPart(); + + attachmentpart.setContent(content, contentType); + + return attachmentpart; + } + + /** + * Updates this <CODE>SOAPMessage</CODE> object with all the + * changes that have been made to it. This method is called + * automatically when a message is sent or written to by the + * methods <CODE>ProviderConnection.send</CODE>, <CODE> + * SOAPConnection.call</CODE>, or <CODE> + * SOAPMessage.writeTo</CODE>. However, if changes are made to + * a message that was received or to one that has already been + * sent, the method <CODE>saveChanges</CODE> needs to be + * called explicitly in order to save the changes. The method + * <CODE>saveChanges</CODE> 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 <CODE>saveChanges</CODE> has been + * called. + * + * <P>In addition, this method marks the point at which the + * data from all constituent <CODE>AttachmentPart</CODE> + * objects are pulled into the message.</P> + * @throws SOAPException if there + * was a problem saving changes to this message. + */ + public abstract void saveChanges() throws SOAPException; + + /** + * Indicates whether this <CODE>SOAPMessage</CODE> object + * has had the method <CODE>saveChanges</CODE> called on + * it. + * @return <CODE>true</CODE> if <CODE>saveChanges</CODE> has + * been called on this message at least once; <CODE> + * false</CODE> otherwise. + */ + public abstract boolean saveRequired(); + + /** + * Writes this <CODE>SOAPMessage</CODE> object to the given + * output stream. The externalization format is as defined by + * the SOAP 1.1 with Attachments specification. + * + * <P>If there are no attachments, just an XML stream is + * written out. For those messages that have attachments, + * <CODE>writeTo</CODE> writes a MIME-encoded byte stream.</P> + * @param out the <CODE>OutputStream</CODE> + * object to which this <CODE>SOAPMessage</CODE> 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 out) + throws SOAPException, IOException; + + /** + * Gets the SOAP Body contained in this <code>SOAPMessage</code> object. + * + * @return the <code>SOAPBody</code> object contained by this + * <code>SOAPMessage</code> object + * @throws SOAPException if the SOAP Body does not exist or cannot be + * retrieved + */ + public SOAPBody getSOAPBody() throws SOAPException { + throw new UnsupportedOperationException("getSOAPBody must be overridden in subclasses of SOAPMessage"); + } + + /** + * Gets the SOAP Header contained in this <code>SOAPMessage</code> object. + * + * @return the <code>SOAPHeader</code> object contained by this + * <code>SOAPMessage</code> object + * @throws SOAPException if the SOAP Header does not exist or cannot be + * retrieved + */ + public SOAPHeader getSOAPHeader() throws SOAPException { + throw new UnsupportedOperationException("getSOAPHeader must be overridden in subclasses of SOAPMessage"); + } + + /** + * Associates the specified value with the specified property. If there was + * already a value associated with this property, the old value is replaced. + * <p> + * The valid property names include <code>WRITE_XML_DECLARATION</code> and + * <code>CHARACTER_SET_ENCODING</code>. 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. + * <p> + * Setting the property <code>WRITE_XML_DECLARATION</code> to + * <code>"true"</code> will cause an XML Declaration to be written out at + * the start of the SOAP message. The default value of "false" suppresses + * this declaration. + * <p> + * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value + * <code>"utf-8"</code> which causes the SOAP message to be encoded using + * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to + * <code>"utf-16"</code> causes the SOAP message to be encoded using UTF-16. + * <p> + * 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 { + throw new UnsupportedOperationException("setProperty must be overridden in subclasses of SOAPMessage"); + } + + /** + * Retrieves value of the specified property. + * + * @param property the name of the property to retrieve + * @return the value of the property or <code>null</code> if no such + * property exists + * @throws SOAPException if the property name is not recognized + */ + public Object getProperty(String property) throws SOAPException { + throw new UnsupportedOperationException("getProperty must be overridden in subclasses of SOAPMessage"); + } + + /** Specifies the character type encoding for the SOAP Message. */ + public static final String CHARACTER_SET_ENCODING + = "javax.xml.soap.character-set-encoding"; + + /** Specifies whether the SOAP Message should contain an XML declaration. */ + public static final String WRITE_XML_DECLARATION + = "javax.xml.soap.write-xml-declaration"; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPPart.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPPart.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPPart.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPPart.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,261 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +import javax.xml.transform.Source; +import java.util.Iterator; + +/** + * <P>The container for the SOAP-specific portion of a <CODE> + * SOAPMessage</CODE> object. All messages are required to have a + * SOAP part, so when a <CODE>SOAPMessage</CODE> object is + * created, it will automatically have a <CODE>SOAPPart</CODE> + * object.</P> + * + * <P>A <CODE>SOAPPart</CODE> object is a MIME part and has the + * MIME headers Content-Id, Content-Location, and Content-Type. + * Because the value of Content-Type must be "text/xml", a <CODE> + * SOAPPart</CODE> object automatically has a MIME header of + * Content-Type with its value set to "text/xml". The value must + * be "text/xml" because content in the SOAP part of a message + * must be in XML format. Content that is not of type "text/xml" + * must be in an <CODE>AttachmentPart</CODE> object rather than in + * the <CODE>SOAPPart</CODE> object.</P> + * + * <P>When a message is sent, its SOAP part must have the MIME + * header Content-Type set to "text/xml". Or, from the other + * perspective, the SOAP part of any message that is received must + * have the MIME header Content-Type with a value of + * "text/xml".</P> + * + * <P>A client can access the <CODE>SOAPPart</CODE> object of a + * <CODE>SOAPMessage</CODE> object by calling the method <CODE> + * SOAPMessage.getSOAPPart</CODE>. The following line of code, in + * which <CODE>message</CODE> is a <CODE>SOAPMessage</CODE> + * object, retrieves the SOAP part of a message.</P> + * <PRE> + * SOAPPart soapPart = message.getSOAPPart(); + * </PRE> + * + * <P>A <CODE>SOAPPart</CODE> object contains a <CODE> + * SOAPEnvelope</CODE> object, which in turn contains a <CODE> + * SOAPBody</CODE> object and a <CODE>SOAPHeader</CODE> object. + * The <CODE>SOAPPart</CODE> method <CODE>getEnvelope</CODE> can + * be used to retrieve the <CODE>SOAPEnvelope</CODE> object.</P> + */ +public abstract class SOAPPart implements org.w3c.dom.Document { + + public SOAPPart() {} + + /** + * Gets the <CODE>SOAPEnvelope</CODE> object associated with + * this <CODE>SOAPPart</CODE> object. Once the SOAP envelope is + * obtained, it can be used to get its contents. + * @return the <CODE>SOAPEnvelope</CODE> object for this <CODE> + * SOAPPart</CODE> object + * @throws SOAPException if there is a SOAP error + */ + public abstract SOAPEnvelope getEnvelope() throws SOAPException; + + /** + * Retrieves the value of the MIME header whose name is + * "Content-Id". + * @return a <CODE>String</CODE> giving the value of the MIME + * header named "Content-Id" + * @see #setContentId(java.lang.String) setContentId(java.lang.String) + */ + public String getContentId() { + + String as[] = getMimeHeader("Content-Id"); + + if (as != null && as.length > 0) { + return as[0]; + } else { + return null; + } + } + + /** + * Retrieves the value of the MIME header whose name is + * "Content-Location". + * @return a <CODE>String</CODE> giving the value of the MIME + * header whose name is "Content-Location" + * @see #setContentLocation(java.lang.String) setContentLocation(java.lang.String) + */ + public String getContentLocation() { + + String as[] = getMimeHeader("Content-Location"); + + if (as != null && as.length > 0) { + return as[0]; + } else { + return null; + } + } + + /** + * Sets the value of the MIME header named "Content-Id" to + * the given <CODE>String</CODE>. + * @param contentId a <CODE>String</CODE> giving + * the value of the MIME header "Content-Id" + * @throws java.lang.IllegalArgumentException if + * there is a problem in setting the content id + * @see #getContentId() getContentId() + */ + public void setContentId(String contentId) { + setMimeHeader("Content-Id", contentId); + } + + /** + * Sets the value of the MIME header "Content-Location" to + * the given <CODE>String</CODE>. + * @param contentLocation a <CODE>String</CODE> + * giving the value of the MIME header + * "Content-Location" + * @throws java.lang.IllegalArgumentException if + * there is a problem in setting the content location. + * @see #getContentLocation() getContentLocation() + */ + public void setContentLocation(String contentLocation) { + setMimeHeader("Content-Location", contentLocation); + } + + /** + * Removes all MIME headers that match the given name. + * @param header a <CODE>String</CODE> giving + * the name of the MIME header(s) to be removed + */ + public abstract void removeMimeHeader(String header); + + /** + * Removes all the <CODE>MimeHeader</CODE> objects for this + * <CODE>SOAPEnvelope</CODE> object. + */ + public abstract void removeAllMimeHeaders(); + + /** + * Gets all the values of the <CODE>MimeHeader</CODE> object + * in this <CODE>SOAPPart</CODE> object that is identified by + * the given <CODE>String</CODE>. + * @param name the name of the header; example: + * "Content-Type" + * @return a <CODE>String</CODE> array giving all the values for + * the specified header + * @see #setMimeHeader(java.lang.String, java.lang.String) setMimeHeader(java.lang.String, java.lang.String) + */ + public abstract String[] getMimeHeader(String name); + + /** + * Changes the first header entry that matches the given + * header name so that its value is the given value, adding a + * new header with the given name and value if no existing + * header is a match. If there is a match, this method clears + * all existing values for the first header that matches and + * sets the given value instead. If more than one header has + * the given name, this method removes all of the matching + * headers after the first one. + * + * <P>Note that RFC822 headers can contain only US-ASCII + * characters.</P> + * @param name a <CODE>String</CODE> giving the + * header name for which to search + * @param value a <CODE>String</CODE> giving the + * value to be set. This value will be substituted for the + * current value(s) of the first header that is a match if + * there is one. If there is no match, this value will be + * the value for a new <CODE>MimeHeader</CODE> object. + * @throws java.lang.IllegalArgumentException if + * there was a problem with the specified mime header name + * or value + * @throws java.lang.IllegalArgumentException if there was a problem with the specified mime header name or value + * @see #getMimeHeader(java.lang.String) getMimeHeader(java.lang.String) + */ + public abstract void setMimeHeader(String name, String value); + + /** + * Creates a <CODE>MimeHeader</CODE> object with the specified + * name and value and adds it to this <CODE>SOAPPart</CODE> + * object. If a <CODE>MimeHeader</CODE> with the specified + * name already exists, this method adds the specified value + * to the already existing value(s). + * + * <P>Note that RFC822 headers can contain only US-ASCII + * characters.</P> + * + * @param name a <CODE>String</CODE> giving the + * header name + * @param value a <CODE>String</CODE> giving the + * value to be set or added + * @throws java.lang.IllegalArgumentException if + * there was a problem with the specified mime header name + * or value + */ + public abstract void addMimeHeader(String name, String value); + + /** + * Retrieves all the headers for this <CODE>SOAPPart</CODE> + * object as an iterator over the <CODE>MimeHeader</CODE> + * objects. + * @return an <CODE>Iterator</CODE> object with all of the Mime + * headers for this <CODE>SOAPPart</CODE> object + */ + public abstract Iterator getAllMimeHeaders(); + + /** + * Retrieves all <CODE>MimeHeader</CODE> objects that match + * a name in the given array. + * @param names a <CODE>String</CODE> array with + * the name(s) of the MIME headers to be returned + * @return all of the MIME headers that match one of the names + * in the given array, returned as an <CODE>Iterator</CODE> + * object + */ + public abstract Iterator getMatchingMimeHeaders(String names[]); + + /** + * Retrieves all <CODE>MimeHeader</CODE> objects whose name + * does not match a name in the given array. + * @param names a <CODE>String</CODE> array with + * the name(s) of the MIME headers not to be returned + * @return all of the MIME headers in this <CODE>SOAPPart</CODE> + * object except those that match one of the names in the + * given array. The nonmatching MIME headers are returned as + * an <CODE>Iterator</CODE> object. + */ + public abstract Iterator getNonMatchingMimeHeaders(String names[]); + + /** + * Sets the content of the <CODE>SOAPEnvelope</CODE> object + * with the data from the given <CODE>Source</CODE> object. + * @param source javax.xml.transform.Source</CODE> object with the data to + * be set + * @throws SOAPException if there is a problem in + * setting the source + * @see #getContent() getContent() + */ + public abstract void setContent(Source source) throws SOAPException; + + /** + * Returns the content of the SOAPEnvelope as a JAXP <CODE> + * Source</CODE> object. + * @return the content as a <CODE> + * javax.xml.transform.Source</CODE> object + * @throws SOAPException if the implementation cannot + * convert the specified <CODE>Source</CODE> object + * @see #setContent(javax.xml.transform.Source) setContent(javax.xml.transform.Source) + */ + public abstract Source getContent() throws SOAPException; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/Text.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/Text.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/Text.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/Text.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,32 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +/** + * A representation of a node whose value is text. A <CODE> + * Text</CODE> object may represent text that is content or text + * that is a comment. + */ +public interface Text extends Node, org.w3c.dom.Text { + + /** + * Retrieves whether this <CODE>Text</CODE> object + * represents a comment. + * @return <CODE>true</CODE> if this <CODE>Text</CODE> object is + * a comment; <CODE>false</CODE> otherwise + */ + public abstract boolean isComment(); +}
