Package com.tagtraum.beatunes.library

Interface MediaLibrary

    • Method Detail

      • getImplementation

        <T> T getImplementation​(Class<T> klass)

      • setRecoveryFlag

        void setRecoveryFlag()
        Call this method before init() in order to force recovery of the database that will be opened upon calling init(). The flag will be reset automatically, once a database recovery was attempted.

      • isForceRecovery

        boolean isForceRecovery()
        Is the recovery flag set?
        Returns:
        true or false

      • init

        void init()
        Initializes this component and its sub-components.

      • shutdown

        void shutdown()
       throws ShutdownVetoException
        Shuts down this component and its sub-components.
        Throws:
        ShutdownVetoException - if this component wants to veto the shutdown. This exception is not guaranteed to be honored, i.e. a calling component may simply ignore it

      • getGenreIRILookupService

        GenreIRILookupService getGenreIRILookupService()
        Returns current genre IRI lookup service.
        Returns:
        service

      • getTunesExecutor

        ExecutorService getTunesExecutor()
        Returns en executor service that should be used for any write access to ITunes related tasks. This takes care of synchronizing your access as well as using the correct thread.

        Typically when working with AudioSong objects, synchronization happens behind the scenes, so you don't have to use this service. However, there may be situations in which you want to access a Track directly. If you intend to write, you should use this executor.

        The service is managed by the application, i.e. you cannot terminate or shut it down.

        Returns:
        executor service
        See Also:
        TunesUtilities.getExecutorService()

      • getAudioMetaDataExecutor

        ExecutorService getAudioMetaDataExecutor()
        Returns en executor service that should be used for any write access to AudioMetaData related tasks. This takes care of synchronizing your access as well as using the correct thread.

        Typically when working with AudioSong objects, synchronization happens behind the scenes, so you don't have to use this service. However, there may be situations in which you want to access a AudioMetaData directly. If you intend to write, you should use this executor.

        The service is managed by the application, i.e. you cannot terminate or shut it down.

        Returns:
        executor service
        See Also:
        AudioMetaData.getExecutorService()

      • smuggle

        <V> V smuggle​(Callable<V> callable)
       throws Exception
        Smuggles read-only calls to the getTunesExecutor() even when it's blocked.
        Type Parameters:
        V - return type
        Parameters:
        callable - callable
        Returns:
        return value, may be null
        Throws:
        Exception

      • getLock

        ReentrantLock getLock​(Long songId)
        Provides a lock object for a song id.
        Parameters:
        songId - song id
        Returns:
        exclusive, reentrant lock

      • lock

        Lock lock​(Long songId)
        Provides a locked lock for a song id.
        Parameters:
        songId - song id
        Returns:
        exclusive, reentrant lock

      • getTunes

        ITunes getTunes()
        Returns the currently associated audio player, probably iTunes.
        Returns:
        audio player

      • isNewDatabase

        boolean isNewDatabase()

      • setNewDatabase

        void setNewDatabase​(boolean newDatabase)

      • countSongs

        int countSongs()
        Number of songs in the library.
        Returns:
        number of songs in the library.

      • countSongsWithPropertyValue

        int countSongsWithPropertyValue​(String propertyName,
                                Object propertyValue)
        Count all songs with a property equal to the given value.
        Parameters:
        propertyName - name of a property
        propertyValue - value of a property
        Returns:
        list of songs whose property has the required value

      • getSongsWithProperties

        List<AudioSong> getSongsWithProperties​(Map<String,​Object> properties)
        Get all song ids for songs that match all given properties.
        Parameters:
        properties - name-value pairs
        Returns:
        list of songs whose properties have the required values

      • getSongsWithoutProperties

        List<AudioSong> getSongsWithoutProperties​(Map<String,​Object> properties)
        Get all songs without properties equal to the given value.
        Parameters:
        properties - name-value pairs
        Returns:
        list of song whose properties do not the given values

      • getSongIdsWithProperties

        List<Long> getSongIdsWithProperties​(Map<String,​Object> properties)
        Get all song ids for songs that match all given properties. All key value pairs are implicitly connected using the AND operator.
        Parameters:
        properties - name-value pairs
        Returns:
        list of song ids whose properties have the required value

      • getSongIdsWithoutProperties

        List<Long> getSongIdsWithoutProperties​(Map<String,​Object> properties)
        Get all song ids for songs that match none of the given properties. All key value pairs are implicitly connected using the AND operator.
        Parameters:
        properties - name-value pairs
        Returns:
        list of song ids whose properties have the required value

      • getSongsWithPropertiesLike

        List<AudioSong> getSongsWithPropertiesLike​(Map<String,​Object> properties)
        Get all songs with a properties that are like the given properties.
        Parameters:
        properties - name-value pairs
        Returns:
        list of songs whose string property contains the given value

      • getSongIdsWithPropertiesLike

        List<Long> getSongIdsWithPropertiesLike​(Map<String,​Object> properties)
        Get all song ids of songs with a properties that are like the given properties.
        Parameters:
        properties - name-value pairs
        Returns:
        list of song ids whose string property contains the given value

      • getSongIdsWithPropertiesILike

        List<Long> getSongIdsWithPropertiesILike​(Map<String,​Object> properties)
        Get all song ids of songs with a properties that are ilike the given properties (case-insensitive).
        Parameters:
        properties - name-value pairs
        Returns:
        list of song ids whose string property contains the given value

      • getSongs

        Iterable<AudioSong> getSongs()
        Returns an Iterable that can be used to iterate over all songs. Shortcut for PlayList.getSongs() called on the library playlist (getLibrary()). Note, that the Iterable may be a List, which would expose other, non-sequential means of accessing the content.
        Returns:
        an object from which one can get an iterator

      • getSongs

        Iterable<AudioSong> getSongs​(Collection<Long> ids)
        Returns an Iterable that can be used to iterate over the specified songs.
        Parameters:
        ids - collection of ids
        Returns:
        an object from which one can get an iterator

      • getSongIds

        List<Long> getSongIds()
        Returns an Iterable that can be used to iterate over all song ids.
        Returns:
        an object from which one can get an iterator

      • getSongIds

        Set<Long> getSongIds​(PlayList.Kind... kinds)
        Returns all ids that are in the given set of PlayList.Kinds.
        Parameters:
        kinds - kind
        Returns:
        set of ids

      • getSong

        AudioSong getSong​(Long id)
        Gets a Song, given its id (Song.getId().
        Parameters:
        id - id
        Returns:
        song or null, if not found

      • fetchCollections

        AudioSong fetchCollections​(AudioSong song)
        Loads dependent collections that otherwise wouldn't have been loaded. Default impl. does nothing.
        Parameters:
        song - song to 'complete'
        Returns:
        song complete with associated collections

      • getGenres

        List<String> getGenres()
        Returns:
        unsorted list of all non-null genre names.

      • getSongPropertyValues

        <T> List<T> getSongPropertyValues​(String propertyName)
        All possible values for a given property.
        Parameters:
        propertyName - property
        Returns:
        values for a given property

      • getSongPropertyValues

        <T> List<T> getSongPropertyValues​(String propertyName,
                                  List<T> valueList)
        All possible values for a given property.
        Parameters:
        propertyName - property
        valueList - list that this method will add the results to. Before the results are added, the list is cleared.
        Returns:
        values for a given property

      • getSongPropertyValues

        <T> List<T> getSongPropertyValues​(String propertyName,
                                  String restrictionPropertyName,
                                  Object restrictionPropertyValue)
        Gets all property values of property propertyName for songs with restrictionPropertyName equaling restrictionPropertyValue.
        Parameters:
        propertyName - properties whose values are going to be returned
        restrictionPropertyName - property that is used to select the return set
        restrictionPropertyValue - property value that is used to select the return set
        Returns:
        values of propertyName

      • getDuplicateTitles

        List<String> getDuplicateTitles()
        Returns a list of titles that have exact duplicates.
        Returns:
        list of duplicate titles
        See Also:
        getSimilarTitles()

      • getDuplicateTrackIds

        List<String> getDuplicateTrackIds()
        Returns a list of track ids that correspond to more than one song.
        Returns:
        list of duplicate ids
        See Also:
        getSimilarTitles()

      • getAcousticallyIdenticalSongIds

        Set<Set<Long>> getAcousticallyIdenticalSongIds​(Set<Long> ids,
                                               int maxSubprintMatchAttempts)
        Returns a collection of sets that each contain song ids of acoustically "identical" songs. Only songs that have fingerprints (see AudioSong.setFingerprint(byte[])) can be found.
        Parameters:
        ids - ids of the the songs to find duplicates for
        maxSubprintMatchAttempts - maximum number of attempts to match a subprint. Negative values cause an exhaustive search (longer runtime). The default value used in getAcousticallyIdenticalSongIds() is 15.
        Returns:
        set of id sets
        See Also:
        getAcousticallyIdenticalSongIds()

      • getSimilarTitles

        Collection<Set<Long>> getSimilarTitles()
        Returns a collection of id sets that point to songs with similar or identical titles.
        Returns:
        collection of id sets
        See Also:
        getDuplicateTitles()

      • getPlayLists

        List<PlayList> getPlayLists()
        List of all playlists.
        Returns:
        list of all playlists in the library

      • getPlayList

        PlayList getPlayList​(long playListPersistentId)
        Get a PlayList for an id.
        Parameters:
        playListPersistentId - persistent id
        Returns:
        the playlist corresponding to the id or null, if it does not exist

      • createPlayList

        PlayList createPlayList​(Long parentId,
                        String name)
        Creates a new PlayList at a specific location.
        Parameters:
        parentId - persistent id of the parent, i.e. the location of the playlist to newly create
        name - name
        Returns:
        new playlist object.

      • createPlayList

        PlayList createPlayList​(String name)
        Creates a new PlayList under the Music playlist/folder.
        Parameters:
        name - name
        Returns:
        new playlist object.

      • createFolder

        PlayList createFolder​(Long parentId)
        Creates a new folder at a specific location.
        Parameters:
        parentId - persistent id of the parent, i.e. the location of the folder to newly create
        Returns:
        new folder object.

      • createFolder

        PlayList createFolder()
        Creates a new folder under the Music playlist/folder.
        Returns:
        new folder object.

      • createPlayList

        PlayList createPlayList​(Long id,
                        Long parentId,
                        String name,
                        boolean folder)
        Creates a new PlayList object with the given name and id.
        Parameters:
        id - persistentId
        parentId - parent playlist persistent id - may be null, if there is no parent
        name - name
        folder - is folder
        Returns:
        a new persistent playlist

      • getAlbum

        @Deprecated
Album getAlbum​(Album.Key key)
        Deprecated.
        Returns an album. The songs contained in this album are not properly wrapped. Writing to them most likely does not work as expected.
        Parameters:
        key - album key, interpreted case-insensitively
        Returns:
        album
        See Also:
        getAlbumSongs(String, String)

      • getAlbumSongIds

        List<Long> getAlbumSongIds​(String album,
                           String artist)
        Returns a list of song ids for songs specified by the given album and artist. At least on of the two parameters must be a non-empty string. The lookup is case-sensitive. To find valid album/artist combinations, check getAlbumKeys().
        Parameters:
        album - album
        artist - artist or album artist
        Returns:
        list of ids
        See Also:
        getAlbumSongs(String, String), getAlbumKeys()

      • getAlbumSongs

        List<AudioSong> getAlbumSongs​(String album,
                              String artist)
        Returns a list of songs specified by the given album and artist. At least one of the two parameters must be a non-empty string. The lookup is case-sensitive. To find valid album/artist combinations, check getAlbumKeys().
        Parameters:
        album - album
        artist - artist or album artist
        Returns:
        list of songs
        See Also:
        getAlbumSongIds(String, String), getAlbumKeys()

      • getAlbumKeys

        Set<Album.Key> getAlbumKeys()
        Returns the set of all valid album keys. To qualify for the set, both an album and either an artist or an album artist must be set.
        Returns:
        album keys

      • countUnprotectedSongsAddedAfter

        int countUnprotectedSongsAddedAfter​(Date time)
        Counts unprotected songs added after a certain date.
        Parameters:
        time - time
        Returns:
        count

      • getUnprotectedSongsAddedAfter

        List<AudioSong> getUnprotectedSongsAddedAfter​(Date time)
        Return unprotected songs added after a certain date.
        Parameters:
        time - time
        Returns:
        songs, at most 1000.

      • getPopularTagCollection

        TagCollection getPopularTagCollection​(int numberOfTags)
        Returns the TagCollection for the X most common tags.
        Parameters:
        numberOfTags - max number of tags to return
        Returns:
        tag collection for strongest tags in the library

      • getTagCollection

        TagCollection getTagCollection()
        Returns the TagCollection for the entire library.
        Returns:
        tag collection for the library

      • store

        void store​(PlayList playList)
        Stores a playlist in the beaTunes database.
        Parameters:
        playList - playlist to save

      • store

        void store​(AudioSong song)

        Stores a song in the beaTunes database.

        The write-process is asynchronous, i.e. this method may return before the songs has actually been written.

        Parameters:
        song - song to save

      • store

        void store​(AudioSong song,
           String changedProperty)

        Stores a song in the beaTunes database and clears any sortorder caches in the playlist objects this song might be in, if the playlist is sorted by the changed property.

        The write-process is asynchronous, i.e. this method may return before the songs has actually been written.

        Parameters:
        song - song to save
        changedProperty - property that has been changed (may be null, if multiple properties have changed or the change is unknown)

      • store

        void store​(Iterable<AudioSong> songs)

        Stores a collection of songs in the beaTunes database.

        The write-process is asynchronous, i.e. this method may return before the songs has actually been written.

        Parameters:
        songs - songs to save

      • deletePlayList

        void deletePlayList​(long id)
        Deletes a playlist from the library.
        Parameters:
        id - id

      • getLastSynchronizationTimestamp

        long getLastSynchronizationTimestamp()
        Timestamp of last synchronization of the current library.
        Returns:
        timestamp or 0, if unknown

      • getPreviousToLastSynchronizationTimestamp

        long getPreviousToLastSynchronizationTimestamp()
        Timestamp of the previous to last synchronization of the current library.
        Returns:
        timestamp or 0, if unknown

      • setLibraryDescriptor

        void setLibraryDescriptor​(LibraryDescriptor libraryDescriptor)
        Sets the library descriptor.
        Parameters:
        libraryDescriptor - library descriptor

      • getApplicationVersion

        Version getApplicationVersion()
        Returns the iTunes application version as specified in the iTunes Music Library.xml.
        Returns:
        iTunes application version

      • getPersistentId

        Long getPersistentId()
        Returns the iTunes library persistent id as specified in the iTunes Music Library.xml.
        Returns:
        persistent library id as long

      • refresh

        void refresh​(boolean blockingCall,
             boolean manuallyInitiated,
             boolean full)
      throws IOException,
             ParserConfigurationException,
             SAXException
        Reloads all objects that are connected to the music library.
        Parameters:
        blockingCall - flag to indicate whether this call should return right away or not.
        manuallyInitiated - indicates whether this refresh was directly triggered by some user action
        full - flag indicating we should attempt a full synchronization (no shortcuts)
        Throws:
        IOException
        ParserConfigurationException
        SAXException

      • isSynchronizing

        boolean isSynchronizing()
        Indicates, whether we are currently synchronizing.
        Returns:
        true or false
        See Also:
        cancelSynchronization()

      • needsRefresh

        boolean needsRefresh()
              throws IOException
        Returns:
        true, if the library is based on an xml files and was changed. Or if we cannot determine, if a refresh is really necessary
        Throws:
        IOException

      • store

        void store​(MatchListInfo matchListInfo)
        Store the given info.
        Parameters:
        matchListInfo - match list info

      • isEmbedAudioMetaData

        boolean isEmbedAudioMetaData()
        Shall all data be embedded into the audio files, when writing?
        Returns:
        true or false

      • setEmbedAudioMetaData

        void setEmbedAudioMetaData​(boolean embedAudioMetaData)
        Shall all data be embedded into audio files or just those fields that are supported by iTunes.
        Parameters:
        embedAudioMetaData - embed

      • isForceAudioMetaDataWrites

        boolean isForceAudioMetaDataWrites()
        Shall new values always be written, even, if the old value seems to be identical? This can happen, when the internal database is out of sync with actual values in audio files or iTunes.
        Returns:
        true or false

      • setForceAudioMetaDataWrites

        void setForceAudioMetaDataWrites​(boolean force)
        Shall new values always be written, even, if the old value seems to be identical? This can happen, when the internal database is out of sync with actual values in audio files or iTunes.
        Parameters:
        force - force writing

      • setDatabaseDir

        void setDatabaseDir​(File databaseDir)

      • getDatabaseDir

        File getDatabaseDir()

      • deleteAllFingerprints

        void deleteAllFingerprints()
        Delete all fingerprints from the database to save disk space.

      • isSupportedPlayList

        boolean isSupportedPlayList​(PlayList.Kind kind)
        Indicates whether a distinguished kind of PlayList is supported.
        Parameters:
        kind - kind
        Returns:
        true or false

      • addPropertyChangeListener

        void addPropertyChangeListener​(PropertyChangeListener propertyChangeListener)

      • addPlayListPropertyChangeListener

        void addPlayListPropertyChangeListener​(PropertyChangeListener propertyChangeListener)
        Lets you register a listener that receives events when a playlist property is changed. Unlike listeners bound to individual, transient playlist objects, this registration is permanent as long as this library is available.
        Parameters:
        propertyChangeListener - listener

      • addPlayListPropertyChangeListener

        void addPlayListPropertyChangeListener​(String property,
                                       PropertyChangeListener propertyChangeListener)
        Lets you register a listener that receives events when a playlist property is changed. Unlike listeners bound to individual, transient playlist objects, this registration is permanent as long as this library is available.
        Parameters:
        propertyChangeListener - listener
        property - property

      • removePlayListPropertyChangeListener

        void removePlayListPropertyChangeListener​(PropertyChangeListener propertyChangeListener)

      • removePlayListPropertyChangeListener

        void removePlayListPropertyChangeListener​(String property,
                                          PropertyChangeListener propertyChangeListener)

      • removePropertyChangeListener

        void removePropertyChangeListener​(PropertyChangeListener propertyChangeListener)

      • removePlayListDataListener

        void removePlayListDataListener​(ListDataListener l)