Interface PlayList

    • Method Detail

      • getImplementation

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

        PlayList objects are sometimes implemented by an object that acts as a facade to other objects. For example, this could be a proxy for an AppleScript iTunes object or a persistent object that is stored in a local database via Hibernate. While normal calls to an object implementing this interface are routed according to some internal logic, using one of the actual implementation classes allows you precise control over what your call does.

        Note to plugin developers: It is hardly ever a good idea to exercise this control, unless you know exactly what you are doing. :-)

        Type Parameters:
        T - implementation class
        Parameters:
        klass - class implementing PlayList
        Returns:
        object of the desired type or null, if such an object is not available
        See Also:
        AudioSong.getImplementation(Class)
      • removePropertyChangeListener

        void removePropertyChangeListener​(PropertyChangeListener propertyChangeListener)
        Remove a listener.
        Parameters:
        propertyChangeListener - listener
      • addPropertyChangeListener

        void addPropertyChangeListener​(PropertyChangeListener propertyChangeListener)
        Add a listener.
        Parameters:
        propertyChangeListener - listener
      • addPropertyChangeListener

        void addPropertyChangeListener​(String property,
                                       PropertyChangeListener propertyChangeListener)
        Add a listener for a specific property.
        Parameters:
        propertyChangeListener - listener
      • getId

        Long getId()
        This list's id.
        Returns:
        id
      • setId

        void setId​(Long id)
        Sets this list's id.
        Parameters:
        id - id
      • getParentId

        Long getParentId()
        If this is a sub-folder/playlist, this returns the parent id.
        Returns:
        id
      • setParentId

        void setParentId​(Long parentId)
        Sets the parent id.
        Parameters:
        parentId - id
      • getSpecialPlayListInfoId

        Long getSpecialPlayListInfoId()
      • setSpecialPlayListInfo

        void setSpecialPlayListInfo​(SpecialPlayListInfo specialPlayListInfo)
      • isSpecialPlayList

        boolean isSpecialPlayList()
      • getDistinguishedKind

        PlayList.Kind getDistinguishedKind()
        Returns the special kind of this playlist.
        Returns:
        null if unknown
      • setDistinguishedKind

        void setDistinguishedKind​(PlayList.Kind distinguishedKind)
        Allows setting of a special song type, like PlayList.Kind.PODCASTS.
        Parameters:
        distinguishedKind - kind
      • setMovies

        void setMovies​(boolean movies)
      • setChildPlayLists

        void setChildPlayLists​(List<PlayList> childPlayLists)
      • getParentPlayList

        PlayList getParentPlayList()
      • setParentPlayList

        void setParentPlayList​(PlayList parentPlayList)
      • getPlayListPath

        PlayList[] getPlayListPath()
        Returns path leading to this playlist and ending with it. I.e., the path has at least the length 1.
        Returns:
        path of playlists
      • setName

        void setName​(String name)
      • getDescription

        String getDescription()
      • setDescription

        void setDescription​(String description)
      • isMaster

        boolean isMaster()
        Indicates whether this playlist is a master playlist. E.g. the (invisible list) Library is typically the master playlist.
        Returns:
        true or false
        See Also:
        isLibrary()
      • setMaster

        void setMaster​(boolean master)
      • isLibrary

        boolean isLibrary()
        Indicates that this is a library playlist, meaning one of the top level library views (e.g. Music, AudioBooks, etc.).
        Returns:
        true or false
        See Also:
        isMaster()
      • getGeniusTrackID

        int getGeniusTrackID()
      • setGeniusTrackID

        void setGeniusTrackID​(int geniusTrackID)
      • isGeniusPlaylist

        boolean isGeniusPlaylist()
      • isAllItems

        boolean isAllItems()
      • setAllItems

        void setAllItems​(boolean allItems)
      • getSmartInfo

        String getSmartInfo()
      • setSmartInfo

        void setSmartInfo​(String smartInfo)
      • isSmartPlaylist

        boolean isSmartPlaylist()
      • getSmartCriteria

        String getSmartCriteria()
      • setSmartCriteria

        void setSmartCriteria​(String smartCriteria)
      • isVideos

        @Deprecated
        boolean isVideos()
        Deprecated.
        iTunes 6 playlist attribute.
        Returns:
        true or false
      • setVideos

        @Deprecated
        void setVideos​(boolean videos)
        Deprecated.
      • getFilteredSongIds

        List<Long> getFilteredSongIds()
        Returns song ids from this playlist, both sorted and filtered.
        Returns:
        song ids
      • getSongIds

        List<Long> getSongIds()
        Returns song ids from this playlist, neither sorted not filtered.
        Returns:
        song ids
      • getIndexedSongIds

        IndexedId[] getIndexedSongIds()
        A complete list of sorted ids along with their natural order indices (via IndexedId.getIndex()). Natural indices of filtered out objects are flipped: -(index+1)
        Returns:
        a complete list of persistent ids along with their natural indices
      • getSongs

        Iterable<AudioSong> getSongs()
        Returns songs from this playlist, neither sorted nor filtered.
        Returns:
        songs
      • getSongsOrderedBy

        default Iterable<AudioSong> getSongsOrderedBy​(String sortProperty)
        Returns an Iterable that can be used to iterate over all songs.
        Parameters:
        sortProperty - property name to order by
        Returns:
        an object from which one can get an iterator
      • getSongsOrderedBy

        Iterable<AudioSong> getSongsOrderedBy​(String sortProperty,
                                              PlayList.SortDirection direction)
        Returns songs from this playlist, sorted by the given property.
        Parameters:
        sortProperty - property
        direction - direction
        Returns:
        songs
      • getSongsOrderedBy

        Iterable<AudioSong> getSongsOrderedBy​(String sortProperty,
                                              PlayList.SortDirection direction,
                                              int limit)
        Returns songs from this playlist, sorted by the given property.
        Parameters:
        sortProperty - property
        direction - direction
        limit - max number of songs to return
        Returns:
        songs
      • getSongs

        List<AudioSong> getSongs​(Collection<? extends SongFilter> filters,
                                 int limit)
        Returns songs from this playlist, filtered with the given filters.
        Parameters:
        filters - filters
        limit - limit, -1 for no limit
        Returns:
        songs
        See Also:
        getSongIds(Set)
      • getFilteredSongs

        Iterable<AudioSong> getFilteredSongs()
        Returns songs from this playlist, both sorted and filtered.
        Returns:
        songs
      • filteredListIterator

        PlayListIterator<AudioSong> filteredListIterator​(int startIndex)
        Creates a dynamically updated iterator for this playlist. This iterator will adjust to sort/filter changes to the underlying playlist.
        The iterator does not support mutable operations.
        Parameters:
        startIndex - index to start iterating from, first call to ListIterator.next() or ListIterator.previous() will produce the song at the given index
        Returns:
        read-only, dynamically adjusting list iterator
      • countSongs

        int countSongs​(Collection<? extends SongFilter> filters)
        Returns song count from this playlist, filtered with the given filters.
        Returns:
        song count
        See Also:
        getSongIds(Set)
      • setSongs

        void setSongs​(List<AudioSong> songs)
        Removes all songs from this playlist and replaces them with the given songs. If the songs are not in your library yet, corresponding entries in the database are created.
        Parameters:
        songs - songs
      • setSongIds

        void setSongIds​(List<Long> songIds)
        Removes all songs from this playlist and replaces them with song connected to the given ids.
        Parameters:
        songIds - song ids
      • addSongIds

        void addSongIds​(List<Long> songIds)
        Adds the songs referenced by the given ids to this playlist.
        Parameters:
        songIds - song ids
      • addSongs

        void addSongs​(int filteredIndex,
                      String... locations)
        Adds songs to the playlist using only their locations.
        Depending on the library implementation, the insert index may be ignored. If it is ignored, the songs will be appended at the end (this is the case for iTunes libraries).
        Parameters:
        filteredIndex - filtered index, set this to -1, if you just want to add the song to the end
        locations - file or URL
        See Also:
        AudioSongLocation.getLocation()
      • addSongs

        void addSongs​(int filteredIndex,
                      List<AudioSong> songs)
        Adds the given songs at the given (filtered) index.
        Parameters:
        filteredIndex - filtered index
        songs - songs
      • addSongIds

        void addSongIds​(int filteredIndex,
                        List<Long> songIds)
        Adds the given songs at the given (filtered) index.
        Parameters:
        filteredIndex - filtered index
        songIds - songs
      • moveSongs

        int moveSongs​(int[] fromIndices,
                      int toIndex)
        Moves songs. All indices have to be filtered.
        Parameters:
        fromIndices - indices to move songs from
        toIndex - index to move the songs to
        Returns:
        new lead index of the moved songs
      • unfilteredIndices

        int[] unfilteredIndices​(int... filteredIndices)
        Returns the unfiltered indices for the given filtered (string, order) indices.
        Parameters:
        filteredIndices - filtered indices
        Returns:
        unfiltered equivalents
      • filteredIndices

        int[] filteredIndices​(int... unfilteredIndices)
        Returns the filtered indices (string, order) for the given unfiltered indices.
        Parameters:
        unfilteredIndices - unfiltered indices
        Returns:
        filtered equivalents or -1, if that does not exist, because the index was filtered out
      • indexOf

        int indexOf​(Long id)
        Returns the first index of the given song.
        Parameters:
        id - song id
        Returns:
        index or -1, if not found
      • indexOf

        default int indexOf​(AudioSong song)
        Returns the first index of the given song.
        Parameters:
        song - song
        Returns:
        index or -1, if not found
      • removeSongs

        boolean removeSongs​(int... filteredIndex)
        Removes the song with the given (filtered) index from the playlist. If this is a library, the file is also deleted.
        Parameters:
        filteredIndex - filtered indices
        Returns:
        true, if the system was able to find and remove the given song
      • removeSongs

        default boolean removeSongs​(Collection<Long> ids)
        Removes the songs with the given ids from the list. If this is the library, the songs are also deleted.
        Parameters:
        ids - ids
        Returns:
        success
      • removeSongs

        boolean removeSongs​(Collection<Long> ids,
                            boolean completelyDeleteSong)
        Removes the songs with the given ids from the list.
        Parameters:
        completelyDeleteSong - if set to true, the song object itself is deleted and removed from all other lists as well
        ids - ids
        Returns:
        success
      • removeAllSongs

        void removeAllSongs()
        Removes all songs from this playlist.
      • getSong

        AudioSong getSong​(int index)
        Returns song from the given index, taking sorting and filtering into account. This method may return null even if a corresponding song exists, because it is loaded asynchronously.
        Use getIdAt(int), if you need a synchronous result.
        Parameters:
        index - index
        Returns:
        song or null, if not in the cache or the index is bad
        See Also:
        getIdAt(int)
      • getIdAt

        Long getIdAt​(int index)
        Returns id of the song at the given index, taking sorting and filtering into account. Other than getSong(int), this method always returns an id, if the index is valid.
        Parameters:
        index - index
        Returns:
        id or null, if the index it not valid
        See Also:
        getSong(int)
      • contains

        boolean contains​(Long id)
      • contains

        default boolean contains​(AudioSong song)
      • isFolder

        boolean isFolder()
      • isParentAFolder

        boolean isParentAFolder()
      • setFolder

        void setFolder​(boolean folder)
      • isUserPlaylist

        boolean isUserPlaylist()
        Indicates that the playlist is just a regular user playlist. Note that Matchlists are not considered regular user playlists.
        Returns:
        true or false.
      • setPurchasedMusic

        void setPurchasedMusic​(boolean purchasedMusic)
      • isItemsEditable

        boolean isItemsEditable()
        Are the contained items editable? E.g., items are not editable, if they are only available online, as the metadata of some stream or online database cannot be changed locally.
        Returns:
        true or false
      • canInsertItem

        boolean canInsertItem()
        Indicates whether we can insert items into this playlist.
        Returns:
        true or false, typically false for generated lists like "Music"
      • canAddItem

        boolean canAddItem()
        Indicates whether we can add items to this playlist.
        Returns:
        true or false, typically false for generated lists like "Music"
      • isEditable

        boolean isEditable()
        Is this playlist editable? Only playlists created by users are editable.
        Returns:
        true or false
      • getTotalTime

        long getTotalTime()
        Get time with filters applied.
        Returns:
        time
      • getUnfilteredTime

        long getUnfilteredTime()
        Get time without any filters applied.
        Returns:
        time
      • getFileSize

        long getFileSize()
        Get the sum of all file sizes (with filters applied).
        Returns:
        sum of file sizes
      • isAggregateDataAvailable

        boolean isAggregateDataAvailable()
        Indicates whether we currently have valid aggregate (total size, duration, etc.) data. If the data is not available, the asynchronous computation is triggered.
        Returns:
        true or false
      • getSortColumnProperty

        String getSortColumnProperty()
        Returns the name of the single property the playlist is sorted by. Note that for special properties like name this may not be the same properties as the ones we use for ORDER BY SQL clauses. But, it's the property that should be highlighted in a UI.
        Returns:
        column
      • setSortColumnProperty

        void setSortColumnProperty​(String property)
        Sets "visual/semantic" sort property.
        Parameters:
        property - name of the property that is marked as sorted-by in the UI
        See Also:
        getSortColumnProperty()
      • getSortProperty

        String getSortProperty​(int index)
        Actual sort property, used in ORDER BY SQL clauses.
        Parameters:
        index - index
        Returns:
        property or null
      • getSortProperties

        String[] getSortProperties()
        Actual sort properties, used in ORDER BY HQL/SQL clauses.
        Returns:
        sort properties
      • getSyncTempo

        com.tagtraum.audiokern.bpm.Tempo getSyncTempo()
        When set to a non-null value, Key values are displayed as if the song was played back at the given tempo. This has consequences for the sort order.
        Returns:
        sync tempo
        See Also:
        setSortProperties(String...)
      • setSyncTempo

        void setSyncTempo​(com.tagtraum.audiokern.bpm.Tempo syncTempo)
        When set to a non-null value, Key values are displayed as if the song was played back at the given tempo. This has consequences for the sort order.
        Specified by:
        setSyncTempo in interface SyncTempoAware
        Parameters:
        syncTempo - sync tempo
      • setSortProperties

        void setSortProperties​(String... properties)
        Sets sort properties.
        Parameters:
        properties - sort properties
      • setSortDirection

        void setSortDirection​(PlayList.SortDirection sortDirection)
        Sort direction.
        Parameters:
        sortDirection - sort direction
      • getSubstringFilter

        String getSubstringFilter()
        Current substring filter.
        Returns:
        filter string
      • setSubstringFilter

        void setSubstringFilter​(String substring,
                                PlayList.SubstringFilterProperty substringFilterProperty)
        Sets the filter and which property to filter in one swoop.
        Parameters:
        substring - filter string
        substringFilterProperty - property to filter