org.ocap.hn.content
Class ContentDatabase

java.lang.Object
  extended by org.ocap.hn.content.ContentDatabase
All Implemented Interfaces:
Enumeration, ContentList

public abstract class ContentDatabase
extends Object
implements ContentList

This class represents the Content database containing content entries accessible from this OCAP device. An implementation MAY add entries to this database in an implementation specific fashion. An implementation MAY make entries it adds searchable by applications. An application MAY add local or remote entries to this database. In this way an application creates a view of the database. The implementation SHALL NOT put ContentObject entries in an application's view of this database if the application does not have read ExtendedFileAccessPermissions, or if that's not applicable in a particular HN Profile, it will be based on the profile specific security defined in any supported HN profile specification, e.g. OCAP UPnP Profile Specification.

The implementation SHALL create a root ContentContainer that applications can read and write; see the #getRootContainer method.

Implementations SHALL persist local entries in this database across reboots and power cycles if persistent storage space is available. Persistence of remote entries is implementation specific.


Method Summary
abstract  void addNewContentContainer(String name, ContentContainer parent, ExtendedFileAccessPermissions efap)
          Adds a new empty local ContentContainer to this database.
static ContentDatabase getInstance()
          Returns an instance of the ContentDatabase.
abstract  ContentContainer getRootContainer()
          Gets the root ContentContainer of this database.
abstract  void removeEntry(ContentEntry entry)
          Removes the specified ContentEntry from this database.
abstract  NetActionRequest requestEntries(ContentServer server, ContentContainer parent, int startingIndex, int requestedCount, ContentContainer container, String searchCriteria, NetActionHandler handler)
          Requests a search of the remote ContentServer which results in the creation of a ContentList.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.ocap.hn.content.navigation.ContentList
addContentListListener, filterContentList, find, find, findAll, getSortOrder, removeContentListListener, setSortOrder, size
 
Methods inherited from interface java.util.Enumeration
hasMoreElements, nextElement
 

Method Detail

getInstance

public static ContentDatabase getInstance()
Returns an instance of the ContentDatabase. The database contains all known and accessible content locally and on the home network.

Returns:
The singleton instance of the ContentDatabase.

getRootContainer

public abstract ContentContainer getRootContainer()
Gets the root ContentContainer of this database.

Returns:
The root container.

addNewContentContainer

public abstract void addNewContentContainer(String name,
                                            ContentContainer parent,
                                            ExtendedFileAccessPermissions efap)
                                     throws IllegalArgumentException
Adds a new empty local ContentContainer to this database.

Parameters:
name - Name of the new ContentContainer.
efap - ExtendedFileAccessPermissions of the new ContentContainer.
parent - ContentContainer to add the new container to. If null the root container of the database is used.
Throws:
IllegalArgumentException - if the name is null or a duplicate in the same parent container.

requestEntries

public abstract NetActionRequest requestEntries(ContentServer server,
                                                ContentContainer parent,
                                                int startingIndex,
                                                int requestedCount,
                                                ContentContainer container,
                                                String searchCriteria,
                                                NetActionHandler handler)
                                         throws IllegalArgumentException
Requests a search of the remote ContentServer which results in the creation of a ContentList.

ContentEntry objects hosted on the remote server will be searched for using the specified search criteria. The format of the string containing the search criteria SHALL follow the format defined by the UPnP Content Directory Service specification section 2.5.5.1: Search Criteria String Syntax.

This is an asynchronous method. The caller gets informed via NetActionHandler.notify(NetActionEvent) of the process. On success an NetActionEvent is created where the NetActionEvent.getResponse() method will return a ContentList containing the search results. If this is null no matches were found.

Parameters:
server - the server that the entries SHALL be requested from.
parent - the ContentContainer on the server to start the search from.
startingIndex - starting zero-based offset to enumerate children under the container specified by parent.
requestedCount - requested number of entries under the ContentContainer specified by parent. Setting this parameter to 0 indicates request all entries.
container - The ContentContainer to place the results in if the request is successful. This parameter MAY be null in which case the results SHALL NOT be added to this database by this request.
searchCriteria - contains the criteria string to search for. If this parameter is null, the implementation SHALL consider all entries in the parent container as matching the search criteria.
handler - NetActionHandler which gets informed once the results ContentList is created or an error occurs. calling getResponse() on handler will return a ContentList containing the requested entries, or if the call was unsuccessful will return an error message supplied by the server.
Returns:
NetActionRequest See NetActionRequest.
Throws:
IllegalArgumentException - if the server parameter is not available from the NetManager, or if the handler parameter is null.

removeEntry

public abstract void removeEntry(ContentEntry entry)
Removes the specified ContentEntry from this database.

Parameters:
entry - The entry to remove.
Throws:
SecurityException - if the calling application does not have write ExtendedFileAccessPermission for the entry.