001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.media.protocol;
027:
028: import javax.microedition.media.Controllable;
029:
030: import javax.microedition.media.Control;
031:
032: import java.io.IOException;
033:
034: /**
035: * A <CODE>DataSource</CODE> is an abstraction for media protocol-handlers.
036: * It hides the details of how the data is read from source--whether
037: * the data is
038: * coming from a file, streaming server or proprietary delivery mechanism.
039: * It provides the methods for a <code>Player</code> to access
040: * the input data.
041: * <p>
042: * An application-defined protocol can be implemented with a custom
043: * <code>DataSource</code>. A <code>Player</code> can then be
044: * created for playing back the media from the custom
045: * <code>DataSource</code> using the
046: * <a href="../Manager.html#createPlayer(javax.microedition.media.protocol.DataSource)">
047: * <code>Manager.createPlayer</code></a> method.
048: * <p>
049: * There are a few reasons why one would choose to implement
050: * a <code>DataSource</code> as opposed to an <code>InputStream</code>
051: * for a custom protocol:
052: * <ul>
053: * <li>
054: * <code>DataSource/SourceStream</code> provides the random
055: * seeking API that
056: * is not supported by an <code>InputStream</code>. i.e., if
057: * the custom protocol
058: * requires random seeking capabilities, a custom
059: * <code>DataSource</code> can be used.
060: * <li>
061: * <code>DataSource/SourceStream</code> supports the concept of
062: * transfer size
063: * that is more suited for frame-delimited data, e.g. video.
064: * </ul>
065: * <p>
066: * A <code>DataSource</code> contains a set of <code>SourceStream</code>s.
067: * Each <code>SourceStream</code> represents one elementary data stream
068: * of the source. In the most common case, a <code>DataSource</code>
069: * only provides one <code>SourceStream</code>. A <code>DataSource</code>
070: * may provide multiple <code>SourceStream</code>s if it encapsulates
071: * multiple elementary data streams.
072: * <p>
073: * Each of the <code>SourceStream</code>s provides the methods to allow
074: * a <code>Player</code> to read data for processing.
075: * <p>
076: * <CODE>DataSource</CODE> manages the life-cycle of the media source
077: * by providing a simple connection protocol.
078: *
079: * <p>
080: * <a name="controls">
081: * <code>DataSource</code> implements <code>Controllable</code> which
082: * provides extra controls via some type-specific <code>Control</code>
083: * interfaces. <code>getControl</code> and <code>getControls</code>
084: * can only be called when the <code>DataSource</code> is connected.
085: * An <code>IllegalStateException</code> will be thrown otherwise.
086: *
087: * @see javax.microedition.media.Manager
088: * @see javax.microedition.media.protocol.SourceStream
089: * @see javax.microedition.media.protocol.ContentDescriptor
090: */
091: abstract public class DataSource implements Controllable {
092: private String sourceLocator;
093:
094: /**
095: * Construct a <CODE>DataSource</CODE> from a locator.
096: * This method should be overloaded by subclasses;
097: * the default implementation just keeps track of
098: * the locator.
099: *
100: * @param locator The locator that describes
101: * the <CODE>DataSource</CODE>.
102: */
103: public DataSource(String locator) {
104: sourceLocator = locator;
105: }
106:
107: /**
108: * Get the locator that describes this source.
109: * Returns <CODE>null</CODE> if the locator hasn't been set.
110: *
111: * @return The locator for this source.
112: */
113: public String getLocator() {
114: return sourceLocator;
115: }
116:
117: /**
118: * Get a string that describes the content-type of the media
119: * that the source is providing.
120: *
121: * @return The name that describes the media content.
122: * Returns <code>null</code> if the content is unknown.
123: * @exception IllegalStateException Thrown if the source is
124: * not connected.
125: */
126: public abstract String getContentType();
127:
128: /**
129: * Open a connection to the source described by
130: * the locator and initiate communication.
131: *
132: * @exception IOException Thrown if there are IO problems
133: * when <CODE>connect</CODE> is called.
134: * @exception SecurityException Thrown if the caller does not
135: * have security permission to call <code>connect</code>.
136: */
137: public abstract void connect() throws IOException;
138:
139: /**
140: * Close the connection to the source described by the locator
141: * and free resources used to maintain the connection.
142: * <p>
143: * If no resources are in use, <CODE>disconnect</CODE> is ignored.
144: * If <CODE>stop</CODE> hasn't already been called,
145: * calling <CODE>disconnect</CODE> implies a stop.
146: *
147: */
148: public abstract void disconnect();
149:
150: /**
151: * Initiate data-transfer. The <CODE>start</CODE> method must be
152: * called before data is available for reading.
153: *
154: * @exception IllegalStateException Thrown if the
155: * <code>DataSource</code> is not connected.
156: * @exception IOException Thrown if the <code>DataSource</code>
157: * cannot be started due to some IO problems.
158: * @exception SecurityException Thrown if the caller does not
159: * have security permission to call <code>start</code>.
160: */
161: public abstract void start() throws IOException;
162:
163: /**
164: * Stop the data-transfer.
165: * If the <code>DataSource</code> has not been connected and started,
166: * <CODE>stop</CODE> is ignored.
167: *
168: * @exception IOException Thrown if the <code>DataSource</code>
169: * cannot be stopped due to some IO problems.
170: */
171: public abstract void stop() throws IOException;
172:
173: /**
174: * Get the collection of streams that this source
175: * manages. The collection of streams is entirely
176: * content dependent. The MIME type of this
177: * <CODE>DataSource</CODE> provides the only indication of
178: * what streams may be available on this connection.
179: *
180: * @return The collection of streams for this source.
181: * @exception IllegalStateException Thrown if the source
182: * is not connected.
183: */
184: public abstract SourceStream[] getStreams();
185:
186: // These two methods are declared here (Controllable interface)
187: // because of a feature in KVM/VM when code is compiled with JDK 1.4
188: // Need to declare these abstract
189:
190: public abstract Control[] getControls();
191:
192: public abstract Control getControl(String controlType);
193:
194: }
|