javax.xml.soap.Detail Maven / Gradle / Ivy

Go to download
/*
 * $Id: Detail.java,v 1.9 2006/03/30 00:59:38 ofung Exp $
 * $Revision: 1.9 $
 * $Date: 2006/03/30 00:59:38 $
 */

/*
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License).  You may not use this file except in
 * compliance with the License.
 * 
 * You can obtain a copy of the license at
 * https://glassfish.dev.java.net/public/CDDLv1.0.html.
 * See the License for the specific language governing
 * permissions and limitations under the License.
 * 
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file
 * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * you own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 * 
 * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
 */
package javax.xml.soap;

import java.util.Iterator;

import javax.xml.namespace.QName;

/**
 * A container for DetailEntry objects. DetailEntry
 * objects give detailed error information that is application-specific and
 * related to the SOAPBody object that contains it.
 *
 * A Detail object, which is part of a SOAPFault
 * object, can be retrieved using the method SOAPFault.getDetail.
 * The Detail interface provides two methods. One creates a new
 * DetailEntry object and also automatically adds it to
 * the Detail object. The second method gets a list of the
 * DetailEntry objects contained in a Detail
 * object.
 * 

 * The following code fragment, in which sf is a SOAPFault
 * object, gets its Detail object (d), adds a new
 * DetailEntry object to d, and then gets a list of all the
 * DetailEntry objects in d. The code also creates a
 * Name object to pass to the method addDetailEntry.
 * The variable se, used to create the Name object,
 * is a SOAPEnvelope object.
 * 
 *    Detail d = sf.getDetail();
 *    Name name = se.createName("GetLastTradePrice", "WOMBAT",
 *                                "http://www.wombat.org/trader");
 *    d.addDetailEntry(name);
 *    Iterator it = d.getDetailEntries();
 * 
 */
public interface Detail extends SOAPFaultElement {

    /**
     * Creates a new DetailEntry object with the given
     * name and adds it to this Detail object.
     *
     * @param name a Name object identifying the
     *         new DetailEntry object
     *
     * @exception SOAPException thrown when there is a problem in adding a
     * DetailEntry object to this Detail object.
     *
     * @see Detail#addDetailEntry(QName qname)
     */
    public DetailEntry addDetailEntry(Name name) throws SOAPException;

    /**
     * Creates a new DetailEntry object with the given
     * QName and adds it to this Detail object. This method
     * is the preferred over the one using Name.
     *
     * @param qname a QName object identifying the
     *         new DetailEntry object
     *
     * @exception SOAPException thrown when there is a problem in adding a
     * DetailEntry object to this Detail object.
     *
     * @see Detail#addDetailEntry(Name name)
     * @since SAAJ 1.3
     */
    public DetailEntry addDetailEntry(QName qname) throws SOAPException;

    /**
     * Gets an Iterator over all of the DetailEntrys in this Detail object.
     *
     * @return an Iterator object over the DetailEntry
     *             objects in this Detail object
     */
    public Iterator getDetailEntries();
}