001: /* Media.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Wed Feb 26 13:29:14 2003, Created by tomyeh
010: }}IS_NOTE
011:
012: Copyright (C) 2002 Potix Corporation. All Rights Reserved.
013:
014: {{IS_RIGHT
015: This program is distributed under GPL Version 2.0 in the hope that
016: it will be useful, but WITHOUT ANY WARRANTY.
017: }}IS_RIGHT
018: */
019: package org.zkoss.util.media;
020:
021: import java.io.Reader;
022: import java.io.InputStream;
023:
024: /**
025: * Represents any multi-medai, such as a voice, a pdf file, an excel file,
026: * an image and so on.
027: *
028: * <p>By implementing this interface, objects can be processed generically
029: * by servlets and many other codes.
030: *
031: * @author tomyeh
032: */
033: public interface Media {
034: /** Returns whether the format of tis content is binary or text-based.
035: * If true, use {@link #getByteData} or {@link #getStreamData}, depending on
036: * {@link #inMemory}, to retrieve its content.
037: * If false, use {@link #getStringData} or {@link #getReaderData}, depending on
038: * {@link #inMemory}, to retrieve its content.
039: *
040: * <p>To decide which API to use, you need to examine
041: * both {@link #isBinary} and {@link #inMemory}.
042: *
043: * @see #getStringData
044: * @see #getByteData
045: * @see #getReaderData
046: * @see #getStreamData
047: */
048: public boolean isBinary();
049:
050: /** Returns whether the data is cached in memory (in form of
051: * byte[] or String).
052: * If true, use {@link #getByteData} or {@link #getStringData}, depending on
053: * {@link #isBinary}, to retrieve its content.
054: * If false, use {@link #getStreamData} or {@link #getReaderData}, depending on
055: * {@link #isBinary}, to retrieve its content.
056: *
057: * <p>To decide which API to use, you need to examine
058: * both {@link #isBinary} and {@link #inMemory}.
059: *
060: * @see #getStringData
061: * @see #getByteData
062: * @see #getReaderData
063: * @see #getStreamData
064: */
065: public boolean inMemory();
066:
067: /** Returns the raw data in byte array.
068: *
069: * <p>It might <i>not</i> be a copy, so don't modify
070: * it directly unless you know what you are doing.
071: *
072: * @exception IllegalStateException if {@link #isBinary} returns false,
073: * or {@link #inMemory} returns false.
074: * @see #getStringData
075: */
076: public byte[] getByteData();
077:
078: /** Returns the raw data in string.
079: *
080: * @exception IllegalStateException if {@link #isBinary} returns false,
081: * or {@link #inMemory} returns false.
082: * @see #getByteData
083: */
084: public String getStringData();
085:
086: /** Returns the raw data in InputStream.
087: *
088: * <p>Note: it wraps {@link #getByteData} with ByteArrayInputStream
089: * if it is in memory ({@link #inMemory} returns true.
090: *
091: * @exception IllegalStateException if {@link #isBinary} returns false.
092: * @see #getReaderData
093: */
094: public InputStream getStreamData();
095:
096: /** Returns the raw data in Reader.
097: *
098: * <p>Note: it wraps {@link #getStringData} with StringReader,
099: * if it is in memory ({@link #inMemory} returns true.
100: *
101: * @exception IllegalStateException if {@link #isBinary} returns true.
102: * @see #getStreamData
103: */
104: public Reader getReaderData();
105:
106: /** Returns the name (usually filename) of this media, or null
107: * if not available.
108: */
109: public String getName();
110:
111: /** Returns the format name, e.g., "jpeg", or null if not available.
112: * @see #getContentType
113: */
114: public String getFormat();
115:
116: /** Returns the content type, e.g., "image/jpeg", or null if not available.
117: * @see #getFormat
118: */
119: public String getContentType();
120: }
|