KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > bind > attachment > AttachmentUnmarshaller


1 package javax.xml.bind.attachment;
2
3 import javax.activation.DataHandler JavaDoc;
4
5 /**
6  * <p>Enables JAXB unmarshalling of a root document containing optimized binary data formats.</p>
7  *
8  * <p>This API enables an efficient cooperative processing of optimized
9  * binary data formats between a JAXB 2.0 implementation and MIME-based package
10  * processor (MTOM/XOP and WS-I AP 1.0). JAXB unmarshals the body of a package, delegating the
11  * understanding of the packaging format being used to a MIME-based
12  * package processor that implements this abstract class.</p>
13  *
14  * <p>This abstract class identifies if a package requires XOP processing, {@link #isXOPPackage()} and provides retrieval of binary content stored as attachments by content-id.</p>
15  *
16  * <h2>Identifying the content-id, cid, to pass to <code>getAttachment*(String cid)</code></h2>
17  * <ul>
18  * <li>
19  * For XOP processing, the infoset representation of the cid is described
20  * in step 2a in
21  * <a HREF="http://www.w3.org/TR/2005/REC-xop10-20050125/#interpreting_xop_packages">Section 3.2 Interpreting XOP Packages</a>
22  * </li>
23  * <li>
24  * For WS-I AP 1.0, the cid is identified as an element or attribute of
25  * type <code>ref:swaRef </code> specified in
26  * <a HREF="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html#Referencing_Attachments_from_the_SOAP_Envelope">Section 4.4 Referencing Attachments from the SOAP Envelope</a>
27  * </li>
28  * </ul>
29  *
30  * @author Marc Hadley
31  * @author Kohsuke Kawaguchi
32  * @author Joseph Fialli
33  *
34  * @since JAXB 2.0
35  *
36  * @see javax.xml.bind.Unmarshaller#setAttachmentUnmarshaller(AttachmentUnmarshaller)
37  *
38  * @see <a HREF="http://www.w3.org/TR/2005/REC-xop10-20050125/">XML-binary Optimized Packaging</a>
39  * @see <a HREF="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">WS-I Attachments Profile Version 1.0.</a>
40  * @see <a HREF="http://www.w3.org/TR/xml-media-types/">Describing Media Content of Binary Data in XML</a>
41  */
42 public abstract class AttachmentUnmarshaller {
43    /**
44     * <p>Lookup MIME content by content-id, <code>cid</code>, and return as a {@link DataHandler}.</p>
45     *
46     * <p>The returned <code>DataHandler</code> instance must be configured
47     * to meet the following required mapping constaint.
48     * <table border="2" rules="all" cellpadding="4">
49     * <thead>
50     * <tr>
51     * <th align="center" colspan="2">
52     * Required Mappings between MIME and Java Types
53     * </tr>
54     * <tr>
55     * <th>MIME Type</th>
56     * <th>Java Type</th>
57     * </tr>
58     * </tr>
59     * <tr>
60     * <th><code>DataHandler.getContentType()</code></th>
61     * <th><code>instanceof DataHandler.getContent()</code></th>
62     * </tr>
63     * </thead>
64     * <tbody>
65     * <tr>
66     * <td>image/gif</td>
67     * <td>java.awt.Image</td>
68     * </tr>
69     * <tr>
70     * <td>image/jpeg</td>
71     * <td>java.awt.Image</td>
72     * </tr>
73     * <tr>
74     * <td>text/xml or application/xml</td>
75     * <td>javax.xml.transform.Source</td>
76     * </tr>
77     * </tbody>
78     * </table>
79     * Note that it is allowable to support additional mappings.</p>
80     *
81     * @param cid It is expected to be a valid lexical form of the XML Schema
82     * <code>xs:anyURI</code> datatype. If <code>{@link #isXOPPackage()}
83     * ==true</code>, it must be a valid URI per the <code>cid:</code> URI scheme (see <a HREF="http://www.ietf.org/rfc/rfc2387.txt">RFC 2387</a>)
84     *
85     * @return
86     * a {@link DataHandler} that represents the MIME attachment.
87     *
88     * @throws IllegalArgumentException if the attachment for the given cid is not found.
89     */
90    public abstract DataHandler JavaDoc getAttachmentAsDataHandler(String JavaDoc cid);
91
92     /**
93      * <p>Retrieve the attachment identified by content-id, <code>cid</code>, as a <tt>byte[]</tt></p>.
94      *
95      * @param cid It is expected to be a valid lexical form of the XML Schema
96      * <code>xs:anyURI</code> datatype. If <code>{@link #isXOPPackage()}
97      * ==true</code>, it must be a valid URI per the <code>cid:</code> URI scheme (see <a HREF="http://www.ietf.org/rfc/rfc2387.txt">RFC 2387</a>)
98      *
99      * @return byte[] representation of attachment identified by cid.
100      *
101     * @throws IllegalArgumentException if the attachment for the given cid is not found.
102      */
103     public abstract byte[] getAttachmentAsByteArray(String JavaDoc cid);
104
105     /**
106      * <p>Read-only property that returns true if JAXB unmarshaller needs to perform XOP processing.</p>
107      *
108      * <p>This method returns <code>true</code> when the constraints specified
109      * in <a HREF="http://www.w3.org/TR/2005/REC-xop10-20050125/#identifying_xop_documents">Identifying XOP Documents</a> are met.
110      * This value must not change during the unmarshalling process.</p>
111      *
112      * @return true when MIME context is a XOP Document.
113      */
114     public boolean isXOPPackage() { return false; }
115 }
116
117
118
Popular Tags