SageTV Platform
V9.0

sage.api
Class MediaNodeAPI

java.lang.Object
  extended by sage.api.MediaNodeAPI

public class MediaNodeAPI
extends java.lang.Object

Virtual content directory abstraction.


Constructor Summary
MediaNodeAPI()
           
 
Method Summary
 void AppendNodeFilter(sage.vfs.MediaNode MediaNode, java.lang.String Technique, boolean MatchPasses)
          Adds a filtering technique to used by the specified MediaNode hierarchy.
 sage.vfs.MediaNode CreateMediaNode(java.lang.String PrimaryLabel, java.lang.String SecondaryLabel, java.lang.Object Thumbnail, java.lang.Object Icon, java.lang.Object DataObject)
          Creates a static MediaNode that has no parents and no children.
 java.util.Collection GetAllNodeDescendants(sage.vfs.MediaNode MediaNode)
          Returns the data set that represents all the children under the specified MediaNode if that data set has already been realized.
 int GetChildrenCheckedCount(sage.vfs.MediaNode MediaNode, boolean State)
          Returns the number of children of the specified MediaNode that are in the specified checked state.
 java.util.Vector GetChildrenCheckedNodes(sage.vfs.MediaNode MediaNode, boolean State)
          Returns the children of the specified MediaNode that are in the specified checked state.
 sage.vfs.MediaNode GetMediaSource(java.lang.String Name)
          Retrieves a MediaNode which is the root of the specified 'Media Source'.
 sage.vfs.MediaNode GetMediaView(java.lang.String Name, java.lang.Object Data)
          Similar to the GetMediaSource API call; but the second argument allows specifying the actual data set to be used for the view.
 sage.vfs.MediaNode GetNodeChildAt(sage.vfs.MediaNode MediaNode, int Index)
          Returns the child of the specified MediaNode at the given index
 sage.vfs.MediaNode[] GetNodeChildren(sage.vfs.MediaNode MediaNode)
          Returns an array of the children of the specified MediaNode
 java.lang.Object GetNodeDataObject(sage.vfs.MediaNode MediaNode)
          Returns the Object that is wrapped by the specified MediaNode
 java.lang.String GetNodeDataType(sage.vfs.MediaNode MediaNode)
          Returns the type of the Object that is wrapped by the specified MediaNode
 java.lang.String GetNodeFilterTechnique(sage.vfs.MediaNode MediaNode, int FilterIndex)
          Returns the name of the current filtering technique used by the specified MediaNode hierarchy.
(package private)  java.lang.String GetNodeFullPath(sage.vfs.MediaNode MediaNode)
          Returns a string which represents the hierarchical path to this MediaNode.
 java.lang.Object GetNodeIcon(sage.vfs.MediaNode MediaNode)
          Returns the icon image associated with the specified MediaNode.
 int GetNodeNumChildren(sage.vfs.MediaNode MediaNode)
          Returns the number of children of the specified MediaNode
(package private)  int GetNodeNumFilters(sage.vfs.MediaNode MediaNode)
          Gets the number of filters that are currently set for the specified MediaNode.
 sage.vfs.MediaNode GetNodeParent(sage.vfs.MediaNode MediaNode)
          Returns the MediaNode parent of the specified MediaNode
 java.lang.String GetNodePrimaryLabel(sage.vfs.MediaNode MediaNode)
          Returns a string representation of the primary data associated with the specified MediaNode suitable for display in the UI.
 java.lang.String GetNodeProperty(sage.vfs.MediaNode MediaNode, java.lang.String PropertyName)
          Returns a specific property associated with this MediaNode.
 java.lang.String GetNodeSecondaryLabel(sage.vfs.MediaNode MediaNode)
          Returns a string representation of the secondary data associated with the specified MediaNode suitable for display in the UI.
 java.lang.String GetNodeSortTechnique(sage.vfs.MediaNode MediaNode)
          Returns the name of the current sorting technique used by the specified MediaNode hierarchy.
 java.lang.Object GetNodeThumbnail(sage.vfs.MediaNode MediaNode)
          Returns the thumbnail image associated with the specified MediaNode.
(package private)  java.lang.String GetNodeTypePath(sage.vfs.MediaNode MediaNode)
          Returns a string which represents the hierarchical path to this MediaNode with type information only.
 sage.vfs.MediaNode GetRelativeMediaSource(java.lang.String Name, java.lang.Object RelativeRoot)
          Creates a MediaNode view with a relative root for a specified media source.
 boolean IsMediaNodeObject(java.lang.Object Object)
          Returns true if the specified object is a MediaNode object.
 boolean IsNodeFilterMatching(sage.vfs.MediaNode MediaNode, int FilterIndex)
          Returns the match state of the current filtering technique used by the specified MediaNode hierarchy.
 boolean IsNodeFolder(sage.vfs.MediaNode MediaNode)
          Returns true if the specified MediaNode has children
 boolean IsNodeHierarchyRealized(sage.vfs.MediaNode MediaNode)
          Returns true if the entire set of data objects that back this MediaNode hierarchy has already been realized.
 boolean IsNodePlayable(sage.vfs.MediaNode MediaNode)
          Returns true if the Object that this MediaNode wraps is suitable for passing to the Watch API call.
 boolean IsNodeSortAscending(sage.vfs.MediaNode MediaNode)
          Returns true if the current sorting technique used by the specified MediaNode hierarchy is in ascending order, false otherwise
 boolean IsNodeVirtual(sage.vfs.MediaNode MediaNode)
          Returns true if the specified MediaNode doesn't wrap an actual data object; but just an abstraction of a hierarchy
 void RefreshNode(sage.vfs.MediaNode MediaNode)
          Refreshes the hierarchy associated with the specified MediaNode.
 void SetAllChildrenChecked(sage.vfs.MediaNode MediaNode, boolean State)
          Sets a flag on all the children of this MediaNode to indicate they are in the checked state.
 void SetNodeChecked(sage.vfs.MediaNode MediaNode, boolean State)
          Sets a flag on this MediaNode to indicate it is in the checked state.
 void SetNodeFilter(sage.vfs.MediaNode MediaNode, java.lang.String Technique, boolean MatchPasses)
          Sets the filtering techniques used by the specified MediaNode hierarchy.
 void SetNodeSort(sage.vfs.MediaNode MediaNode, java.lang.String Technique, boolean Ascending)
          Sets the sorting technique used by the specified MediaNode hierarchy.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MediaNodeAPI

public MediaNodeAPI()
Method Detail

GetMediaSource

public sage.vfs.MediaNode GetMediaSource(java.lang.String Name)
Retrieves a MediaNode which is the root of the specified 'Media Source'. All names are case insensitive. Valid names are: Filesystem - provides a view of the native filesystem VideoNavigator - provides various views of the imported videos MusicNavigator - provides various views of the imported music MusicVideosNavigator - provides various views of the imported videos with the 'music videos' category MoviesNavigator - provides various views of all content with the 'Movie' category or that are DVDs or BluRays TVNavigator - provides various views of recorded TV content
You can also use names that are "ContentByGrouping" or just "Content". Valid values for "Content" are: Clips - all video files with a duration under 10 mins (controlled by the property max_duration_to_be_a_clip) Music or ImportedMusic - all imported music files Videos or ImportedVideso - all imported video files Picture or Photos or ImportedPictures or ImportedPhotos - all imported picture files DVDs or ImportedDVDs - all imported DVDs BluRays or ImportedBluRays - all imported BluRays Movies - all videos or TV recordings with the 'Movie' category or that are DVDs or BluRays MusicVideos - all imported videos with the 'Music Video' category TV - all recorded TV content MediaFiles - all files in SageTV Compilations - all music files that are by 'Various Artist' MusicPlaylists - all music playlists VideoPlaylists - all video playlists
Valid values for "Grouping" are: Folder - grouped according to their relative import path Category or Genre - grouped by category, for music files they are then subgrouped by Artist and then Album Year - grouped by year, for music files they are subgrouped by Album Director - grouped by Director Actor - grouped by actors/actress Studio - grouped by the studio that produced the content if known Title - grouped by title Series - grouped by television series if known (SeriesInfo object) Album - grouped by album Artist - grouped by artist and then subgrouped by album Channel - grouped by channel

Parameters:
Name - the name of the media source
Returns:
a MediaNode which contains the hierarchy for the specified media source
Since:
7.0

GetMediaView

public sage.vfs.MediaNode GetMediaView(java.lang.String Name,
                                       java.lang.Object Data)
Similar to the GetMediaSource API call; but the second argument allows specifying the actual data set to be used for the view. The name describes the type of content or grouping just like in GetMediaSource. Can be used for presenting a subset of another view or for creating a MediaNode view of a fixed list of data such as a list of MediaFiles or Actors.

Parameters:
Name - the view name to use
Data - the dataset that defines the content in the view, can be a Collection, Object[] or a single object
Returns:
a MediaNode that represents the specified Data using the specified view Name
Since:
7.0

GetRelativeMediaSource

public sage.vfs.MediaNode GetRelativeMediaSource(java.lang.String Name,
                                                 java.lang.Object RelativeRoot)
Creates a MediaNode view with a relative root for a specified media source. This is currently only useable with the 'Filesystem' media source

Parameters:
Name - should be Filesystem; anything else will behave like the GetMediaSource API call
RelativeRoot - the subdirectory which should be the root of this view
Returns:
a MediaNode that represents the relative view of the specified media source
Since:
7.0

IsNodeFolder

public boolean IsNodeFolder(sage.vfs.MediaNode MediaNode)
Returns true if the specified MediaNode has children

Parameters:
MediaNode - the specified MediaNode
Returns:
true if the specified MediaNode has children, false otherwise
Since:
7.0

GetNodeChildren

public sage.vfs.MediaNode[] GetNodeChildren(sage.vfs.MediaNode MediaNode)
Returns an array of the children of the specified MediaNode

Parameters:
MediaNode - the specified MediaNode
Returns:
an array of the children of the specified MediaNode
Since:
7.0

GetNodeNumChildren

public int GetNodeNumChildren(sage.vfs.MediaNode MediaNode)
Returns the number of children of the specified MediaNode

Parameters:
MediaNode - the specified MediaNode
Returns:
the number of children of the specified MediaNode
Since:
7.0

GetNodeChildAt

public sage.vfs.MediaNode GetNodeChildAt(sage.vfs.MediaNode MediaNode,
                                         int Index)
Returns the child of the specified MediaNode at the given index

Parameters:
MediaNode - the specified MediaNode
Index - the index of the child to return (0-based)
Returns:
the child of the specified MediaNode at the given index
Since:
7.0

SetNodeSort

public void SetNodeSort(sage.vfs.MediaNode MediaNode,
                        java.lang.String Technique,
                        boolean Ascending)
Sets the sorting technique used by the specified MediaNode hierarchy. This effects all levels of the hierarchy. MediaNodes that are folders are always listed first when sorting. Some of the sorting techniques can also ignore 'the' as a prefix; this is controlled by the property "ui/ignore_the_when_sorting" which defaults to true. Valid sorting technique names are: Date, Size, Name (can ignore the), Filename, Track, Duration, Title (can ignore the), Artist (can ignore the), Album (can ignore the), Category, Year, Rating, Count, EpisodeName, EpisodeID, Rated, Runtime, Studio (can ignore the), Fullpath, OriginalAirDate, ChannelName, Intelligent

Parameters:
MediaNode - the specified MediaNode
Technique - the name of the sorting technique to use, case insensitive
Ascending - true if the sorting should occur in ascending order, false otherwise
Since:
7.0

GetNodeSortTechnique

public java.lang.String GetNodeSortTechnique(sage.vfs.MediaNode MediaNode)
Returns the name of the current sorting technique used by the specified MediaNode hierarchy.

Parameters:
MediaNode - the specified MediaNode
Returns:
the name of the current sorting technique used by the specified MediaNode hierarchy.
Since:
7.0

IsNodeSortAscending

public boolean IsNodeSortAscending(sage.vfs.MediaNode MediaNode)
Returns true if the current sorting technique used by the specified MediaNode hierarchy is in ascending order, false otherwise

Parameters:
MediaNode - the specified MediaNode
Returns:
true if the current sorting technique used by the specified MediaNode hierarchy is in ascending order, false otherwise
Since:
7.0

SetNodeFilter

public void SetNodeFilter(sage.vfs.MediaNode MediaNode,
                          java.lang.String Technique,
                          boolean MatchPasses)
Sets the filtering techniques used by the specified MediaNode hierarchy. This effects all levels of the hierarchy. Filters can either be inclusive or exclusive. This method will clear all other filters and set this as the only filter. Valid filtering technique names are: Directories, Pictures, Videos, Music, DVD, BluRay, TV, Watched, Archived, DontLike, Favorite, HDTV, ManualRecord, FirstRun, CompleteRecording

Parameters:
MediaNode - the specified MediaNode
Technique - the name of the filtering technique to use, case insensitive
MatchPasses - true if the items matching the filter should be retained, false if matching items should be removed
Since:
7.0

GetNodeNumFilters

int GetNodeNumFilters(sage.vfs.MediaNode MediaNode)
Gets the number of filters that are currently set for the specified MediaNode.

Parameters:
MediaNode - the specified MediaNode
Returns:
the number of filters that are currently set for the specified MediaNode.
Since:
7.0

GetNodeFilterTechnique

public java.lang.String GetNodeFilterTechnique(sage.vfs.MediaNode MediaNode,
                                               int FilterIndex)
Returns the name of the current filtering technique used by the specified MediaNode hierarchy. Since multiple filters can be set; an index must be specified to determine which one to get the technique of

Parameters:
MediaNode - the specified MediaNode
FilterIndex - the 0-based index of the filtering technique to retrieve
Returns:
the name of the current filtering technique used by the specified MediaNode hierarchy at the specified index, null if the index is out of bounds
Since:
7.0

IsNodeFilterMatching

public boolean IsNodeFilterMatching(sage.vfs.MediaNode MediaNode,
                                    int FilterIndex)
Returns the match state of the current filtering technique used by the specified MediaNode hierarchy. Since multiple filters can be set; an index must be specified to determine which one to get the matching state of

Parameters:
MediaNode - the specified MediaNode
FilterIndex - the 0-based index of the filtering match state to retrieve
Returns:
true if the current filtering technique used by the specified MediaNode hierarchy at the specified index is MatchPasses, false otherwise or if the index is out of bounds
Since:
7.0

AppendNodeFilter

public void AppendNodeFilter(sage.vfs.MediaNode MediaNode,
                             java.lang.String Technique,
                             boolean MatchPasses)
Adds a filtering technique to used by the specified MediaNode hierarchy. This effects all levels of the hierarchy. Filters can either be inclusive or exclusive. This method will not clear other filters that have been set. Valid filtering technique names are: Directories, Pictures, Videos, Music, DVD, BluRay, TV, Watched, Archived, DontLike, Favorite, HDTV, ManualRecord, FirstRun, CompleteRecording

Parameters:
MediaNode - the specified MediaNode
Technique - the name of the filtering technique to use, case insensitive
MatchPasses - true if the items matching the filter should be retained, false if matching items should be removed
Since:
7.0

IsNodeHierarchyRealized

public boolean IsNodeHierarchyRealized(sage.vfs.MediaNode MediaNode)
Returns true if the entire set of data objects that back this MediaNode hierarchy has already been realized. This will be true for fixed sets of data; but false for abstractions like the filesystem. When this is true the API call GetAllNodeDescendants will return a valid result.

Parameters:
MediaNode - the specified MediaNode
Returns:
true if the entire set of data objects that back this MediaNode hierarchy has already been realized, false otherwise
Since:
7.0

GetAllNodeDescendants

public java.util.Collection GetAllNodeDescendants(sage.vfs.MediaNode MediaNode)
Returns the data set that represents all the children under the specified MediaNode if that data set has already been realized.

Parameters:
MediaNode - the specified MediaNode
Returns:
a Collection which holds all of the resulting descendants of the specified Media Node; this Collection should NOT be modified
Since:
7.0

GetNodeIcon

public java.lang.Object GetNodeIcon(sage.vfs.MediaNode MediaNode)
Returns the icon image associated with the specified MediaNode. This is currently the same as GetNodeThumbnail.

Parameters:
MediaNode - the specified MediaNode
Returns:
an Object which represents the icon for this MediaNode; this may be a MetaImage or a resource path that can be used to load an image
Since:
7.0

GetNodeThumbnail

public java.lang.Object GetNodeThumbnail(sage.vfs.MediaNode MediaNode)
Returns the thumbnail image associated with the specified MediaNode.

Parameters:
MediaNode - the specified MediaNode
Returns:
an Object which represents the thumbnail for this MediaNode; this may be a MetaImage or a resource path that can be used to load an image
Since:
7.0

GetNodePrimaryLabel

public java.lang.String GetNodePrimaryLabel(sage.vfs.MediaNode MediaNode)
Returns a string representation of the primary data associated with the specified MediaNode suitable for display in the UI.

Parameters:
MediaNode - the specified MediaNode
Returns:
a string representation of the primary data associated with the specified MediaNode suitable for display in the UI
Since:
7.0

GetNodeSecondaryLabel

public java.lang.String GetNodeSecondaryLabel(sage.vfs.MediaNode MediaNode)
Returns a string representation of the secondary data associated with the specified MediaNode suitable for display in the UI. This will usually relate to whatever the current sorting technique is.

Parameters:
MediaNode - the specified MediaNode
Returns:
a string representation of the secondary data associated with the specified MediaNode suitable for display in the UI
Since:
7.0

IsNodePlayable

public boolean IsNodePlayable(sage.vfs.MediaNode MediaNode)
Returns true if the Object that this MediaNode wraps is suitable for passing to the Watch API call.

Parameters:
MediaNode - the specified MediaNode
Returns:
true if the Object that this MediaNode wraps is suitable for passing to the Watch API call
Since:
7.0

IsNodeVirtual

public boolean IsNodeVirtual(sage.vfs.MediaNode MediaNode)
Returns true if the specified MediaNode doesn't wrap an actual data object; but just an abstraction of a hierarchy

Parameters:
MediaNode - the specified MediaNode
Returns:
true if the specified MediaNode doesn't wrap an actual data object; but just an abstraction of a hierarchy
Since:
7.0

GetNodeDataObject

public java.lang.Object GetNodeDataObject(sage.vfs.MediaNode MediaNode)
Returns the Object that is wrapped by the specified MediaNode

Parameters:
MediaNode - the specified MediaNode
Returns:
the Object that is wrapped by the specified MediaNode
Since:
7.0

GetNodeDataType

public java.lang.String GetNodeDataType(sage.vfs.MediaNode MediaNode)
Returns the type of the Object that is wrapped by the specified MediaNode

Parameters:
MediaNode - the specified MediaNode
Returns:
the type of the Object that is wrapped by the specified MediaNode
Since:
7.0

GetNodeProperty

public java.lang.String GetNodeProperty(sage.vfs.MediaNode MediaNode,
                                        java.lang.String PropertyName)
Returns a specific property associated with this MediaNode. This varies depending upon the data type of the MediaNode. For MediaFile based nodes this will end up calling GetMediaFileMetadata.

Parameters:
MediaNode - the specified MediaNode
PropertyName - the name of the property
Returns:
the value of the specified property for the specified MediaNode
Since:
7.0

GetNodeParent

public sage.vfs.MediaNode GetNodeParent(sage.vfs.MediaNode MediaNode)
Returns the MediaNode parent of the specified MediaNode

Parameters:
MediaNode - the specified MediaNode
Returns:
the MediaNode parent of the specified MediaNode or null if it doesn't have a parent
Since:
7.0

RefreshNode

public void RefreshNode(sage.vfs.MediaNode MediaNode)
Refreshes the hierarchy associated with the specified MediaNode.

Parameters:
MediaNode - the specified MediaNode
Since:
7.0

SetNodeChecked

public void SetNodeChecked(sage.vfs.MediaNode MediaNode,
                           boolean State)
Sets a flag on this MediaNode to indicate it is in the checked state. Useful for tracking multi-selection of child MediaNodes.

Parameters:
MediaNode - the specified MediaNode
State - true if the MediaNode should be marked as being in the checked state, false otherwise
Since:
7.0

SetAllChildrenChecked

public void SetAllChildrenChecked(sage.vfs.MediaNode MediaNode,
                                  boolean State)
Sets a flag on all the children of this MediaNode to indicate they are in the checked state. Useful for tracking multi-selection of child MediaNodes.

Parameters:
MediaNode - the specified MediaNode
State - true if all the children of the MediaNode should be marked as being in the checked state, false if they should be marked as unchecked
Since:
7.0

GetChildrenCheckedCount

public int GetChildrenCheckedCount(sage.vfs.MediaNode MediaNode,
                                   boolean State)
Returns the number of children of the specified MediaNode that are in the specified checked state.

Parameters:
MediaNode - the specified MediaNode
State - true if the returned count should be for checked children, false if it should be for unchecked children
Returns:
the number of children of the specified MediaNode that are in the specified checked state
Since:
7.0

GetChildrenCheckedNodes

public java.util.Vector GetChildrenCheckedNodes(sage.vfs.MediaNode MediaNode,
                                                boolean State)
Returns the children of the specified MediaNode that are in the specified checked state.

Parameters:
MediaNode - the specified MediaNode
State - true if the returned list should be for checked children, false if it should be for unchecked children
Returns:
an array of children of the specified MediaNode that are in the specified checked state
Since:
7.0

CreateMediaNode

public sage.vfs.MediaNode CreateMediaNode(java.lang.String PrimaryLabel,
                                          java.lang.String SecondaryLabel,
                                          java.lang.Object Thumbnail,
                                          java.lang.Object Icon,
                                          java.lang.Object DataObject)
Creates a static MediaNode that has no parents and no children. Can be used to add arbitrary items to MediaNode lists for display in the UI. The data type for the node will be Virtual.

Parameters:
PrimaryLabel - the value to set as the primary label for the MediaNode
SecondaryLabel - the value to set as the secondary label for the MediaNode
Thumbnail - the Object to use as the thumbnail for the MediaNode
Icon - the Object to use as the icon for the MediaNode
DataObject - the Object that should be the data object for the MediaNode
Returns:
a new MediaNode object that has the specified attributes
Since:
7.0

GetNodeFullPath

java.lang.String GetNodeFullPath(sage.vfs.MediaNode MediaNode)
Returns a string which represents the hierarchical path to this MediaNode. This is created by appending the primary labels of all the parents up to the root of the hierarchy. The forward slash is used as a separator.

Parameters:
MediaNode - the specified MediaNode
Returns:
a string which represents the hierarchical path to this MediaNode
Since:
7.0

GetNodeTypePath

java.lang.String GetNodeTypePath(sage.vfs.MediaNode MediaNode)
Returns a string which represents the hierarchical path to this MediaNode with type information only. This is created by appending the data types of all the parents up to the root of the hierarchy. The forward slash is used as a separator. For Virtual nodes, it will use F if it represents a folder in the import hierarchy; otherwise it'll use the primary label unless that is null, in which case it'll use V.

Parameters:
MediaNode - the specified MediaNode
Returns:
a string which represents the hierarchical type path to this MediaNode
Since:
7.0

IsMediaNodeObject

public boolean IsMediaNodeObject(java.lang.Object Object)
Returns true if the specified object is a MediaNode object. No automatic type conversion will be performed on the argument.

Parameters:
Object - the object to test to see if it is a MediaNode object
Returns:
true if the argument is a MediaNode object, false otherwise
Since:
7.1

SageTV Platform
V9.0

SageTV is a trademark or registered trademark of Google, Inc. in the US and other countries.
Copyright 2000-2015 The SageTV Authors. All Rights Reserved.