001 /*
002 * $Id: Detail.java,v 1.7 2004/04/02 01:24:17 ofung Exp $
003 * $Revision: 1.7 $
004 * $Date: 2004/04/02 01:24:17 $
005 */
006
007 /*
008 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
009 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
010 *
011 * This code is free software; you can redistribute it and/or modify it
012 * under the terms of the GNU General Public License version 2 only, as
013 * published by the Free Software Foundation. Sun designates this
014 * particular file as subject to the "Classpath" exception as provided
015 * by Sun in the LICENSE file that accompanied this code.
016 *
017 * This code is distributed in the hope that it will be useful, but WITHOUT
018 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
019 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
020 * version 2 for more details (a copy is included in the LICENSE file that
021 * accompanied this code).
022 *
023 * You should have received a copy of the GNU General Public License version
024 * 2 along with this work; if not, write to the Free Software Foundation,
025 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
026 *
027 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
028 * CA 95054 USA or visit www.sun.com if you need additional information or
029 * have any questions.
030 */
031 package javax.xml.soap;
032
033 import java.util.Iterator;
034
035 import javax.xml.namespace.QName;
036
037 /**
038 * A container for <code>DetailEntry</code> objects. <code>DetailEntry</code>
039 * objects give detailed error information that is application-specific and
040 * related to the <code>SOAPBody</code> object that contains it.
041 *<P>
042 * A <code>Detail</code> object, which is part of a <code>SOAPFault</code>
043 * object, can be retrieved using the method <code>SOAPFault.getDetail</code>.
044 * The <code>Detail</code> interface provides two methods. One creates a new
045 * <code>DetailEntry</code> object and also automatically adds it to
046 * the <code>Detail</code> object. The second method gets a list of the
047 * <code>DetailEntry</code> objects contained in a <code>Detail</code>
048 * object.
049 * <P>
050 * The following code fragment, in which <i>sf</i> is a <code>SOAPFault</code>
051 * object, gets its <code>Detail</code> object (<i>d</i>), adds a new
052 * <code>DetailEntry</code> object to <i>d</i>, and then gets a list of all the
053 * <code>DetailEntry</code> objects in <i>d</i>. The code also creates a
054 * <code>Name</code> object to pass to the method <code>addDetailEntry</code>.
055 * The variable <i>se</i>, used to create the <code>Name</code> object,
056 * is a <code>SOAPEnvelope</code> object.
057 * <PRE>
058 * Detail d = sf.getDetail();
059 * Name name = se.createName("GetLastTradePrice", "WOMBAT",
060 * "http://www.wombat.org/trader");
061 * d.addDetailEntry(name);
062 * Iterator it = d.getDetailEntries();
063 * </PRE>
064 */
065 public interface Detail extends SOAPFaultElement {
066
067 /**
068 * Creates a new <code>DetailEntry</code> object with the given
069 * name and adds it to this <code>Detail</code> object.
070 *
071 * @param name a <code>Name</code> object identifying the
072 * new <code>DetailEntry</code> object
073 *
074 * @exception SOAPException thrown when there is a problem in adding a
075 * DetailEntry object to this Detail object.
076 *
077 * @see Detail#addDetailEntry(QName qname)
078 */
079 public DetailEntry addDetailEntry(Name name) throws SOAPException;
080
081 /**
082 * Creates a new <code>DetailEntry</code> object with the given
083 * QName and adds it to this <code>Detail</code> object. This method
084 * is the preferred over the one using Name.
085 *
086 * @param qname a <code>QName</code> object identifying the
087 * new <code>DetailEntry</code> object
088 *
089 * @exception SOAPException thrown when there is a problem in adding a
090 * DetailEntry object to this Detail object.
091 *
092 * @see Detail#addDetailEntry(Name name)
093 * @since SAAJ 1.3
094 */
095 public DetailEntry addDetailEntry(QName qname) throws SOAPException;
096
097 /**
098 * Gets an Iterator over all of the <code>DetailEntry</code>s in this <code>Detail</code> object.
099 *
100 * @return an <code>Iterator</code> object over the <code>DetailEntry</code>
101 * objects in this <code>Detail</code> object
102 */
103 public Iterator getDetailEntries();
104 }
|