Java tutorial
/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.media; import android.graphics.Bitmap; import android.media.session.MediaSession; import android.os.Bundle; import android.os.Parcelable; import android.util.Log; import android.util.SparseIntArray; /** * An abstract class for editing and storing metadata that can be published by * {@link RemoteControlClient}. See the {@link RemoteControlClient#editMetadata(boolean)} * method to instantiate a {@link RemoteControlClient.MetadataEditor} object. * * @deprecated Use {@link MediaMetadata} instead together with {@link MediaSession}. */ @Deprecated public abstract class MediaMetadataEditor { private final static String TAG = "MediaMetadataEditor"; /** * @hide */ protected MediaMetadataEditor() { } // Public keys for metadata used by RemoteControlClient and RemoteController. // Note that these keys are defined here, and not in MediaMetadataRetriever // because they are not supported by the MediaMetadataRetriever features. /** * The metadata key for the content artwork / album art. */ public final static int BITMAP_KEY_ARTWORK = RemoteControlClient.MetadataEditor.BITMAP_KEY_ARTWORK; /** * The metadata key for the content's average rating, not the user's rating. * The value associated with this key is a {@link Rating} instance. * @see #RATING_KEY_BY_USER */ public final static int RATING_KEY_BY_OTHERS = 101; /** * The metadata key for the content's user rating. * The value associated with this key is a {@link Rating} instance. * This key can be flagged as "editable" (with {@link #addEditableKey(int)}) to enable * receiving user rating values through the * {@link android.media.RemoteControlClient.OnMetadataUpdateListener} interface. */ public final static int RATING_KEY_BY_USER = 0x10000001; /** * @hide * Editable key mask */ public final static int KEY_EDITABLE_MASK = 0x1FFFFFFF; /** * Applies all of the metadata changes that have been set since the MediaMetadataEditor instance * was created or since {@link #clear()} was called. Subclasses should synchronize on * {@code this} for thread safety. */ public abstract void apply(); /** * @hide * Mask of editable keys. */ protected long mEditableKeys; /** * @hide */ protected boolean mMetadataChanged = false; /** * @hide */ protected boolean mApplied = false; /** * @hide */ protected boolean mArtworkChanged = false; /** * @hide */ protected Bitmap mEditorArtwork; /** * @hide */ protected Bundle mEditorMetadata; /** * @hide */ protected MediaMetadata.Builder mMetadataBuilder; /** * Clears all the pending metadata changes set since the MediaMetadataEditor instance was * created or since this method was last called. * Note that clearing the metadata doesn't reset the editable keys * (use {@link #removeEditableKeys()} instead). */ public synchronized void clear() { if (mApplied) { Log.e(TAG, "Can't clear a previously applied MediaMetadataEditor"); return; } mEditorMetadata.clear(); mEditorArtwork = null; mMetadataBuilder = new MediaMetadata.Builder(); } /** * Flags the given key as being editable. * This should only be used by metadata publishers, such as {@link RemoteControlClient}, * which will declare the metadata field as eligible to be updated, with new values * received through the {@link RemoteControlClient.OnMetadataUpdateListener} interface. * @param key the type of metadata that can be edited. The supported key is * {@link #RATING_KEY_BY_USER}. */ public synchronized void addEditableKey(int key) { if (mApplied) { Log.e(TAG, "Can't change editable keys of a previously applied MetadataEditor"); return; } // only one editable key at the moment, so we're not wasting memory on an array // of editable keys to check the validity of the key, just hardcode the supported key. if (key == RATING_KEY_BY_USER) { mEditableKeys |= (KEY_EDITABLE_MASK & key); mMetadataChanged = true; } else { Log.e(TAG, "Metadata key " + key + " cannot be edited"); } } /** * Causes all metadata fields to be read-only. */ public synchronized void removeEditableKeys() { if (mApplied) { Log.e(TAG, "Can't remove all editable keys of a previously applied MetadataEditor"); return; } if (mEditableKeys != 0) { mEditableKeys = 0; mMetadataChanged = true; } } /** * Retrieves the keys flagged as editable. * @return null if there are no editable keys, or an array containing the keys. */ public synchronized int[] getEditableKeys() { // only one editable key supported here if (mEditableKeys == RATING_KEY_BY_USER) { int[] keys = { RATING_KEY_BY_USER }; return keys; } else { return null; } } /** * Adds textual information. * Note that none of the information added after {@link #apply()} has been called, * will be available to consumers of metadata stored by the MediaMetadataEditor. * @param key The identifier of a the metadata field to set. Valid values are * {@link android.media.MediaMetadataRetriever#METADATA_KEY_ALBUM}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_ALBUMARTIST}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_TITLE}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_ARTIST}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_AUTHOR}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_COMPILATION}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_COMPOSER}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_DATE}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_GENRE}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_WRITER}. * @param value The text for the given key, or {@code null} to signify there is no valid * information for the field. * @return Returns a reference to the same MediaMetadataEditor object, so you can chain put * calls together. */ public synchronized MediaMetadataEditor putString(int key, String value) throws IllegalArgumentException { if (mApplied) { Log.e(TAG, "Can't edit a previously applied MediaMetadataEditor"); return this; } if (METADATA_KEYS_TYPE.get(key, METADATA_TYPE_INVALID) != METADATA_TYPE_STRING) { throw (new IllegalArgumentException("Invalid type 'String' for key " + key)); } mEditorMetadata.putString(String.valueOf(key), value); mMetadataChanged = true; return this; } /** * Adds numerical information. * Note that none of the information added after {@link #apply()} has been called * will be available to consumers of metadata stored by the MediaMetadataEditor. * @param key the identifier of a the metadata field to set. Valid values are * {@link android.media.MediaMetadataRetriever#METADATA_KEY_CD_TRACK_NUMBER}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_DISC_NUMBER}, * {@link android.media.MediaMetadataRetriever#METADATA_KEY_DURATION} (with a value * expressed in milliseconds), * {@link android.media.MediaMetadataRetriever#METADATA_KEY_YEAR}. * @param value The long value for the given key * @return Returns a reference to the same MediaMetadataEditor object, so you can chain put * calls together. * @throws IllegalArgumentException */ public synchronized MediaMetadataEditor putLong(int key, long value) throws IllegalArgumentException { if (mApplied) { Log.e(TAG, "Can't edit a previously applied MediaMetadataEditor"); return this; } if (METADATA_KEYS_TYPE.get(key, METADATA_TYPE_INVALID) != METADATA_TYPE_LONG) { throw (new IllegalArgumentException("Invalid type 'long' for key " + key)); } mEditorMetadata.putLong(String.valueOf(key), value); mMetadataChanged = true; return this; } /** * Adds image. * @param key the identifier of the bitmap to set. The only valid value is * {@link #BITMAP_KEY_ARTWORK} * @param bitmap The bitmap for the artwork, or null if there isn't any. * @return Returns a reference to the same MediaMetadataEditor object, so you can chain put * calls together. * @throws IllegalArgumentException * @see android.graphics.Bitmap */ public synchronized MediaMetadataEditor putBitmap(int key, Bitmap bitmap) throws IllegalArgumentException { if (mApplied) { Log.e(TAG, "Can't edit a previously applied MediaMetadataEditor"); return this; } if (key != BITMAP_KEY_ARTWORK) { throw (new IllegalArgumentException("Invalid type 'Bitmap' for key " + key)); } mEditorArtwork = bitmap; mArtworkChanged = true; return this; } /** * Adds information stored as an instance. * Note that none of the information added after {@link #apply()} has been called * will be available to consumers of metadata stored by the MediaMetadataEditor. * @param key the identifier of a the metadata field to set. Valid keys for a: * <ul> * <li>{@link Bitmap} object are {@link #BITMAP_KEY_ARTWORK},</li> * <li>{@link String} object are the same as for {@link #putString(int, String)}</li> * <li>{@link Long} object are the same as for {@link #putLong(int, long)}</li> * <li>{@link Rating} object are {@link #RATING_KEY_BY_OTHERS} * and {@link #RATING_KEY_BY_USER}.</li> * </ul> * @param value the metadata to add. * @return Returns a reference to the same MediaMetadataEditor object, so you can chain put * calls together. * @throws IllegalArgumentException */ public synchronized MediaMetadataEditor putObject(int key, Object value) throws IllegalArgumentException { if (mApplied) { Log.e(TAG, "Can't edit a previously applied MediaMetadataEditor"); return this; } switch (METADATA_KEYS_TYPE.get(key, METADATA_TYPE_INVALID)) { case METADATA_TYPE_LONG: if (value instanceof Long) { return putLong(key, ((Long) value).longValue()); } else { throw (new IllegalArgumentException("Not a non-null Long for key " + key)); } case METADATA_TYPE_STRING: if ((value == null) || (value instanceof String)) { return putString(key, (String) value); } else { throw (new IllegalArgumentException("Not a String for key " + key)); } case METADATA_TYPE_RATING: mEditorMetadata.putParcelable(String.valueOf(key), (Parcelable) value); mMetadataChanged = true; break; case METADATA_TYPE_BITMAP: if ((value == null) || (value instanceof Bitmap)) { return putBitmap(key, (Bitmap) value); } else { throw (new IllegalArgumentException("Not a Bitmap for key " + key)); } default: throw (new IllegalArgumentException("Invalid key " + key)); } return this; } /** * Returns the long value for the key. * @param key one of the keys supported in {@link #putLong(int, long)} * @param defaultValue the value returned if the key is not present * @return the long value for the key, or the supplied default value if the key is not present * @throws IllegalArgumentException */ public synchronized long getLong(int key, long defaultValue) throws IllegalArgumentException { if (METADATA_KEYS_TYPE.get(key, METADATA_TYPE_INVALID) != METADATA_TYPE_LONG) { throw (new IllegalArgumentException("Invalid type 'long' for key " + key)); } return mEditorMetadata.getLong(String.valueOf(key), defaultValue); } /** * Returns the {@link String} value for the key. * @param key one of the keys supported in {@link #putString(int, String)} * @param defaultValue the value returned if the key is not present * @return the {@link String} value for the key, or the supplied default value if the key is * not present * @throws IllegalArgumentException */ public synchronized String getString(int key, String defaultValue) throws IllegalArgumentException { if (METADATA_KEYS_TYPE.get(key, METADATA_TYPE_INVALID) != METADATA_TYPE_STRING) { throw (new IllegalArgumentException("Invalid type 'String' for key " + key)); } return mEditorMetadata.getString(String.valueOf(key), defaultValue); } /** * Returns the {@link Bitmap} value for the key. * @param key the {@link #BITMAP_KEY_ARTWORK} key * @param defaultValue the value returned if the key is not present * @return the {@link Bitmap} value for the key, or the supplied default value if the key is * not present * @throws IllegalArgumentException */ public synchronized Bitmap getBitmap(int key, Bitmap defaultValue) throws IllegalArgumentException { if (key != BITMAP_KEY_ARTWORK) { throw (new IllegalArgumentException("Invalid type 'Bitmap' for key " + key)); } return (mEditorArtwork != null ? mEditorArtwork : defaultValue); } /** * Returns an object representation of the value for the key * @param key one of the keys supported in {@link #putObject(int, Object)} * @param defaultValue the value returned if the key is not present * @return the object for the key, as a {@link Long}, {@link Bitmap}, {@link String}, or * {@link Rating} depending on the key value, or the supplied default value if the key is * not present * @throws IllegalArgumentException */ public synchronized Object getObject(int key, Object defaultValue) throws IllegalArgumentException { switch (METADATA_KEYS_TYPE.get(key, METADATA_TYPE_INVALID)) { case METADATA_TYPE_LONG: if (mEditorMetadata.containsKey(String.valueOf(key))) { return mEditorMetadata.getLong(String.valueOf(key)); } else { return defaultValue; } case METADATA_TYPE_STRING: if (mEditorMetadata.containsKey(String.valueOf(key))) { return mEditorMetadata.getString(String.valueOf(key)); } else { return defaultValue; } case METADATA_TYPE_RATING: if (mEditorMetadata.containsKey(String.valueOf(key))) { return mEditorMetadata.getParcelable(String.valueOf(key)); } else { return defaultValue; } case METADATA_TYPE_BITMAP: // only one key for Bitmap supported, value is not stored in mEditorMetadata Bundle if (key == BITMAP_KEY_ARTWORK) { return (mEditorArtwork != null ? mEditorArtwork : defaultValue); } // else: fall through to invalid key handling default: throw (new IllegalArgumentException("Invalid key " + key)); } } /** * @hide */ protected static final int METADATA_TYPE_INVALID = -1; /** * @hide */ protected static final int METADATA_TYPE_LONG = 0; /** * @hide */ protected static final int METADATA_TYPE_STRING = 1; /** * @hide */ protected static final int METADATA_TYPE_BITMAP = 2; /** * @hide */ protected static final int METADATA_TYPE_RATING = 3; /** * @hide */ protected static final SparseIntArray METADATA_KEYS_TYPE; static { METADATA_KEYS_TYPE = new SparseIntArray(17); // NOTE: if adding to the list below, make sure you increment the array initialization size // keys with long values METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_CD_TRACK_NUMBER, METADATA_TYPE_LONG); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_DISC_NUMBER, METADATA_TYPE_LONG); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_DURATION, METADATA_TYPE_LONG); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_YEAR, METADATA_TYPE_LONG); // keys with String values METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_ALBUM, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_ALBUMARTIST, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_TITLE, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_ARTIST, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_AUTHOR, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_COMPILATION, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_COMPOSER, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_DATE, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_GENRE, METADATA_TYPE_STRING); METADATA_KEYS_TYPE.put(MediaMetadataRetriever.METADATA_KEY_WRITER, METADATA_TYPE_STRING); // keys with Bitmap values METADATA_KEYS_TYPE.put(BITMAP_KEY_ARTWORK, METADATA_TYPE_BITMAP); // keys with Rating values METADATA_KEYS_TYPE.put(RATING_KEY_BY_OTHERS, METADATA_TYPE_RATING); METADATA_KEYS_TYPE.put(RATING_KEY_BY_USER, METADATA_TYPE_RATING); } }