Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/MessageFactory.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/MessageFactory.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/MessageFactory.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/MessageFactory.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,169 @@ +/* + * 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.io.IOException; +import java.io.InputStream; + +/** + * <P>A factory for creating <CODE>SOAPMessage</CODE> objects.</P> + * + * <P>A JAXM client performs the following steps to create a + * message.</P> + * + * <UL> + * <LI> + * Creates a <CODE>MessageFactory</CODE> object from a <CODE> + * ProviderConnection</CODE> object (<CODE>con</CODE> in the + * following line of code). The <CODE>String</CODE> passed to + * the <CODE>createMessageFactory</CODE> method is the name of + * of a messaging profile, which must be the URL for the + * schema. + * <PRE> + * MessageFactory mf = con.createMessageFactory(schemaURL); + * </PRE> + * </LI> + * + * <LI> + * Calls the method <CODE>createMessage</CODE> on the <CODE> + * MessageFactory</CODE> object. All messages produced by this + * <CODE>MessageFactory</CODE> object will have the header + * information appropriate for the messaging profile that was + * specified when the <CODE>MessageFactory</CODE> object was + * created. + * <PRE> + * SOAPMessage m = mf.createMessage(); + * </PRE> + * </LI> + * </UL> + * It is also possible to create a <CODE>MessageFactory</CODE> + * object using the method <CODE>newInstance</CODE>, as shown in + * the following line of code. + * <PRE> + * MessageFactory mf = MessageFactory.newInstance(); + * </PRE> + * A standalone client (a client that is not running in a + * container) can use the <CODE>newInstance</CODE> method to + * create a <CODE>MessageFactory</CODE> object. + * + * <P>All <CODE>MessageFactory</CODE> objects, regardless of how + * they are created, will produce <CODE>SOAPMessage</CODE> objects + * that have the following elements 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> + * If a <CODE>MessageFactory</CODE> object was created using a + * <CODE>ProviderConnection</CODE> object, which means that it was + * initialized with a specified profile, it will produce messages + * that also come prepopulated with additional entries in the + * <CODE>SOAPHeader</CODE> object and the <CODE>SOAPBody</CODE> + * object. The content of a new <CODE>SOAPMessage</CODE> object + * depends on which of the two <CODE>MessageFactory</CODE> methods + * is used to create it. + * + * <UL> + * <LI><CODE>createMessage()</CODE> -- message has no + * content<BR> + * This is the method clients would normally use to create a + * request message.</LI> + * + * <LI><CODE>createMessage(MimeHeaders, + * java.io.InputStream)</CODE> -- message has content from the + * <CODE>InputStream</CODE> object and headers from the <CODE> + * MimeHeaders</CODE> object<BR> + * This method can be used internally by a service + * implementation to create a message that is a response to a + * request.</LI> + * </UL> + */ +public abstract class MessageFactory { + + // fixme: this should be protected as the class is abstract. + /** Create a new MessageFactory. */ + public MessageFactory() {} + + /** + * Creates a new <CODE>MessageFactory</CODE> object that is + * an instance of the default implementation. + * @return a new <CODE>MessageFactory</CODE> object + * @throws SOAPException if there was an error in + * creating the default implementation of the <CODE> + * MessageFactory</CODE> + */ + public static MessageFactory newInstance() throws SOAPException { + + try { + return (MessageFactory) FactoryFinder.find(MESSAGE_FACTORY_PROPERTY, + DEFAULT_MESSAGE_FACTORY); + } catch (Exception exception) { + throw new SOAPException( + "Unable to create message factory for SOAP: " + + exception.getMessage()); + } + } + + /** + * Creates a new <CODE>SOAPMessage</CODE> object with the + * default <CODE>SOAPPart</CODE>, <CODE>SOAPEnvelope</CODE>, + * <CODE>SOAPBody</CODE>, and <CODE>SOAPHeader</CODE> objects. + * Profile-specific message factories can choose to + * prepopulate the <CODE>SOAPMessage</CODE> object with + * profile-specific headers. + * + * <P>Content can be added to this message's <CODE> + * SOAPPart</CODE> object, and the message can be sent "as is" + * when a message containing only a SOAP part is sufficient. + * Otherwise, the <CODE>SOAPMessage</CODE> object needs to + * create one or more <CODE>AttachmentPart</CODE> objects and + * add them to itself. Any content that is not in XML format + * must be in an <CODE>AttachmentPart</CODE> object.</P> + * @return a new <CODE>SOAPMessage</CODE> object + * @throws SOAPException if a SOAP error occurs + */ + public abstract SOAPMessage createMessage() throws SOAPException; + + /** + * Internalizes the contents of the given <CODE> + * InputStream</CODE> object into a new <CODE>SOAPMessage</CODE> + * object and returns the <CODE>SOAPMessage</CODE> object. + * @param mimeheaders the transport-specific headers + * passed to the message in a transport-independent fashion + * for creation of the message + * @param inputstream the <CODE>InputStream</CODE> object + * that contains the data for a message + * @return a new <CODE>SOAPMessage</CODE> object containing the + * data from the given <CODE>InputStream</CODE> object + * @throws IOException if there is a + * problem in reading data from the input stream + * @throws SOAPException if the message is invalid + */ + public abstract SOAPMessage createMessage( + MimeHeaders mimeheaders, InputStream inputstream) + throws IOException, SOAPException; + + private static final String DEFAULT_MESSAGE_FACTORY = + "org.apache.axis.soap.MessageFactoryImpl"; + + private static final String MESSAGE_FACTORY_PROPERTY = + "javax.xml.soap.MessageFactory"; +}
Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeader.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeader.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeader.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeader.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,60 @@ +/* + * 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; + +/** + * An object that stores a MIME header name and its value. One + * or more <CODE>MimeHeader</CODE> objects may be contained in a + * <CODE>MimeHeaders</CODE> object. + * @see MimeHeaders MimeHeaders + */ +public class MimeHeader { + + /** + * Constructs a <CODE>MimeHeader</CODE> object initialized + * with the given name and value. + * @param name a <CODE>String</CODE> giving the + * name of the header + * @param value a <CODE>String</CODE> giving the + * value of the header + */ + public MimeHeader(String name, String value) { + this.name = name; + this.value = value; + } + + /** + * Returns the name of this <CODE>MimeHeader</CODE> + * object. + * @return the name of the header as a <CODE>String</CODE> + */ + public String getName() { + return name; + } + + /** + * Returns the value of this <CODE>MimeHeader</CODE> + * object. + * @return the value of the header as a <CODE>String</CODE> + */ + public String getValue() { + return value; + } + + private String name; + + private String value; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeaders.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeaders.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeaders.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/MimeHeaders.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,310 @@ +/* + * 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; +import java.util.Vector; + +/** + * A container for <CODE>MimeHeader</CODE> objects, which + * represent the MIME headers present in a MIME part of a + * message.</P> + * + * <P>This class is used primarily when an application wants to + * retrieve specific attachments based on certain MIME headers and + * values. This class will most likely be used by implementations + * of <CODE>AttachmentPart</CODE> and other MIME dependent parts + * of the JAXM API. + * @see SOAPMessage#getAttachments() SOAPMessage.getAttachments() + * @see AttachmentPart AttachmentPart + */ +public class MimeHeaders { + + class MatchingIterator implements Iterator { + + private Object nextMatch() { + + label0: + while (iterator.hasNext()) { + MimeHeader mimeheader = (MimeHeader) iterator.next(); + + if (names == null) { + return match + ? null + : mimeheader; + } + + for (int i = 0; i < names.length; i++) { + if (!mimeheader.getName().equalsIgnoreCase(names[i])) { + continue; + } + + if (match) { + return mimeheader; + } + + continue label0; + } + + if (!match) { + return mimeheader; + } + } + + return null; + } + + public boolean hasNext() { + + if (nextHeader == null) { + nextHeader = nextMatch(); + } + + return nextHeader != null; + } + + public Object next() { + + if (nextHeader != null) { + Object obj = nextHeader; + + nextHeader = null; + + return obj; + } + + if (hasNext()) { + return nextHeader; + } else { + return null; + } + } + + public void remove() { + iterator.remove(); + } + + private boolean match; + + private Iterator iterator; + + private String names[]; + + private Object nextHeader; + + MatchingIterator(String as[], boolean flag) { + + match = flag; + names = as; + iterator = headers.iterator(); + } + } + + /** + * Constructs + * a default <CODE>MimeHeaders</CODE> object initialized with + * an empty <CODE>Vector</CODE> object. + */ + public MimeHeaders() { + headers = new Vector(); + } + + /** + * Returns all of the values for the specified header as an + * array of <CODE>String</CODE> objects. + * @param name the name of the header for which + * values will be returned + * @return a <CODE>String</CODE> array with all of the values + * for the specified header + * @see #setHeader(java.lang.String, java.lang.String) setHeader(java.lang.String, java.lang.String) + */ + public String[] getHeader(String name) { + + Vector vector = new Vector(); + + for (int i = 0; i < headers.size(); i++) { + MimeHeader mimeheader = (MimeHeader) headers.elementAt(i); + + if (mimeheader.getName().equalsIgnoreCase(name) + && (mimeheader.getValue() != null)) { + vector.addElement(mimeheader.getValue()); + } + } + + if (vector.size() == 0) { + return null; + } else { + String as[] = new String[vector.size()]; + + vector.copyInto(as); + + return as; + } + } + + /** + * Replaces the current value of the first header entry whose + * name matches the given name with the given value, adding a + * new header if no existing header name matches. This method + * also removes all matching headers after the first one. + * + * <P>Note that RFC822 headers can contain only US-ASCII + * characters.</P> + * @param name a <CODE>String</CODE> with the + * name of the header for which to search + * @param value a <CODE>String</CODE> with the + * value that will replace the current value of the + * specified header + * @throws java.lang.IllegalArgumentException if there was a + * problem in the mime header name or the value being set + * @see #getHeader(java.lang.String) getHeader(java.lang.String) + */ + public void setHeader(String name, String value) { + + boolean flag = false; + + if ((name == null) || name.equals("")) { + throw new IllegalArgumentException( + "Illegal MimeHeader name"); + } + + for (int i = 0; i < headers.size(); i++) { + MimeHeader mimeheader = (MimeHeader) headers.elementAt(i); + + if (mimeheader.getName().equalsIgnoreCase(name)) { + if (!flag) { + headers.setElementAt(new MimeHeader(mimeheader + .getName(), value), i); + + flag = true; + } else { + headers.removeElementAt(i--); + } + } + } + + if (!flag) { + addHeader(name, value); + } + } + + /** + * Adds a <CODE>MimeHeader</CODE> object with the specified + * name and value to this <CODE>MimeHeaders</CODE> object's + * list of headers. + * + * <P>Note that RFC822 headers can contain only US-ASCII + * characters.</P> + * @param name a <CODE>String</CODE> with the + * name of the header to be added + * @param value a <CODE>String</CODE> with the + * value of the header to be added + * @throws java.lang.IllegalArgumentException if + * there was a problem in the mime header name or value + * being added + */ + public void addHeader(String name, String value) { + + if ((name == null) || name.equals("")) { + throw new IllegalArgumentException( + "Illegal MimeHeader name"); + } + + int i = headers.size(); + + for (int j = i - 1; j >= 0; j--) { + MimeHeader mimeheader = (MimeHeader) headers.elementAt(j); + + if (mimeheader.getName().equalsIgnoreCase(name)) { + headers.insertElementAt(new MimeHeader(name, value), j + 1); + + return; + } + } + + headers.addElement(new MimeHeader(name, value)); + } + + /** + * Remove all <CODE>MimeHeader</CODE> objects whose name + * matches the the given name. + * @param name a <CODE>String</CODE> with the + * name of the header for which to search + */ + public void removeHeader(String name) { + + for (int i = 0; i < headers.size(); i++) { + MimeHeader mimeheader = (MimeHeader) headers.elementAt(i); + + if (mimeheader.getName().equalsIgnoreCase(name)) { + headers.removeElementAt(i--); + } + } + } + + /** + * Removes all the header entries from this <CODE> + * MimeHeaders</CODE> object. + */ + public void removeAllHeaders() { + headers.removeAllElements(); + } + + /** + * Returns all the headers in this <CODE>MimeHeaders</CODE> + * object. + * @return an <CODE>Iterator</CODE> object over this <CODE> + * MimeHeaders</CODE> object's list of <CODE> + * MimeHeader</CODE> objects + */ + public Iterator getAllHeaders() { + return headers.iterator(); + } + + /** + * Returns all the <CODE>MimeHeader</CODE> objects whose + * name matches a name in the given array of names. + * @param names an array of <CODE>String</CODE> + * objects with the names for which to search + * @return an <CODE>Iterator</CODE> object over the <CODE> + * MimeHeader</CODE> objects whose name matches one of the + * names in the given list + */ + public Iterator getMatchingHeaders(String names[]) { + return new MatchingIterator(names, true); + } + + /** + * Returns all of the <CODE>MimeHeader</CODE> objects whose + * name does not match a name in the given array of names. + * @param names an array of <CODE>String</CODE> + * objects with the names for which to search + * @return an <CODE>Iterator</CODE> object over the <CODE> + * MimeHeader</CODE> objects whose name does not match one + * of the names in the given list + */ + public Iterator getNonMatchingHeaders(String names[]) { + return new MatchingIterator(names, false); + } + + // fixme: does this need to be a Vector? Will a non-synchronized impl of + // List do? + /** + * A <code>Vector</code> containing the headers as <code>MimeHeader</code> + * instances. + */ + private Vector headers; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/Name.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/Name.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/Name.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/Name.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,91 @@ +/* + * 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 an XML name. This interface provides methods for + * getting the local and namespace-qualified names and also for getting the + * prefix associated with the namespace for the name. It is also possible + * to get the URI of the namespace. + * <P> + * The following is an example of a namespace declaration in an element. + * <PRE> + * <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader"> + * </PRE> + * ("xmlns" stands for "XML namespace".) + * The following + * shows what the methods in the <code>Name</code> interface will return. + * <UL> + * <LI><code>getQualifiedName</code> will return "prefix:LocalName" = + * "WOMBAT:GetLastTradePrice" + * <LI><code>getURI</code> will return "http://www.wombat.org/trader"; + * <LI><code>getLocalName</code> will return "GetLastTracePrice" + * <LI><code>getPrefix</code> will return "WOMBAT" + * </UL> + * <P> + * XML namespaces are used to disambiguate SOAP identifiers from + * application-specific identifiers. + * <P> + * <code>Name</code> objects are created using the method + * <code>SOAPEnvelope.createName</code>, which has two versions. + * One method creates <code>Name</code> objects with + * a local name, a namespace prefix, and a namespace URI. + * and the second creates <code>Name</code> objects with just a local name. + * The following line of + * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new + * <code>Name</code> object with all three. + * <PRE> + * Name name = se.createName("GetLastTradePrice", "WOMBAT", + * "http://www.wombat.org/trader";); + * </PRE> + * The following line of code gives an example of how a <code>Name</code> object + * can be used. The variable <i>element</i> is a <code>SOAPElement</code> object. + * This code creates a new <code>SOAPElement</code> object with the given name and + * adds it to <i>element</i>. + * <PRE> + * element.addChildElement(name); + * </PRE> + */ +public interface Name { + + /** + * Gets the local name part of the XML name that this <code>Name</code> + * object represents. + * @return a string giving the local name + */ + public abstract String getLocalName(); + + /** + * Gets the namespace-qualified name of the XML name that this + * <code>Name</code> object represents. + * @return the namespace-qualified name as a string + */ + public abstract String getQualifiedName(); + + /** + * Returns the prefix associated with the namespace for the XML + * name that this <code>Name</code> object represents. + * @return the prefix as a string + */ + public abstract String getPrefix(); + + /** + * Returns the URI of the namespace for the XML + * name that this <code>Name</code> object represents. + * @return the URI as a string + */ + public abstract String getURI(); +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/Node.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/Node.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/Node.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/Node.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,92 @@ +/* + * 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 (element) in a DOM representation of an XML document + * that provides some tree manipulation methods. + * This interface provides methods for getting the value of a node, for + * getting and setting the parent of a node, and for removing a node. + */ +public interface Node extends org.w3c.dom.Node { + + /** + * Returns the the value of the immediate child of this <code>Node</code> + * object if a child exists and its value is text. + * @return a <code>String</code> with the text of the immediate child of + * this <code>Node</code> object if (1) there is a child and + * (2) the child is a <code>Text</code> object; + * <code>null</code> otherwise + */ + public abstract String getValue(); + + /** + * Sets the parent of this <code>Node</code> object to the given + * <code>SOAPElement</code> object. + * @param parent the <code>SOAPElement</code> object to be set as + * the parent of this <code>Node</code> object + * @throws SOAPException if there is a problem in setting the + * parent to the given element + * @see #getParentElement() getParentElement() + */ + public abstract void setParentElement(SOAPElement parent) + throws SOAPException; + + /** + * Returns the parent element of this <code>Node</code> object. + * This method can throw an <code>UnsupportedOperationException</code> + * if the tree is not kept in memory. + * @return the <code>SOAPElement</code> object that is the parent of + * this <code>Node</code> object or <code>null</code> if this + * <code>Node</code> object is root + * @throws java.lang.UnsupportedOperationException if the whole tree is not kept in memory + * @see #setParentElement(javax.xml.soap.SOAPElement) setParentElement(javax.xml.soap.SOAPElement) + */ + public abstract SOAPElement getParentElement(); + + /** + * Removes this <code>Node</code> object from the tree. Once + * removed, this node can be garbage collected if there are no + * application references to it. + */ + public abstract void detachNode(); + + /** + * Notifies the implementation that this <code>Node</code> + * object is no longer being used by the application and that the + * implementation is free to reuse this object for nodes that may + * be created later. + * <P> + * Calling the method <code>recycleNode</code> implies that the method + * <code>detachNode</code> has been called previously. + */ + public abstract void recycleNode(); + + /** + * If this is a Text node then this method will set its value, otherwise it + * sets the value of the immediate (Text) child of this node. The value of + * the immediate child of this node can be set only if, there is one child + * node and that node is a Text node, or if there are no children in which + * case a child Text node will be created. + * + * @param value the text to set + * @throws IllegalStateException if the node is not a Text node and + * either has more than one child node or has a child node that + * is not a Text node + */ + + public abstract void setValue(String value); +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBody.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBody.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBody.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBody.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,125 @@ +/* + * 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 org.w3c.dom.Document; + +import java.util.Locale; + +/** + * An object that represents the contents of the SOAP body + * element in a SOAP message. A SOAP body element consists of XML data + * that affects the way the application-specific content is processed. + * <P> + * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code> + * objects, which have the content for the SOAP body. + * A <code>SOAPFault</code> object, which carries status and/or + * error information, is an example of a <code>SOAPBodyElement</code> object. + * @see SOAPFault SOAPFault + */ +public interface SOAPBody extends SOAPElement { + + /** + * Creates a new <code>SOAPFault</code> object and adds it to + * this <code>SOAPBody</code> object. + * @return the new <code>SOAPFault</code> object + * @throws SOAPException if there is a SOAP error + */ + public abstract SOAPFault addFault() throws SOAPException; + + /** + * Indicates whether a <code>SOAPFault</code> object exists in + * this <code>SOAPBody</code> object. + * @return <code>true</code> if a <code>SOAPFault</code> object exists in + * this <code>SOAPBody</code> object; <code>false</code> + * otherwise + */ + public abstract boolean hasFault(); + + /** + * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code> + * object. + * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code> + * object + */ + public abstract SOAPFault getFault(); + + /** + * Creates a new <code>SOAPBodyElement</code> object with the + * specified name and adds it to this <code>SOAPBody</code> object. + * @param name a <code>Name</code> object with the name for the new + * <code>SOAPBodyElement</code> object + * @return the new <code>SOAPBodyElement</code> object + * @throws SOAPException if a SOAP error occurs + */ + public abstract SOAPBodyElement addBodyElement(Name name) + throws SOAPException; + + /** + * Creates a new <code>SOAPFault</code> object and adds it to this + * <code>SOAPBody</code> object. The new <code>SOAPFault</code> will have a + * <code>faultcode</code> element that is set to the <code>faultCode</code> + * parameter and a <code>faultstring</code> set to <code>faultstring</code> + * and localized to <code>locale</code>. + * + * @param faultCode a <code>Name</code> object giving the fault code to be + * set; must be one of the fault codes defined in the SOAP 1.1 + * specification and of type QName + * @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 <ocde>faultString</code> + * @return the new <code>SOAPFault</code> object + * @throws SOAPException if there is a SOAP error + */ + public abstract SOAPFault addFault(Name faultCode, + String faultString, + Locale locale) throws SOAPException; + + /** + * Creates a new <code>SOAPFault</code> object and adds it to this + * <code>SOAPBody</code> object. The new <code>SOAPFault</code> will have a + * <code>faultcode</code> element that is set to the <code>faultCode</code> + * parameter and a <code>faultstring</code> set to <code>faultstring</code>. + * + * @param faultCode a <code>Name</code> object giving the fault code to be + * set; must be one of the fault codes defined in the SOAP 1.1 + * specification and of type QName + * @param faultString a <code>String</code> giving an explanation of the + * fault + * @return the new <code>SOAPFault</code> object + * @throws SOAPException if there is a SOAP error + */ + public abstract SOAPFault addFault(Name faultCode, String faultString) throws SOAPException; + + /** + * Adds the root node of the DOM <code>Document</code> to this + * <code>SOAPBody</code> object. + * <p> + * Calling this method invalidates the <code>document</code> parameter. The + * client application should discard all references to this + * <code>Document</code> and its contents upon calling + * <code>addDocument</code>. The behavior of an application that continues + * to use such references is undefined. + * + * @param document the <code>Document</code> object whose root node will be + * added to this <code>SOAPBody</code> + * @return the <code>SOAPBodyElement</code> that represents the root node + * that was added + * @throws SOAPException if the <code>Document</code> cannot be added + */ + public abstract SOAPBodyElement addDocument(Document document) throws SOAPException; + } Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBodyElement.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBodyElement.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBodyElement.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPBodyElement.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 <code>SOAPBodyElement</code> object represents the contents in + * a <code>SOAPBody</code> object. The <code>SOAPFault</code> interface + * is a <code>SOAPBodyElement</code> object that has been defined. + * <P> + * A new <code>SOAPBodyElement</code> object can be created and added + * to a <code>SOAPBody</code> object with the <code>SOAPBody</code> + * method <code>addBodyElement</code>. In the following line of code, + * <code>sb</code> is a <code>SOAPBody</code> object, and + * <code>myName</code> is a <code>Name</code> object. + * <PRE> + * SOAPBodyElement sbe = sb.addBodyElement(myName); + * </PRE> + */ +public interface SOAPBodyElement extends SOAPElement {} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnection.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnection.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnection.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnection.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,60 @@ +/* + * 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 point-to-point connection that a client can use for sending messages + * directly to a remote party (represented by a URL, for instance). + * <p> + * A client can obtain a <code>SOAPConnection</code> object simply by + * calling the following static method. + * <pre> + * + * SOAPConnection con = SOAPConnection.newInstance(); + * </pre> + * A <code>SOAPConnection</code> object can be used to send messages + * directly to a URL following the request/response paradigm. That is, + * messages are sent using the method <code>call</code>, which sends the + * message and then waits until it gets a reply. + */ +public abstract class SOAPConnection { + + public SOAPConnection() {} + + /** + * Sends the given message to the specified endpoint and + * blocks until it has returned the response. + * @param request the <CODE>SOAPMessage</CODE> + * object to be sent + * @param endpoint an <code>Object</code> that identifies + * where the message should be sent. It is required to + * support Objects of type + * <code>java.lang.String</code>, + * <code>java.net.URL</code>, and when JAXM is present + * <code>javax.xml.messaging.URLEndpoint</code> + * @return the <CODE>SOAPMessage</CODE> object that is the + * response to the message that was sent + * @throws SOAPException if there is a SOAP error + */ + public abstract SOAPMessage call(SOAPMessage request, Object endpoint) + throws SOAPException; + + /** + * Closes this <CODE>SOAPConnection</CODE> object. + * @throws SOAPException if there is a SOAP error + */ + public abstract void close() throws SOAPException; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnectionFactory.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnectionFactory.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnectionFactory.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConnectionFactory.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,65 @@ +/* + * 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 factory for creating <code>SOAPConnection</code> objects. Implementation of + * this class is optional. If <code>SOAPConnectionFactory.newInstance()</code> + * throws an <code>UnsupportedOperationException</code> then the implementation + * does not support the SAAJ communication infrastructure. Otherwise + * <code>SOAPConnection</code> objects can be created by calling + * <code>createConnection()</code> on the newly created + * <code>SOAPConnectionFactory</code> object. + */ +public abstract class SOAPConnectionFactory { + + public SOAPConnectionFactory() {} + + /** + * Creates an instance of the default <CODE> + * SOAPConnectionFactory</CODE> object. + * @return a new instance of a default <CODE> + * SOAPConnectionFactory</CODE> object + * @throws SOAPException if there was an error creating + * the <CODE>SOAPConnectionFactory + * @throws UnsupportedOperationException if newInstance is not supported. + */ + public static SOAPConnectionFactory newInstance() + throws SOAPException, UnsupportedOperationException { + + try { + return (SOAPConnectionFactory) FactoryFinder.find(SF_PROPERTY, + DEFAULT_SOAP_CONNECTION_FACTORY); + } catch (Exception exception) { + throw new SOAPException("Unable to create SOAP connection factory: " + + exception.getMessage()); + } + } + + /** + * Create a new <CODE>SOAPConnection</CODE>. + * @return the new <CODE>SOAPConnection</CODE> object. + * @throws SOAPException if there was an exception + * creating the <CODE>SOAPConnection</CODE> object. + */ + public abstract SOAPConnection createConnection() throws SOAPException; + + private static final String DEFAULT_SOAP_CONNECTION_FACTORY = + "org.apache.axis.soap.SOAPConnectionFactoryImpl"; + + private static final String SF_PROPERTY = + "javax.xml.soap.SOAPConnectionFactory"; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConstants.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConstants.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConstants.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPConstants.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,38 @@ +/* + * 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; + +/** The definition of constants pertaining to the SOAP 1.1 protocol. */ +public interface SOAPConstants { + + /** The namespace identifier for the SOAP envelope. */ + public static final String URI_NS_SOAP_ENVELOPE = + "http://schemas.xmlsoap.org/soap/envelope/";; + + /** + * The namespace identifier for the SOAP encoding (see section 5 of + * the SOAP 1.1 specification). + */ + public static final String URI_NS_SOAP_ENCODING = + "http://schemas.xmlsoap.org/soap/encoding/";; + + /** + * The URI identifying the first application processing a SOAP request as the intended + * actor for a SOAP header entry (see section 4.2.2 of the SOAP 1.1 specification). + */ + public static final String URI_SOAP_ACTOR_NEXT = + "http://schemas.xmlsoap.org/soap/actor/next";; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElement.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElement.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElement.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElement.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,288 @@ +/* + * 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; + +/** + * An object representing the contents in a + * <code>SOAPBody</code> object, the contents in a <code>SOAPHeader</code> + * object, the content that can follow the <code>SOAPBody</code> object in a + * <code>SOAPEnvelope</code> object, or what can follow the detail element + * in a <code>SOAPFault</code> object. It is + * the base class for all of the classes that represent the SOAP objects as + * defined in the SOAP specification. + */ +public interface SOAPElement extends Node, org.w3c.dom.Element { + + /** + * Creates a new <code>SOAPElement</code> object initialized with the + * given <code>Name</code> object and adds the new element to this + * <code>SOAPElement</code> object. + * @param name a <code>Name</code> object with the XML name for the + * new element + * @return the new <code>SOAPElement</code> object that was created + * @throws SOAPException if there is an error in creating the + * <code>SOAPElement</code> object + */ + public abstract SOAPElement addChildElement(Name name) throws SOAPException; + + /** + * Creates a new <code>SOAPElement</code> object initialized with the + * given <code>String</code> object and adds the new element to this + * <code>SOAPElement</code> object. + * @param localName a <code>String</code> giving the local name for + * the element + * @return the new <code>SOAPElement</code> object that was created + * @throws SOAPException if there is an error in creating the + * <code>SOAPElement</code> object + */ + public abstract SOAPElement addChildElement(String localName) + throws SOAPException; + + /** + * Creates a new <code>SOAPElement</code> object initialized with the + * specified local name and prefix and adds the new element to this + * <code>SOAPElement</code> object. + * @param localName a <code>String</code> giving the local name for + * the new element + * @param prefix a <code>String</code> giving the namespace prefix for + * the new element + * @return the new <code>SOAPElement</code> object that was created + * @throws SOAPException if there is an error in creating the + * <code>SOAPElement</code> object + */ + public abstract SOAPElement addChildElement(String localName, String prefix) + throws SOAPException; + + /** + * Creates a new <code>SOAPElement</code> object initialized with the + * specified local name, prefix, and URI and adds the new element to this + * <code>SOAPElement</code> object. + * @param localName a <code>String</code> giving the local name for + * the new element + * @param prefix a <code>String</code> giving the namespace prefix for + * the new element + * @param uri a <code>String</code> giving the URI of the namespace + * to which the new element belongs + * @return the new <code>SOAPElement</code> object that was created + * @throws SOAPException if there is an error in creating the + * <code>SOAPElement</code> object + */ + public abstract SOAPElement addChildElement( + String localName, String prefix, String uri) throws SOAPException; + + /** + * Add a <code>SOAPElement</code> as a child of this + * <code>SOAPElement</code> instance. The <code>SOAPElement</code> + * is expected to be created by a + * <code>SOAPElementFactory</code>. Callers should not rely on the + * element instance being added as is into the XML + * tree. Implementations could end up copying the content + * of the <code>SOAPElement</code> passed into an instance of + * a different <code>SOAPElement</code> implementation. For + * instance if <code>addChildElement()</code> is called on a + * <code>SOAPHeader</code>, <code>element</code> will be copied + * into an instance of a <code>SOAPHeaderElement</code>. + * + * <P>The fragment rooted in <code>element</code> is either added + * as a whole or not at all, if there was an error. + * + * <P>The fragment rooted in <code>element</code> cannot contain + * elements named "Envelope", "Header" or "Body" and in the SOAP + * namespace. Any namespace prefixes present in the fragment + * should be fully resolved using appropriate namespace + * declarations within the fragment itself. + * @param element the <code>SOAPElement</code> to be added as a + * new child + * @return an instance representing the new SOAP element that was + * actually added to the tree. + * @throws SOAPException if there was an error in adding this + * element as a child + */ + public abstract SOAPElement addChildElement(SOAPElement element) + throws SOAPException; + + /** + * Creates a new <code>Text</code> object initialized with the given + * <code>String</code> and adds it to this <code>SOAPElement</code> object. + * @param text a <code>String</code> object with the textual content to be added + * @return the <code>SOAPElement</code> object into which + * the new <code>Text</code> object was inserted + * @throws SOAPException if there is an error in creating the + * new <code>Text</code> object + */ + public abstract SOAPElement addTextNode(String text) throws SOAPException; + + /** + * Adds an attribute with the specified name and value to this + * <code>SOAPElement</code> object. + * <p> + * @param name a <code>Name</code> object with the name of the attribute + * @param value a <code>String</code> giving the value of the attribute + * @return the <code>SOAPElement</code> object into which the attribute was + * inserted + * @throws SOAPException if there is an error in creating the + * Attribute + */ + public abstract SOAPElement addAttribute(Name name, String value) + throws SOAPException; + + /** + * Adds a namespace declaration with the specified prefix and URI to this + * <code>SOAPElement</code> object. + * <p> + * @param prefix a <code>String</code> giving the prefix of the namespace + * @param uri a <CODE>String</CODE> giving + * the prefix of the namespace + * @return the <code>SOAPElement</code> object into which this + * namespace declaration was inserted. + * @throws SOAPException if there is an error in creating the + * namespace + */ + public abstract SOAPElement addNamespaceDeclaration( + String prefix, String uri) throws SOAPException; + + /** + * Returns the value of the attribute with the specified + * name. + * @param name a <CODE>Name</CODE> object with + * the name of the attribute + * @return a <CODE>String</CODE> giving the value of the + * specified attribute + */ + public abstract String getAttributeValue(Name name); + + /** + * Returns an iterator over all of the attribute names in + * this <CODE>SOAPElement</CODE> object. The iterator can be + * used to get the attribute names, which can then be passed to + * the method <CODE>getAttributeValue</CODE> to retrieve the + * value of each attribute. + * @return an iterator over the names of the attributes + */ + public abstract Iterator getAllAttributes(); + + /** + * Returns the URI of the namespace that has the given + * prefix. + * + * @param prefix a <CODE>String</CODE> giving + * the prefix of the namespace for which to search + * @return a <CODE>String</CODE> with the uri of the namespace + * that has the given prefix + */ + public abstract String getNamespaceURI(String prefix); + + /** + * Returns an iterator of namespace prefixes. The iterator + * can be used to get the namespace prefixes, which can then be + * passed to the method <CODE>getNamespaceURI</CODE> to retrieve + * the URI of each namespace. + * @return an iterator over the namespace prefixes in this + * <CODE>SOAPElement</CODE> object + */ + public abstract Iterator getNamespacePrefixes(); + + /** + * Returns the name of this <CODE>SOAPElement</CODE> + * object. + * @return a <CODE>Name</CODE> object with the name of this + * <CODE>SOAPElement</CODE> object + */ + public abstract Name getElementName(); + + /** + * Removes the attribute with the specified name. + * @param name the <CODE>Name</CODE> object with + * the name of the attribute to be removed + * @return <CODE>true</CODE> if the attribute was removed + * successfully; <CODE>false</CODE> if it was not + */ + public abstract boolean removeAttribute(Name name); + + /** + * Removes the namespace declaration corresponding to the + * given prefix. + * @param prefix a <CODE>String</CODE> giving + * the prefix for which to search + * @return <CODE>true</CODE> if the namespace declaration was + * removed successfully; <CODE>false</CODE> if it was + * not + */ + public abstract boolean removeNamespaceDeclaration(String prefix); + + /** + * Returns an iterator over all the immediate content of + * this element. This includes <CODE>Text</CODE> objects as well + * as <CODE>SOAPElement</CODE> objects. + * @return an iterator with the content of this <CODE> + * SOAPElement</CODE> object + */ + public abstract Iterator getChildElements(); + + /** + * Returns an iterator over all the child elements with the + * specified name. + * @param name a <CODE>Name</CODE> object with + * the name of the child elements to be returned + * @return an <CODE>Iterator</CODE> object over all the elements + * in this <CODE>SOAPElement</CODE> object with the + * specified name + */ + public abstract Iterator getChildElements(Name name); + + /** + * Sets the encoding style for this <CODE>SOAPElement</CODE> + * object to one specified. + * @param encodingStyle a <CODE>String</CODE> + * giving the encoding style + * @throws java.lang.IllegalArgumentException if + * there was a problem in the encoding style being set. + * @see #getEncodingStyle() getEncodingStyle() + */ + public abstract void setEncodingStyle(String encodingStyle) + throws SOAPException; + + /** + * Returns the encoding style for this <CODE> + * SOAPElement</CODE> object. + * @return a <CODE>String</CODE> giving the encoding style + * @see #setEncodingStyle(java.lang.String) setEncodingStyle(java.lang.String) + */ + public abstract String getEncodingStyle(); + + /** + * Detaches all children of this <code>SOAPElement</code>. + * <p> + * This method is useful for rolling back the construction of partially + * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in + * reparation for sending a fault when an error condition is detected. It is + * also useful for recycling portions of a document within a SOAP message. + */ + public abstract void removeContents(); + + /** + * Returns an <code>Iterator</code> over the namespace prefix + * <code>String</code>s visible to this element. The prefixes returned by + * this iterator can be passed to the method <code>getNamespaceURI()</code> + * to retrieve the URI of each namespace. + * + * @return an iterator over the namespace prefixes are within scope of this + * <code>SOAPElement</code> object + */ + public abstract Iterator getVisibleNamespacePrefixes(); +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElementFactory.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElementFactory.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElementFactory.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPElementFactory.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,116 @@ +/* + * 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><CODE>SOAPElementFactory</CODE> is a factory for XML + * fragments that will eventually end up in the SOAP part. These + * fragments can be inserted as children of the <CODE> + * SOAPHeader</CODE> or <CODE>SOAPBody</CODE> or <CODE> + * SOAPEnvelope</CODE>.</P> + * + * <P>Elements created using this factory do not have the + * properties of an element that lives inside a SOAP header + * document. These elements are copied into the XML document tree + * when they are inserted.</P> + * @deprecated - Use javax.xml.soap.SOAPFactory for creating SOAPElements. + * @see SOAPFactory SOAPFactory + */ +public class SOAPElementFactory { + + /** + * Create a new <code>SOAPElementFactory from a <code>SOAPFactory</code>. + * + * @param soapfactory the <code>SOAPFactory</code> to use + */ + private SOAPElementFactory(SOAPFactory soapfactory) { + sf = soapfactory; + } + + /** + * Create a <CODE>SOAPElement</CODE> object initialized with + * the given <CODE>Name</CODE> object. + * @param name a <CODE>Name</CODE> object with + * the XML name for the new element + * @return the new <CODE>SOAPElement</CODE> object that was + * created + * @throws SOAPException if there is an error in + * creating the <CODE>SOAPElement</CODE> object + * @deprecated Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead + * @see SOAPFactory#createElement(javax.xml.soap.Name) SOAPFactory.createElement(javax.xml.soap.Name) + */ + public SOAPElement create(Name name) throws SOAPException { + return sf.createElement(name); + } + + /** + * Create a <CODE>SOAPElement</CODE> object initialized with + * the given local name. + * @param localName a <CODE>String</CODE> giving + * the local name for the new element + * @return the new <CODE>SOAPElement</CODE> object that was + * created + * @throws SOAPException if there is an error in + * creating the <CODE>SOAPElement</CODE> object + * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String localName) instead + * @see SOAPFactory#createElement(java.lang.String) SOAPFactory.createElement(java.lang.String) + */ + public SOAPElement create(String localName) throws SOAPException { + return sf.createElement(localName); + } + + /** + * Create a new <CODE>SOAPElement</CODE> object with the + * given local name, prefix and uri. + * @param localName a <CODE>String</CODE> giving + * the local name for the new element + * @param prefix the prefix for this <CODE> + * SOAPElement</CODE> + * @param uri a <CODE>String</CODE> giving the + * URI of the namespace to which the new element + * belongs + * @return the new <CODE>SOAPElement</CODE> object that was + * created + * @throws SOAPException if there is an error in + * creating the <CODE>SOAPElement</CODE> object + * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String localName, String prefix, String uri) instead + * @see SOAPFactory#createElement(java.lang.String, java.lang.String, java.lang.String) SOAPFactory.createElement(java.lang.String, java.lang.String, java.lang.String) + */ + public SOAPElement create(String localName, String prefix, String uri) + throws SOAPException { + return sf.createElement(localName, prefix, uri); + } + + /** + * Creates a new instance of <CODE>SOAPElementFactory</CODE>. + * + * @return a new instance of a <CODE> + * SOAPElementFactory</CODE> + * @throws SOAPException if there was an error creating + * the default <CODE>SOAPElementFactory + */ + public static SOAPElementFactory newInstance() throws SOAPException { + + try { + return new SOAPElementFactory(SOAPFactory.newInstance()); + } catch (Exception exception) { + throw new SOAPException("Unable to create SOAP Element Factory: " + + exception.getMessage()); + } + } + + private SOAPFactory sf; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPEnvelope.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPEnvelope.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPEnvelope.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPEnvelope.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,191 @@ +/* + * 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; + +/** + * The container for the SOAPHeader and SOAPBody portions of a + * <CODE>SOAPPart</CODE> object. By default, a <CODE> + * SOAPMessage</CODE> object is created with a <CODE> + * SOAPPart</CODE> object that has a <CODE>SOAPEnvelope</CODE> + * object. The <CODE>SOAPEnvelope</CODE> object by default has an + * empty <CODE>SOAPBody</CODE> object and an empty <CODE> + * SOAPHeader</CODE> object. The <CODE>SOAPBody</CODE> object is + * required, and the <CODE>SOAPHeader</CODE> object, though + * optional, is used in the majority of cases. If the <CODE> + * SOAPHeader</CODE> object is not needed, it can be deleted, + * which is shown later.</P> + * + * <P>A client can access the <CODE>SOAPHeader</CODE> and <CODE> + * SOAPBody</CODE> objects by calling the methods <CODE> + * SOAPEnvelope.getHeader</CODE> and <CODE> + * SOAPEnvelope.getBody</CODE>. The following lines of code use + * these two methods after starting with the <CODE> + * SOAPMessage</CODE> object <I>message</I> to get the <CODE> + * SOAPPart</CODE> object <I>sp</I>, which is then used to get the + * <CODE>SOAPEnvelope</CODE> object <I>se</I>.</P> + * <PRE> + * SOAPPart sp = message.getSOAPPart(); + * SOAPEnvelope se = sp.getEnvelope(); + * SOAPHeader sh = se.getHeader(); + * SOAPBody sb = se.getBody(); + * </PRE> + * + * <P>It is possible to change the body or header of a <CODE> + * SOAPEnvelope</CODE> object by retrieving the current one, + * deleting it, and then adding a new body or header. The <CODE> + * javax.xml.soap.Node</CODE> method <CODE>detachNode</CODE> + * detaches the XML element (node) on which it is called. For + * example, the following line of code deletes the <CODE> + * SOAPBody</CODE> object that is retrieved by the method <CODE> + * getBody</CODE>.</P> + * <PRE> + * se.getBody().detachNode(); + * </PRE> + * To create a <CODE>SOAPHeader</CODE> object to replace the one + * that was removed, a client uses the method <CODE> + * SOAPEnvelope.addHeader</CODE>, which creates a new header and + * adds it to the <CODE>SOAPEnvelope</CODE> object. Similarly, the + * method <CODE>addBody</CODE> creates a new <CODE>SOAPBody</CODE> + * object and adds it to the <CODE>SOAPEnvelope</CODE> object. The + * following code fragment retrieves the current header, removes + * it, and adds a new one. Then it retrieves the current body, + * removes it, and adds a new one. + * <PRE> + * SOAPPart sp = message.getSOAPPart(); + * SOAPEnvelope se = sp.getEnvelope(); + * se.getHeader().detachNode(); + * SOAPHeader sh = se.addHeader(); + * se.getBody().detachNode(); + * SOAPBody sb = se.addBody(); + * </PRE> + * It is an error to add a <CODE>SOAPBody</CODE> or <CODE> + * SOAPHeader</CODE> object if one already exists. + * + * <P>The <CODE>SOAPEnvelope</CODE> interface provides three + * methods for creating <CODE>Name</CODE> objects. One method + * creates <CODE>Name</CODE> objects with a local name, a + * namespace prefix, and a namesapce URI. The second method + * creates <CODE>Name</CODE> objects with a local name and a + * namespace prefix, and the third creates <CODE>Name</CODE> + * objects with just a local name. The following line of code, in + * which <I>se</I> is a <CODE>SOAPEnvelope</CODE> object, creates + * a new <CODE>Name</CODE> object with all three.</P> + * <PRE> + * Name name = se.createName("GetLastTradePrice", "WOMBAT", + * "http://www.wombat.org/trader";); + * </PRE> + */ +public interface SOAPEnvelope extends SOAPElement { + + /** + * Creates a new <CODE>Name</CODE> object initialized with the + * given local name, namespace prefix, and namespace URI. + * + * <P>This factory method creates <CODE>Name</CODE> objects + * for use in the SOAP/XML document. + * @param localName a <CODE>String</CODE> giving + * the local name + * @param prefix a <CODE>String</CODE> giving + * the prefix of the namespace + * @param uri a <CODE>String</CODE> giving the + * URI of the namespace + * @return a <CODE>Name</CODE> object initialized with the given + * local name, namespace prefix, and namespace URI + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName, String prefix, String uri) + throws SOAPException; + + /** + * Creates a new <CODE>Name</CODE> object initialized with the + * given local name. + * + * <P>This factory method creates <CODE>Name</CODE> objects + * for use in the SOAP/XML document. + * + * @param localName a <CODE>String</CODE> giving + * the local name + * @return a <CODE>Name</CODE> object initialized with the given + * local name + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName) throws SOAPException; + + /** + * Returns the <CODE>SOAPHeader</CODE> object for this <CODE> + * SOAPEnvelope</CODE> object. + * + * <P>A new <CODE>SOAPMessage</CODE> object is by default + * created with a <CODE>SOAPEnvelope</CODE> object that + * contains an empty <CODE>SOAPHeader</CODE> object. As a + * result, the method <CODE>getHeader</CODE> will always + * return a <CODE>SOAPHeader</CODE> object unless the header + * has been removed and a new one has not been added. + * @return the <CODE>SOAPHeader</CODE> object or <CODE> + * null</CODE> if there is none + * @throws SOAPException if there is a problem + * obtaining the <CODE>SOAPHeader</CODE> object + */ + public abstract SOAPHeader getHeader() throws SOAPException; + + /** + * Returns the <CODE>SOAPBody</CODE> object associated with + * this <CODE>SOAPEnvelope</CODE> object. + * + * <P>A new <CODE>SOAPMessage</CODE> object is by default + * created with a <CODE>SOAPEnvelope</CODE> object that + * contains an empty <CODE>SOAPBody</CODE> object. As a + * result, the method <CODE>getBody</CODE> will always return + * a <CODE>SOAPBody</CODE> object unless the body has been + * removed and a new one has not been added. + * @return the <CODE>SOAPBody</CODE> object for this <CODE> + * SOAPEnvelope</CODE> object or <CODE>null</CODE> if there + * is none + * @throws SOAPException if there is a problem + * obtaining the <CODE>SOAPBody</CODE> object + */ + public abstract SOAPBody getBody() throws SOAPException; + + /** + * Creates a <CODE>SOAPHeader</CODE> object and sets it as the + * <CODE>SOAPHeader</CODE> object for this <CODE> + * SOAPEnvelope</CODE> object. + * + * <P>It is illegal to add a header when the envelope already + * contains a header. Therefore, this method should be called + * only after the existing header has been removed. + * @return the new <CODE>SOAPHeader</CODE> object + * @throws SOAPException if this <CODE> + * SOAPEnvelope</CODE> object already contains a valid + * <CODE>SOAPHeader</CODE> object + */ + public abstract SOAPHeader addHeader() throws SOAPException; + + /** + * Creates a <CODE>SOAPBody</CODE> object and sets it as the + * <CODE>SOAPBody</CODE> object for this <CODE> + * SOAPEnvelope</CODE> object. + * + * <P>It is illegal to add a body when the envelope already + * contains a body. Therefore, this method should be called + * only after the existing body has been removed. + * @return the new <CODE>SOAPBody</CODE> object + * @throws SOAPException if this <CODE> + * SOAPEnvelope</CODE> object already contains a valid + * <CODE>SOAPBody</CODE> object + */ + public abstract SOAPBody addBody() throws SOAPException; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPException.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPException.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPException.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPException.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,177 @@ +/* + * 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; + +/** + * An exception that signals that a SOAP exception has + * occurred. A <CODE>SOAPException</CODE> object may contain a + * <CODE>String</CODE> that gives the reason for the exception, an + * embedded <CODE>Throwable</CODE> object, or both. This class + * provides methods for retrieving reason messages and for + * retrieving the embedded <CODE>Throwable</CODE> object.</P> + * + * <P>Typical reasons for throwing a <CODE>SOAPException</CODE> + * object are problems such as difficulty setting a header, not + * being able to send a message, and not being able to get a + * connection with the provider. Reasons for embedding a <CODE> + * Throwable</CODE> object include problems such as input/output + * errors or a parsing problem, such as an error in parsing a + * header. + */ +public class SOAPException extends Exception { + + /** + * Constructs a <CODE>SOAPException</CODE> object with no + * reason or embedded <CODE>Throwable</CODE> object. + */ + public SOAPException() { + cause = null; + } + + /** + * Constructs a <CODE>SOAPException</CODE> object with the + * given <CODE>String</CODE> as the reason for the exception + * being thrown. + * @param reason a description of what caused + * the exception + */ + public SOAPException(String reason) { + + super(reason); + + cause = null; + } + + /** + * Constructs a <CODE>SOAPException</CODE> object with the + * given <CODE>String</CODE> as the reason for the exception + * being thrown and the given <CODE>Throwable</CODE> object as + * an embedded exception. + * @param reason a description of what caused + * the exception + * @param cause a <CODE>Throwable</CODE> object + * that is to be embedded in this <CODE>SOAPException</CODE> + * object + */ + public SOAPException(String reason, Throwable cause) { + + super(reason); + + initCause(cause); + } + + /** + * Constructs a <CODE>SOAPException</CODE> object + * initialized with the given <CODE>Throwable</CODE> + * object. + * @param cause a <CODE>Throwable</CODE> object + * that is to be embedded in this <CODE>SOAPException</CODE> + * object + */ + public SOAPException(Throwable cause) { + + super(cause.toString()); + + initCause(cause); + } + + /** + * Returns the detail message for this <CODE> + * SOAPException</CODE> object. + * + * <P>If there is an embedded <CODE>Throwable</CODE> object, + * and if the <CODE>SOAPException</CODE> object has no detail + * message of its own, this method will return the detail + * message from the embedded <CODE>Throwable</CODE> + * object.</P> + * @return the error or warning message for this <CODE> + * SOAPException</CODE> or, if it has none, the message of + * the embedded <CODE>Throwable</CODE> object, if there is + * one + */ + public String getMessage() { + + String s = super.getMessage(); + + if ((s == null) && (cause != null)) { + return cause.getMessage(); + } else { + return s; + } + } + + /** + * Returns the <CODE>Throwable</CODE> object embedded in + * this <CODE>SOAPException</CODE> if there is one. Otherwise, + * this method returns <CODE>null</CODE>. + * @return the embedded <CODE>Throwable</CODE> object or <CODE> + * null</CODE> if there is none + */ + public Throwable getCause() { + return cause; + } + + /** + * Initializes the <CODE>cause</CODE> field of this <CODE> + * SOAPException</CODE> object with the given <CODE> + * Throwable</CODE> object. + * + * <P>This method can be called at most once. It is generally + * called from within the constructor or immediately after the + * constructor has returned a new <CODE>SOAPException</CODE> + * object. If this <CODE>SOAPException</CODE> object was + * created with the constructor [EMAIL PROTECTED] #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)} + * or [EMAIL PROTECTED] #SOAPException(java.lang.String, java.lang.Throwable) SOAPException(java.lang.String, java.lang.Throwable)}, meaning + * that its <CODE>cause</CODE> field already has a value, this + * method cannot be called even once. + * + * @param cause the <CODE>Throwable</CODE> + * object that caused this <CODE>SOAPException</CODE> object + * to be thrown. The value of this parameter is saved for + * later retrieval by the <A href= + * "../../../javax/xml/soap/SOAPException.html#getCause()"> + * <CODE>getCause()</CODE></A> method. A <TT>null</TT> value + * is permitted and indicates that the cause is nonexistent + * or unknown. + * @return a reference to this <CODE>SOAPException</CODE> + * instance + * @throws java.lang.IllegalArgumentException if + * <CODE>cause</CODE> is this <CODE>Throwable</CODE> object. + * (A <CODE>Throwable</CODE> object cannot be its own + * cause.) + * @throws java.lang.IllegalStateException if this <CODE> + * SOAPException</CODE> object was created with [EMAIL PROTECTED] #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)} + * or [EMAIL PROTECTED] #SOAPException(java.lang.String, java.lang.Throwable) SOAPException(java.lang.String, java.lang.Throwable)}, or this + * method has already been called on this <CODE> + * SOAPException</CODE> object + */ + public synchronized Throwable initCause(Throwable cause) { + + if (this.cause != null) { + throw new IllegalStateException("Can't override cause"); + } + + if (cause == this) { + throw new IllegalArgumentException("Self-causation not permitted"); + } else { + this.cause = cause; + + return this; + } + } + + private Throwable cause; +} Added: geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFactory.java URL: http://svn.apache.org/viewcvs/geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFactory.java?view=auto&rev=153028 ============================================================================== --- geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFactory.java (added) +++ geronimo/trunk/specs/saaj/src/javax/xml/soap/SOAPFactory.java Tue Feb 8 22:00:44 2005 @@ -0,0 +1,147 @@ +/* + * 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; + +/** + * <code>SOAPFactory</code> is a factory for creating various objects + * that exist in the SOAP XML tree. + * + * <code>SOAPFactory</code> can be + * used to create XML fragments that will eventually end up in the + * SOAP part. These fragments can be inserted as children of the + * <code>SOAPHeaderElement</code> or <code>SOAPBodyElement</code> or + * <code>SOAPEnvelope</code>. + * + * <code>SOAPFactory</code> also has methods to create + * <code>javax.xml.soap.Detail</code> objects as well as + * <code>java.xml.soap.Name</code> objects. + * + */ +public abstract class SOAPFactory { + + public SOAPFactory() {} + + /** + * Create a <code>SOAPElement</code> object initialized with the + * given <code>Name</code> object. + * + * @param name a <code>Name</code> object with the XML name for + * the new element + * @return the new <code>SOAPElement</code> object that was + * created + * @throws SOAPException if there is an error in creating the + * <code>SOAPElement</code> object + */ + public abstract SOAPElement createElement(Name name) throws SOAPException; + + /** + * Create a <code>SOAPElement</code> object initialized with the + * given local name. + * + * @param localName a <code>String</code> giving the local name for + * the new element + * @return the new <code>SOAPElement</code> object that was + * created + * @throws SOAPException if there is an error in creating the + * <code>SOAPElement</code> object + */ + public abstract SOAPElement createElement(String localName) throws SOAPException; + + /** + * Create a new <code>SOAPElement</code> object with the given + * local name, prefix and uri. + * + * @param localName a <code>String</code> giving the local name + * for the new element + * @param prefix the prefix for this <code>SOAPElement</code> + * @param uri a <code>String</code> giving the URI of the + * namespace to which the new element belongs + * @return the new <code>SOAPElement</code> object that was + * created + * @throws SOAPException if there is an error in creating the + * <code>SOAPElement</code> object + */ + public abstract SOAPElement createElement(String localName, String prefix, String uri) + throws SOAPException; + + /** + * Creates a new <code>Detail</code> object which serves as a container + * for <code>DetailEntry</code> objects. + * <p> + * This factory method creates <code>Detail</code> objects for use in + * situations where it is not practical to use the <code>SOAPFault</code> + * abstraction. + * + * @return a <code>Detail</code> object + * @throws SOAPException if there is a SOAP error + */ + public abstract Detail createDetail() throws SOAPException; + + /** + * Creates a new <code>Name</code> object initialized with the + * given local name, namespace prefix, and namespace URI. + * <p> + * This factory method creates <code>Name</code> objects for use in + * situations where it is not practical to use the <code>SOAPEnvelope</code> + * abstraction. + * + * @param localName a <code>String</code> giving the local name + * @param prefix a <code>String</code> giving the prefix of the namespace + * @param uri a <code>String</code> giving the URI of the namespace + * @return a <code>Name</code> object initialized with the given + * local name, namespace prefix, and namespace URI + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName, String prefix, String uri) + throws SOAPException; + + /** + * Creates a new <code>Name</code> object initialized with the + * given local name. + * <p> + * This factory method creates <code>Name</code> objects for use in + * situations where it is not practical to use the <code>SOAPEnvelope</code> + * abstraction. + * + * @param localName a <code>String</code> giving the local name + * @return a <code>Name</code> object initialized with the given + * local name + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName) throws SOAPException; + + /** + * Creates a new instance of <code>SOAPFactory</code>. + * + * @return a new instance of a <code>SOAPFactory</code> + * @throws SOAPException if there was an error creating the + * default <code>SOAPFactory</code> + */ + public static SOAPFactory newInstance() throws SOAPException { + + try { + return (SOAPFactory) FactoryFinder.find(SF_PROPERTY, DEFAULT_SF); + } catch (Exception exception) { + throw new SOAPException("Unable to create SOAP Factory: " + + exception.getMessage()); + } + } + + private static final String SF_PROPERTY = "javax.xml.soap.SOAPFactory"; + + private static final String DEFAULT_SF = + "org.apache.axis.soap.SOAPFactoryImpl"; +}
