KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > emb > Media


1 /*
2  * JBoss, the OpenSource J2EE webOS
3  *
4  * Distributable under LGPL license. See terms of license at gnu.org.
5  */
6
7 package javax.emb;
8
9 import java.io.Serializable;
10
11 /**
12  * This basic interface is used throughout Enterprise Media Beans to define the
13  * most common behavior for media objects. It defines the services common to
14  * all kinds of media objects, regardless of them being persistent or
15  * transient.
16  *
17  * <p>There are basically two major ways to implement this interface. Media
18  * Entity Beans deal with media content modeled as EJB entity beans, i.e. media
19  * that is persistent and mutable. The class {@link MediaBean} models media
20  * content that is local, possibly transient and immutable.
21  *
22  * <p>In order to allow a common view on all kinds of media objects, the Media
23  * interface extends {@link java.io.Serializable}, regardless of media being
24  * persistent or transient. Having the Media interface extend Serializable
25  * ensures that instances can be transferred over remote boundaries, for
26  * example using facade stateless session beans.
27  *
28  * @version <tt>$Revision: 1.4 $</tt>
29  * @author <a HREF="mailto:ricardoarguello@users.sourceforge.net">Ricardo
30  * Argüello</a>
31  */
32 public interface Media extends Serializable
33 {
34    static final String MIME_TYPE_UNKNOWN = "www/unknown";
35
36    /**
37     * Returns the complete media content as a byte array. This method is
38     * intended for convenient access to media content up to a few MB in size.
39     * Streaming I/O access as defined in readContent() should be used instead
40     * to access large content.
41     *
42     * @return the media content.
43     * @throws javax.emb.ContentTooLargeException if the resulting byte array
44     * size exceeds the theoretical maximum Java array size of 2 GB.
45     * @throws javax.emb.ContentAccessException if the content cannot be
46     * accessed.
47     */
48    byte[] getContent() throws MediaException;
49
50    /**
51     * Queries a suitable media format instance from the MediaFormatRegistry
52     * singleton and returns it. The file extension contained in the name
53     * property is used as a key for this query.
54     *
55     * @return the media format.
56     * @throws javax.emb.FormatNotFoundException if the file extension is not
57     * registered with the media format registry.
58     */
59    MediaFormat getFormat() throws MediaException;
60
61    /**
62     * Returns the receiver's header information. Queries a suitable media
63     * format instance from the MediaFormatRegistry singleton and determines the
64     * header information based on it.
65     *
66     * @return the media header.
67     * @throws javax.emb.FormatNotFoundException if the file extension is not
68     * registered with the media format registry.
69     * @throws javax.emb.FormatSyntaxException if the receiver's content does
70     * not match the syntax defined for the receiver's media format.
71     * @throws javax.emb.FormatFeatureException if the header cannot be
72     * extracted because a vital feature of the media format involved is
73     * not supported by the implementation.
74     * @throws javax.emb.ContentAccessException if the actual content access
75     * fails.
76     */
77    MediaHeader getHeader() throws MediaException;
78
79    /**
80     * Returns a mime type for the receiver's content as a string. This allows
81     * media content to be written directly to a Servlet output stream, as this
82     * technique requires a mime type to be specified in case the output is
83     * different from HTML. If no mime type has been set explicitly a default
84     * mime type is returned, possibly based on the receiver's format.
85     *
86     * @return the mime type.
87     * @throws javax.emb.FormatNotFoundException if the receiver's media format
88     * cannot be determined.
89     */
90    String getMimeType() throws MediaException;
91
92    /**
93     * Returns the receiver's non-unique name as a String. The name is used as a
94     * file name hint in case the media content is to be stored in a file system
95     * and therefore may only contain characters that are valid in file names.
96     * It contains a file extension that represents the receiver's media format.
97     *
98     * @return the media name.
99     */
100    String getName() throws MediaException;
101
102    /**
103     * Returns a media object that can be used as a proxy for the receiver, e.g.
104     * a thumbnail, an icon, a short video/audio clip. Servlets can use this
105     * operation whenever a thumbnail or sound bite is required to represent a
106     * given media and give users an up front impression of the content. The
107     * value returned may have any format and is never null.
108     *
109     * @return the media proxy
110     */
111    Media getProxy() throws MediaException;
112
113    /**
114     * This operation returns the receiver's content size in number of bytes as
115     * a long value.
116     *
117     * @return the media size.
118     * @throws javax.emb.ContentAccessException if there's a problem accessing
119     * the receiver's content.
120     */
121    long getSize() throws MediaException;
122
123    /**
124     * Similarly to input streams, this method fills the given buffer with
125     * content read from the media object. The media content is copied from the
126     * given position, and the buffer is filled beginning with offset 0. In case
127     * the buffer is larger than the amount of bytes available, it is only
128     * partially filled. The buffer may also be filled partially if the
129     * implementation uses non-blocking I/O. The method returns the number of
130     * bytes copied into the buffer, or -1 in case the given position equals the
131     * content size.
132     *
133     * @param position the position in media to copy from.
134     * @param buffer the byte array to store content.
135     * @return the number of bytes copied into the buffer.
136     * @throws java.lang.IndexOutOfBoundsException if the given position is
137     * negative or exceeding the content size.
138     * @throws java.lang.NullPointerException if the given buffer is null.
139     * @throws javax.emb.ContentAccessException if the actual content access
140     * fails.
141     */
142    int readContent(long position, byte[] buffer) throws MediaException;
143
144    /**
145     * Similar to input streams, this method fills the given buffer with content
146     * read from the media object. The media content is copied from the given
147     * position, and the buffer is filled beginning from the given offset with a
148     * maximum amount of bytes defined by the given length. In case the buffer
149     * is larger than the amount of bytes available, it is only partially
150     * filled. The buffer may also be filled partially if the implementation
151     * uses non-blocking I/O. The method returns the number of bytes copied into
152     * the buffer, or -1 in case the given position equals the content size.
153     *
154     * @param position the position in media to copy from.
155     * @param buffer the byte array to store content.
156     * @param offset the offset in the buffer to begin storing content.
157     * @param length the number of bytes to copy from the content.
158     * @return number of bytes copied into the buffer.
159     * @throws java.lang.IndexOutOfBoundsException if the given position is
160     * negative or exceeding the content size, or in case the given
161     * offset is negative or exceeding the buffer size.
162     * @throws java.lang.NegativeArraySizeException if the given length is
163     * negative.
164     * @throws java.lang.NullPointerExcetion if the given buffer is null.
165     * @throws javax.emb.ContentAccessException if the actual content access
166     * fails.
167     */
168    int readContent(long position, byte[] buffer, int offset, int length)
169       throws MediaException;
170 }
Popular Tags