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.control;
027:
028: import javax.microedition.media.MediaException;
029:
030: /**
031: * <code>MetaDataControl</code> is used to retrieve metadata information
032: * included within the media streams. A <code>MetaDataControl</code>
033: * object recognizes and stores metadata and provides XML-like accessor
034: * methods to retrieve this information.
035: * <br>
036: * Predefined keys are provided to refer to commonly used metadata fields
037: * (title, copyright, data, author).
038: */
039: public interface MetaDataControl extends
040: javax.microedition.media.Control {
041:
042: /**
043: * Default key for AUTHOR information.
044: * <p>
045: * Value "author" is assigned to <code>AUTHOR_KEY</code>.
046: */
047: String AUTHOR_KEY = "author";
048:
049: /**
050: * Default key for COPYRIGHT information.
051: * <p>
052: * Value "copyright" is assigned to <code>COPYRIGHT_KEY</code>.
053: */
054: String COPYRIGHT_KEY = "copyright";
055:
056: /**
057: * Default key for DATE information.
058: * <p>
059: * Value "date" is assigned to <code>DATE_KEY</code>.
060: */
061: String DATE_KEY = "date";
062:
063: /**
064: * Default key for TITLE information.
065: * <p>
066: * Value "title" is assigned to <code>TITLE_KEY</code>.
067: */
068: String TITLE_KEY = "title";
069:
070: /**
071: * Return the list of keys for the available metadata values.
072: * The returned array must be an array with at least one
073: * key.
074: *
075: * @return The list of keys for the available metadata values.
076: */
077: String[] getKeys();
078:
079: /**
080: * Retrieve the value found in the metadata associated with the
081: * given key. Only keys obtained from <code>getKeys</code>
082: * are valid and can be used to retrieve metadata values.
083: * If <code>null</code> or an invalid key is used, an
084: * <code>IllegalArgumentException</code> will be thrown.
085: * <p>
086: * Some keys are valid but the associated metadata may not
087: * be available before a certain portion of the media is
088: * played. For example, some streaming media types may
089: * contain metadata that's stored at the end of the file.
090: * As a result, the metadata may not be available
091: * until the playback reaches the end of media. When
092: * that happens, calling <code>getKeyValues</code> with
093: * those keys will return <code>null</code> before the
094: * data is available. However, when the playback reaches
095: * the end of media, all metadata values must be
096: * made available.
097: *
098: * @param key a key to retrieve the value.
099: * @return the value of the key or null if the given key is valid but
100: * the value is not yet available.
101: * @exception IllegalArgumentException Thrown if the given key is
102: * <code>null</code> or invalid.
103: */
104: String getKeyValue(String key);
105: }
|