org.ocap.hn.content
Interface ContentContainer

All Superinterfaces:
ContentEntry

public interface ContentContainer
extends ContentEntry

This class represents a container that contains one or more content entries. Can contain children containers.


Field Summary
static int ALBUM_CONTAINER
          Represents the base album container.
static int ALBUM_CONTAINER_MUSIC
          Represents a music album container.
static int ALBUM_CONTAINER_PHOTO
          Represents a photo album container.
static int CONTAINER
          Represents the base container class.
static int GENRE_CONTAINER
          Represents an unordered collection of 'objects' that "belong" to the genre.
static int GENRE_CONTAINER_MOVIE
          Represents a movie genre container.
static int GENRE_CONTAINER_MUSIC
          Represents a music genre container.
static int PERSON_CONTAINER
          Represents an unordered collection of 'objects' that "belong" to the people.
static int PERSON_CONTAINER_MUSIC_ARTIST
          Represents a music artist person container.
static int PLAYLIST_CONTAINER
          Represents a collection of objects.
static int STORAGE_FOLDER_CONTAINER
          Represents all, or a partition of some physical storage unit of a single type.
static int STORAGE_SYSTEM_CONTAINER
          Represents a potentially heterogeneous collection of storage media.
static int STORAGE_VOLUME_CONTAINER
          Represents all, or a partition of, some physical storage unit of a single type.
 
Method Summary
 boolean addContentEntry(ContentEntry entry)
          Adds a ContentEntry to this ContentContainer.
 boolean contains(ContentEntry entry)
          Checks whether the given ContentEntry is in this ContentContainer in local cache only.
 boolean createContentContainer(String name, ExtendedFileAccessPermissions permissions)
          Creates a new ContentContainer as a child of this ContentContainer, in local cache only; does not cause network activity.
 boolean delete()
          Deletes this ContentContainer if and only if it is empty.
 boolean deleteContents()
          Deletes all the ContentEntry objects in this container except for ContentContainer entries.
 boolean deleteRecursive(boolean recursive)
          Deletes this ContentContainer and all of its ContentEntry objects.
 int getComponentCount()
          Gets the number of ContentEntry objects in this ContentContainer.
 int getContainerClass()
          Returns the container class of this container.
 long getContentSize()
          Gets the size of the ContentContainer and all its content including all its contained ContentContainer objects.
 Date getCreationDate()
          Returns the creation date of this ContentContainer.
 Enumeration getEntries()
          Gets an Enumeration over all entries in this ContentContainer, from local cache only; does not cause network activity.
 ContentList getEntries(ContentDatabaseFilter filter, boolean traverse)
          Returns a ContentList which contains the filtered ContentItems of this ContentContainer.
 ContentEntry getEntry(int n)
          Returns the nth ContentEntry in this container, from local cache only; does not cause network activity.
 ExtendedFileAccessPermissions getExtendedFileAccessPermissions()
          Gets the ExtendedFileAccessPermissions of this ContentContainer.
 int getIndex(ContentEntry n)
          Gets the index of the specified ContentEntry, from local cache only; does not cause network activity.
 String getName()
          Gets the name of this ContentContainer.
 boolean isEmpty()
          Returns an empty indication.
 NetActionRequest requestNewEntry(ContentEntry entry, ContentServer server, NetActionHandler handler)
          Requests a ContentEntry be created and added to a Container in a remote server.
 ContentEntry[] toArray()
          Returns an array of all ContentEntry in this ContentContainers including other ContentContainers.
 
Methods inherited from interface org.ocap.hn.content.ContentEntry
getMetadata, getParent, getServer
 

Field Detail

CONTAINER

static final int CONTAINER
Represents the base container class.

See Also:
Constant Field Values

ALBUM_CONTAINER

static final int ALBUM_CONTAINER
Represents the base album container.

See Also:
Constant Field Values

ALBUM_CONTAINER_MUSIC

static final int ALBUM_CONTAINER_MUSIC
Represents a music album container. In addition to being an ALBUM_CONTAINER container may be a music album.

See Also:
Constant Field Values

ALBUM_CONTAINER_PHOTO

static final int ALBUM_CONTAINER_PHOTO
Represents a photo album container. In addition to being an ALBUM_CONTAINER container may be a photo album.

See Also:
Constant Field Values

GENRE_CONTAINER

static final int GENRE_CONTAINER
Represents an unordered collection of 'objects' that "belong" to the genre.

See Also:
Constant Field Values

GENRE_CONTAINER_MUSIC

static final int GENRE_CONTAINER_MUSIC
Represents a music genre container. In addition to being a GENRE_CONTAINER a container may be a music genre container

See Also:
Constant Field Values

GENRE_CONTAINER_MOVIE

static final int GENRE_CONTAINER_MOVIE
Represents a movie genre container. In addition to being a GENRE_CONTAINER a container may be a movie genre container

See Also:
Constant Field Values

PLAYLIST_CONTAINER

static final int PLAYLIST_CONTAINER
Represents a collection of objects.

See Also:
Constant Field Values

PERSON_CONTAINER

static final int PERSON_CONTAINER
Represents an unordered collection of 'objects' that "belong" to the people.

See Also:
Constant Field Values

PERSON_CONTAINER_MUSIC_ARTIST

static final int PERSON_CONTAINER_MUSIC_ARTIST
Represents a music artist person container. In addition to being a PERSON_CONTAINER a container may be a music artist.

See Also:
Constant Field Values

STORAGE_SYSTEM_CONTAINER

static final int STORAGE_SYSTEM_CONTAINER
Represents a potentially heterogeneous collection of storage media.

See Also:
Constant Field Values

STORAGE_VOLUME_CONTAINER

static final int STORAGE_VOLUME_CONTAINER
Represents all, or a partition of, some physical storage unit of a single type.

See Also:
Constant Field Values

STORAGE_FOLDER_CONTAINER

static final int STORAGE_FOLDER_CONTAINER
Represents all, or a partition of some physical storage unit of a single type.

See Also:
Constant Field Values
Method Detail

getContainerClass

int getContainerClass()
Returns the container class of this container.

Returns:
The content class of this item.
See Also:
ALBUM_CONTAINER, ALBUM_CONTAINER_MUSIC, ALBUM_CONTAINER_PHOTO, GENRE_CONTAINER, GENRE_CONTAINER_MUSIC, GENRE_CONTAINER_MOVIE, PLAYLIST_CONTAINER, PERSON_CONTAINER, PERSON_CONTAINER_MUSIC_ARTIST, STORAGE_SYSTEM_CONTAINER, STORAGE_VOLUME_CONTAINER, STORAGE_FOLDER_CONTAINER

toArray

ContentEntry[] toArray()
Returns an array of all ContentEntry in this ContentContainers including other ContentContainers. Returns ContentEntry objects stored in local cache only; does not cause network activity.

Returns:
array containing all entries of this ContentContainers

contains

boolean contains(ContentEntry entry)
Checks whether the given ContentEntry is in this ContentContainer in local cache only.

Parameters:
entry - To search for in this ContentEntry.
Returns:
True if the ContentEntry is contained in this container, otherwise returns false.

getEntry

ContentEntry getEntry(int n)
Returns the nth ContentEntry in this container, from local cache only; does not cause network activity.

Parameters:
n - Index of the entry to get.
Returns:
the nth ContentEntry.
Throws:
ArrayIndexOutOfBoundsException - if the nth value does not exist.

getEntries

Enumeration getEntries()
Gets an Enumeration over all entries in this ContentContainer, from local cache only; does not cause network activity.

Returns:
Enumeration over all entries in this ContentContainers, or null if there are no entries.

getIndex

int getIndex(ContentEntry n)
Gets the index of the specified ContentEntry, from local cache only; does not cause network activity.

Parameters:
n - The index of the ContentEntry to search for.
Returns:
The index of the ContentEntry or -1 if it doesn't exist in this container.

createContentContainer

boolean createContentContainer(String name,
                               ExtendedFileAccessPermissions permissions)
                               throws SecurityException
Creates a new ContentContainer as a child of this ContentContainer, in local cache only; does not cause network activity. If this ContentContainer #isLocal method returns false this method will return false. Can be used to create a directory structure.

Parameters:
name - The name of the new ContentContainer.
permissions - Access permissions of the new ContentContainer.
Returns:
True if a new ContentContainer has been created, otherwise returns false.
Throws:
SecurityException - if the application is denied to perform the action. Determined by ExtendedFileAccessPermissions if the container is local, otherwise determined by protocol specific security, e.g., UPnP SecurityConsole.

getEntries

ContentList getEntries(ContentDatabaseFilter filter,
                       boolean traverse)
Returns a ContentList which contains the filtered ContentItems of this ContentContainer. If the traverse parameter is true the ContentItems of all its children ContentContainers is included. The list returned is filtered by the filter parameter. If the filter is null all items are returned.

Parameters:
filter - A ContentDatabaseFilter to filter the ContentItems. If the filter is null all entries are returned
traverse - If true entries in the sub-containers are returned, otherwise only entries in this ContentContainer are returned.
Returns:
a ContentList filtered by the ContentDatabaseFilter

getName

String getName()
Gets the name of this ContentContainer.

Specified by:
getName in interface ContentEntry
Returns:
The name of this ContentContainer.
See Also:
ContentEntry.getName()

delete

boolean delete()
               throws IOException,
                      SecurityException
Deletes this ContentContainer if and only if it is empty. References to this ContentContainer are not valid after this call. This method deletes a local ContentContainer only. If the #isLocal method returns false a exception is thrown.

Specified by:
delete in interface ContentEntry
Returns:
True if this ContentContainer was deleted, otherwise returns false.
Throws:
SecurityException - if the application is denied to perform the action
IOException - if this ContentContainer is not local.

deleteContents

boolean deleteContents()
                       throws IOException,
                              SecurityException
Deletes all the ContentEntry objects in this container except for ContentContainer entries. Calls the ContentEntry.delete() method on each entry in this container. References to ContentEntry objects in this container are not valid after this call when the deletions are successful. This method deletes local ContentEntry instances only. If the #isLocal method returns false, an exception is thrown.

Returns:
True if all of the ContentEntry objects in this container were deleted, otherwise returns false.
Throws:
SecurityException - if the calling application does not have ExtendedFileAccessPermission to delete any of the ContentEntry objects in this container.
IOException - if this ContentContainer is not local.

deleteRecursive

boolean deleteRecursive(boolean recursive)
                        throws IOException,
                               SecurityException
Deletes this ContentContainer and all of its ContentEntry objects. For entries that are ContentContainer objects a possible implementation is a recursive traversal where these objects are deleted in a bottom-up fashion by calling this method on each one.

Parameters:
recursive - if true all entries and their entries will be deleted.
Throws:
SecurityException - if the application is denied to perform the action
IOException - if action fails due to an IO error.
See Also:
ContentManagementModule.delete(Locator, NetActionHandler), delete()

addContentEntry

boolean addContentEntry(ContentEntry entry)
Adds a ContentEntry to this ContentContainer. Can only add local ContentEntry objects to local ContentContainer.

Returns:
True if the entry was added. Returns false if the isLocal method of this ContentContainer or the parameter ContentEntry returns false.

getContentSize

long getContentSize()
Gets the size of the ContentContainer and all its content including all its contained ContentContainer objects. Note that the size may have changed during the call to this method.

Specified by:
getContentSize in interface ContentEntry
Returns:
The content size in bytes or -1 if the size is indeterminate.

getCreationDate

Date getCreationDate()
Returns the creation date of this ContentContainer.

Specified by:
getCreationDate in interface ContentEntry
Returns:
The Date the content was created or null if the creation date is indeterminate.

getExtendedFileAccessPermissions

ExtendedFileAccessPermissions getExtendedFileAccessPermissions()
Gets the ExtendedFileAccessPermissions of this ContentContainer.

Specified by:
getExtendedFileAccessPermissions in interface ContentEntry
Returns:
The ExtendedFileAccessPermission.

getComponentCount

int getComponentCount()
Gets the number of ContentEntry objects in this ContentContainer. Does not include component count of entries within ContentContainer objects contained in this ContentContainer.

Returns:
Number of entries.

isEmpty

boolean isEmpty()
Returns an empty indication.

Returns:
True if this ContentContainer does not contain any ContentEntry objects, otherwise returns false.

requestNewEntry

NetActionRequest requestNewEntry(ContentEntry entry,
                                 ContentServer server,
                                 NetActionHandler handler)
                                 throws IllegalArgumentException
Requests a ContentEntry be created and added to a Container in a remote server. If the entry is a ContentContainer it must be empty.

Parameters:
entry - The entry to add in this container.
server - The ContentServer to request the new entry on.
handler - NetActionHandler which gets informed once the request completes.
Returns:
NetActionRequest to inform calling application of results.
Throws:
IllegalArgumentException - if the entry or handler parameter is null. If the entry is a ContentContainer and is not empty.
DatabaseException - if this Container is local; #isLocal returns true.