You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by db...@apache.org on 2005/02/09 07:01:04 UTC
svn commit: r153028 [4/5] - in geronimo/trunk: etc/ specs/j2ee/
specs/jaxrpc/ specs/jaxrpc/src/ specs/jaxrpc/src/javax/
specs/jaxrpc/src/javax/xml/ specs/jaxrpc/src/javax/xml/rpc/
specs/jaxrpc/src/javax/xml/rpc/encoding/
specs/jaxrpc/src/javax/xml/rpc/handler/
specs/jaxrpc/src/javax/xml/rpc/handler/soap/
specs/jaxrpc/src/javax/xml/rpc/holders/
specs/jaxrpc/src/javax/xml/rpc/server/ specs/jaxrpc/src/javax/xml/rpc/soap/
specs/qname/ specs/qname/src/ specs/qname/src/javax/
specs/qname/src/javax/xml/ specs/qname/src/javax/xml/namespace/ specs/saaj/
specs/saaj/src/ specs/saaj/src/javax/ specs/saaj/src/javax/xml/
specs/saaj/src/javax/xml/soap/
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 {@link #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)}
+ * or {@link #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 {@link #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)}
+ * or {@link #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";
+}