001: /*
002: * $Id: Detail.java,v 1.9 2006/03/30 00:59:38 ofung Exp $
003: * $Revision: 1.9 $
004: * $Date: 2006/03/30 00:59:38 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: import java.util.Iterator;
031:
032: import javax.xml.namespace.QName;
033:
034: /**
035: * A container for <code>DetailEntry</code> objects. <code>DetailEntry</code>
036: * objects give detailed error information that is application-specific and
037: * related to the <code>SOAPBody</code> object that contains it.
038: *<P>
039: * A <code>Detail</code> object, which is part of a <code>SOAPFault</code>
040: * object, can be retrieved using the method <code>SOAPFault.getDetail</code>.
041: * The <code>Detail</code> interface provides two methods. One creates a new
042: * <code>DetailEntry</code> object and also automatically adds it to
043: * the <code>Detail</code> object. The second method gets a list of the
044: * <code>DetailEntry</code> objects contained in a <code>Detail</code>
045: * object.
046: * <P>
047: * The following code fragment, in which <i>sf</i> is a <code>SOAPFault</code>
048: * object, gets its <code>Detail</code> object (<i>d</i>), adds a new
049: * <code>DetailEntry</code> object to <i>d</i>, and then gets a list of all the
050: * <code>DetailEntry</code> objects in <i>d</i>. The code also creates a
051: * <code>Name</code> object to pass to the method <code>addDetailEntry</code>.
052: * The variable <i>se</i>, used to create the <code>Name</code> object,
053: * is a <code>SOAPEnvelope</code> object.
054: * <PRE>
055: * Detail d = sf.getDetail();
056: * Name name = se.createName("GetLastTradePrice", "WOMBAT",
057: * "http://www.wombat.org/trader");
058: * d.addDetailEntry(name);
059: * Iterator it = d.getDetailEntries();
060: * </PRE>
061: */
062: public interface Detail extends SOAPFaultElement {
063:
064: /**
065: * Creates a new <code>DetailEntry</code> object with the given
066: * name and adds it to this <code>Detail</code> object.
067: *
068: * @param name a <code>Name</code> object identifying the
069: * new <code>DetailEntry</code> object
070: *
071: * @exception SOAPException thrown when there is a problem in adding a
072: * DetailEntry object to this Detail object.
073: *
074: * @see Detail#addDetailEntry(QName qname)
075: */
076: public DetailEntry addDetailEntry(Name name) throws SOAPException;
077:
078: /**
079: * Creates a new <code>DetailEntry</code> object with the given
080: * QName and adds it to this <code>Detail</code> object. This method
081: * is the preferred over the one using Name.
082: *
083: * @param qname a <code>QName</code> object identifying the
084: * new <code>DetailEntry</code> object
085: *
086: * @exception SOAPException thrown when there is a problem in adding a
087: * DetailEntry object to this Detail object.
088: *
089: * @see Detail#addDetailEntry(Name name)
090: * @since SAAJ 1.3
091: */
092: public DetailEntry addDetailEntry(QName qname) throws SOAPException;
093:
094: /**
095: * Gets an Iterator over all of the <code>DetailEntry</code>s in this <code>Detail</code> object.
096: *
097: * @return an <code>Iterator</code> object over the <code>DetailEntry</code>
098: * objects in this <code>Detail</code> object
099: */
100: public Iterator getDetailEntries();
101: }
|