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

Go to download
/*
 * 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;

/**
 * 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
     * @return DetailEntry.
     * @throws SOAPException  thrown when there is a problem in adding a DetailEntry object to this Detail object.
     */
    public abstract DetailEntry addDetailEntry(Name name) throws SOAPException;

    /**
     * Gets a list of the detail entries in this Detail object.
     * @return  an Iterator object over the DetailEntry
     *        objects in this Detail object
     */
    public abstract Iterator getDetailEntries();
}