View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package javax.xml.soap;
17  
18  import java.util.Iterator;
19  
20  /**
21   * A container for <code>DetailEntry</code> objects. <code>DetailEntry</code>
22   * objects give detailed error information that is application-specific and
23   * related to the <code>SOAPBody</code> object that contains it.
24   * <P>
25   * A <code>Detail</code> object, which is part of a <code>SOAPFault</code>
26   * object, can be retrieved using the method <code>SOAPFault.getDetail</code>.
27   * The <code>Detail</code> interface provides two methods. One creates a new
28   * <code>DetailEntry</code> object and also automatically adds it to
29   * the <code>Detail</code> object. The second method gets a list of the
30   * <code>DetailEntry</code> objects contained in a <code>Detail</code>
31   * object.
32   * <P>
33   * The following code fragment, in which <i>sf</i> is a <code>SOAPFault</code>
34   * object, gets its <code>Detail</code> object (<i>d</i>), adds a new
35   * <code>DetailEntry</code> object to <i>d</i>, and then gets a list of all the
36   * <code>DetailEntry</code> objects in <i>d</i>. The code also creates a
37   * <code>Name</code> object to pass to the method <code>addDetailEntry</code>.
38   * The variable <i>se</i>, used to create the <code>Name</code> object,
39   * is a <code>SOAPEnvelope</code> object.
40   * <PRE>
41   *    Detail d = sf.getDetail();
42   *    Name name = se.createName("GetLastTradePrice", "WOMBAT",
43   *                                "http://www.wombat.org/trader");
44   *    d.addDetailEntry(name);
45   *    Iterator it = d.getDetailEntries();
46   * </PRE>
47   */
48  public interface Detail extends SOAPFaultElement {
49  
50      /**
51       * Creates a new <code>DetailEntry</code> object with the given
52       * name and adds it to this <code>Detail</code> object.
53       * @param   name a <code>Name</code> object identifying the new <code>DetailEntry</code> object
54       * @return DetailEntry.
55       * @throws SOAPException  thrown when there is a problem in adding a DetailEntry object to this Detail object.
56       */
57      public abstract DetailEntry addDetailEntry(Name name) throws SOAPException;
58  
59      /**
60       * Gets a list of the detail entries in this <code>Detail</code> object.
61       * @return  an <code>Iterator</code> object over the <code>DetailEntry</code>
62       *        objects in this <code>Detail</code> object
63       */
64      public abstract Iterator getDetailEntries();
65  }